Lumina Flow

A Minecraft client enhancement mod with two core features: shaderpack quick-switching and in-game CG video playback.

---

Feature 1: Shaderpack Switcher

Switch or disable shaderpacks in-game with simple commands — no need to open the shader selection screen.

Requirements

• Oculus — required
• Embeddium (recommended) — performance optimization, common Oculus companion

Commands

Command	Description
/shader list	List all shaderpacks in the shaderpacks/ directory
/shader set <name>	Switch to the specified shaderpack
/shader off	Disable shaders
/shader reload	Reload the current shaderpack
/shader status	Show current shader status

All subcommands support an optional <target> selector (e.g. @p, @a):

/shader list
/shader list @p
/shader set BSL_v8.2
/shader set BSL_v8.2 @s
/shader off
/shader off @r
/shader reload
/shader reload @p
/shader status
/shader status Steve

---

Feature 2: CG Video Playback

Play MP4/WMV videos directly inside Minecraft. Built-in FFmpeg decoder with auto-download — no manual installation required.

First Launch

The mod automatically downloads FFmpeg DLLs (~85MB, one-time) on game startup. Download and extraction run in the background; you can play without waiting. Progress is logged in debug.log.

Setup

1. Create an mp4/ folder in your game directory (auto-created on first launch)
2. Place video files (.mp4 or .wmv) into the mp4/ folder

Commands

Command	Description
/cg play <name>	Play a video for yourself (Tab-completion for filenames)
/cg play <name> <target>	Play a video for target player(s) (OP required)
/cg stop	Stop playback for yourself
/cg stop <target>	Stop playback for target player(s) (OP required)
/cg list	List video files in mp4/

Target examples:

/cg play fahanay.mp4              ← Play for yourself
/cg play fahanay.mp4 @a           ← Play for everyone (OP)
/cg play test.mp4 @p              ← Play for nearest player (OP)
/cg play demo.mp4 Steve           ← Play for a specific player (OP)
/cg stop                          ← Stop yourself
/cg stop @a                       ← Stop everyone (OP)

Controls

• Press ESC to exit video playback
• Supports 44100Hz/48000Hz mono/stereo audio (auto-converts FLTP/S16P planar formats)

Tips

Q: No audio or distorted audio.
A: Make sure the video file contains an audio stream. The mod handles common planar formats (FLTP, S16P, etc.) and converts to S16 automatically.

Q: Video stutters or skips frames.
A: Playback is paced at 30fps. If the source video has a lower framerate, this is expected.

Q: Where is the mp4/ folder?
A: The mod creates it automatically in the game directory on startup. For integrated servers, place it in the server root directory.

---

Installation

1. Install Minecraft Forge 1.20.1
2. Place lumina_flow-1.1.0.jar into the mods/ folder
3. (Optional) Install Oculus + Embeddium for shader features
4. Launch the game — all dependencies (FFmpeg DLLs) are auto-downloaded in the background

About the JNA dependency

The mod uses JNA to call native FFmpeg libraries for video decoding.

• If your mods/ folder already has other mods depending on JNA (common in modpacks), the mod works out of the box
• If /cg reports FFmpeg not available, download jna-5.14.0.jar into your mods/ folder
• JNA download: Maven Central

---

How It Works

• Shader switching: Uses Oculus's public API to modify IrisConfig and call Iris.reload()
• Video playback: JNA calls native FFmpeg libraries for decoding; audio via SourceDataLine; video rendered via manual YUV→RGB → DynamicTexture
• Network sync: Server sends CGBindPacket via SimpleChannel; client plays the video

---

FAQ

Q: /shader commands don't work.
A: Make sure Oculus is installed.

Q: /cg says FFmpeg not available.
A: Check debug.log for download errors. The mod auto-downloads FFmpeg on first launch; it may take a few seconds. If it still says FFmpeg is unavailable, verify JNA is on the classpath (either provided by another mod or manually installed).

Q: Can /cg play <name> <target> be used on multiplayer servers?
A: Yes, with OP permission (level 2). Video files are read from the server's mp4/ directory.

Q: Nothing changed after switching shaders.
A: Try /shader reload to force a reload.

Lumina Flow

一个综合 MC 客户端增强模组，包含光影包快速切换和 CG 视频播放两大功能。

---

功能一：光影包切换

无需打开光影选择界面，在游戏中直接用命令切换或关闭光影包。

前置要求

