diff --git a/docs/mc_video_player_mod_integration.md b/docs/mc_video_player_mod_integration.md new file mode 100644 index 0000000..694081f --- /dev/null +++ b/docs/mc_video_player_mod_integration.md @@ -0,0 +1,184 @@ +# mc_video_player_mod — 음악퀴즈 데이터팩 연동 사양 + +음악퀴즈 데이터팩(`music_quiz`)이 영상재생 모드의 **서버 측 + 클라이언트 측** +설치 여부를 둘 다 검증할 수 있도록, 모드의 서버 컴포넌트가 두 가지 점수를 +갱신한다. + +| holder | 의미 | 갱신 주체 / 시점 | +|--------|------|------------------| +| `#server mq_video_mod` | 서버에 모드 jar 존재 | 서버 컴포넌트가 매 server tick 마다 1 | +| ` mq_video_mod` | 해당 플레이어 클라에 모드 존재 | 서버 컴포넌트가 client→server payload 수신 시 1 | + +둘 다 같은 objective `mq_video_mod` (dummy) 를 쓰고 holder 이름으로 의미를 +구분한다. 데이터팩 `mq:commands/start` 가드는 두 단계로 검사: +서버 부재 → 전원 안내 후 차단 / 일부 플레이어 클라 부재 → 본인 안내 + 차단. + +> 참고: 자매 모드 `mc_chat_answer_mod` 는 채팅 가로채기가 본질적으로 서버 +> 측 동작이라 `#server mq_chat_mod` 한 가지만 쓴다 (per-player handshake 무의미). +> 본 모드는 클라이언트가 직접 영상 렌더링하므로 per-player handshake 도 필요함. + +## 데이터팩 측이 이미 제공하는 것 + +`music_quiz/data/mq/function/load.mcfunction` + +``` +scoreboard objectives add mq_video_mod dummy +``` + +`music_quiz/data/mq/function/players/login.mcfunction` 에서 로그인 시 0 +으로 초기화 (handshake 없는 플레이어는 0 유지). + +``` +scoreboard players set @s mq_video_mod 0 +``` + +`mq:commands/start.mcfunction` 가드: + +```mcfunction +# 서버 부재 우선 차단 +execute unless score #server mq_video_mod matches 1 run return run function mq:tellraw {"text":"영상재생 모드가 서버에 미설치 — 서버 관리자에게 문의해주세요.","color":"red","msg":""} +# unset 매치 안 되므로 materialize +scoreboard players add @a mq_video_mod 0 +# 본인 안내 (tellraw @s 직접 — mq:tellraw 는 @a broadcast 라 부적합) +execute as @a[scores={mq_video_mod=..0}] run tellraw @s ["",{"text":"영상재생 모드 미설치 — 모드 적용 후 다시 입장해주세요.","color":"red"}] +# 한 명이라도 누락이면 시작 차단 +execute if entity @a[scores={mq_video_mod=..0}] run return run function mq:tellraw {"text":"필수 모드 미설치 플레이어가 있어 시작할 수 없습니다.","color":"red","msg":""} +``` + +`load.mcfunction` 에서 `#server mq_video_mod = 0` 으로 미리 깔아둠 → 서버 +컴포넌트가 한 tick 도 안 돌면 0 유지 → 가드 차단. + +즉, **서버 컴포넌트가 (a) 매 tick `#server mq_video_mod=1` 갱신, +(b) client payload 수신 시 송신 플레이어 점수=1 갱신**, 이 두 가지만 하면 +나머지는 데이터팩이 알아서 한다. + +## 모드가 구현해야 하는 동작 + +### 권장: 커스텀 payload handshake (Fabric Networking API / NeoForge Network) + +가장 깔끔하고 위변조 방어도 자연스러움. `/trigger` 방식보다 추천. + +#### Payload 정의 (공용) + +식별자: `mq_video_mod:hello` (또는 자체 modid 네임스페이스). +페이로드 본문은 비어도 되고, 버전 정수 한 개 정도면 충분. + +```java +public record HelloPayload(int version) implements CustomPacketPayload { + public static final CustomPacketPayload.Type TYPE = + new CustomPacketPayload.Type<>(ResourceLocation.fromNamespaceAndPath("mq_video_mod", "hello")); + public static final StreamCodec CODEC = + StreamCodec.composite(ByteBufCodecs.VAR_INT, HelloPayload::version, HelloPayload::new); + @Override public Type type() { return TYPE; } +} +``` + +#### 클라이언트 측 + +- payload 를 `PayloadTypeRegistry.playC2S()` 에 등록 (Fabric) / + `IPayloadRegistrar` 에 등록 (NeoForge). +- `ClientPlayConnectionEvents.JOIN` (Fabric) 또는 동등 NeoForge 이벤트에서 + 서버로 1회 전송 + **이후 5초마다 주기적으로 재전송 (필수)**. 데이터팩 + `mq:players/login` 이 spawn dialog 통과 시점에 점수를 0 으로 리셋하기 + 때문에, JOIN 시점의 1 회 전송만으로는 login 의 리셋이 뒤에 들어와 가드 + 통과가 실패한다. 주기 재전송으로 login 이후 늦어도 다음 5 초 안에 다시 + 1 로 복구되어야 정상 동작. + +```java +// JOIN 직후 1 회 +ClientPlayNetworking.send(new HelloPayload(1)); + +// + 주기 재전송 (필수). ClientTickEvents.END_CLIENT_TICK 등에서 카운터. +// 100 tick = 5 초 (client 20 tps). 너무 빈번해도 부담 없으니 1~5 초 +// 사이로 자유롭게. +``` + +#### 서버 측 (이 모드의 서버 컴포넌트) + +서버 컴포넌트는 **두 가지** 를 한다. + +(1) 매 server tick 마다 `#server mq_video_mod = 1` 갱신 (server presence). +점수 값이 변하지 않으면 packet 미전송이므로 매 tick 호출해도 비용 없음. + +```java +public static void onServerTick(MinecraftServer server) { + Scoreboard sb = server.getScoreboard(); + Objective obj = sb.getObjective("mq_video_mod"); + if (obj == null) return; // 데이터팩 미적용 or 아직 load 전 + sb.getOrCreatePlayerScore(ScoreHolder.forNameOnly("#server"), obj).set(1); +} +``` + +Fabric: `ServerTickEvents.END_SERVER_TICK.register(...)`. +NeoForge: `NeoForge.EVENT_BUS.addListener(ServerTickEvent.Post::...)`. + +(2) payload 등록 + 수신 시 송신 플레이어 점수 갱신 (client presence). +같은 payload 를 `PayloadTypeRegistry.playC2S()` 에 등록한 뒤: + +```java +ServerPlayNetworking.registerGlobalReceiver(HelloPayload.TYPE, (payload, context) -> { + ServerPlayer player = context.player(); + MinecraftServer server = player.getServer(); + if (server == null) return; + Scoreboard sb = server.getScoreboard(); + Objective obj = sb.getObjective("mq_video_mod"); + if (obj == null) return; // 데이터팩 미적용 or 아직 load 전 + // ServerPlayer 자체가 ScoreHolder — @s selector 와 정확히 매칭 + sb.getOrCreatePlayerScore(player, obj).set(1); +}); +``` + +> 참고 구현: `mc_chat_answer_mod` 의 `ChatAnswerCore::markModPresence` 가 +> 똑같이 `#server` holder 패턴을 쓴다 (단 그 쪽은 client payload 부분 없음). + +#### 타이밍 / 안전망 + +- 데이터팩 `mq:players/login` 이 spawn dialog 통과 시점에 점수를 0 으로 + 리셋하므로, **클라 payload 주기 재전송은 필수**. login 이후 다음 재전송 + 까지의 짧은 공백에 호스트가 start 를 누르면 가드가 차단되니, 재전송 + 간격은 5 초 이하 권장. +- 서버가 set 한 점수는 다음 join 시 login 에서 다시 0 으로 리셋됨 → 모드를 + 빼고 재접속한 플레이어가 stale 1 을 가질 일 없음. +- payload 송신 → 서버 처리는 ms 단위 → 주기 재전송이 살아 있는 한 start + 타이밍 race 없음. + +### 대안: `/trigger` 방식 (별도 서버 컴포넌트 불필요) + +데이터팩이 trigger objective 를 만들고 클라 모드가 `/trigger mq_video_mod set 1` +을 채팅 명령으로 전송하는 방식. 단점: +- 데이터팩에 `scoreboard objectives add mq_video_mod trigger` 와 매 join 시 + `scoreboard players enable @a mq_video_mod` 가 추가로 필요 (현재는 dummy). +- 클라 모드가 commands 권한으로 채팅 명령을 보내야 함. +- 명령어 packet 이 chat history 에 흔적이 남을 수 있음. + +커스텀 payload 가 추천이지만, 서버 컴포넌트를 추가하기 싫다면 이 경로도 +가능. 그 경우 데이터팩 측 변경이 필요하니 별도 요청해주세요. + +## 동작 흐름 (권장 경로) + +1. 서버 시작 → 데이터팩 load → `mq_video_mod` objective 생성. +2. 클라(모드 있음) 접속 → `ClientPlayConnectionEvents.JOIN` → payload 1 회 전송. +3. 서버 모드 수신 → 해당 플레이어 `mq_video_mod = 1`. +4. 플레이어 spawn dialog 통과 → `mq:players/login` 이 점수를 0 으로 리셋. +5. **클라 모드가 주기 재전송 (5 초 이하 권장, 필수)** → 늦어도 다음 주기에 + 서버 모드가 다시 `mq_video_mod = 1` 로 갱신. +6. 호스트 start → 가드가 `@a[scores={mq_video_mod=..0}]` 검사 → 클라 모드 + 미설치 플레이어 있으면 시작 차단. + +## 테스트 + +1. **서버 미설치**: 서버에 모드 jar 가 없는 상태에서 데이터팩만 적용 → + 호스트 start → "영상재생 모드가 서버에 미설치 — 서버 관리자에게..." 한 + 줄 출력 후 차단. (`#server mq_video_mod` 가 갱신되지 않음.) +2. **서버 설치 + 일부 클라 미설치**: 모드를 클라에 설치한 플레이어와 안 + 한 플레이어 혼재 → 호스트 start → 클라 미설치 본인에게 "영상재생 모드 + 미설치" + 전원에게 "필수 모드 미설치 플레이어가 있어..." 후 차단. +3. **서버 + 모든 클라 설치**: 모두 정상 → start 정상 진행. +4. `/scoreboard players list #server` 로 server presence 점수 확인, + `/scoreboard players list ` 로 client presence 점수 확인. + +## 참고: 자매 모드 `mc_chat_answer_mod` 의 다른 접근 + +`mc_chat_answer_mod/common/.../ChatAnswerCore.java::markModPresence` 참고. +서버 전용 모드라 fake player `#server` 한 곳에만 set 한다. 클라이언트 +렌더링 모드인 본 모드는 이 패턴이 아닌 per-player handshake 가 정답. diff --git a/music_quiz/data/mq/function/commands/start.mcfunction b/music_quiz/data/mq/function/commands/start.mcfunction index d2a7220..8e08a05 100644 --- a/music_quiz/data/mq/function/commands/start.mcfunction +++ b/music_quiz/data/mq/function/commands/start.mcfunction @@ -1,5 +1,36 @@ execute if score init main matches 10 run return run function mq:tellraw {"text":"퀴즈가 완전히 종료된후 시작해주세요.","color":"red","msg":""} +# ---- 외부 모드 설치 검증 ---- +# 두 모드는 성격이 달라서 검증 방식이 다름: +# +# * mq_chat_mod : mc_chat_answer_mod = 서버 전용 모드 (채팅 가로채기는 +# 서버에서 일어남, 클라 설치 불필요). 따라서 fake player `#server` +# 점수를 모드가 매 server tick 마다 1 로 set. 서버에 모드가 없으면 +# 이 점수가 갱신되지 않음. +# +# * mq_video_mod : mc_video_player_mod = 클라이언트 측 렌더링 + 서버 측 +# 컴포넌트. 같은 objective 안에 holder 두 종류 사용: +# - `#server mq_video_mod` : 서버 컴포넌트가 매 tick 1 로 갱신 (server +# presence). 없으면 0 → 서버에 모드 미설치. +# - ` mq_video_mod` : 클라 join 시 payload 가 서버로 오면 서버 +# 컴포넌트가 해당 플레이어 점수를 1 로 set (client presence). 클라 +# 미설치면 0 유지. +# 이렇게 분리해야 "서버 미설치"와 "특정 플레이어 클라 미설치"가 안내에서 +# 구분된다. +# +# 1) 서버 측 모드 부재 — 전원 차단, 단일 안내. 서버 부재는 클라 검사보다 +# 우선해야 — 클라가 다 설치되어 있어도 서버가 없으면 동작 안 한다. +execute unless score #server mq_chat_mod matches 1 run return run function mq:tellraw {"text":"채팅정답 모드가 서버에 미설치 — 서버 관리자에게 문의해주세요.","color":"red","msg":""} +execute unless score #server mq_video_mod matches 1 run return run function mq:tellraw {"text":"영상재생 모드가 서버에 미설치 — 서버 관리자에게 문의해주세요.","color":"red","msg":""} + +# 2) 클라이언트 측 모드 (mc_video_player_mod) 부재 — 본인 누락 안내 + 차단. +# selector `scores={X=..0}` 는 점수 미존재를 매치하지 않으므로 직전에 +# `add @a ... 0` 으로 materialize. 개인 안내는 tellraw @s 직접 (mq:tellraw +# 는 내부 @a broadcast 라 부적합). +scoreboard players add @a mq_video_mod 0 +execute as @a[scores={mq_video_mod=..0}] run tellraw @s ["",{"text":"영상재생 모드 미설치 — 모드 적용 후 다시 입장해주세요.","color":"red"}] +execute if entity @a[scores={mq_video_mod=..0}] run return run function mq:tellraw {"text":"필수 모드 미설치 플레이어가 있어 시작할 수 없습니다.","color":"red","msg":""} + setblock ~ ~ ~ minecraft:air function mq:quiz/stop_sound diff --git a/music_quiz/data/mq/function/load.mcfunction b/music_quiz/data/mq/function/load.mcfunction index 9845e29..3daef27 100644 --- a/music_quiz/data/mq/function/load.mcfunction +++ b/music_quiz/data/mq/function/load.mcfunction @@ -21,6 +21,24 @@ scoreboard objectives add buttons dummy scoreboard objectives add answer dummy scoreboard objectives add leave_game custom:leave_game +# 외부 모드 존재 확인용 점수. +# mq_chat_mod : 서버 전용 모드(mc_chat_answer_mod). 모드가 매 server tick +# 마다 fake player `#server` 점수를 1 로 set. 모드가 서버에 없으면 0 유지. +# mq_video_mod : 클라이언트 모드(mc_video_player_mod). 클라 join 시 서버로 +# handshake payload 전송 → 서버 측 모드가 해당 플레이어 점수를 1 로 set. +# 클라에 모드가 없으면 0 유지. (login.mcfunction 에서 플레이어별 0 초기화.) +scoreboard objectives remove mq_chat_mod +scoreboard objectives remove mq_video_mod +scoreboard objectives add mq_chat_mod dummy +scoreboard objectives add mq_video_mod dummy +# /reload 후 모드가 한 tick 도 돌기 전에 start 가 호출될 수 있으니 +# #server 점수도 0 으로 materialize. 모드가 살아 있으면 다음 tick 에 1 로 갱신. +# mq_video_mod 도 같은 objective 안에서 holder 만 다르게 — `#server` 는 서버 +# 컴포넌트 존재 (서버 측 모드가 매 tick 1 로 갱신), `` 는 클라 측 +# 존재 (payload 수신 시 1 로 갱신). +scoreboard players set #server mq_chat_mod 0 +scoreboard players set #server mq_video_mod 0 + scoreboard players set two func.temp 2 bossbar add mq:process [{"text":"진행도: ","color": "yellow","bold": true},{"text":"0","color": "yellow","bold": true},{"text":"/","color": "yellow","bold": true},{"text":"0","color": "yellow","bold": true}] diff --git a/music_quiz/data/mq/function/players/login.mcfunction b/music_quiz/data/mq/function/players/login.mcfunction index 226bec4..0c90af8 100644 --- a/music_quiz/data/mq/function/players/login.mcfunction +++ b/music_quiz/data/mq/function/players/login.mcfunction @@ -1,6 +1,15 @@ tag @s add player scoreboard players reset @s leave_game +# 외부 모드 검증 점수 초기화 (per-player 검증 대상만). +# mq_video_mod : 클라이언트 모드(mc_video_player_mod) 가 join 시 handshake +# payload 를 서버로 보내면 서버 모드가 해당 플레이어 점수를 1 로 set 한다. +# 여기서 0 으로 미리 깔아 두면 handshake 가 없는 플레이어는 0 유지 → +# start 가드 차단. handshake 가 오면 곧바로 1 로 갱신됨. +# mq_chat_mod 는 서버 전용 모드라 fake player(#server) 로 검증 — per-player +# 초기화 불필요. +scoreboard players set @s mq_video_mod 0 + title @s times 10t 80t 10t title @s subtitle "" title @s title "" diff --git a/music_quiz/data/mq/function/quiz/setanswer.mcfunction b/music_quiz/data/mq/function/quiz/setanswer.mcfunction index 1bf71b3..f77094a 100644 --- a/music_quiz/data/mq/function/quiz/setanswer.mcfunction +++ b/music_quiz/data/mq/function/quiz/setanswer.mcfunction @@ -13,14 +13,13 @@ scoreboard players set hint buttons -1 scoreboard players set replay buttons -1 # 이전 문제의 미처리 정답 입력 정리 + 새 문제의 input trigger 활성화 +# input trigger 는 유지 (mod 없는 환경에서 /trigger input 으로 dialog 열기 가능). +# 채팅 안내 메시지는 제거 — mc_chat_answer_mod 가 채팅 직접 입력을 처리함. data remove storage mq:input queue scoreboard players reset @a submit_seq scoreboard players set seq func.temp 0 scoreboard players enable @a input -# 정답 입력 안내 (클릭 시 trigger input → tick 에서 dialog 오픈) -function mq:tellraw {"text":"","color":"black",msg:[{"text":"[ 정답 입력 ]","color":"green","bold":true,"click_event":{"action":"run_command","command":"/trigger input set 1"},"hover_event":{"action":"show_text","value":{"text":"클릭하여 정답 입력창 열기","color":"gray"}}}]} - scoreboard players set init main 5 function mq:quiz/play_sound