docs: README·연동문서를 영상 시스템/선택 모드 현행화

- README: 정답 영상 시스템(커맨드블럭 큐·preload/FIFO 캐시·동적 src),
  gif 페인팅, videos/ 파일트리, video 스토리지/스코어보드/설정, 영상 모드
  선택화 설치 절차, 2026-06-05 변경 이력 추가
- mc_video_player_mod_integration.md: 가드가 차단→경고만으로 바뀐 점 반영,
  README 에서 상호 링크

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

README.md

@@ -25,18 +25,26 @@
 
 ### 외부 모드 의존성 (서버/클라)
 
-서버 측 검증이 들어가 있어 다음 두 모드가 반드시 깔려 있어야 `/start` 가
-진행된다. 미설치 시 `commands/start` 의 게이트가 사유와 함께 차단한다.
+모드는 **필수 1 + 선택 1** 구성이다.
 
-- **`mc_chat_answer_mod` v1.3.7+** — 서버 전용. 채팅으로 정답 입력을
-  받는다. presence 는 `#server mq_chat_mod` 점수로 매 tick 표시되며,
-  `SERVER_STARTED` / `END_DATA_PACK_RELOAD` / `PlayerJoin` / `ServerTick`
-  네 지점에서 갱신된다.
+- **`mc_chat_answer_mod` v1.3.7+ (필수)** — 서버 전용. 채팅으로 정답 입력을
+  받는다. 정답 판정의 핵심이라 없으면 `/start` 가 차단된다. presence 는
+  `#server mq_chat_mod` 점수로 매 tick 표시되며, `SERVER_STARTED` /
+  `END_DATA_PACK_RELOAD` / `PlayerJoin` / `ServerTick` 네 지점에서 갱신된다.
   https://git.tkrmagid.kr/tkrmagid/mc_chat_answer_mod/releases/tag/v1.3.7
-- **`mc_video_player_mod`** — 클라이언트 + 서버 모두 필요. 서버 컴포넌트가
-  `#server mq_video_mod` 를 1 로 갱신하고, 클라 join handshake 가 도착하면
-  `<player> mq_video_mod` 를 1 로 set. `/start` 는 서버 부재 시 단일 차단,
-  특정 플레이어 부재 시 본인에게 안내 + 게임 시작 차단.
+- **`mc_video_player_mod` (선택)** — 정답 영상 재생용. **없어도 게임은
+  정상 진행되며 영상만 표시되지 않는다.** `/start` 는 차단하지 않고 노란
+  경고만 출력한다 (서버 부재 시 전체 안내, 특정 플레이어 클라 부재 시 본인
+  에게만 안내). presence 는 `#server mq_video_mod` (서버 컴포넌트가 매 tick
+  1 로 갱신) + `<player> mq_video_mod` (클라 join handshake 수신 시 1 로 set)
+  로 나눠 표시한다. 모드 측 연동 사양(presence handshake)은
+  [docs/mc_video_player_mod_integration.md](docs/mc_video_player_mod_integration.md) 참고.
+  https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod
+
+> 데이터팩은 모드 명령(`videoCache`/`videoPlace`/`videoDelete`)을 mcfunction
+> 안에서 직접 실행하지 않고 **NBT 문자열 큐 → 커맨드블럭** 으로만 내보낸다.
+> 덕분에 영상 모드가 없어도 데이터팩 로드 시 미등록 명령 파싱 에러가 나지
+> 않는다 (자세한 건 아래 "정답 영상" 절).
 
 ### 100% 바닐라 — 의존 플러그인 없음 (모드 외)
 
@@ -51,10 +59,48 @@
   비프와 종료 클릭 같은 UI 사운드는 별도로 `weather` 채널을 사용한다.
 - 정답 이미지: `painting_variant musicquiz:cover_NN` 을 `/summon painting` 으로
   벽에 띄우고, 다음 곡 직전 `kill @e[type=painting,tag=mq_cover]` 로 제거.
