v0.4.23: fix wall z-fight and texture discard at distance

Reported: with render_distance_blocks=256, the panel started shimmering
and the wall texture bled through at ~30 blocks away. Both issues are
inherent distance-rendering bugs that were previously hidden by the
default ~64-block view distance.

Two fixes in VideoAnchorRenderer:
1. SURFACE_EPSILON 0.001 → 0.02. With 24-bit depth and near=0.05, the
   smallest resolvable depth step at 30 blocks is ~1mm, so the old 1mm
   offset was right at the z-fight boundary. 2cm gives ~20× margin at
   30 blocks and remains visually unnoticeable up close.
2. RenderType entityCutout → entitySolid. swscale outputs RGBA with
   alpha=255, so there is no real cutout. Cutout's alpha-discard step
   makes distant sampling unstable on a dynamic non-mipmapped texture;
   solid removes that and is the semantically correct type.

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.4.16
+mod_version=0.4.23
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player
 

src/main/java/com/ejclaw/videoplayer/VideoPlayerClient.java

@@ -1,6 +1,7 @@
 package com.ejclaw.videoplayer;
 
 import com.ejclaw.videoplayer.block.VideoAnchorBlockEntity;
+import com.ejclaw.videoplayer.client.MusicQuizClient;
 import com.ejclaw.videoplayer.client.net.ClientNetworking;
 import com.ejclaw.videoplayer.client.playback.VideoPlayback;
 import com.ejclaw.videoplayer.client.render.VideoAnchorRenderer;
@@ -19,6 +20,7 @@ import net.fabricmc.fabric.api.event.player.AttackBlockCallback;
 import net.minecraft.client.Minecraft;
 import net.minecraft.client.player.LocalPlayer;
 import net.minecraft.core.BlockPos;
+import net.minecraft.sounds.SoundSource;
 import net.minecraft.world.InteractionResult;
 import net.minecraft.world.phys.Vec3;
 
