Skip to content

Home

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

ConditionalVideos — Developer Wiki

Welcome to the developer documentation for ConditionalVideos. This wiki is for mod authors who want to integrate with ConditionalVideos: register their own conditions and trigger, force, stop, or pause cinematic playback from their own code.

If you are a server owner or pack author looking for configuration docs, see the project README instead — this wiki only covers the programmatic API.

Pages

  • Home — this page: concepts, where things run, and dependency setup.
  • API Reference — every public type and method, parameters, return values, and the full list of condition keys.
  • Custom Conditions & Examples — end-to-end recipes for the most common integrations.

What the API lets you do

The public surface lives in the package org.mateof24.conditionalvideos.api and is intentionally small and stable:

  • Register custom conditions — define a custom/<id> condition that has no built-in detector. Your mod decides when it fires; server admins map videos to it in their config.
  • Trigger playback — ask a player's client to play a configured condition, either honoring its "first time / repeatable" gate or forcing it unconditionally.
  • Control playback — stop or toggle-pause the current video.
  • Observe playback — query whether a video is playing/paused on the local client and which condition it is, and subscribe to start/end events.

Everything is exposed as static methods on ConditionalVideosAPI. You never instantiate it.

The golden rule: where things run

Playback always happens on the client. The server can only order a client to play, stop, or pause.

ConditionalVideos opens the video screen on the client. In multiplayer, the dedicated server detects server-side events and sends a control message to the target player's client over the mod's internal channel. This shapes the entire API:

Your code runs on… Use these methods Why
Server (a ServerPlayer is available) triggerOnServer, triggerCustomOnServer, forcePlayOnServer, stopOnServer, togglePauseOnServer The order is routed to that player's client.
Client (client-only mod / singleplayer) playOnClient, stopOnClient, togglePauseOnClient, and all state/event methods Acts directly on the local client.

Environment safety: every *OnClient method and the state queries are no-ops in the wrong environment (e.g. calling playOnClient on a dedicated server does nothing). You do not need to wrap calls in your own side checks, though doing so is still good practice.

In singleplayer, server-side methods work too (there is an integrated server), and the integrated server routes the order back to the local client — so prefer *OnServer when you have a ServerPlayer, even in singleplayer.

Adding ConditionalVideos as a dependency

ConditionalVideos is built with Architectury (Forge/Fabric on 1.20.1, NeoForge/Fabric on 1.21.1). The API package is plain Java + Minecraft types, so you can compile against it from your common/platform source sets.

Add the ConditionalVideos jar as a compile-time dependency. You only need it at compile time — at runtime users install the mod themselves, and you should treat it as a soft/optional dependency so your mod still loads without it.

dependencies {
    // Compile against the API. Replace with the coordinate/file you use.
    compileOnly "org.mateof24:conditionalvideos:<version>"
    // or, if you keep the jar locally:
    // compileOnly files("libs/conditionalvideos-<version>.jar")
}
  • Maven group / artifact: org.mateof24 / conditionalvideos.
  • API package: org.mateof24.conditionalvideos.api.

Make it optional at runtime

Because ConditionalVideos may not be installed, guard your usage so your mod degrades gracefully:

public final class CvBridge {
    public static final boolean PRESENT =
            net.fabricmc.loader.api.FabricLoader.getInstance().isModLoaded("conditionalvideos");
    // On (Neo)Forge use ModList.get().isLoaded("conditionalvideos") instead.
}
if (CvBridge.PRESENT) {
    ConditionalVideosAPI.triggerOnServer(player, "firstJoin");
}

Touching ConditionalVideosAPI only inside an if (PRESENT) branch (or a separate class loaded lazily) prevents a NoClassDefFoundError when the mod is absent.

A 60-second example

Register a custom condition during your mod's init, then fire it when your own event happens:

// During mod init (any side):
ConditionalVideosAPI.registerCustomCondition(
        "my_event", "My Event", "Plays when the boss spawns");

// Later, on the server, when your event fires for a specific player:
ConditionalVideosAPI.triggerCustomOnServer(serverPlayer, "my_event");

A server admin adds videos to custom/my_event in conditionalvideos-server.json (the entry is seeded empty automatically), and the cinematic plays on that player's client.

Continue to the API Reference for the complete surface, or jump to Custom Conditions & Examples for full recipes.

Clone this wiki locally