+- gif 페인팅: `images/gif.mcfunction` 을 실행하면 실행한 플레이어에게
+  `mq:gif` variant 페인팅 아이템을 지급한다. 벽에 설치하면 랜덤 선택 없이
+  `mq:gif` 로 고정 배치되고, 리소스팩의 애니메이션 텍스처
+  (`musicquiz:gif` `.png` + `.png.mcmeta`) 덕분에 gif 처럼 움직인다.
+  variant 정의는 `painting_variant/gif.json` (`asset_id: musicquiz:gif`).
 
 리소스팩 트랙 번호와 `mq:init/songs` 리스트의 순서가 1:1로 일치해야 한다.
 1번째 곡 → `track_01` / `cover_01`, … (2자리 zero-pad).
 
+### 정답 영상 (선택)
+
+`mc_video_player_mod` 가 설치돼 있으면 정답 공개 시 곡별 영상을 벽면에
+띄운다. 모드가 없어도 게임은 정상 진행되며 영상만 표시되지 않는다.
+
+핵심은 **모드 명령을 mcfunction 안에서 직접 실행하지 않는다**는 점이다.
+모드 명령(`videoCache add/remove/clear`, `videoPlace`, `videoDelete`)은
+미설치 시 데이터팩 로드 단계에서 미등록 명령 파싱 에러를 일으키므로,
+NBT 문자열로만 만들어 큐에 적재하고 **커맨드블럭**으로 실행한다.
+
+- **큐 적재** — `mq:videos/macro/cmd` 가 명령을 문자열로 조립해
+  `mq:main video.cmdq` 리스트(`{c:"<명령 문자열>"}`)에 push 한다.
+  문자열은 mcfunction 파서를 거치지 않으므로 모드가 없어도 로드된다.
+- **드레인** — `mq:videos/drain` (매 tick, `mq:tick` 에서 호출) 이 큐를
+  한 tick 에 한 개씩 꺼내 `cmd_x/cmd_y/cmd_z` 좌표에 커맨드블럭을
+  setblock 하고 `auto` 를 켜 1회 실행한다. 커맨드블럭은 `auto:1b` 면 매
+  tick 재실행되므로, `video.armed` 플래그로 실행한 다음 tick 에
+  `mq:videos/macro/drain_off` 가 `auto:0b` 로 꺼 **정확히 1회만** 실행되게
+  한다 (모드의 `videoCache add` 가 중복 이름을 실패 처리해 스팸나는 것 방지).
+- **캐시(preload / FIFO keep)** — 게임 시작 시 `videos/cache/preload` 가
+  1..`preload` 번 영상을 미리 받아두고, 라운드마다 `videos/cache/add` 가
+  N개 앞까지 캐시를 채운다. 캐시 개수가 `keep` 을 넘으면
+  `videos/cache/evict` 가 가장 먼저 받은 것부터 FIFO 로 축출한다
+  (`keep<=0` 이면 무제한). 데이터팩이 `mq:main video.cached`
+  (`{i:N}` 리스트) 로 캐시 상태를 1:1 추적해 중복 등록을 막고 src 를 고른다.
+- **동적 src** — 재생 시 해당 번호가 캐시에 있으면 등록 이름 `video_N` 으로,
+  없으면 전체 URL `$(namespace)/N` 으로 `videoPlace` 한다.
+  `videos/normalize` 가 `namespace` 끝의 `/` 를 떼어 경로 중복 `//` 를 막는다.
+
+모드 측이 구현해야 하는 presence handshake(서버 tick + 클라 payload) 사양은
+[docs/mc_video_player_mod_integration.md](docs/mc_video_player_mod_integration.md)
+참고.
+
 ### 게임 흐름과 상태 (`init` 스코어보드)
 
 게임 전체 상태는 `main` 스코어보드의 가상 플레이어 `init` 값으로 관리한다.
@@ -155,7 +201,18 @@ music_quiz/
         │   ├── images/                 # 정답 페인팅 표시·제거
         │   │   ├── show.mcfunction          # cover painting 소환
         │   │   ├── clear.mcfunction         # cover painting 일괄 제거
+        │   │   ├── gif.mcfunction           # 실행 플레이어에게 mq:gif 페인팅 아이템 지급
         │   │   └── macro/show.mcfunction    # $summon painting 매크로
