docs: add missing javacpp native jar to install guide (v0.4.3)

JavaCPP Loader (javacpp.jar) ships pure-Java code that needs its own
JNI bridge DLL (jnijavacpp) to extract & link other native libraries.
That bridge lives in the platform-specific javacpp-<os>-<arch>.jar
which the old install guide silently omitted — users following it
ended up with a black panel and an UnsatisfiedLinkError for jnijavacpp
because FFmpeg natives could never be loaded.

This bumps the required JavaCV jar list from 4 to 5, updates the
-Xbootclasspath/a: examples on all three OSes, and adds a diagnostic
note for the matching log line.

Docs-only change; mod code is unchanged from v0.4.2.

README.md

@@ -1,29 +1,190 @@
 # video_player (영상재생모드)
 
-마인크래프트(Fabric, MC 1.21.6+) 안에서 임의의 mp4 URL을 블록 표면에 재생하는 모드.
+마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
 
 - 모드 ID: `video_player`
-- 한글명: 영상재생모드
+- 현재 버전: **0.4.3**
-- 로더: Fabric (싱글플레이어 / 전용 서버 양쪽 지원)
+- 마인크래프트 버전: **26.1.2**
-- 명세: 별도 SPEC 문서 참조
+- 필요 Java: **25** (마인크래프트 26.x 가 요구함)
 
