ConditionalVideos

<h1 align="center">🎬 ConditionalVideos</h1>

<div align="center">

Fabric 1.20.1

Fabric 1.21.1

Forge 1.20.1

NeoForge 1.21.1

Environment

Report Issues

</div>

<p align="center"> Server-aware cinematic triggers for Minecraft. Configure conditions once and let clients play synced videos exactly when it matters. </p>

---

✨ Overview

ConditionalVideos plays custom videos when specific in-game events are detected. It is not strictly client-side: it runs on both client and dedicated server, with different responsibilities in each environment.

It is designed for curated gameplay experiences such as servers, story maps, quest packs, and roleplay setups where cinematic feedback improves immersion.

***

🧩 Compatibility & Requirements

* Required 1.20.1 * Required Fabric (1.20.1/1.21.1), Forge (1.20.1), NeoForge (1.21.1) * Required 17+ (1.20.1), 21+ (1.21.1) * Required `config/conditionalvideos.json` * Required `config/conditionalvideos-server.json` * Required * Required * Required Required (Fabric still requires it even on the server side, while Forge only requires it on the client side!)

> Known issue for Minecraft 1.21.1: Advancement-based videos may not replay within the same continuous session if an advancement is revoked and then earned again without the player leaving the world/server.

***

🧭 Client vs Server (Important)

Client Instance

* Creates and uses: * `config/conditionalvideos.json` * In not: * Uses local client config directly. * Local `video` paths are resolved from the local game directory (or absolute path). * In not: * Acts as a not for server data. * Receives synced server config at runtime (it does not use your local client rules for server gameplay). * Downloads server-provided videos to cache and reuses them on reconnect. * Cache location pattern: * `config/conditionalvideos/<server-id>/<condition-type>/<file>` * On disconnect: * Synced runtime state is cleared and re-requested next time you join.

Dedicated Server Instance

* Creates and uses: * `config/conditionalvideos-server.json` * Owns the authoritative config for connected clients. * On player join: * Sends synced config to clients. * Publishes a manifest of configured videos. * Serves missing/outdated files to clients in chunks. * If you replace a video file on server or change path/config: * Clients detect hash mismatch and re-download updated files automatically.

What this means in practice

* Clients still need the mod installed to receive/play synced videos from the server. * You can install video assets only on the server and clients will receive needed files automatically. * Local client config stays useful for singleplayer testing, but does not override dedicated-server behavior in multiplayer. * For multiplayer content pipelines, treat `conditionalvideos-server.json` as the source of truth.

***

🎯 Supported Conditions

Supports multiple gameplay trigger types so you can tailor cinematic playback to meaningful moments during progression.

* First connection trigger Plays an intro/cinematic when the player enters the world/session.

* General death trigger Works as the default fallback cinematic for any player death event.

* Entity-specific death trigger Lets you override the generic death behavior with custom videos based on the killer entity ID (`namespace:entity`), such as `minecraft:zombie` or `minecraft:creeper`. When this trigger matches, it takes precedence over the general death trigger.

* Entity kill trigger Plays a video when the player defeats specific configured entity IDs.

* Advancement completion trigger Plays a video when configured advancements are completed.

* Dimension transition trigger Plays a video when the player enters configured dimensions.

***

🧱 Condition Object Schema

Each condition entry shares the same structure:

| Property |Type |Required |Description | | ------------------------ |------- |-------- |----------------------------------------------------------------------------------------------------------------------- | | <code>video</code> |<code>string</code> |Yes |Path to the video file. Relative paths are resolved from the Minecraft game directory; absolute paths are also allowed. | | <code>skippable</code> |<code>boolean</code> |Yes |If <code>true</code>, the user can skip playback with <code>ESC</code>. | | <code>repeatableInSameSession</code> |<code>boolean</code> |Yes |If <code>false</code>, this condition key can trigger once per session. If <code>true</code>, it can trigger repeatedly during the same session. | | <code>enableBackground</code> |<code>boolean</code> |Yes |Enables a solid-color full-screen background behind the video. | | <code>colorBackground</code> |<code>string</code> |Yes* |Hex color in <code>#RRGGBB</code> or <code>#AARRGGBB</code> format. | | <code>videoTitle</code> |<code>string</code> |No |Optional title overlay. Supports legacy Minecraft format codes (<code>&amp;amp;amp;6</code>, <code>&amp;amp;amp;l</code>, <code>&amp;amp;amp;r</code>, etc.). | | <code>videoTitlePosition</code> |<code>string</code> |No |<code>topLeft</code>, <code>topRight</code>, <code>bottomLeft</code>, <code>bottomRight</code>. | | <code>videoDescription</code> |<code>string</code> |No |Optional description overlay. Supports legacy format codes. | | <code>videoDescriptionPosition</code> |<code>string</code> |No |<code>topLeft</code>, <code>topRight</code>, <code>bottomLeft</code>, <code>bottomRight</code>. |

