ConditionalVideos

Play custom videos when specific in-game events are detected — first joins, deaths, kills, advancements, item milestones, scoreboard thresholds, and more.

✨ Overview

Choose a condition, add videos to its file, and the mod plays them at the right moment. It works in singleplayer, on LAN and on dedicated servers, where the server decides what plays and sends its video files to the players.

• Sources: local files, direct URLs, YouTube, Twitch, Kick, TikTok, SoundCloud and more, through WATERMeDIA.
• Playlists: transitions, loops, text overlays, per-video volume, start and end times.
• Waiting room: players wait for each other on firstJoin, then watch together.
• Safe to watch: players are protected during videos, and the world can freeze while everyone is watching.
• Commands to play, stop, pause and edit videos in-game, plus an API for other mods.

🧩 Requirements

| Minecraft | Loaders | Java |
|—|—|—|
| 1.20.1 | Fabric, Forge | 17+ |
| 1.21.1 | Fabric, NeoForge | 21+ |
| 1.21.11 | Fabric, NeoForge | 21+ |
| 26.1.2 | Fabric, NeoForge | 25+ |
| 26.2 | Fabric, NeoForge | 25+ |

Everywhere:

• Architectury API
• Fabric API (Fabric only)

On the client:

• WATERMeDIA: Multimedia API 3.0.0+
• WATERMeDIA: Native Binaries 3.0.0+

On 26.2, videos play on both renderers, but Vulkan support is experimental. OpenGL is the safest choice.

🎯 Conditions

| Condition | Plays when |
|—|—|
| firstJoin | The player joins the world. It always plays before anything else. |
| playerDeath | The player dies. |
| totemUsed | A Totem of Undying saves the player. |
| bedSleep | The player starts sleeping. |
| deathByEntity | A specific entity kills the player. Takes priority over playerDeath. |
| entityKilled | The player kills a specific entity. |
| advancementCompleted | The player completes an advancement. |
| dimensionChanged | The player enters a dimension. |
| itemObtained | The player gets an item. |
| itemCrafted | The player crafts an item. |
| recipeUnlocked | The player unlocks a recipe. |
| scoreboard | A score meets a comparison. |
| worldPosition | The player enters or leaves an area. |
| custom | A command or another mod fires it. |

⌨️ Commands

For operators (permission level 2+), command blocks and the server console:

/conditionalvideos play <targets> <condition> [delay <seconds>] [exclude <players>] [excludeteam <team>] [excludeops] [once] [sync]
/conditionalvideos stop <targets>
/conditionalvideos pause <targets>
/conditionalvideos reset <targets> <condition | all>

/conditionalvideos set defaultvolume <volume>
/conditionalvideos set volume <condition> <video_index> <volume>
/conditionalvideos set conditiondelay <condition> <seconds>
/conditionalvideos set startat <condition> <video_index> <seconds>
/conditionalvideos set title <condition> <video_index> [at_position <x> <y>] <text>
/conditionalvideos set description <condition> <video_index> [at_position <x> <y>] <text>
/conditionalvideos set titleposition <condition> <video_index> <position | x y>
/conditionalvideos set descriptionposition <condition> <video_index> <position | x y>

/conditionalvideos waitingroom start [force]
/conditionalvideos waitingroom join [targets]
/conditionalvideos waitingroom leave [targets]
/conditionalvideos waitingroom add <targets>
/conditionalvideos waitingroom remove <targets>

🗂️ Configuration

Each condition is a file:

config/conditionalvideos/
├─ conditions/          singleplayer and LAN host
│  ├─ firstJoin.json
│  ├─ entityKilled/minecraft/warden.json
│  ├─ advancementCompleted/minecraft/story/mine_diamond.json
│  ├─ scoreboard/kills.json
│  └─ worldPosition/spawn_area.json
└─ server-conditions/   dedicated server, same layout

Changes apply right away, also for connected players. The mod adds any missing option with its default at the top of the file and never changes what you wrote. A broken file is left untouched and reported in the log and in the chat. Configs from older versions migrate on the first launch and the originals stay as .bak.

{
  "repeatableInSameSession": false,
  "videos": [
    {
      "source": "videos/intro.mp4",
      "videoTitle": "&6&lWelcome",
      "videoVolume": 0.8,
      "nextAt": 8.0
    },
    {
      "source": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "transition": "fadeOut/In"
    }
  ]
}

Condition options