• Oculus — 必须安装
• Embeddium（推荐）— 性能优化，Oculus 常见搭档

命令

命令	作用
/shader list	列出 shaderpacks/ 目录下所有光影包
/shader set <名称>	切换到指定光影包
/shader off	关闭光影
/shader reload	重载当前光影包
/shader status	查看当前光影状态

所有子命令均可选加 <target> 目标选择器（如 @p、@a）：

/shader list
/shader list @p
/shader set BSL_v8.2
/shader set BSL_v8.2 @s
/shader off
/shader off @r
/shader reload
/shader reload @p
/shader status
/shader status Steve

---

功能二：CG 视频播放

在游戏内播放 MP4/WMV 视频，内置 FFmpeg 解码器，无需额外安装解码器。

首次使用

模组会在游戏启动后自动下载 FFmpeg DLL（~85MB，仅首次），下载和解压在后台进行，不影响进入游戏。进度可查看日志 debug.log。

使用前准备

1. 在游戏目录下创建 mp4/ 文件夹（启动游戏会自动创建）
2. 将要播放的视频文件（.mp4 或 .wmv）放入 mp4/ 文件夹

命令

命令	作用
/cg play <文件名>	自己播放视频（文件名支持 Tab 补全）
/cg play <文件名> <目标>	给指定玩家播放（需要 OP 权限）
/cg stop	自己停止播放
/cg stop <目标>	停止指定玩家的播放（需要 OP 权限）
/cg list	列出 mp4/ 目录下的视频文件

目标选择器示例：

/cg play fahanay.mp4              ← 自己播
/cg play fahanay.mp4 @a           ← 播给所有人（OP）
/cg play test.mp4 @p              ← 播给最近的玩家（OP）
/cg play demo.mp4 Steve           ← 播给指定玩家（OP）
/cg stop                          ← 自己停
/cg stop @a                       ← 停所有人（OP）

操作

• 播放中按 ESC 键退出视频
• 支持 44100Hz/48000Hz 单声道/立体声音频（自动转换 FLTP/S16P 格式）

常见问题

Q: 播放时没有声音或声音异常。
A: 确保视频文件包含音频流。模组支持常见的 planar 格式（FLTP、S16P 等），会自动转换为 S16 播放。

Q: 视频卡顿或跳帧。
A: 视频以 30fps 帧率播放，若视频本身低于 30fps 属正常现象。

Q: 为什么 MP4 文件夹不在游戏目录下？
A: 启动游戏后模组会自动创建 mp4/ 文件夹。集成服务器环境下请放在服务端根目录。

---

安装

1. 确保已安装 Minecraft Forge 1.20.1
2. 将 lumina_flow-1.1.0.jar 放入 mods/ 文件夹
3. 可选安装：Oculus、Embeddium（光影功能需要 Oculus）
4. 启动游戏，所有依赖（FFmpeg DLL）会在后台自动下载

关于 JNA 依赖

模组使用 JNA 调用 FFmpeg 原生库解码视频。

• 如果你的 mods/ 文件夹中已有其他模组依赖 JNA（常见于大型整合包），本模组可直接使用
• 若启动后 /cg 命令提示 FFmpeg not available，请下载 jna-5.14.0.jar 放入 mods/ 文件夹
• JNA 下载地址：Maven Central

---

工作原理

• 光影切换：通过 Oculus 的公开 API 操作 IrisConfig 并调用 Iris.reload()
• 视频播放：使用 JNA 直接调用 FFmpeg 原生库解码视频帧，通过 SourceDataLine 输出音频，手动 YUV→RGB 渲染到 DynamicTexture
• 网络同步：服务端通过 SimpleChannel 发送 CGBindPacket，客户端播放视频

---

常见问题

Q: 为什么用不了 /shader 命令？
A: 请确保已安装 Oculus mod。

Q: /cg 命令提示找不到 FFmpeg。
A: 检查 debug.log 中是否有下载错误信息。首次启动后模组会自动下载 FFmpeg DLL，可能需要等待几秒。若提示 FFmpeg 不可用，请确认 JNA 已正确加载（检查是否有其他模组提供了 JNA，或手动安装 jna-5.14.0.jar）。

Q: 联机模式下 /cg play <文件名> <目标> 能用吗？
A: 能，需要 OP 权限（level 2）。默认播放文件取自服务端 mp4/ 目录。

Q: 切换光影后画面没变？
A: 试试 /shader reload 强制重载。