Skip to content

API Reference

Jump to bottom
MateoF24 edited this page Jun 4, 2026 · 2 revisions

API Reference

Complete reference for the public API in org.mateof24.conditionalvideos.api.

All methods are static. The class is final and cannot be instantiated. See Home for the client-vs-server model that governs which methods to call.

ConditionalVideosAPI

Fully-qualified: org.mateof24.conditionalvideos.api.ConditionalVideosAPI.

Custom condition registration

void registerCustomCondition(CustomCondition condition)

Registers a custom condition so it is dispatchable by id and discoverable in config. null is ignored. Registering the same id again replaces the previous entry.

Registered conditions are seeded into the active config file as empty entries when a world starts — but only when the file does not already contain them. Existing entries are never altered, and a config file that cannot be parsed as JSON is left untouched. Admins add videos under custom/<id> to make it playable.

void registerCustomCondition(String id)

Convenience overload — equivalent to registerCustomCondition(new CustomCondition(id)).

void registerCustomCondition(String id, String displayName, String description)

Convenience overload — equivalent to registerCustomCondition(new CustomCondition(id, displayName, description)).

boolean isCustomConditionRegistered(String id)

Returns true if a custom condition with this id has been registered. Trims the id; null returns false.

Collection<CustomCondition> registeredCustomConditions()

Returns an immutable snapshot of all registered custom conditions.

When to register: during your mod's common/init phase. Registration is process-global (an in-memory registry); it is not persisted, so re-register on every launch. Seeding into the config happens at SERVER_STARTING, so register before a world is loaded.

Server-side triggering

Call these when you have a ServerPlayer. The order is routed to that player's client over the S2C control channel. All are no-ops for null/blank arguments.

boolean triggerOnServer(ServerPlayer player, String conditionKey)

Triggers a condition for a player, honoring its "first time / repeatable" gating (the same gate the built-in detectors use).

  • conditionKey — a condition key, e.g. firstJoin, itemObtained/minecraft:diamond, custom/my_event.
  • Returns true if an order was sent — i.e. the condition resolved, has at least one video, and passed the session gate. Returns false otherwise (unknown key, no videos, or already consumed this session for a non-repeatable condition).

boolean triggerCustomOnServer(ServerPlayer player, String customId)

Convenience for triggerOnServer(player, "custom/" + customId). Same gating and return semantics.

boolean forcePlayOnServer(ServerPlayer player, String conditionKey)

Plays a condition for a player ignoring session gating (mirrors the /conditionalvideos play command). Validates that the condition resolves and has at least one video.

  • Returns true if an order was sent (resolved + has videos), false otherwise.
  • Unlike triggerOnServer, this does not consume the once-per-session state and will replay even if already shown.

void stopOnServer(ServerPlayer player)

Orders the player's client to stop the current playback and clear its pending queue.

void togglePauseOnServer(ServerPlayer player)

Orders the player's client to toggle pause/resume on the current video.

Gating vs. forcing. triggerOnServer respects repeatableInSameSession and the per-session "already consumed" record, exactly like the built-in conditions. forcePlayOnServer bypasses that gate. Both still respect the playback queue: if a video is already on screen, the new one is postponed (it does not cut the current video off).

Client-side triggering

Call these from a client-only mod or for singleplayer convenience. Each is a no-op unless running on the client with an initialized Minecraft instance.

void playOnClient(String conditionKey)

Plays the given condition on the local client, resolving it against the active config. This is a forced play (no session gate), matching the command path.

void stopOnClient()

Stops the current playback on the local client and clears its pending queue.

void togglePauseOnClient()

Toggles pause/resume on the local client's current video.

Client-side state queries

Each returns a safe default when not on the client.

boolean isPlaying()

true if a video is currently on screen on this client.

boolean isPaused()

true if a video is playing and currently paused.

Optional<String> currentConditionKey()

The condition key currently playing on this client, if any. Empty when nothing is playing (or for internally-keyed playback with no key).

Client-side playback events

void addPlaybackListener(PlaybackListener listener)

Registers a PlaybackListener. Listeners are invoked on the client render thread.