***

📁 Path Rules by Environment

Singleplayer / Client-only local playback

* `video` can be: * Relative path (resolved from game directory) * Absolute path

Dedicated server playback for connected clients

* Server resolves `video` from server filesystem. * Client does not need that same path to exist locally. * Client receives file content from server and plays cached copy instead.

> Recommendation: keep all server video assets in a dedicated folder (for example `videos/`) and reference them with relative paths in `conditionalvideos-server.json`.

***

Session Tracking Field

The config includes one internal tracking field managed by the mod:

* `consumedConditionSessions` * Stores condition/session keys that were already consumed when `repeatableInSameSession` is `false`. * Prevents non-repeatable conditions from replaying in the same session.

> You usually should not edit this field manually unless you intentionally want to reset session trigger history for testing.

***

🗂️ Full `config/conditionalvideos.json` or `config/conditionalvideos-server.json` Example

``` { "firstJoin": { "video": "videos/intro.mp4", "skippable": true, "repeatableInSameSession": false, "enableBackground": true, "colorBackground": "#FF000000", "videoTitle": "&6&lWelcome", "videoTitlePosition": "topLeft", "videoDescription": "&fEnjoy your journey", "videoDescriptionPosition": "topLeft" }, "playerDeath": { "video": "videos/death/default_death.mp4", "skippable": true, "repeatableInSameSession": true, "enableBackground": true, "colorBackground": "#AA000000", "videoTitle": "&cYou Died", "videoTitlePosition": "bottomLeft", "videoDescription": "&7Try again", "videoDescriptionPosition": "bottomLeft" }, "entityKilled": { "minecraft:skeleton": { "video": "videos/kills/skeleton.mp4", "skippable": true, "repeatableInSameSession": true, "enableBackground": false, "colorBackground": "#000000", "videoTitle": "&fSkeleton Defeated", "videoTitlePosition": "topRight", "videoDescription": "&7Nice shot", "videoDescriptionPosition": "topRight" }, "minecraft:warden": { "video": "videos/kills/warden.mp4", "skippable": false, "repeatableInSameSession": false, "enableBackground": true, "colorBackground": "#CC000000", "videoTitle": "&5&lEpic Victory", "videoTitlePosition": "topRight", "videoDescription": "&dYou defeated the Warden", "videoDescriptionPosition": "topRight" } }, "deathByEntity": { "minecraft:zombie": { "video": "videos/death/zombie_death.mp4", "skippable": true, "repeatableInSameSession": true, "enableBackground": true, "colorBackground": "#B0000000", "videoTitle": "&2A Zombie got you", "videoTitlePosition": "bottomRight", "videoDescription": "&7Watch your back at night", "videoDescriptionPosition": "bottomRight" }, "minecraft:creeper": { "video": "videos/death/creeper_death.mp4", "skippable": true, "repeatableInSameSession": false, "enableBackground": true, "colorBackground": "#99000000", "videoTitle": "&aBoom...", "videoTitlePosition": "bottomRight", "videoDescription": "&7A Creeper surprised you", "videoDescriptionPosition": "bottomRight" } }, "advancementCompleted": { "minecraft:story/mine_diamond": { "video": "videos/advancements/diamond.mp4", "skippable": true, "repeatableInSameSession": false, "enableBackground": false, "colorBackground": "#000000", "videoTitle": "&bDiamonds!", "videoTitlePosition": "topLeft", "videoDescription": "&fFirst diamond obtained", "videoDescriptionPosition": "topLeft" }, "minecraft:nether/root": { "video": "videos/advancements/nether_entry.mp4", "skippable": true, "repeatableInSameSession": false, "enableBackground": true, "colorBackground": "#AA1A0000", "videoTitle": "&4Welcome to the Nether", "videoTitlePosition": "topLeft", "videoDescription": "&7Temperature rising", "videoDescriptionPosition": "topLeft" } }, "dimensionChanged": { "minecraft:the_nether": { "video": "videos/dimensions/nether.mp4", "skippable": true, "repeatableInSameSession": true, "enableBackground": true, "colorBackground": "#CC000000", "videoTitle": "&cEntered the Nether", "videoTitlePosition": "bottomLeft", "videoDescription": "&7Bring fire resistance", "videoDescriptionPosition": "bottomLeft" }, "minecraft:the_end": { "video": "videos/dimensions/end.mp4", "skippable": false, "repeatableInSameSession": false, "enableBackground": true, "colorBackground": "#CC000000", "videoTitle": "&5The End awaits", "videoTitlePosition": "bottomLeft", "videoDescription": "&dPrepare for the dragon", "videoDescriptionPosition": "bottomLeft" } }, "consumedConditionSessions": [] } ```

***

🛠️ Support

* Found a bug or want to request a feature?

Report Issues