@@ -28,6 +30,7 @@ public class VideoPlayerClient implements ClientModInitializer {
     @Override
     public void onInitializeClient() {
         ClientNetworking.register();
+        MusicQuizClient.register();
 
         BlockEntityRendererRegistry.register(
             VideoPlayerBlockEntities.VIDEO_ANCHOR,
@@ -87,17 +90,26 @@ public class VideoPlayerClient implements ClientModInitializer {
      * Distance is measured from the player's eye to the <em>panel center</em>, not the anchor
      * block corner — for a 4×4 panel the corner is ~2 blocks off from where the screen visually
      * sits, which made the audio feel like it was off to the side.
+     *
+     * <p>Gain is also gated by the Minecraft sound options so the in-game sliders work as
+     * expected: vanilla {@code SoundEngine.calculateVolume} multiplies by master × category, so
+     * we do the same with {@link SoundSource#PLAYERS} as the category. Result: dragging the
+     * "Players" slider in Options → Music & Sounds attenuates video audio just like other
+     * player sounds, and "Master" still gates everything.
      */
     private static void updateDistanceGains(Minecraft client) {
         LocalPlayer p = client.player;
         if (p == null || client.level == null) return;
         Vec3 eye = p.getEyePosition();
+        float masterVol = client.options.getSoundSourceVolume(SoundSource.MASTER);
+        float playersVol = client.options.getSoundSourceVolume(SoundSource.PLAYERS);
+        float categoryScale = masterVol * playersVol;
         for (BlockPos pos : VideoPlayback.activePositions()) {
             if (!(client.level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity be)) continue;
             Vec3 center = be.panelCenter();
             double d = center.distanceTo(eye);
             float attenuation = (float) Math.max(0.0, Math.min(1.0, 1.0 - d / 16.0));
-            float gain = be.isMuted() ? 0F : be.getVolume() * attenuation;
+            float gain = be.isMuted() ? 0F : be.getVolume() * attenuation * categoryScale;
             VideoPlayback.setGain(pos, gain);
         }
     }

src/main/java/com/ejclaw/videoplayer/VideoPlayerMod.java

@@ -8,6 +8,7 @@ import com.ejclaw.videoplayer.command.VideoStickCommand;
 import com.ejclaw.videoplayer.net.CachePolicyPayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
 import com.ejclaw.videoplayer.net.VideoPlayerNetwork;
+import com.ejclaw.videoplayer.server.MusicQuizPresence;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlockEntities;
 import com.ejclaw.videoplayer.registry.VideoPlayerBlocks;
 import com.ejclaw.videoplayer.registry.VideoPlayerItems;
@@ -30,6 +31,7 @@ public class VideoPlayerMod implements ModInitializer {
 
         VideoPlayerNetwork.registerPayloadTypes();
         VideoPlayerNetwork.registerServerReceivers();
+        MusicQuizPresence.register();
 
         VideoPlayerConfig.load();
 

src/main/java/com/ejclaw/videoplayer/client/MusicQuizClient.java

@@ -0,0 +1,56 @@
+package com.ejclaw.videoplayer.client;
+
+import com.ejclaw.videoplayer.net.MqHelloPayload;
+import net.fabricmc.api.EnvType;
+import net.fabricmc.api.Environment;
+import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayConnectionEvents;
+import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
+
+/**
+ * Client side of the {@code music_quiz} datapack handshake
+ * ({@code docs/mc_video_player_mod_integration.md}). Sends one {@link MqHelloPayload}
+ * on JOIN, then repeats every 100 client ticks (~5 s at 20 tps).
+ *
+ * <p>The periodic resend is <em>mandatory</em>: the datapack's
+ * {@code mq:players/login} resets the per-player score to 0 the moment the player
+ * passes the spawn dialog. The single JOIN-time send can land before that reset,
+ * leaving the score at 0 and breaking the {@code mq:commands/start} guard. With a
+ * 5-second resend, the score is restored to 1 within at most one cycle.
+ */
+@Environment(EnvType.CLIENT)
+public final class MusicQuizClient {
+    private MusicQuizClient() {}
+
+    /** ~5 s at 20 tps. Spec recommends ≤5 s; tighter is fine but unnecessary. */
+    private static final int RESEND_INTERVAL_TICKS = 100;
+
+    private static int tickCounter = 0;
+
+    public static void register() {
+        ClientPlayConnectionEvents.JOIN.register((handler, sender, client) ->
+            send());
+
+        ClientTickEvents.END_CLIENT_TICK.register(client -> {
+            // Gate on world presence — when the player isn't in-game, level is null and the
+            // counter resets so the next session starts fresh instead of firing immediately.
+            if (client.level == null) {
+                tickCounter = 0;
+                return;
+            }
+            tickCounter++;
+            if (tickCounter >= RESEND_INTERVAL_TICKS) {
+                tickCounter = 0;
+                send();
+            }
+        });
+    }
+
+    private static void send() {
+        // ClientPlayNetworking.send no-ops when the server hasn't registered the payload
+        // type (e.g. vanilla server or server without this mod) — safe to call blindly.
+        if (ClientPlayNetworking.canSend(MqHelloPayload.TYPE)) {
+            ClientPlayNetworking.send(new MqHelloPayload(MqHelloPayload.CURRENT_VERSION));
+        }
+    }
+}

src/main/java/com/ejclaw/videoplayer/client/playback/VideoCache.java

@@ -22,6 +22,7 @@ import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicLong;
 
 /**
  * Client-side disk cache for preloaded HTTP video URLs. Driven by the {@code /videopreload}
@@ -42,6 +43,14 @@ public final class VideoCache {
     private static final Map<String, Path> READY = new ConcurrentHashMap<>();
     /** urls whose download is currently queued or in flight. */
     private static final Set<String> IN_FLIGHT = ConcurrentHashMap.newKeySet();
+    /**
+     * Monotonic cache-generation counter. {@link #clearAll()} bumps this; every download
+     * captures the value at submit time and bails (deletes its {@code .part} without
+     * publishing) if the epoch has moved since. This is the cancellation channel for the
+     * in-flight download — without it, {@code clearAll} only wipes already-finalized files
+     * while the running download keeps writing and re-publishes one entry post-clear.
+     */
+    private static final AtomicLong CACHE_EPOCH = new AtomicLong(0);
 
     /**
      * Single-thread executor that serializes all downloads. Cap enforcement (the total
@@ -121,11 +130,36 @@ public final class VideoCache {
 
     /**
      * Wipe the entire cache directory and drop both indexes. Sent in response to
-     * {@code /videoCache clear}. Best-effort per-file deletion; logs failures but doesn't
+     * {@code /videoCache clear}.
-     * abort on the first one. In-flight downloads aren't cancelled — they'll fail at the
+     *
-     * atomic-move step (target dir gone) and log a warning, which is fine.
+     * <p>Three phases that need to stay in this order:
+     * <ol>
+     *   <li>Bump the epoch first — that flips the cancellation flag for any in-flight
+     *       download. The download thread checks the epoch in the read loop and at the
+     *       move step, so after this point it will refuse to publish a new entry and
+     *       will delete its own {@code .part}.</li>
+     *   <li>Clear the in-memory indexes. (READY clears whatever was already finalized
+     *       pre-clear; IN_FLIGHT is wiped so a subsequent same-URL preload re-enters
+     *       the queue instead of getting deduped by stale state.)</li>
+     *   <li>Best-effort delete every regular file in the cache directory. We do this
+     *       last so that if the in-flight download was momentarily holding a {@code .part}
+     *       open, the listing here also catches its post-close residue (though normally
+     *       phase 1 → the download deletes its own part).</li>
+     * </ol>
+     *
+     * <p>Best-effort per-file deletion; logs failures but doesn't abort on the first one.
+     * On Windows the open {@code .part} may not be deletable here — phase 1's cancellation
+     * + the download's own cleanup-on-bail handles that case.
      */
     public static void clearAll() {
+        // Phase 1: signal cancellation to any in-flight download BEFORE wiping disk.
+        CACHE_EPOCH.incrementAndGet();
+
+        // Phase 2: drop indexes.
+        READY.clear();
+        IN_FLIGHT.clear();
+
+        // Phase 3: delete files on disk.
         int deleted = 0;
         int failed  = 0;
         try {
@@ -147,8 +181,6 @@ public final class VideoCache {
             VideoPlayerMod.LOG.warn("[{}] clearAll failed: {}",
                 VideoPlayerMod.MOD_ID, t.toString());
         }
-        READY.clear();
-        IN_FLIGHT.clear();
         VideoPlayerMod.LOG.info("[{}] clearAll: deleted={} failed={}",
             VideoPlayerMod.MOD_ID, deleted, failed);
         notifyChat("[videocache] 전체 캐시 삭제: " + deleted + "개 파일", ChatFormatting.YELLOW);
@@ -158,7 +190,11 @@ public final class VideoCache {
     public static void preload(String url) {
         if (url == null || url.isEmpty()) return;
         if (!(url.startsWith("http://") || url.startsWith("https://"))) return;
-        if (READY.containsKey(url)) {
+        // Use lookup() (which also verifies the file exists on disk) instead of
+        // READY.containsKey — defends against READY containing a stale entry whose
+        // backing file was removed by clearAll() / a user-side file delete. Without this,
+        // a stale key would silently block a re-preload.
+        if (lookup(url) != null) {
             VideoPlayerMod.LOG.info("[{}] preload: already cached {}", VideoPlayerMod.MOD_ID, url);
             notifyChat("[videopreload] 이미 캐시됨: " + url, ChatFormatting.GRAY);
             return;
@@ -169,7 +205,11 @@ public final class VideoCache {
             return;
         }
         notifyChat("[videopreload] 다운로드 대기열 추가: " + url, ChatFormatting.YELLOW);
-        DOWNLOAD_POOL.submit(() -> download(url));
+        // Capture the current epoch at submit time. The download thread checks against
+        // CACHE_EPOCH later — any mismatch means clearAll() ran in between and this
+        // download must abort without publishing.
+        long epoch = CACHE_EPOCH.get();
+        DOWNLOAD_POOL.submit(() -> download(url, epoch));
     }
 
     /** Return the local cached file path for this URL, or {@code null} if not yet ready. */
@@ -193,25 +233,64 @@ public final class VideoCache {
 
     // -- internals -----------------------------------------------------------------------
 
-    private static void download(String url) {
+    /**
+     * Publish {@code path} into {@link #READY} for {@code url}, but only if the cache
+     * epoch hasn't moved since {@code startEpoch} was captured. Wraps the
+     * pre-check / put / post-check / rollback dance so every publish site uses the
+     * same race-free pattern instead of re-implementing it.
+     *
+     * <p>Race coverage: if {@link #clearAll()} runs at any point between the
+     * pre-check and the post-check, the post-check sees the epoch bump and we
+     * roll back — {@link Map#remove(Object, Object)} is a compareAndRemove so we
+     * don't clobber a legitimate concurrent put under the same key, and we delete
+     * the on-disk file because clearAll's directory scan may have missed it (the
+     * file may not have existed yet when clearAll ran).
+     *
+     * @return {@code true} if the entry is now published; {@code false} if the
+     *         caller's work was cancelled and {@code path} has been cleaned up.
+     */
+    private static boolean publishIfNotCancelled(String url, Path path, long startEpoch) {
+        if (CACHE_EPOCH.get() != startEpoch) return false;
+        READY.put(url, path);
+        if (CACHE_EPOCH.get() != startEpoch) {
+            READY.remove(url, path);
+            try { Files.deleteIfExists(path); } catch (Throwable ignored) {}
+            return false;
+        }
+        return true;
+    }
+
+    private static void download(String url, long startEpoch) {
         Path cacheDir = cacheDir();
+        Path partPath = null;
         try {
             if (cacheDir == null) {
                 VideoPlayerMod.LOG.warn("[{}] preload: no game dir, skipping {}",
                     VideoPlayerMod.MOD_ID, url);
                 return;
             }
+            // Pre-flight cancellation check — if clearAll already ran between submit and now,
+            // skip the whole thing. Avoids creating directories / .part files post-clear.
+            if (CACHE_EPOCH.get() != startEpoch) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before start (clearAll ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                return;
+            }
             Files.createDirectories(cacheDir);
 
             String hash = sha256(url);
             String ext  = extensionFromUrl(url);
             Path finalPath = cacheDir.resolve(hash + ext);
-            Path partPath  = cacheDir.resolve(hash + ext + ".part");
+            partPath  = cacheDir.resolve(hash + ext + ".part");
 
             // Resume-friendly: if the file's already on disk from an earlier session, just
             // index it without re-downloading.
             if (Files.exists(finalPath) && Files.size(finalPath) > 0) {
-                READY.put(url, finalPath);
+                if (!publishIfNotCancelled(url, finalPath, startEpoch)) {
+                    VideoPlayerMod.LOG.info("[{}] preload: reindex cancelled (clearAll ran) — {}",
+                        VideoPlayerMod.MOD_ID, url);
+                    return;
+                }
                 VideoPlayerMod.LOG.info("[{}] preload: indexed existing cache {} -> {}",
                     VideoPlayerMod.MOD_ID, url, finalPath.getFileName());
                 notifyChat("[videopreload] 기존 캐시 사용: " + url, ChatFormatting.GREEN);
@@ -250,21 +329,30 @@ public final class VideoCache {
             }
 
             long total = 0;
+            boolean cancelled = false;
             try (InputStream in = raw.getInputStream();
                  OutputStream out = Files.newOutputStream(partPath)) {
                 byte[] buf = new byte[64 * 1024];
                 int n;
                 while ((n = in.read(buf)) >= 0) {
+                    // Cancellation check inside the loop. Break (not return) so the try-with
+                    // closes the output stream first — on Windows, deleting an open .part can
+                    // fail with AccessDeniedException, so we always close before deleting.
+                    if (CACHE_EPOCH.get() != startEpoch) {
+                        cancelled = true;
+                        break;
+                    }
                     total += n;
                     if (total > MAX_BYTES) {
                         long capMb = MAX_BYTES / (1024 * 1024);
                         VideoPlayerMod.LOG.warn(
                             "[{}] preload: {} exceeded per-video {} MB cap; aborting",
                             VideoPlayerMod.MOD_ID, url, capMb);
-                        try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                        // Same close-before-delete dance for Windows.
+                        cancelled = true;
                         notifyChat("[videopreload] 실패 (단일 영상 " + capMb + "MB 초과): " + url,
                             ChatFormatting.RED);
-                        return;
+                        break;
                     }
                     if (existingCacheBytes + total > MAX_CACHE_BYTES) {
                         long capMb = MAX_CACHE_BYTES / (1024 * 1024);
@@ -272,18 +360,42 @@ public final class VideoCache {
                         VideoPlayerMod.LOG.warn(
                             "[{}] preload: total-cache cap exceeded ({}>{} MB); aborting {}",
                             VideoPlayerMod.MOD_ID, usedMb, capMb, url);
-                        try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                        cancelled = true;
                         notifyChat("[videopreload] 실패 (전체 캐시 " + capMb + "MB 초과): " + url,
                             ChatFormatting.RED);
-                        return;
+                        break;
                     }
                     out.write(buf, 0, n);
                 }
             }
+            // Now the .part file is closed — safe to delete on Windows.
+            if (cancelled) {
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                return;
+            }
+
+            // Pre-move cancellation check. If clearAll ran during the read loop, abort
+            // before promoting .part to final — saves a wasted move + delete.
+            if (CACHE_EPOCH.get() != startEpoch) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled before move (clearAll ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+                return;
+            }
 
             Files.move(partPath, finalPath, StandardCopyOption.REPLACE_EXISTING,
                 StandardCopyOption.ATOMIC_MOVE);
-            READY.put(url, finalPath);
+
+            // Race-safe publish: this covers the window between Files.move and READY.put
+            // (clearAll deletes the freshly-moved file then we resurrect it in READY) AND
+            // the window between READY.put and the "완료" notification (clearAll wipes
+            // READY then we re-publish + emit stale completion chat). publishIfNotCancelled
+            // rolls back both READY and the on-disk file if the epoch moved at any time.
+            if (!publishIfNotCancelled(url, finalPath, startEpoch)) {
+                VideoPlayerMod.LOG.info("[{}] preload: cancelled at publish (clearAll ran) — {}",
+                    VideoPlayerMod.MOD_ID, url);
+                return;
+            }
             VideoPlayerMod.LOG.info("[{}] preload: cached {} ({} bytes) -> {}",
                 VideoPlayerMod.MOD_ID, url, total, finalPath.getFileName());
             long mb = Math.max(1, total / (1024 * 1024));
@@ -293,6 +405,10 @@ public final class VideoCache {
                 VideoPlayerMod.MOD_ID, url, t.toString());
             notifyChat("[videopreload] 실패 (" + t.getClass().getSimpleName() + "): " + url,
                 ChatFormatting.RED);
+            // Best-effort cleanup of any leftover .part on the error path.
+            if (partPath != null) {
+                try { Files.deleteIfExists(partPath); } catch (Throwable ignored) {}
+            }
         } finally {
             IN_FLIGHT.remove(url);
         }

src/main/java/com/ejclaw/videoplayer/client/render/VideoAnchorRenderer.java

@@ -31,8 +31,19 @@ import org.joml.Matrix4f;
 @Environment(EnvType.CLIENT)
 public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlockEntity, VideoAnchorRenderer.State> {
 
-    /** Tiny outward offset so the quad doesn't z-fight with the wall. */
+    /**
-    private static final float SURFACE_EPSILON = 0.001F;
+     * Outward offset so the quad doesn't z-fight with the wall it sits on.
+     *
+     * <p>Depth-buffer precision drops with the square of view distance: with near=0.05 and
+     * 24-bit depth, the smallest resolvable step at 30 blocks is ~1mm, and ~12mm at 100
+     * blocks. The old 0.001 (1mm) offset was right at the precision boundary at ~30 blocks
+     * — which is exactly the distance users started seeing the wall texture flicker through
+     * the video panel once {@code render_distance_blocks} was raised past the default.
+     *
+     * <p>2cm gives ~20× margin at 30 blocks and is still visually unnoticeable up close
+     * (~3% of a block thickness).
+     */
+    private static final float SURFACE_EPSILON = 0.02F;
 
     public VideoAnchorRenderer(BlockEntityRendererProvider.Context ctx) {
         // no-op
@@ -75,7 +86,12 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         pose.translate(-0.5F, -0.5F, -0.5F + SURFACE_EPSILON);
 
         final Matrix4f mat = new Matrix4f(pose.last().pose());
-        RenderType rt = RenderTypes.entityCutout(tex);
+        // entitySolid (not entityCutout): video frames come from swscale → AV_PIX_FMT_RGBA with
+        // alpha hard-set to 255, so there is no alpha-tested cutout. Cutout's alpha-discard step
+        // adds nothing here and makes distant sampling unstable — without mipmaps on a dynamic
+        // texture, neighbouring texels can shimmer above/below the discard threshold at sub-pixel
+        // sampling rates, contributing to the flicker users see once render distance is raised.
+        RenderType rt = RenderTypes.entitySolid(tex);
         collector.submitCustomGeometry(pose, rt, (poseUnused, vc) -> {
             // Single-sided: the back of the anchor is by design pressed against the wall the
             // player clicked, so a back face is pure GPU waste. Halves the fragment shader work

src/main/java/com/ejclaw/videoplayer/net/MqHelloPayload.java

@@ -0,0 +1,35 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.Identifier;
+
+/**
+ * C2S — client-presence handshake for the {@code music_quiz} datapack
+ * ({@code docs/mc_video_player_mod_integration.md}). Each modded client sends one on JOIN
+ * and one every ~5 s thereafter. The server side flips the player's {@code mq_video_mod}
+ * scoreboard score to {@code 1}, which the datapack reads in its {@code mq:commands/start}
+ * guard.
+ *
+ * <p>Payload body is a single int (protocol version) so future schema bumps don't require
+ * a new packet id. v1 is the only version that exists today.
+ */
+public record MqHelloPayload(int version) implements CustomPacketPayload {
+    public static final int CURRENT_VERSION = 1;
+
+    public static final CustomPacketPayload.Type<MqHelloPayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "mq_hello"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, MqHelloPayload> CODEC = StreamCodec.composite(
+        ByteBufCodecs.VAR_INT, MqHelloPayload::version,
+        MqHelloPayload::new
+    );
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}

src/main/java/com/ejclaw/videoplayer/net/VideoPlayerNetwork.java

@@ -32,6 +32,7 @@ public final class VideoPlayerNetwork {
         // C2S
         PayloadTypeRegistry.serverboundPlay().register(SaveConfigPayload.TYPE, SaveConfigPayload.CODEC);
         PayloadTypeRegistry.serverboundPlay().register(DeleteAnchorPayload.TYPE, DeleteAnchorPayload.CODEC);
+        PayloadTypeRegistry.serverboundPlay().register(MqHelloPayload.TYPE, MqHelloPayload.CODEC);
     }
 
     public static void registerServerReceivers() {

src/main/java/com/ejclaw/videoplayer/server/MusicQuizPresence.java

@@ -0,0 +1,74 @@
+package com.ejclaw.videoplayer.server;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import com.ejclaw.videoplayer.net.MqHelloPayload;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerTickEvents;
+import net.fabricmc.fabric.api.networking.v1.ServerPlayNetworking;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerPlayer;
+import net.minecraft.world.scores.Objective;
+import net.minecraft.world.scores.ScoreHolder;
+import net.minecraft.world.scores.Scoreboard;
+
+/**
+ * Implements the server side of the {@code music_quiz} datapack handshake described in
+ * {@code docs/mc_video_player_mod_integration.md}.
+ *
+ * <p>Two scoreboard writes against objective {@code mq_video_mod} (dummy):
+ * <ul>
+ *   <li>Every server tick — {@code #server mq_video_mod = 1}. Proves the mod jar is on the
+ *       server side. The datapack's {@code mq:commands/start} guard checks this first.</li>
+ *   <li>Every received {@link MqHelloPayload} — {@code <player> mq_video_mod = 1}. Proves
+ *       the sending player's client has the mod installed. Per-player flag is needed
+ *       because rendering is client-side; the server can't tell from join state alone.</li>
+ * </ul>
+ *
+ * <p>The objective itself ({@code scoreboard objectives add mq_video_mod dummy}) is
+ * created by the datapack's {@code mq:load} function. If it isn't present yet (datapack
+ * not applied, or load hasn't run), the writes are silently skipped — when the datapack
+ * appears later, the next tick / next payload arrival populates it.
+ */
+public final class MusicQuizPresence {
+    private MusicQuizPresence() {}
+
+    /** Scoreboard objective name expected by the {@code music_quiz} datapack. */
+    private static final String OBJECTIVE = "mq_video_mod";
+    /** Fake holder used to mark "the server has the mod" (datapack reads {@code #server}). */
+    private static final String SERVER_HOLDER = "#server";
+
+    /** Call from {@code VideoPlayerMod.onInitialize} after payload types are registered. */
+    public static void register() {
+        // (a) per-tick server presence
+        ServerTickEvents.END_SERVER_TICK.register(MusicQuizPresence::onServerTick);
+
+        // (b) per-player client presence — flipped on every received Hello
+        ServerPlayNetworking.registerGlobalReceiver(MqHelloPayload.TYPE, (payload, context) -> {
+            ServerPlayer player = context.player();
+            MinecraftServer server = context.server();
+            // hop back onto the server thread before touching the scoreboard
+            server.execute(() -> markPlayerPresent(server, player));
+        });
+    }
+
+    private static void onServerTick(MinecraftServer server) {
+        Scoreboard sb = server.getScoreboard();
+        Objective obj = sb.getObjective(OBJECTIVE);
+        // Datapack not loaded yet — silently skip. The score holder doesn't exist until
+        // the objective does, and trying to write blind would just blow up.
+        if (obj == null) return;
+        sb.getOrCreatePlayerScore(ScoreHolder.forNameOnly(SERVER_HOLDER), obj).set(1);
+    }
+
+    private static void markPlayerPresent(MinecraftServer server, ServerPlayer player) {
+        Scoreboard sb = server.getScoreboard();
+        Objective obj = sb.getObjective(OBJECTIVE);
+        if (obj == null) {
+            VideoPlayerMod.LOG.debug("[{}] mq hello from {} but objective '{}' not present",
+                VideoPlayerMod.MOD_ID, player.getName().getString(), OBJECTIVE);
+            return;
+        }
+        // ServerPlayer itself implements ScoreHolder, so this matches selector @s on the
+        // datapack side without name-formatting quirks (uuid vs profile name).
+        sb.getOrCreatePlayerScore(player, obj).set(1);
+    }
+}