From d382babfbdf9fdabff5516918dc8cb4e6e28ba67 Mon Sep 17 00:00:00 2001
From: tkrmagid <tkrmagid@git.tkrmagid.kr>
Date: Fri, 15 May 2026 20:39:02 +0900
Subject: [PATCH] docs: client-side install guide for v0.4.1 + JavaCV 1.5.13

README rewritten for MC 26.1.2 / Java 25 / Fabric Loader 0.19.2 target.
Added JavaCV install section (Prism/MultiMC preferred, JVM args fallback,
Maven coords for builders) pointing at the 2026-02-22 1.5.13 binaries
bundling FFmpeg 8.0.1. Usage section reflects the v0.4.1 invisible-anchor
flow: clicked block = bottom-left, sneak+left-click deletes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md | 110 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 93 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index a99f52c..6887bb2 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,105 @@
 # video_player (영상재생모드)
 
-마인크래프트(Fabric, MC 1.21.6+) 안에서 임의의 mp4 URL을 블록 표면에 재생하는 모드.
+마인크래프트(Fabric, MC 26.1.2) 안에서 임의의 http/https mp4·webm URL을 블록 표면에 재생하는 클라이언트/서버 양립 모드.
 
 - 모드 ID: `video_player`
 - 한글명: 영상재생모드
-- 로더: Fabric (싱글플레이어 / 전용 서버 양쪽 지원)
-- 명세: 별도 SPEC 문서 참조
+- 현재 버전: **0.4.1**
+- 타겟: Minecraft **26.1.2** (Mojmap, intermediary/Yarn 단종 이후 단일 타겟)
+- 로더: Fabric Loader **0.19.2** 이상
+- Java: **25** (Minecraft 26.x 요구사항)
 
-## 빌드
+## 클라이언트 설치
 
