v1.0.26: 삭제됐던 docs/temp 복구 + README 사실 정정
리뷰어 지적 후속:
- docs/mc_video_player_mod_integration.md 복구 (f0a2e4f 에서 추출).
pull 시점에 main 에 없어서 같이 사라졌던 파일.
- temp/ 부분 적용 패키지 v1.0.26 기준으로 복구. 좌표 보존을 위해
init/*.mcfunction 은 일부러 제외, framework 파일만 포함:
- commands/start.mcfunction, load.mcfunction (모드 게이트 + objective)
- repeat/buttons/{btn,btn_prep,handler}.mcfunction
- repeat/timer.mcfunction + repeat/timers/{init2,init6,init10}.mcfunction
- temp/README.md 에 적용 방법 + 라벨 추가 안내 명시.
- README.md 사실 정정:
- 음원 채널 "기본 weather" → 실제 config.mcfunction 은 player
(UI 비프만 weather). source 가 무엇이 무엇인지 명시.
- 스토리지 섹션의 marker 항목 제거 (현재 config 에 marker 정의 없음,
legacy kill 한 줄만 잔존). mq:input 큐 추가, mq:tmp 페이로드 갱신.
- init/config.mcfunction 설명 / 좌표 의존성 섹션에서 marker 제거.
데이터팩 코드 변경 없음 — v1.0.25 = v1.0.26 동작 동일.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Claude (owner)
184
docs/mc_video_player_mod_integration.md
Normal file
184
docs/mc_video_player_mod_integration.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# mc_video_player_mod — 음악퀴즈 데이터팩 연동 사양
|
||||
|
||||
음악퀴즈 데이터팩(`music_quiz`)이 영상재생 모드의 **서버 측 + 클라이언트 측**
|
||||
설치 여부를 둘 다 검증할 수 있도록, 모드의 서버 컴포넌트가 두 가지 점수를
|
||||
갱신한다.
|
||||
|
||||
| holder | 의미 | 갱신 주체 / 시점 |
|
||||
|--------|------|------------------|
|
||||
| `#server mq_video_mod` | 서버에 모드 jar 존재 | 서버 컴포넌트가 매 server tick 마다 1 |
|
||||
| `<player> 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<HelloPayload> TYPE =
|
||||
new CustomPacketPayload.Type<>(ResourceLocation.fromNamespaceAndPath("mq_video_mod", "hello"));
|
||||
public static final StreamCodec<FriendlyByteBuf, HelloPayload> 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 <player>` 로 client presence 점수 확인.
|
||||
|
||||
## 참고: 자매 모드 `mc_chat_answer_mod` 의 다른 접근
|
||||
|
||||
`mc_chat_answer_mod/common/.../ChatAnswerCore.java::markModPresence` 참고.
|
||||
서버 전용 모드라 fake player `#server` 한 곳에만 set 한다. 클라이언트
|
||||
렌더링 모드인 본 모드는 이 패턴이 아닌 per-player handshake 가 정답.
|
||||
Reference in New Issue
Block a user