-## 빌드
+---
+
+## 처음 사용하는 분을 위한 설치 가이드
+
+이 모드는 마인크래프트 **공식 런처**에 **Fabric**을 설치해서 쓰는 것을 기준으로 합니다. 차근차근 따라오시면 됩니다.
+
+### STEP 1. 마인크래프트 공식 런처를 켜고 최소 1회 26.1.2 바닐라로 접속
+
+런처 메뉴에서 마인크래프트 버전을 **26.1.2** 로 한 번 실행해 두면, 게임 폴더(`.minecraft`)와 `versions/26.1.2/` 가 자동으로 만들어집니다. 월드를 만들 필요는 없고 메인 화면까지만 들어가면 됩니다.
+
+### STEP 2. Fabric 설치하기
+
+Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니다.
+
+1. https://fabricmc.net/use/installer/ 에 접속해서 "Download for Windows" (또는 macOS / Linux)를 누릅니다. `fabric-installer-1.x.x.exe` (또는 `.jar`) 파일이 다운로드 됩니다.
+2. 받은 파일을 **더블 클릭** 으로 실행합니다.
+3. 창이 뜨면:
+   - **클라이언트** 탭이 선택되어 있는지 확인
+   - 마인크래프트 버전: **26.1.2**
+   - 로더 버전: **0.19.2** (또는 그보다 높은 숫자)
+   - 설치 위치는 그대로 두세요
+4. **설치** 버튼을 누르고 완료 메시지가 뜨면 닫습니다.
+5. 다시 공식 마인크래프트 런처를 열면 좌측 하단 프로필 선택 칸에 **`fabric-loader-0.19.2-26.1.2`** (이름 비슷한 항목) 이 새로 생겨 있습니다. 이 프로필을 선택합니다.
+
+### STEP 3. 모드 폴더 열기
+
+선택한 fabric 프로필 옆에 톱니바퀴 ⚙ 모양 아이콘이나 "편집" 버튼이 있습니다. (없으면 그냥 한 번 플레이를 눌러서 게임을 띄웠다가 닫으면 폴더가 만들어집니다.)
+
+`.minecraft/mods` 폴더가 모드를 넣는 곳입니다. 운영체제별 경로:
+
+- **Windows**: 키보드에서 `윈도우키+R` → `%appdata%\.minecraft\mods` 입력 → 엔터
+- **macOS**: Finder → `Go` 메뉴 → `Go to Folder` → `~/Library/Application Support/minecraft/mods`
+- **Linux**: `~/.minecraft/mods`
+
+폴더가 없으면 `mods` 라는 이름으로 직접 만드세요.
+
+### STEP 4. 모드 jar 파일 두 개를 mods 폴더에 넣기
+
+1. **Fabric API** (Fabric 모드들이 공통으로 쓰는 라이브러리. 거의 모든 Fabric 모드에 필요)
+   - **반드시 26.1.2 용으로 받아야 합니다.** 파일명 끝에 `+26.1.2.jar` 가 붙어있는지 꼭 확인하세요. `+1.21.11.jar` 같은 다른 버전을 받으면 게임이 "Incompatible mods found / requires Minecraft 1.21.x" 에러로 안 켜집니다.
+   - 직접 다운로드 (2026-05-14 빌드, MC 26.1.2 전용):
+     https://cdn.modrinth.com/data/P7dR8mSH/versions/Sy2Bq7Xc/fabric-api-0.149.0%2B26.1.2.jar
+   - 더 최신 빌드를 찾을 땐: https://modrinth.com/mod/fabric-api/versions → 페이지에서 게임 버전 필터 `26.1.2` 를 직접 선택. (URL 파라미터 필터가 듣지 않는 경우가 있어서 페이지 안에서 한 번 더 확인하는 게 안전합니다.)
+   - 받은 `fabric-api-0.149.0+26.1.2.jar` 를 `mods` 폴더에 넣습니다.
+2. **video_player** (이 모드)
+   - 다운로드: https://git.tkrmagid.kr/tkrmagid/mc_video_player_mod/releases
+   - `video_player-0.4.3.jar` 를 다운로드해서 같은 `mods` 폴더에 넣습니다.
+
+이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다.
+
+### STEP 5. 영상 재생 라이브러리 (JavaCV) 설치
+
+여기까지만 하면 마인크래프트는 켜지지만, 영상 자리에 검은 판만 보입니다. 진짜 영상을 재생하려면 **JavaCV** 라는 디코더 라이브러리가 필요합니다.
+
+> 솔직한 안내: 마인크래프트 공식 런처는 mods 폴더에 들어있는 일반 라이브러리 jar를 자동으로 읽어 주지 않습니다. 그래서 JavaCV 설치 절차가 조금 번거롭습니다. 가장 쉬운 길과 공식 런처에서 동작시키는 길 두 가지를 안내합니다.
+
+#### 5-A. 가장 쉬운 길: Prism Launcher 로 갈아타기 (선택)
+
+공식 런처 대신 무료 오픈소스 런처인 **Prism Launcher** 를 쓰면 클릭 몇 번으로 JavaCV를 라이브러리로 추가할 수 있습니다. 게임 자체는 같고, 정품 마인크래프트 계정으로 로그인하는 것도 동일합니다.
+
+1. https://prismlauncher.org/download/ 에서 다운로드 → 설치
+2. Prism에서 인스턴스 → 마인크래프트 26.1.2 + Fabric Loader 0.19.2 선택해서 생성
+3. 인스턴스 우클릭 → **Edit** → 왼쪽의 **Version** 탭 → **Add to Minecraft.jar** 버튼
+4. 아래 STEP 5-B 의 1번 항목에서 받은 JavaCV jar 5개를 한꺼번에 선택해서 추가
+5. **Launch** 로 실행
+
+이 방법이 가장 안정적이고 빠릅니다.
+
+#### 5-B. 공식 런처에서 동작시키기
+
+공식 런처를 계속 쓰고 싶다면 아래 절차를 따르세요.
+
+1. **JavaCV 1.5.13 다운로드**
+   - 다운로드 링크: https://github.com/bytedeco/javacv/releases/download/1.5.13/javacv-platform-1.5.13-bin.zip (2026-02-22 릴리스, FFmpeg 8.0.1 동봉)
+   - 압축을 풀고 `javacv-platform-1.5.13-bin` 폴더 안에서 **다음 jar 5개**를 골라 둡니다 (다른 파일은 안 씁니다):
+     - `javacv.jar`
+     - `javacpp.jar`
+     - 자신의 OS에 맞는 **javacpp 네이티브 jar** (이게 빠지면 검은 화면 — JNI bridge `jnijavacpp` 로딩에 꼭 필요):
+       - Windows 64bit: `javacpp-1.5.13-windows-x86_64.jar`
+       - macOS Intel: `javacpp-1.5.13-macosx-x86_64.jar`
+       - macOS Apple Silicon (M1/M2/M3/M4): `javacpp-1.5.13-macosx-arm64.jar`
+       - Linux 64bit: `javacpp-1.5.13-linux-x86_64.jar`
+     - `ffmpeg.jar`
+     - 자신의 OS에 맞는 **ffmpeg 네이티브 jar**:
+       - Windows 64bit: `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar`
+       - macOS Intel: `ffmpeg-8.0.1-1.5.13-macosx-x86_64.jar`
+       - macOS Apple Silicon (M1/M2/M3/M4): `ffmpeg-8.0.1-1.5.13-macosx-arm64.jar`
+       - Linux 64bit: `ffmpeg-8.0.1-1.5.13-linux-x86_64.jar`
+
+2. **이 5개 jar 를 게임이 읽도록 등록**
+   - 가장 안전한 위치: `.minecraft/libraries/javacv/` 폴더를 새로 만들고 5개 jar를 거기에 복사하세요. (긴 파일명이 부담스러우면 `javacpp-1.5.13-windows-x86_64.jar` → `javacpp-windows-x86_64.jar`, `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar` → `ffmpeg-windows-x86_64.jar` 식으로 짧게 rename해도 됩니다. 아래 예시는 짧은 이름 기준.)
+   - 그 다음, 공식 런처에서 fabric 프로필 옆 **편집** 또는 **설치 설정** → 화면 아래쪽 **"JVM 인수"** (Java arguments) 칸을 켜고 기존 인수 **끝**에 한 칸 띄우고 다음 한 줄을 추가합니다.
+
+     ⚠ **반드시 절대경로(`C:\Users\...`)로 적어주세요.** 마인크래프트 공식 런처는 JVM 인수의 `%APPDATA%`·`%USERPROFILE%` 같은 환경변수를 풀어주지 않고 글자 그대로 Java 에 넘깁니다. 그러면 boot classpath 가 빈 상태가 되어 영상이 안 나옵니다.
+
+     Windows (사용자명 `홍길동` 예시):
+     ```
+     -Xbootclasspath/a:C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacv.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacpp.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\javacpp-windows-x86_64.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg-windows-x86_64.jar
+     ```
+     (`C:\Users\<본인 윈도우 사용자명>\AppData\Roaming\` 부분을 본인 사용자 폴더로 바꾸세요. 윈도우키+R → `cmd` → `echo %APPDATA%` 로 정확한 경로 확인 가능.)
+
+     macOS (Apple Silicon 예시):
+     ```
+     -Xbootclasspath/a:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacv.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacpp.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/javacpp-macosx-arm64.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/ffmpeg.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/ffmpeg-macosx-arm64.jar
+     ```
+
+     Linux:
+     ```
+     -Xbootclasspath/a:/home/사용자이름/.minecraft/libraries/javacv/javacv.jar:/home/사용자이름/.minecraft/libraries/javacv/javacpp.jar:/home/사용자이름/.minecraft/libraries/javacv/javacpp-linux-x86_64.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg-linux-x86_64.jar
+     ```
+
+     주의:
+     - Windows는 jar 사이를 **세미콜론(`;`)** 으로 구분합니다.
+     - macOS/Linux는 **콜론(`:`)** 으로 구분합니다.
+     - 경로에 띄어쓰기가 있으면(특히 macOS의 `Application Support`) 전체 인수를 큰따옴표로 감싸세요.
+     - `사용자이름` 부분은 실제 자신의 사용자 폴더 이름으로 바꾸세요.
+     - `javacpp-...` 와 `ffmpeg-...` 부분의 jar 이름은 OS에 맞춰 1번에서 고른 그 파일명 그대로 적습니다 (zip 안에는 `javacpp-1.5.13-windows-x86_64.jar`, `ffmpeg-8.0.1-1.5.13-windows-x86_64.jar` 같은 긴 이름으로 들어 있고, 위 예시는 짧게 rename한 것 기준입니다).
+     - **5개 모두** 적어야 합니다. `javacpp-<os>.jar` (네이티브) 가 빠지면 JNI bridge 가 로딩 안 돼서 영상이 검게만 보입니다.
+
+3. 저장 후 **플레이** 를 누르면 영상이 재생됩니다.
+
+> 절차가 너무 번거롭다고 느끼면 **5-A 의 Prism Launcher** 를 권장합니다. 동일한 jar 를 클릭으로 끌어다 놓기만 하면 끝납니다.
+
+### STEP 6. 잘 설치됐는지 확인
+
+게임 안에서 채팅창에 `/videostick` 을 입력하세요. 정상이라면:
+
+- 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
+- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.3` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
+
+---
+
+## 사용법
+
+### 영상 배치
+
+1. 비디오 스틱을 손에 들고, 영상을 띄우고 싶은 벽/바닥/천장 블록을 **우클릭**.
+2. 열린 GUI 에 영상 URL, 가로(W), 세로(H), 반복 여부, 자동재생 여부를 입력.
+3. **클릭한 그 블록의 면** 이 영상의 왼쪽 아래 모서리가 되고, 오른쪽으로 W블록, 위로 H블록 만큼 영상이 펼쳐집니다.
+
+### 영상 수정 / 삭제
+
+- 이미 영상이 걸린 면을 다시 **우클릭** → GUI 재오픈, 내용 수정 가능
+- 영상 삭제: **쉬프트(Shift)** 누른 상태로 그 면을 **좌클릭**
+
+### URL 조건
+
+- `http://` 또는 `https://` URL만 됩니다 (`file://`, 로컬 파일 X)
+- 길이 256자 이하
+- FFmpeg 가 디코드 가능한 형식이면 됩니다 — mp4, webm, mkv, mov 등
+- 인증 토큰이 URL 에 들어 있으면 그 상태로 저장되니 공유 주의
+
+### 명령어
+
+| 명령 | 설명 |
+| --- | --- |
+| `/videostick` | 비디오 스틱 아이템을 인벤토리에 지급 |
+| `/videoplace <url> [w] [h] [loop] [autoplay]` | 정조준한 블록 면에 즉시 영상 배치 |
+| `/videodelete` | 정조준한 블록 면의 영상 제거 |
+
+---
+
+## 알려진 이슈
+
+- JavaCV가 안 잡혀있으면 영상 자리만 잡힐 뿐 검게 보입니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 또는 `JavaCV decode error: ...UnsatisfiedLinkError... jnijavacpp` 메시지로 확인 가능합니다. 후자는 `javacpp-<os>.jar` 네이티브 jar 가 빠진 케이스입니다 (STEP 5-B 1번의 5개 jar 모두 등록되어야 함).
+- 0.3.x 이하 버전에서 만든 영상은 새 버전(0.4.x) 에서 보이지 않으니 다시 배치해야 합니다.
+
+---
+
+## 개발자용 빌드
 
 ```sh
-JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 ./gradlew build
+JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
 ```
 
-산출물: `build/libs/video_player-<version>.jar`
+산출물: `build/libs/video_player-0.4.3.jar`
 
-## 현재 진행도
+JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
-
+```
-이 저장소는 SPEC §10 마일스톤을 순차적으로 채우는 중입니다.
+org.bytedeco:javacv-platform:1.5.13
-
+```
-- **M1 — 스캐폴드** (현재): Fabric 모드 골격, 비디오 앵커 블록/엔티티 등록, 비디오 스틱 아이템, `/videoStick` 명령.
-- M2 — 정적 렌더
-- M3 — JavaCV mp4 재생
-- M4 — GUI / 네트워크
-- M5 — 좌클릭 삭제 + `/videoPlace`, `/videoDelete`
-- M6 — 오디오 + 거리감 + Mute(소리 on/off)
-- M7 — WaterMedia 백엔드 + 자동 선택
-- M8 — Stonecutter 멀티버전

gradle.properties

@@ -5,7 +5,7 @@ org.gradle.configuration-cache=false
 
 # Mod
 mod_id=video_player
-mod_version=0.3.1
+mod_version=0.4.3
 maven_group=com.ejclaw.videoplayer
 archives_base_name=video_player
 

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

@@ -33,9 +33,20 @@ public class VideoPlayerClient implements ClientModInitializer {
         );
 
         AttackBlockCallback.EVENT.register((player, level, hand, pos, direction) -> {
-            if (level.isClientSide()
+            if (!level.isClientSide()) return InteractionResult.PASS;
-                && player.getMainHandItem().getItem() instanceof VideoStickItem
+            if (!(player.getMainHandItem().getItem() instanceof VideoStickItem)) return InteractionResult.PASS;
-                && level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity) {
+            // The anchor itself is invisible / non-collidable so the player cannot left-click it
+            // directly. Sneak + left-click on the wall the video sits on → delete the anchor in
+            // the adjacent air block.
+            if (player.isShiftKeyDown()) {
+                BlockPos anchorPos = pos.relative(direction);
+                if (level.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity) {
+                    ClientPlayNetworking.send(new DeleteAnchorPayload(anchorPos));
+                    return InteractionResult.SUCCESS;
+                }
+            }
+            // Legacy / safety: if the player somehow targets the anchor block directly.
+            if (level.getBlockEntity(pos) instanceof VideoAnchorBlockEntity) {
                 ClientPlayNetworking.send(new DeleteAnchorPayload(pos));
                 return InteractionResult.SUCCESS;
             }

src/main/java/com/ejclaw/videoplayer/block/VideoAnchorBlock.java

@@ -10,13 +10,26 @@ import net.minecraft.world.InteractionHand;
 import net.minecraft.world.InteractionResult;
 import net.minecraft.world.entity.player.Player;
 import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.level.BlockGetter;
 import net.minecraft.world.level.Level;
 import net.minecraft.world.level.block.BaseEntityBlock;
+import net.minecraft.world.level.block.RenderShape;
 import net.minecraft.world.level.block.entity.BlockEntity;
 import net.minecraft.world.level.block.state.BlockBehaviour;
 import net.minecraft.world.level.block.state.BlockState;
 import net.minecraft.world.phys.BlockHitResult;
+import net.minecraft.world.phys.shapes.CollisionContext;
+import net.minecraft.world.phys.shapes.Shapes;
+import net.minecraft.world.phys.shapes.VoxelShape;
 
+/**
+ * Anchor block — invisible, non-collidable host for {@link VideoAnchorBlockEntity}.
+ *
+ * <p>The block exists only so a {@link BlockEntity} can be attached to a position; visually it is
+ * completely empty (no model, no selection outline, no collision). The video itself is drawn by
+ * {@link com.ejclaw.videoplayer.client.render.VideoAnchorRenderer} flush against the wall the
+ * player clicked, not as a textured surface on this block.
+ */
 public class VideoAnchorBlock extends BaseEntityBlock {
     public static final MapCodec<VideoAnchorBlock> CODEC = simpleCodec(VideoAnchorBlock::new);
 
@@ -34,6 +47,31 @@ public class VideoAnchorBlock extends BaseEntityBlock {
         return new VideoAnchorBlockEntity(pos, state);
     }
 
+    @Override
+    protected RenderShape getRenderShape(BlockState state) {
+        return RenderShape.INVISIBLE;
+    }
+
+    @Override
+    protected VoxelShape getShape(BlockState state, BlockGetter level, BlockPos pos, CollisionContext ctx) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected VoxelShape getCollisionShape(BlockState state, BlockGetter level, BlockPos pos, CollisionContext ctx) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected VoxelShape getOcclusionShape(BlockState state) {
+        return Shapes.empty();
+    }
+
+    @Override
+    protected boolean propagatesSkylightDown(BlockState state) {
+        return true;
+    }
+
     @Override
     protected InteractionResult useItemOn(ItemStack stack, BlockState state, Level level,
                                           BlockPos pos, Player player, InteractionHand hand,

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

@@ -108,9 +108,14 @@ public class JavaCvBackend implements VideoBackend {
             Method setOpt = grabberCls.getMethod("setOption", String.class, String.class);
             Method setSampleFormat  = grabberCls.getMethod("setSampleFormat", int.class);
 
-            // mp4/http(s) network tuning
+            // HTTP(S) tuning for streaming URLs (e.g. webm via Range / chunked transfer).
-            try { setOpt.invoke(grabber, "rw_timeout", "5000000"); } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "rw_timeout",         "10000000"); } catch (Throwable ignored) {}
-            try { setOpt.invoke(grabber, "stimeout",   "5000000"); } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "timeout",            "10000000"); } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect",          "1");        } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect_streamed", "1");        } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "reconnect_at_eof",   "1");        } catch (Throwable ignored) {}
+            try { setOpt.invoke(grabber, "user_agent",
+                "video_player/" + com.ejclaw.videoplayer.VideoPlayerMod.MOD_ID); } catch (Throwable ignored) {}
             // Force interleaved signed 16-bit PCM so the audio sink path is single-shape.
             try { setSampleFormat.invoke(grabber, AV_SAMPLE_FMT_S16); } catch (Throwable ignored) {}
 
