🎬 ConditionalVideos

Server-aware cinematic triggers for Minecraft. Configure conditions once and let clients play synced videos exactly when it matters.

---

✨ 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

• Minecraft Version: 1.20.1
• Loaders: Fabric, Forge
• Java: 17+
• Client Config File: config/conditionalvideos.json
• Dedicated Server Config File: config/conditionalvideos-server.json
• Required Fabric API
• Required WATERMeDIA: Multimedia API

---

🧭 Client vs Server (Important)

Client Instance

• Creates and uses:
  • config/conditionalvideos.json
• In singleplayer:
  • Uses local client config directly.
  • Local video paths are resolved from the local game directory (or absolute path).
• In multiplayer:
  • Acts as a passive receiver 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
video	string	Yes	Path to the video file. Relative paths are resolved from the Minecraft game directory; absolute paths are also allowed.
skippable	boolean	Yes	If true, the user can skip playback with ESC.
repeatableInSameSession	boolean	Yes	If false, this condition key can trigger once per session. If true, it can trigger repeatedly during the same session.
enableBackground	boolean	Yes	Enables a solid-color full-screen background behind the video.
colorBackground	string	Yes*	Hex color in #RRGGBB or #AARRGGBB format.
videoTitle	string	No	Optional title overlay. Supports legacy Minecraft format codes (&6, &l, &r, etc.).
videoTitlePosition	string	No	topLeft, topRight, bottomLeft, bottomRight.
videoDescription	string	No	Optional description overlay. Supports legacy format codes.
videoDescriptionPosition	string	No	topLeft, topRight, bottomLeft, bottomRight.

---

📁 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?