v0.4.17: music_quiz datapack handshake (server + per-player presence)

Implements docs/mc_video_player_mod_integration.md.

Server (MusicQuizPresence):
- every server tick: #server mq_video_mod = 1
- on MqHelloPayload receive: <player> mq_video_mod = 1
- both silently skip if objective absent (datapack not yet loaded)

Client (MusicQuizClient):
- send MqHelloPayload(1) on JOIN
- resend every 100 client ticks (~5 s) — mandatory because the datapack's
  mq:players/login resets per-player score to 0 at spawn-dialog passage

Payload: video_player:mq_hello, single VAR_INT body (version=1).

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.4.15
+mod_version=0.4.17
 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;
@@ -28,6 +29,7 @@ public class VideoPlayerClient implements ClientModInitializer {
     @Override
     public void onInitializeClient() {
         ClientNetworking.register();
+        MusicQuizClient.register();
 
         BlockEntityRendererRegistry.register(
             VideoPlayerBlockEntities.VIDEO_ANCHOR,

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

@@ -299,10 +299,12 @@ public final class VideoPlayerConfig {
             JsonObject root = new JsonObject();
             root.addProperty("_comment",
                 "max_preload_mb: per-video download cap (each client). "
+                    + "max_cache_mb: total cache directory cap (each client). "
                     + "render_distance_blocks: max distance at which a video anchor still renders. "
                     + "preload_urls: legacy un-named auto-preload list. "
                     + "cache_entries: managed by /videoCache add|list|remove.");
             root.addProperty("max_preload_mb", maxPreloadMb);
+            root.addProperty("max_cache_mb", maxCacheMb);
             root.addProperty("render_distance_blocks", renderDistanceBlocks);
             JsonArray legacyArr = new JsonArray();
             for (String u : preloadUrls) legacyArr.add(u);

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/net/ClientNetworking.java

@@ -6,6 +6,7 @@ import com.ejclaw.videoplayer.client.gui.VideoConfigScreen;
 import com.ejclaw.videoplayer.client.playback.VideoCache;
 import com.ejclaw.videoplayer.client.playback.VideoPlayback;
 import com.ejclaw.videoplayer.net.CachePolicyPayload;
+import com.ejclaw.videoplayer.net.ClearCachePayload;
 import com.ejclaw.videoplayer.net.DeleteCachePayload;
 import com.ejclaw.videoplayer.net.OpenScreenPayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
@@ -57,5 +58,10 @@ public final class ClientNetworking {
         ClientPlayNetworking.registerGlobalReceiver(DeleteCachePayload.TYPE, (payload, context) -> {
             VideoCache.purge(payload.url());
         });
+
+        // /videoCache clear — wipe the entire client cache directory.
+        ClientPlayNetworking.registerGlobalReceiver(ClearCachePayload.TYPE, (payload, context) -> {
+            VideoCache.clearAll();
+        });
     }
 }

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

@@ -20,6 +20,8 @@ import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
 
 /**
  * Client-side disk cache for preloaded HTTP video URLs. Driven by the {@code /videopreload}
@@ -38,9 +40,23 @@ public final class VideoCache {
 
     /** url → local absolute path of the fully-downloaded cache file. */
     private static final Map<String, Path> READY = new ConcurrentHashMap<>();
-    /** urls whose download is currently in flight. */
+    /** urls whose download is currently queued or in flight. */
     private static final Set<String> IN_FLIGHT = ConcurrentHashMap.newKeySet();
 
+    /**
+     * Single-thread executor that serializes all downloads. Cap enforcement (the total
+     * cache size check) needs an authoritative view of the cache directory at the moment a
+     * download starts, so we run one download at a time — that way the directory scan in
+     * {@link #cacheDirSize} reflects every finished download up to this point. Parallel
+     * downloads were racing the cap by each reading the directory before any of them had
+     * renamed their .part to final.
+     */
+    private static final ExecutorService DOWNLOAD_POOL = Executors.newSingleThreadExecutor(r -> {
+        Thread t = new Thread(r, "video_player-preload");
+        t.setDaemon(true);
+        return t;
+    });
+
     /**
      * Hard ceiling on a single preload, in bytes. Default 2 GB sized to allow a single 4K
      * short clip; overridden per-session by {@link com.ejclaw.videoplayer.net.CachePolicyPayload}
@@ -103,6 +119,41 @@ 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
+     * 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.
+     */
+    public static void clearAll() {
+        int deleted = 0;
+        int failed  = 0;
+        try {
+            Path dir = cacheDir();
+            if (dir != null && Files.isDirectory(dir)) {
+                try (var stream = Files.newDirectoryStream(dir)) {
+                    for (Path p : stream) {
+                        try {
+                            if (Files.isRegularFile(p) && Files.deleteIfExists(p)) deleted++;
+                        } catch (Throwable t) {
+                            failed++;
+                            VideoPlayerMod.LOG.warn("[{}] clearAll: could not delete {}: {}",
+                                VideoPlayerMod.MOD_ID, p.getFileName(), t.toString());
+                        }
+                    }
+                }
+            }
+        } catch (Throwable t) {
+            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);
+    }
+
     /** Kick off a background download. No-op if already cached or in flight. */
     public static void preload(String url) {
         if (url == null || url.isEmpty()) return;
@@ -117,10 +168,8 @@ public final class VideoCache {
             notifyChat("[videopreload] 이미 다운로드 중: " + url, ChatFormatting.GRAY);
             return;
         }
-        notifyChat("[videopreload] 다운로드 시작: " + url, ChatFormatting.YELLOW);
-        Thread t = new Thread(() -> download(url), "video_player-preload");
-        t.setDaemon(true);
-        t.start();
+        notifyChat("[videopreload] 다운로드 대기열 추가: " + url, ChatFormatting.YELLOW);
+        DOWNLOAD_POOL.submit(() -> download(url));
     }
 
     /** Return the local cached file path for this URL, or {@code null} if not yet ready. */

src/main/java/com/ejclaw/videoplayer/command/VideoCacheCommand.java

@@ -1,6 +1,7 @@
 package com.ejclaw.videoplayer.command;
 
 import com.ejclaw.videoplayer.VideoPlayerConfig;
+import com.ejclaw.videoplayer.net.ClearCachePayload;
 import com.ejclaw.videoplayer.net.DeleteCachePayload;
 import com.ejclaw.videoplayer.net.PreloadPayload;
 import com.mojang.brigadier.CommandDispatcher;
@@ -127,26 +128,26 @@ public final class VideoCacheCommand {
 
     private static int runClear(CommandContext<CommandSourceStack> ctx) {
         CommandSourceStack src = ctx.getSource();
+        // Drop server-side named entries (preload_urls is left alone — it's an admin-edited
+        // list, not something /videoCache manages).
         java.util.List<String> urls = VideoPlayerConfig.clearCacheEntries();
-        if (urls.isEmpty()) {
-            src.sendSuccess(() -> Component.literal("[videocache] 저장된 항목이 없습니다")
-                .withStyle(ChatFormatting.GRAY), false);
-            return 0;
-        }
+
+        // Always broadcast a full-cache wipe to every client, even if the named index was
+        // empty — leftover files from prior sessions, legacy preload_urls downloads, and
+        // any in-flight stragglers all get scrubbed in one shot.
         MinecraftServer server = src.getServer();
+        ClearCachePayload payload = new ClearCachePayload();
         int clients = 0;
         for (ServerPlayer p : PlayerLookup.all(server)) {
-            for (String url : urls) {
-                ServerPlayNetworking.send(p, new DeleteCachePayload(url));
-            }
+            ServerPlayNetworking.send(p, payload);
             clients++;
         }
         final int sentFinal = clients;
         final int countFinal = urls.size();
         src.sendSuccess(() -> Component.literal(
-            "[videocache] 전체 삭제: " + countFinal + "개 항목"
-                + "  (" + sentFinal + " 클라이언트에 cache_delete 전송)"), false);
-        return countFinal;
+            "[videocache] 전체 삭제: 등록 항목 " + countFinal + "개 제거"
+                + " + " + sentFinal + " 클라이언트 디스크 캐시 전체 wipe"), false);
+        return Math.max(countFinal, 1);
     }
 
     private static int runRemove(CommandContext<CommandSourceStack> ctx) throws CommandSyntaxException {

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

@@ -0,0 +1,26 @@
+package com.ejclaw.videoplayer.net;
+
+import com.ejclaw.videoplayer.VideoPlayerMod;
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.Identifier;
+
+/**
+ * S2C — tell every client to wipe its entire {@code video_player_cache} directory and reset
+ * the in-memory READY/IN_FLIGHT index. Sent by {@code /videoCache clear}. Carries no payload —
+ * the receiving client just nukes everything under the cache dir regardless of how the file
+ * got there (named entry, legacy preload_url, or leftover from a prior session).
+ */
+public record ClearCachePayload() implements CustomPacketPayload {
+    public static final CustomPacketPayload.Type<ClearCachePayload> TYPE =
+        new CustomPacketPayload.Type<>(Identifier.fromNamespaceAndPath(VideoPlayerMod.MOD_ID, "cache_clear"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, ClearCachePayload> CODEC =
+        StreamCodec.unit(new ClearCachePayload());
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+}

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

@@ -28,9 +28,11 @@ public final class VideoPlayerNetwork {
         PayloadTypeRegistry.clientboundPlay().register(PreloadPayload.TYPE, PreloadPayload.CODEC);
         PayloadTypeRegistry.clientboundPlay().register(CachePolicyPayload.TYPE, CachePolicyPayload.CODEC);
         PayloadTypeRegistry.clientboundPlay().register(DeleteCachePayload.TYPE, DeleteCachePayload.CODEC);
+        PayloadTypeRegistry.clientboundPlay().register(ClearCachePayload.TYPE, ClearCachePayload.CODEC);
         // 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);
+    }
+}