+        │   ├── videos/                 # 정답 영상 (선택 모드, 커맨드블럭 큐 경로)
+        │   │   ├── show.mcfunction          # "play" 큐 적재
+        │   │   ├── clear.mcfunction         # "delete" 큐 적재
+        │   │   ├── normalize.mcfunction     # namespace 끝 / 제거 + 캐시 상태 초기화
+        │   │   ├── drain.mcfunction         # 매 tick 큐 1개씩 커맨드블럭 실행 (mq:tick)
+        │   │   ├── cache/{fill,add,preload,evict,clear}.mcfunction  # preload/FIFO 캐시 관리
+        │   │   └── macro/               # 매크로 진입점
+        │   │     ├── cmd.mcfunction         # 모드 명령 문자열 조립 → cmdq push
+        │   │     ├── drain.mcfunction       # $setblock command_block + auto 1b
+        │   │     └── drain_off.mcfunction   # $auto 0b (다음 tick 재실행 방지)
         │   ├── repeat/                 # tick에서 호출되는 매 틱 처리
         │   │   ├── players·check_answer·timer.mcfunction
         │   │   ├── timers/{init2,init6,init10}.mcfunction  # init 단계별 timer 디스패치 분할
@@ -178,6 +235,10 @@ music_quiz/
 - `func.temp` — 산술용 임시 상수 (`two=2` 등)
 - `leave_game` — `custom:leave_game` 통계 (재접속 감지)
 - `score` — 사이드바 표시용 점수
+- `mq_chat_mod` — `mc_chat_answer_mod` presence. `#server` 점수 1 이면 설치됨
+  (없으면 `/start` 차단)
+- `mq_video_mod` — `mc_video_player_mod` presence. `#server` = 서버 측 모드
+  존재, `<player>` = 클라 측 모드 존재 (없으면 경고만, 차단 X)
 - `ready` / `cancel` / `stop` / `skip` / `hint` / `replay` — 플레이어 트리거
 
 스토리지:
@@ -186,6 +247,11 @@ music_quiz/
   - `title`, `max_index`, `spawn` — 설정
   - `audio` = `{namespace, source, volume, pitch}` — `/playsound` 파라미터
   - `image` = `{namespace, x, y, z, facing}` — 정답 페인팅 좌표
+  - `video` = `{namespace, cmd_x/y/z, x/y/z, facing, w, h, sound, preload, keep}`
+    — 정답 영상 설정 + 런타임 캐시 상태. `cmd_*` 는 큐 실행용 커맨드블럭
+    좌표, `x/y/z`·`facing`·`w/h` 는 영상 표시 위치/크기. 런타임에
+    `cached`(`{i:N}` 리스트), `cmdq`(명령 큐), `armed`(커맨드블럭 1회 실행
+    플래그) 가 이 컴파운드에 추가된다
   - `answer` = `{title, author, alias, track, cover}` — 현재 곡 정답
   - `songs` — 곡 목록 (`mq:init/songs` 가 채움)
   - `button_defs` / `trigger_defs` — 버튼·트리거 정의
@@ -203,7 +269,11 @@ music_quiz/
 `/reload` 후 반영된다.
 
 - **`init/config.mcfunction`** — 주제, 스폰 위치, 오디오 설정(`audio`),
-  정답 페인팅 좌표(`image`). `title` 은 `[ … ]` 채팅 접두사로도 사용된다.
+  정답 페인팅 좌표(`image`), 정답 영상 설정(`video`). `title` 은 `[ … ]`
+  채팅 접두사로도 사용된다. `video` 의 `namespace` 는 영상 URL 베이스,
+  `cmd_x/y/z` 는 모드 명령 실행용 커맨드블럭 좌표, `x/y/z`·`facing`·`w/h`
+  는 영상 표시 위치/크기, `sound` 는 음량(-1 음소거), `preload` 는 미리
+  받아둘 캐시 개수(0 이면 끔), `keep` 은 FIFO 유지 개수(0 이하 무제한).
 - **`init/songs.mcfunction`** — 곡 목록 (한 줄에 한 곡씩 append). `alias`
   배열의 문자열은 정답 판정 시 동의어로 인정된다. **곡의 순서가 리소스팩
   트랙 번호와 1:1 매칭** 되므로 순서 변경 시 리소스팩도 함께 재생성해야