-```sh
-JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 ./gradlew build
+### 1. 필수 의존성
+
+순서대로 `mods/` 폴더에 넣으세요.
+
+1. **Fabric Loader 0.19.2+**
+   https://fabricmc.net/use/installer/
+2. **Fabric API 0.149.0+26.1.2 (이상)**
+   https://modrinth.com/mod/fabric-api/versions?g=26.1.2
+3. **video_player-0.4.1.jar** (이 모드)
+   https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
+
+### 2. 영상 재생 라이브러리 (JavaCV) — **필수**
+
+JavaCV가 없으면 모드는 로드되지만 영상은 재생되지 않습니다(앵커 자리만 표시). FFmpeg 8.0.1이 동봉된 **JavaCV 1.5.13** (2026-02-22 릴리스)을 권장합니다.
+
+#### 방법 A — Prism Launcher / MultiMC (권장)
+
+런처에서 인스턴스 → 편집 → **Version → Add to Minecraft.jar (Java libraries)** 로 아래 jar들을 추가하세요. 이 방식은 클래스패스에 라이브러리로 등록되므로 모드 폴더에 넣는 것보다 안정적입니다.
+
+1. JavaCV 1.5.13 바이너리 zip 다운로드:
+   https://github.com/bytedeco/javacv/releases/download/1.5.13/javacv-platform-1.5.13-bin.zip
+2. 압축 해제 후 다음 jar를 추가:
+   - `javacv.jar`
+   - `javacpp.jar`
+   - `ffmpeg.jar`
+   - 자신의 OS에 맞는 ffmpeg 네이티브 1개:
+     - Windows: `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar`
+     - Linux: `ffmpeg-8.0.1-1.5.13-linux-x86_64.jar`
+     - macOS Intel: `ffmpeg-8.0.1-1.5.13-macosx-x86_64.jar`
+     - macOS Apple Silicon: `ffmpeg-8.0.1-1.5.13-macosx-arm64.jar`
+
+#### 방법 B — 공식 런처 (JVM args)
+
+공식 런처는 `mods/` 폴더의 일반 jar를 라이브러리로 자동 로드하지 않습니다. 직접 클래스패스에 추가하려면 jar 위치를 정한 뒤 게임 실행 인자(JVM args)에 다음을 더하세요:
+
+```
+-Xss4M -Dorg.lwjgl.system.allocator=system
+-cp /절대경로/javacv.jar:/절대경로/javacpp.jar:/절대경로/ffmpeg.jar:/절대경로/ffmpeg-8.0.1-1.5.13-linux-x86_64.jar
 ```
 
-산출물: `build/libs/video_player-<version>.jar`
+Windows는 `:` 대신 `;` 구분자. 이 방식은 까다로워서 **Prism/MultiMC 사용을 강하게 권장합니다.**
 
-## 현재 진행도
+#### 방법 C — Maven 좌표 (직접 빌드 / 모드팩 제작자)
 
-이 저장소는 SPEC §10 마일스톤을 순차적으로 채우는 중입니다.
+```
+org.bytedeco:javacv-platform:1.5.13          # 모든 플랫폼 ffmpeg 포함 (~500MB)
+  또는
+org.bytedeco:javacv:1.5.13
+org.bytedeco:ffmpeg-platform:8.0.1-1.5.13    # ffmpeg만
+```
 
-- **M1 — 스캐폴드** (현재): Fabric 모드 골격, 비디오 앵커 블록/엔티티 등록, 비디오 스틱 아이템, `/videoStick` 명령.
-- M2 — 정적 렌더
-- M3 — JavaCV mp4 재생
-- M4 — GUI / 네트워크
-- M5 — 좌클릭 삭제 + `/videoPlace`, `/videoDelete`
-- M6 — 오디오 + 거리감 + Mute(소리 on/off)
-- M7 — WaterMedia 백엔드 + 자동 선택
-- M8 — Stonecutter 멀티버전
+## 사용법
+
+### 영상 배치
+
+1. 인벤토리에서 **비디오 스틱** 획득 (`/videostick`)
+2. 원하는 벽/바닥/천장 블록을 비디오 스틱으로 **우클릭**
+3. 열린 GUI에 URL·너비·높이·반복·자동재생 입력
+4. 클릭한 블록이 영상의 **왼쪽 아래** 모서리가 되고, 너비 W × 높이 H 만큼 오른쪽/위로 펼쳐집니다 (벽면에 딱 붙음).
+
+### 영상 수정 / 삭제
+
+- 이미 영상이 걸린 벽면을 비디오 스틱으로 **우클릭** → GUI 재오픈
+- **쉬프트 + 좌클릭**으로 영상 삭제 (앵커가 인접 공기 블록에 숨어 있어 일반 좌클릭으로는 안 지워집니다)
+
+### URL 요구사항
+
+- `http://` 또는 `https://`만
+- 길이 256자 이하
+- FFmpeg가 디코드할 수 있는 컨테이너/코덱 (mp4, webm, mkv, mov 등)
+- Range/Chunked 응답을 지원하는 서버 권장
+- 인증 토큰이 URL에 포함된 경우 GUI 보호되지만 평문 저장됨에 주의
+
+### 명령어
+
+- `/videostick` — 비디오 스틱 지급
+- `/videoplace <url> [w] [h] [loop] [autoplay]` — 정조준한 블록면에 영상 배치
+- `/videodelete` — 정조준한 영상 제거
+
+## 빌드 (개발자)
+
+```sh
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
+```
+
+산출물: `build/libs/video_player-0.4.1.jar`
+
+## 알려진 이슈
+
+- JavaCV가 없으면 영상 영역에 자리만 잡힐 뿐 그려지지 않습니다 (로그에 `WARN ... JavaCV not on classpath` 출력).
+- 0.3.x 이하에서 만든 비주얼 앵커 블록은 0.4.0 이후 보이지 않습니다 — 다시 배치하세요.
+- WaterMedia 백엔드는 26.1.2 포트가 나오기 전까진 더미 상태입니다 (JavaCV 백엔드만 동작).