猹件开发组视频组件
视频组件用于在 ChaUI 页面中播放本地或网络 MP4，适合开场动画、剧情片段、教程演示和动态背景。第一版仅保证 Windows x64 客户端播放 H.264 视频与 AAC 音频，不依赖 MCEF 或 HTML。
视频来源
本地视频路径相对于当前游戏版本目录下的 resourcepacks/ChaUI/：
video/intro.mp4
→ .minecraft/resourcepacks/ChaUI/video/intro.mp4网络视频只支持直接返回 MP4 数据的 http:// 或 https:// 地址。不支持网页播放器地址、HLS、直播流和其他协议。
网络视频会边下载边播放，响应内容只进入当前页面会话的内存分块缓冲，不会写入素材目录、系统临时目录或 ChaUI 视频缓存文件。组件隐藏、删除、切换来源或页面关闭时，会取消请求并释放下载缓冲、解码器、音频队列与动态纹理。
通用配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
id | ID | 字符串 | 自动生成 video_N | 页面内唯一组件 ID。 |
type | 类型 | 只读字符串 | video | 创建后不可修改。 |
parent | 父级 | 字符串 | 空 | 可指向布局组件。 |
z | 层级 | 整数 | 0 | 数值越大越晚绘制。 |
visible | 显示 | 布尔值 | true | 变为不可见时立即销毁播放会话。 |
enabled | 启用 | 布尔值 | true | 控制组件事件是否可触发。 |
pointerEvents | 指针处理 | 枚举 | auto | 配置事件或提示后 auto 命中；block 强制遮挡，pass 永远穿透。 |
scale | 缩放 | 数字或公式 | 1 | 以视频中心缩放画面和命中范围，不改变布局值。 |
opacity | 透明度 | 数字或公式 | 1 | 0 至 1，控制视频画面透明度，不改变命中。 |
visibleWhen | 显示条件 | 条件表达式 | 空 | 条件变为假时停止并释放视频资源。 |
enabledWhen | 启用条件 | 条件表达式 | 空 | 条件为假时不响应交互。 |
tooltip | 多行提示 | 字符串列表 | 空 | 最多 32 行，每行最多 256 字符。 |
containerBinding | 容器绑定 | 字符串 | 空 | 仅容器替换页面使用，可读取绑定物品信息。 |
containerTooltip | 容器提示 | 布尔值 | true | 没有显式 tooltip 时是否显示绑定物品提示。 |
layout.x / layout.y | X / Y | 数字或公式 | 创建位置 | 使用 ChaUI GUI scaled 坐标。 |
layout.width | 宽 | 数字或公式 | 160 | 视频显示区域宽度。 |
layout.height | 高 | 数字或公式 | 90 | 视频显示区域高度。 |
events.leftPress/rightPress/middlePress | 按下脚本 | ChaUI Script | 空 | 对应按键按下时触发。 |
events.leftRelease/rightRelease/middleRelease | 松开脚本 | ChaUI Script | 空 | 对应按键捕获仍有效并松开时触发。 |
events.leftClick/rightClick/middleClick | 点击脚本 | ChaUI Script | 空 | 在同一组件完成按下和松开后触发。 |
视频配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 范围或可选值 | 说明 |
|---|---|---|---|---|---|
video.path | 视频路径 | 字符串 | video/video_N.mp4 | 本地相对路径或 HTTP/HTTPS MP4 直链 | 切换路径会销毁旧会话并从新源重新开始。 |
video.autoplay | 自动播放 | 布尔值 | true | true、false | 准备完成后是否自动播放。 |
video.loop | 循环播放 | 布尔值 | false | true、false | 播放结束后是否循环。 |
video.startTimeMs | 起播毫秒 | 非负整数 | 0 | 0 至长整数上限 | 首次播放和循环的起始位置。 |
video.playbackRate | 播放速度 | 数字 | 1.0 | 0.25 至 4.0 | 视频节奏与音频 tempo 同步调整。 |
video.volume | 音量 | 数字 | 1.0 | 0.0 至 1.0 | 最终音量还会乘客户端主音量。 |
video.muted | 静音 | 布尔值 | false | true、false | 静音时仍保持播放时钟。 |
video.fit | 画面适配 | 字符串 | contain | contain、cover、stretch | 控制源画面如何放入组件矩形。 |
画面适配含义：
contain：保持比例完整显示，可能留黑边。cover：保持比例铺满，居中裁掉超出部分。stretch：直接拉伸到组件宽高，可能变形。
配置示例
- id: intro_video
type: video
visible: true
enabled: true
pointerEvents: auto
scale: 1
opacity: 0.9
z: 10
layout:
x: window.width * 0.5 - 160
y: window.height * 0.5 - 90
width: 320
height: 180
video:
path: video/intro.mp4
autoplay: true
loop: false
startTimeMs: 0
playbackRate: 1.0
volume: 1.0
muted: false
fit: contain示例文件由服务器管理员或客户端更新 Mod 放入玩家本地；ChaUI 服务端不会分发 video/intro.mp4。
脚本控制
视频控制是客户端当前页面会话的本地动作，不发送新的服务端命令。下面这段可以直接放进 intro_video 组件：
events:
leftClick: |-
component("intro_video").video.pause()
rightClick: |-
component("intro_video").video.play()
middleClick: |-
component("intro_video").video.seek(15000)
hoverLeave: |-
component("intro_video").video.stop()中文等价写法：
events:
leftClick: 组件("intro_video").视频.暂停()
rightClick: 组件("intro_video").视频.播放()
middleClick: 组件("intro_video").视频.跳转(15000)
hoverLeave: 组件("intro_video").视频.停止()component("intro_video") 返回视频组件对象，所以还可以读取当前 video.path、video.volume、video.muted、video.playbackRate 与 video.loop。脚本和 state_patch 也可以临时修改这些开放字段；非法值会被安全忽略。
网络安全与内存限制
默认禁止访问 localhost、回环地址、链路本地地址和私有网段，避免页面配置借客户端访问本机或局域网服务。确有内网媒体服务器需求时，玩家需要在 .minecraft/config/chaui-video.properties 中显式启用：
allowPrivateNetworkHosts=true常见问题
本地视频提示加载失败
确认文件位于当前版本的 .minecraft/resourcepacks/ChaUI/ 下，路径没有绝对路径、反斜杠、.. 或错误扩展名，并确认视频编码为 H.264/AAC MP4。
网络视频一直缓冲
确认 URL 直接返回 MP4，响应类型和文件头正确，并优先启用 Range 或使用 faststart/fragmented MP4。
页面关闭后还有声音
正常实现会在页面关闭、组件隐藏或来源切换时停止并释放音频。若仍有声音，请保留 latest.log 并检查页面是否存在另一个 HUD 或世界页面实例正在播放同一视频。
创建事件
视频组件支持 events.create，可在实例创建时设置来源、显隐或配合脚本决定播放状态。初始视频和动态视频实例各触发一次。页面关闭、reload 和退出预览都会释放当前作用域的解码、音频与内存下载数据。