| Option | Default | Description |
|—|—|—|
| videos | [] | The videos, played in order. |
| repeatableInSameSession | false on firstJoin, true on the rest | false plays once per player and world. |
| playlistLoop | false | Restarts the playlist when it ends. |
| conditionDelay | 0.0 | Seconds to wait before playing. |
| replayOnReconnect | false | Plays an interrupted video again from the start on reconnect. |
| disableLoadingScreen | false | The first video gets ready in the background and appears once it has a picture. |
| protectPlayer | true | No damage, hunger, pickups or pushing during the video. |
| freezeWorld | true on firstJoin, false on the rest | The world stops while every connected player is watching. |
| excludePlayers, excludeTeams | [] | Players and teams that never see this condition. |
| excludeOps | false | Operators never see this condition. |

scoreboard adds value (default 0) and comparator: equal, less, greater, lessOrEqual or greaterOrEqual (default). It fires when the comparison becomes true.

worldPosition adds the area. Without y it covers any height, and trigger is enter or exit:

{
  "dimension": "minecraft:overworld",
  "from": { "x": -20, "z": -20 },
  "to": { "x": 20, "z": 20 },
  "trigger": "enter",
  "videos": [ { "source": "videos/zone.mp4" } ]
}

Video options

| Option | Default | Description |
|—|—|—|
| source | Required | Local path (relative to the game folder or absolute) or URL. |
| skippable | true | Whether the player can skip it. |
| videoLoop | false | Loops until skipped. Forces skippable. |
| enableBackground | true | Draws a solid color behind the video. |
| colorBackground | #000000 | #RRGGBB or #AARRGGBB. |
| videoTitle, videoDescription | Empty | Text with color codes (&6, &l). \n breaks the line. |
| videoTitlePosition, videoDescriptionPosition | bottomLeft | topLeft, topRight, bottomLeft, bottomRight, center or X/Y in pixels. Negative values measure from the right and bottom. |
| videoTitleAlignment, videoDescriptionAlignment | left | left, center or right. |
| titleTextScale, descriptionTextScale | 1.0 | Text size. |
| textBoxOpacity | Automatic | 0.0–1.0, opacity of the box behind the text. |
| videoVolume | defaultVolume | 0.0–1.0. |
| transition | cut | How it enters from the previous video: cut or fadeOut/In. |
| startAt | 0.0 | Second where it starts. |
| nextAt | Video end | Second where it moves on to the next video. |

Waiting room

It is the waitingRoom block in firstJoin.json. Players wait covered by the background until the room is ready, then watch together. A singleplayer or LAN host doesn’t enter unless they use waitingroom join.

| Option | Default | Description |
|—|—|—|
| enabled | false | Turns the room on. |
| requiredPlayers | 0 | Players needed. 0 means the server’s maximum. |
| requiredPlayerNames, requiredTeams | [] | If set, only these players enter and count. |
| startMode | auto | auto starts by itself. op waits for an operator, who can also press Space. |
| allowLeave | false | Lets players leave with the skip key. |
| allowChat | false | Lets players chat. Operators always can. |
| background | #000000 | #RRGGBB, or the path or URL of an image or GIF. |
| title, description, counter | Only counter is set | Room texts. They accept %current_players%, %required_players% and %missing_players%. |
| titlePosition, titleAlignment, titleScale | center, center, 1.0 | Same for description and counter. |

Common options

config/conditionalvideos-common.json:

| Option | Default | Description |
|—|—|—|
| videoQuality | AUTO | Or LOWEST, LOWER, LOW, LOWISH, MEDIUM, HIGH, HIGHER, HIGHEST, ULTRA_8K. |
| defaultVolume | 1.0 | Volume of videos without their own. |
| videoLoadTimeoutSeconds | 180 | How long to wait for a video to start. Minimum 30. |
| alwaysShowCursor | false | Never hides the cursor during a video. |
| allowGameSounds | false | Keeps other sounds playing during videos. |
| blockMatureContent | true | Blocks mature sources. Each player’s own choice. |
| debugLogging | false | Detailed log, for troubleshooting. Each installation’s own choice. |

On a server, it sets the first five for its players.

🎮 Skipping videos

The skip key is ESC until you bind Skip video in Options → Controls.

• Tap to skip to the next video.
• Hold until the bar fills, then release to skip the whole playlist.

🌍 Languages and API

Available in English and Spanish (es_es, es_ar, es_mx). Other mods can add custom conditions and control playback through the API in org.mateof24.conditionalvideos.api.

📜 License

ConditionalVideos License: free for any server and any free modpack. Charging for anything that uses the mod requires permission.