@@ -222,13 +292,16 @@ JSON 텍스트 컴포넌트가 storage 참조를 일관되게 지원하지 않
 ### 설치
 
 1. 서버 월드 폴더 `datapacks/`에 `music_quiz/` 디렉터리째 복사.
-2. 서버 mods 폴더에 `mc_chat_answer_mod` v1.3.7+ 와 `mc_video_player_mod`
-   jar 설치. `mc_video_player_mod` 는 클라이언트 측에도 설치 필요.
+2. 서버 mods 폴더에 `mc_chat_answer_mod` v1.3.7+ (필수) 설치.
+   `mc_video_player_mod` (선택) 는 정답 영상을 쓸 때만 서버 + 클라이언트
+   양쪽에 설치한다. 없어도 게임은 정상 동작하며 영상만 표시되지 않는다.
 3. minecraft_launcher 에서 생성한 `musicquiz` 리소스팩을 클라이언트에 적용
    (런처가 자동 처리).
 4. 서버 `/reload` — 리로드 성공 메시지가 채팅에 표시되면 정상.
 5. `mq:init/buttons` 에 정의된 좌표 부근에 6개 버튼이 자동 배치된다.
-6. `start` 버튼을 눌러 게임 시작 — 모드 미설치 시 사유와 함께 차단된다.
+6. `start` 버튼을 눌러 게임 시작 — `mc_chat_answer_mod` (필수) 미설치 시
+   사유와 함께 차단된다. `mc_video_player_mod` (선택) 미설치 시에는 노란
+   경고만 출력하고 영상 없이 진행된다.
 
 ### 좌표 의존성 (주의)
 
@@ -243,6 +316,28 @@ JSON 텍스트 컴포넌트가 storage 참조를 일관되게 지원하지 않
 
 ## 변경 이력
 
+### 2026-06-05 — 정답 영상 시스템 + 영상 모드 선택화 + gif 페인팅
+
+- **정답 영상 추가** — `mc_video_player_mod` 연동으로 정답 공개 시 곡별
+  영상을 벽면에 표시. `videos/` 트리 신설 (show/clear/normalize/drain +
+  cache/{fill,add,preload,evict,clear} + macro/{cmd,drain,drain_off}).
+- **모드 명령 커맨드블럭 큐 경로** — 모드 명령(`videoCache`/`videoPlace`/
+  `videoDelete`)을 mcfunction 에서 직접 실행하지 않고 NBT 문자열로 큐
+  (`mq:main video.cmdq`) 에 적재 → `videos/drain` 이 매 tick 한 개씩
+  커맨드블럭으로 실행. 미설치 모드여도 데이터팩 로드 시 파싱 에러 없음.
+  `video.armed` 플래그 + `drain_off` (auto:0b) 로 정확히 1회 실행 보장.
+- **영상 모드 선택화** — `mc_video_player_mod` 없어도 `/start` 차단 안 함
+  (노란 경고만, 영상 없이 진행). 채팅 모드(`mc_chat_answer_mod`) 만 필수.
+- **캐시 (preload / FIFO keep)** — `config.video` 의 `preload`/`keep` 으로
+  미리받기 개수와 FIFO 유지 개수 제어. `video.cached` 로 캐시 상태 자체
+  추적, 동적 src (`video_N` vs 전체 URL), `normalize` 가 namespace 끝 `/`
+  제거.
+- **gif 페인팅** — `images/gif.mcfunction`: 실행 플레이어에게 `mq:gif`
+  variant 페인팅 아이템 지급. 벽 설치 시 리소스팩 애니메이션 텍스처로
+  움직임. `painting_variant/gif.json` (`asset_id: musicquiz:gif`) 신설.
+- `init/config.mcfunction` 에 `video` 컴파운드 추가, `load.mcfunction` 에
+  `mq_chat_mod`/`mq_video_mod` objective 추가.
+
 ### 2026-05-19 — v1.0.25: 버튼 hitbox/라벨 미세조정 + 곡목록·좌표 갱신
 
 - `repeat/buttons/btn.mcfunction`: interaction hitbox 미세조정 (`width`