@@ -162,7 +167,10 @@ public class JavaCvBackend implements VideoBackend {
                 if (audioLine == null) Thread.sleep(15);
             }
         } catch (ClassNotFoundException cnf) {
-            VideoPlayerMod.LOG.info("[{}] JavaCV not on classpath; backend inactive", VideoPlayerMod.MOD_ID);
+            VideoPlayerMod.LOG.warn(
+                "[{}] JavaCV not on classpath — install org.bytedeco:javacv-platform (or javacv + ffmpeg natives)" +
+                " to enable video/audio playback. Anchor placeholder will remain visible.",
+                VideoPlayerMod.MOD_ID);
         } catch (InterruptedException ie) {
             Thread.currentThread().interrupt();
         } catch (Throwable t) {

src/main/java/com/ejclaw/videoplayer/client/render/VideoAnchorRenderer.java

@@ -20,15 +20,19 @@ import net.minecraft.world.phys.Vec3;
 import org.joml.Matrix4f;
 
 /**
- * SPEC §5.2 — submits a width×height textured quad in front of the anchor, oriented by facing.
+ * Draws the video as a textured quad <em>on the surface of the block the user clicked</em>.
  *
- * <p>Ported to 26.1.2's render-state pipeline: per-frame BE state is captured in
+ * <p>The anchor BE lives in the air block adjacent to the clicked wall. Its {@code facing}
- * {@link State} via {@link #extractRenderState}, then drawn via
+ * field is the surface normal of the wall (= the {@link Direction} the player clicked). The
- * {@link SubmitNodeCollector#submitCustomGeometry} during {@link #submit}.
+ * quad is rotated so its normal aligns with that direction and shifted so it sits flush against
+ * the wall surface, with a tiny outward offset to avoid z-fighting.
  */
 @Environment(EnvType.CLIENT)
 public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlockEntity, VideoAnchorRenderer.State> {
 
+    /** Tiny outward offset so the quad doesn't z-fight with the wall. */
+    private static final float SURFACE_EPSILON = 0.001F;
+
     public VideoAnchorRenderer(BlockEntityRendererProvider.Context ctx) {
         // no-op
     }
@@ -44,8 +48,7 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         BlockEntityRenderState.extractBase(be, state, crumbling);
         state.width = be.getWidth();
         state.height = be.getHeight();
-        Direction facing = be.getFacing();
+        state.facing = be.getFacing();
-        state.yaw = facing.getAxis().isHorizontal() ? facing.toYRot() : 0F;
         state.textureId = VideoPlayback.getOrStart(be);
     }
 
@@ -57,25 +60,28 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         final float w = state.width;
         final float h = state.height;
         final int light = state.lightCoords;
+        final Direction f = state.facing == null ? Direction.NORTH : state.facing;
 
         pose.pushPose();
-        // Center quad on the anchor's top face, rotated to face the configured direction.
+        // 1) Move to the anchor block's center.
-        pose.translate(0.5F, 1.01F, 0.5F);
+        pose.translate(0.5F, 0.5F, 0.5F);
-        pose.mulPose(Axis.YP.rotationDegrees(-state.yaw));
+        // 2) Rotate local +Z to align with the wall's outward normal.
-        pose.translate(-w / 2.0F, 0F, 0F);
+        applyFaceRotation(pose, f);
+        // 3) Place the quad's local origin (0,0) at the bottom-left corner of the anchor block's
+        //    wall face, so the clicked block becomes the lower-left and the video grows up & right.
+        //    Push it onto the wall surface (-0.5 along local +Z, the outward normal) plus a tiny
+        //    epsilon outward so the quad doesn't z-fight with the wall.
+        pose.translate(-0.5F, -0.5F, -0.5F + SURFACE_EPSILON);
 
-        // Snapshot the matrix so the callback's matrix-aware addVertex works even though
-        // submitCustomGeometry hands us a fresh Pose (its `pose` parameter).
         final Matrix4f mat = new Matrix4f(pose.last().pose());
-
         RenderType rt = RenderTypes.entityCutout(tex);
         collector.submitCustomGeometry(pose, rt, (poseUnused, vc) -> {
-            // Front face (visible from the direction the anchor faces)
+            // Front face (visible from outside, looking back at the wall)
             emit(vc, mat, 0F, 0F, 0F, 0F, 1F, light);
             emit(vc, mat, w,  0F, 0F, 1F, 1F, light);
             emit(vc, mat, w,  h,  0F, 1F, 0F, light);
             emit(vc, mat, 0F, h,  0F, 0F, 0F, light);
-            // Back face (visible from behind)
+            // Back face (in case the player ends up on the other side, e.g. clipping into the wall)
             emit(vc, mat, 0F, h,  0F, 0F, 0F, light);
             emit(vc, mat, w,  h,  0F, 1F, 0F, light);
             emit(vc, mat, w,  0F, 0F, 1F, 1F, light);
@@ -85,6 +91,24 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         pose.popPose();
     }
 
+    /**
+     * Rotate so local +Z (the quad's outward normal in its base orientation) becomes world {@code f},
+     * with local +X mapped to the natural "right" direction the player sees when looking at the face.
+     * Derivation: for each face {@code f}, pick the rotation that maps local +Z → f, +Y → world up
+     * (or a sensible substitute for top/bottom), so the quad lies flush against the wall, oriented
+     * the way the player intuits.
+     */
+    private static void applyFaceRotation(PoseStack pose, Direction f) {
+        switch (f) {
+            case SOUTH -> { /* identity: local +Z = world +Z (south). +X = east, +Y = up. */ }
+            case NORTH -> pose.mulPose(Axis.YP.rotationDegrees(180F));  // +Z → -Z, +X → -X (west)
+            case EAST  -> pose.mulPose(Axis.YP.rotationDegrees(90F));   // +Z → +X, +X → -Z (north)
+            case WEST  -> pose.mulPose(Axis.YP.rotationDegrees(-90F));  // +Z → -X, +X → +Z (south)
+            case UP    -> pose.mulPose(Axis.XP.rotationDegrees(-90F));  // +Z → +Y, +Y → -Z (north)
+            case DOWN  -> pose.mulPose(Axis.XP.rotationDegrees(90F));   // +Z → -Y, +Y → +Z (south)
+        }
+    }
+
     private static void emit(com.mojang.blaze3d.vertex.VertexConsumer vc, Matrix4f mat,
                              float x, float y, float z, float u, float v, int light) {
         vc.addVertex(mat, x, y, z)
@@ -110,6 +134,6 @@ public class VideoAnchorRenderer implements BlockEntityRenderer<VideoAnchorBlock
         public Identifier textureId;
         public int width = 1;
         public int height = 1;
-        public float yaw = 0F;
+        public Direction facing = Direction.NORTH;
     }
 }

src/main/java/com/ejclaw/videoplayer/item/VideoStickItem.java

@@ -16,7 +16,18 @@ import net.minecraft.world.level.Level;
 import net.minecraft.world.level.block.Block;
 import net.minecraft.world.level.block.state.BlockState;
 
-/** Right-click empty face → place anchor + open GUI. Right-click existing anchor → edit. */
+/**
+ * Right-click a block's face with the video stick:
+ * <ul>
+ *   <li>If a video anchor already exists in the adjacent air (= an anchor already drawn on this
+ *       face), reopen its config GUI.</li>
+ *   <li>Otherwise place an invisible anchor in the adjacent air block, set its facing to the
+ *       clicked face direction (so the renderer draws the quad flush against this face), and
+ *       open the config GUI.</li>
+ * </ul>
+ * The anchor block itself is invisible / non-collidable, so visually no new block appears —
+ * the video just shows up on the face the user clicked.
+ */
 public class VideoStickItem extends Item {
     public VideoStickItem(Properties properties) {
         super(properties);
@@ -33,25 +44,27 @@ public class VideoStickItem extends Item {
         if (!(player instanceof ServerPlayer sp)) return InteractionResult.PASS;
 
         BlockPos hit = ctx.getClickedPos();
+        Direction face = ctx.getClickedFace();
+        BlockPos anchorPos = hit.relative(face);
 
-        // Existing anchor → edit
+        // Existing anchor on this face → reopen edit GUI.
-        if (sl.getBlockEntity(hit) instanceof VideoAnchorBlockEntity existing) {
+        if (sl.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity existing) {
-            ServerPlayNetworking.send(sp, new OpenScreenPayload(hit, existing.toNbt()));
+            ServerPlayNetworking.send(sp, new OpenScreenPayload(anchorPos, existing.toNbt()));
             return InteractionResult.SUCCESS;
         }
 
-        // Empty face → place anchor on top of the clicked face
+        // Need an empty / replaceable space in front of the clicked face.
-        Direction side = ctx.getClickedFace();
+        BlockState there = sl.getBlockState(anchorPos);
-        BlockPos placeAt = hit.relative(side);
-        BlockState there = sl.getBlockState(placeAt);
         if (!there.canBeReplaced()) return InteractionResult.PASS;
 
         Block anchor = VideoPlayerBlocks.VIDEO_ANCHOR;
-        sl.setBlock(placeAt, anchor.defaultBlockState(), Block.UPDATE_ALL);
+        sl.setBlock(anchorPos, anchor.defaultBlockState(), Block.UPDATE_ALL);
 
-        if (sl.getBlockEntity(placeAt) instanceof VideoAnchorBlockEntity be) {
+        if (sl.getBlockEntity(anchorPos) instanceof VideoAnchorBlockEntity be) {
-            be.setFacing(ctx.getHorizontalDirection().getOpposite());
+            // Surface normal of the wall we're painting on points outward in the same direction
-            ServerPlayNetworking.send(sp, new OpenScreenPayload(placeAt, be.toNbt()));
+            // as the face the player clicked.
+            be.setFacing(face);
+            ServerPlayNetworking.send(sp, new OpenScreenPayload(anchorPos, be.toNbt()));
         }
         return InteractionResult.SUCCESS;
     }

src/main/java/com/ejclaw/videoplayer/registry/VideoPlayerBlocks.java

@@ -14,7 +14,12 @@ public final class VideoPlayerBlocks {
 
     public static final Block VIDEO_ANCHOR = register(
         "video_anchor",
-        BlockBehaviour.Properties.of().strength(1.0F).noOcclusion(),
+        BlockBehaviour.Properties.of()
+            .noCollision()
+            .noOcclusion()
+            .instabreak()
+            .replaceable()
+            .strength(0F),
         VideoAnchorBlock::new
     );
 

src/main/resources/assets/video_player/items/video_stick.json

@@ -0,0 +1,6 @@
+{
+  "model": {
+    "type": "minecraft:model",
+    "model": "video_player:item/video_stick"
+  }
+}

src/main/resources/assets/video_player/models/block/video_anchor.json

@@ -1,21 +1,5 @@
 {
-  "parent": "block/block",
   "textures": {
-    "all": "video_player:block/video_anchor",
     "particle": "video_player:block/video_anchor"
-  },
-  "elements": [
-    {
-      "from": [0, 0, 0],
-      "to": [16, 2, 16],
-      "faces": {
-        "down":  { "texture": "#all", "uv": [0, 0, 16, 16] },
-        "up":    { "texture": "#all", "uv": [0, 0, 16, 16] },
-        "north": { "texture": "#all", "uv": [0, 0, 16, 2] },
-        "south": { "texture": "#all", "uv": [0, 0, 16, 2] },
-        "east":  { "texture": "#all", "uv": [0, 0, 16, 2] },
-        "west":  { "texture": "#all", "uv": [0, 0, 16, 2] }
   }
-    }
-  ]
 }

src/main/resources/assets/video_player/models/item/video_stick.json

@@ -1,5 +1,5 @@
 {
-  "parent": "item/generated",
+  "parent": "minecraft:item/generated",
   "textures": {
     "layer0": "video_player:item/video_stick"
   }