void removePlaybackListener(PlaybackListener listener)

Removes a previously registered listener.

CustomCondition

A record describing a mod-defined condition. Fully-qualified: org.mateof24.conditionalvideos.api.CustomCondition.

public record CustomCondition(String id, String displayName, String description)
Component Meaning
id Unique, non-blank identifier. Becomes the config key custom/<id>. Trimmed; throws IllegalArgumentException if blank and NullPointerException if null.
displayName Human-readable name; falls back to id when blank. Informational (tooling).
description Optional one-line description; never null (normalized to empty string when unset).

Constructors

  • new CustomCondition(String id) — displayName and description default to id / empty.
  • new CustomCondition(String id, String displayName, String description) — full form.

Methods

  • String conditionKey() — returns custom/<id>, the wire/config key for this condition.

A custom condition has no built-in detector. Your mod decides when it fires (via the trigger methods), and server admins map videos to custom/<id> in their config. The display metadata is purely informational.

PlaybackListener

A client-side callback interface for the playback lifecycle. Fully-qualified: org.mateof24.conditionalvideos.api.PlaybackListener. Both methods are default (no-ops), so implement only what you need.

public interface PlaybackListener {
    default void onPlaybackStarted(String conditionKey) {}
    default void onPlaybackEnded(String conditionKey) {}
}
  • onPlaybackStarted(conditionKey) — called when a VideoPlaybackScreen opens.
  • onPlaybackEnded(conditionKey) — called when playback ends for any reason: natural end, skip-to-close, the skip/close key, playback failure, or a stop command/API call.

Notes:

  • Invoked on the client render thread — keep handlers short and thread-safe; offload heavy work.
  • conditionKey may be null for internally-keyed playback.
  • Register via ConditionalVideosAPI.addPlaybackListener(...).
ConditionalVideosAPI.addPlaybackListener(new PlaybackListener() {
    @Override public void onPlaybackEnded(String key) {
        if ("custom:cutscene".equals(key)) {
            // re-enable your HUD, resume music, etc.
        }
    }
});

Condition keys

Every trigger/resolve method takes a condition key string. Simple conditions use a bare key; keyed conditions use a type/key form (split on the first /, so the key part may itself contain / and :).

Key form Examples Config location
firstJoin firstJoin top-level object
playerDeath playerDeath top-level object
totemUsed totemUsed top-level object
bedSleep bedSleep top-level object
entityKilled/<entity> entityKilled/minecraft:warden entityKilled map
deathByEntity/<entity> deathByEntity/minecraft:creeper deathByEntity map
advancement/<id> advancement/minecraft:story/mine_diamond advancementCompleted map
dimension/<id> dimension/minecraft:the_nether dimensionChanged map
itemObtained/<item> itemObtained/minecraft:diamond itemObtained map
itemCrafted/<item> itemCrafted/minecraft:crafting_table itemCrafted map
recipeUnlocked/<recipe> recipeUnlocked/minecraft:furnace recipeUnlocked map
scoreboard/<objective> scoreboard/kills scoreboard map
custom/<id> custom/my_event custom map

⚠️ Prefix vs. config map name. The advancement and dimension keys use the prefixes advancement/ and dimension/ in API/command keys, but their config maps are named advancementCompleted and dimensionChanged. All other types share the same name in both places.

A key only "resolves" (and therefore plays) if the config has that entry with at least one video. triggerOnServer/forcePlayOnServer return false for keys that don't resolve, so you can use the boolean result to detect "no cinematic configured for this".

Threading & environment summary

Concern Behavior
Server methods (*OnServer) Call with a valid ServerPlayer; safe in singleplayer (integrated server) and dedicated servers.
Client methods (*OnClient), state queries No-op off-client; safe to call from common code.
Listeners Invoked on the client render thread.
Custom condition registry In-memory, process-global, not persisted; re-register each launch.
Config seeding Happens at world start (SERVER_STARTING); never overwrites existing entries or a malformed file.

See Custom Conditions & Examples for complete, copy-pasteable integrations.

Clone this wiki locally