docs: add missing javacpp native jar to install guide (v0.4.3)
Some checks failed
build / build (push) Has been cancelled
Some checks failed
build / build (push) Has been cancelled
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.
This commit is contained in:
tkrmagid
38
README.md
38
README.md
@@ -3,7 +3,7 @@
|
||||
마인크래프트 안에서 임의의 동영상 URL을 벽·바닥·천장에 평면으로 재생하는 Fabric 모드.
|
||||
|
||||
- 모드 ID: `video_player`
|
||||
- 현재 버전: **0.4.2**
|
||||
- 현재 버전: **0.4.3**
|
||||
- 마인크래프트 버전: **26.1.2**
|
||||
- 필요 Java: **25** (마인크래프트 26.x 가 요구함)
|
||||
|
||||
@@ -53,9 +53,9 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
- 받은 `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.2.jar` 를 다운로드해서 같은 `mods` 폴더에 넣습니다.
|
||||
- `video_player-0.4.3.jar` 를 다운로드해서 같은 `mods` 폴더에 넣습니다.
|
||||
|
||||
이전 버전(`video_player-0.4.0.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다.
|
||||
이전 버전(`video_player-0.4.0.jar`, `0.4.2.jar`, `0.3.x.jar` 등)이 mods 폴더에 남아있다면 **반드시 삭제**하세요. 두 개가 같이 있으면 마인크래프트가 충돌로 켜지지 않습니다.
|
||||
|
||||
### STEP 5. 영상 재생 라이브러리 (JavaCV) 설치
|
||||
|
||||
@@ -70,7 +70,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
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 4개를 한꺼번에 선택해서 추가
|
||||
4. 아래 STEP 5-B 의 1번 항목에서 받은 JavaCV jar 5개를 한꺼번에 선택해서 추가
|
||||
5. **Launch** 로 실행
|
||||
|
||||
이 방법이 가장 안정적이고 빠릅니다.
|
||||
@@ -81,36 +81,41 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
|
||||
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 4개**를 골라 둡니다 (다른 파일은 안 씁니다):
|
||||
- 압축을 풀고 `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 **하나**:
|
||||
- 자신의 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. **이 4개 jar 를 게임이 읽도록 등록**
|
||||
- 가장 안전한 위치: `.minecraft/libraries/javacv/` 폴더를 새로 만들고 4개 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\ffmpeg.jar;C:\Users\홍길동\AppData\Roaming\.minecraft\libraries\javacv\ffmpeg-windows-x86_64.jar
|
||||
-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:
|
||||
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/ffmpeg.jar:/Users/사용자이름/Library/Application Support/minecraft/libraries/javacv/ffmpeg-macosx-arm64.jar
|
||||
-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/ffmpeg.jar:/home/사용자이름/.minecraft/libraries/javacv/ffmpeg-linux-x86_64.jar
|
||||
-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
|
||||
```
|
||||
|
||||
주의:
|
||||
@@ -118,7 +123,8 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
- macOS/Linux는 **콜론(`:`)** 으로 구분합니다.
|
||||
- 경로에 띄어쓰기가 있으면(특히 macOS의 `Application Support`) 전체 인수를 큰따옴표로 감싸세요.
|
||||
- `사용자이름` 부분은 실제 자신의 사용자 폴더 이름으로 바꾸세요.
|
||||
- ffmpeg-... 부분의 jar 이름은 OS에 맞춰 1번에서 고른 그 파일명 그대로 적습니다 (zip 안에는 `ffmpeg-windows-x86_64.jar` 같은 짧은 이름으로 들어있습니다).
|
||||
- `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. 저장 후 **플레이** 를 누르면 영상이 재생됩니다.
|
||||
|
||||
@@ -129,7 +135,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
게임 안에서 채팅창에 `/videostick` 을 입력하세요. 정상이라면:
|
||||
|
||||
- 인벤토리에 **비디오 스틱** 아이템이 들어옵니다 (보라/검정 missing-texture 가 아니라 작대기 모양 아이콘).
|
||||
- 보라/검정 missing texture 가 나오면 **STEP 4** 에서 이전 버전 jar(`video_player-0.4.0.jar` / `0.4.1.jar` 등)가 mods 폴더에 같이 남아있는 경우입니다. 다 지우고 `0.4.2` 만 남기고 다시 시작하세요. (0.4.1 이하는 Fabric 26.1.2 model 로더가 unprefixed `item/generated` parent 를 거부해서 스틱 아이콘이 missing-model 큐브로 보입니다 — 0.4.2 에서 수정됨.)
|
||||
- 보라/검정 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 에서 수정됨.)
|
||||
|
||||
---
|
||||
|
||||
@@ -165,7 +171,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
|
||||
## 알려진 이슈
|
||||
|
||||
- JavaCV가 안 잡혀있으면 영상 자리만 잡힐 뿐 검게 보입니다. 로그 파일(`.minecraft/logs/latest.log`)에서 `JavaCV not on classpath` WARN 메시지로 확인 가능합니다.
|
||||
- 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) 에서 보이지 않으니 다시 배치해야 합니다.
|
||||
|
||||
---
|
||||
@@ -176,7 +182,7 @@ Fabric은 마인크래프트에 모드 기능을 추가해 주는 로더입니
|
||||
JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 ./gradlew build
|
||||
```
|
||||
|
||||
산출물: `build/libs/video_player-0.4.2.jar`
|
||||
산출물: `build/libs/video_player-0.4.3.jar`
|
||||
|
||||
JavaCV를 직접 의존성으로 가져오는 경우의 Maven 좌표:
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user