ImmersiveCinematics

[0.3.4] - 2026-08-06

音乐配乐 + 覆盖层 + 事件重构 + 镜头追踪与呼吸扰动 + 翻滚角修复。

2026-08-10 追加 — 字幕两级缩放、OVERLAY 中心锚点、循环增强、结构中心定位、相对基准扩展、透明度补全修复

OVERLAY 字幕缩放（用户需求：字号与固定字号缩放分离）

• font_scale 关键帧：字号倍数（1 = 原版 9px），矩阵缩放实现，与 MC /title 大字同一机制；scale_x/scale_y 在固定字号基础上做百分比缩放（与图片 scale 语义一致），两级叠加（最终 = font_scale × scale_x/y）
• schema 补 font_scale 字段，编辑器属性面板/默认值自动对齐（schema 驱动）

OVERLAY 锚点统一为元素中心

• x/y = 0.5 即屏幕居中（不再手算左上角偏移）；ImageLayer/SubtitleLayer 按渲染尺寸/2 偏移；旧脚本按"中心 = 左上角 + 尺寸/2"迁移（仓库脚本与文档同步）

循环功能增强

• loop_mode 支持 "repeat"（默认）与 "pingpong"（往复折返，监控视角来回摇，关键帧只写半程）
• 无限循环（loop: true + loop_count: -1）已开始的片段使脚本永不自然结束（唯一退出 = skippable/interruptible 手动退出）
• loop_count: 0 解析报错并按 1 处理；Clip 新增窗口语义（getWindowEnd/getAnimPeriod/isEffectivelyInfinite）

结构目标改为真中心

• 新增 StructureLocator：findNearestMapStructure 锚点（/locate 同源，结构起点）→ STRUCTURE_STARTS → getBoundingBox().getCenter()，返回结构几何中心（含 +0.5 块中心偏移）
• look_at_target_structure 与 position.relative_origin（结构 id）均按结构中心解析，服务端推送前替换为坐标（多人生效），编辑器预览（单人）客户端直连兜底；就近搜索 100 区块，不做无限查找

position 相对基准扩展（relative_origin）

• 相对模式基准可选：缺省 = 玩家激活位置；"coordinate" = 相对固定坐标（relative_origin_x/y/z）；结构 id = 相对结构中心

编辑器

• look_at 坐标/结构互斥：coordinate 模式下指定结构后坐标输入隐藏，结构下拉选"（空）"自动恢复
• 脚本重组：showcase_welcome 拆分为 showcase_01_welcome / showcase_02_kill_sheep / showcase_03_village

修复

• 字幕低透明度被补全为不透明（根因：opacity 量化为 alpha 0~3 时颜色 alpha 高 6 位为 0，触发 MC Font.adjustColor() 的"未指定 alpha"补全 → 0x00FFFFFF → 0xFFFFFFFF，透明度 <1.6% 的文字反而满透明度渲染；表现为渐出/渐入段末尾闪现全亮文本）。修复：alpha < 4 直接跳过渲染；代码注释与文档记录该坑，未来走 Font 的 fade 需避开（ImageLayer 走 shader 颜色不受影响）

2026-08-09 追加 — 触发器完成、播放队列、编辑器事件树重构、预览与网络加固

触发器（23 种，custom 删除）

• 接线 item_on_interact（物品+目标+target_type，支持空手 ""）与 advancement（PLAYER_ADVANCEMENT 事件携带 id 匹配，不再误判历史进度）
• 新增 ItemUseMixin 覆盖使用状态机：item_consume（用完，completeUsingItem）/ item_release（弓/弩/三叉戟/望远镜松手，UseAnim 判定）/ item_use_interrupt（吃一半松手等）
• 新增 item_instant_use（投掷物实体判定：雪球/鸡蛋/珍珠/药水/经验瓶）、xp（等级/累计经验轮询）、dimension（维度驻留轮询）、item_pickup/item_drop（拾取/丢弃事件）
• 新增 observation（服务端射线注视，block/entity/缺省近者优先，reach 可配）
• entity_kill 场景条件：dimension/biome/position/corner1+corner2（按击杀时刻记录，非玩家当前位置）
• 删除 custom 触发器（注册/求值/编辑器/文档/示例脚本全清）
• B5 触发器状态同步：触发/完成/JOIN 补发 S2CTriggerStateSyncPacket

播放队列（C1，用户确认规则）

• ScriptQueue 容量 8：不可打断脚本播放时新请求一律排队（priority 降序 + FIFO），结束自动接播；可打断脚本被请求立即替换（无渐出）
• 优先级不能大于打断：priority 仅用于队列内排序；移除 queueable 参数与高优先级强制抢占
• 客户端 /icinematics queue 查询命令不实施（与服务端命令根冲突）

编辑器

• 事件树命中统一绝对屏幕坐标（修复面板/预览区点击错位：absX/absY 双加父偏移）；滚动容器语义化（getScrollOffset 沿父链），移除 pushScroll 改 mouseY 的坐标补偿
• 鼠标事件模板加容器裁剪（滚动区外不再命中不可见内容）；tab 栏固定不随内容滚动；切模式滚动归零（修复面板"全白"）
• 顶部状态栏移除脚本列表按钮（面板 tab 已覆盖）；播放/暂停合并 toggle 按钮；终止按钮改为重置播放头到第一帧（保持预览激活，不再退出到玩家视角；玩家视角由脚本时间空隙自然产生）
• 预览器修复：编辑器加载不同轨道布局脚本后轨道索引错位（OVERLAY 层不创建/音频误读）→ replaceScript 按布局重建 TrackPlayer；捕获前 flush GUI 缓冲（覆盖层落盘）
• E1 布局常量提取、E3 letterbox smoothstep、E4 删除无用 MathUtil 方法

网络加固

• 新增 NetworkGuard：所有 C2S 发包统一防护，玩家随时退出/断线不再因 sendToServer 抛异常闪退（覆盖脚本结束通知/暂停握手/ACK 重发/回执）

其它

• ScriptValidator position 检查限定 CAMERA 轨道（消除非 CAMERA 轨道误报）；新增 9 个触发器冒烟测试脚本
• 统一关键帧级调控（用户决定）：删除 letterbox clip 级 aspect_ratio 简写兼容与 EVENT clip 级 command 向后兼容——所有轨道一律以 keyframes 调控，旧格式脚本需改写（校验会报缺 keyframes）；补建 inventory change 冒烟脚本（共 10 个）

Added

• AUDIO 轨道：OGG/WAV 音频播放（LWJGL OpenAL 直驱），关键帧控制音量与空间位置，淡入淡出、循环、衰减
• OVERLAY 轨道：fade 全屏遮罩 / image 图片 / subtitle 字幕 / pip 画中画四类覆盖层，多层叠加按 zIndex 渲染
• EVENT 轨道重构：从 clip 段改为 keyframe 驱动多点触发，&& 命令链、权限 4 执行
• 镜头追踪：CAMERA clip 级 cam_tracking_look_at（注视坐标/实体）+ cam_tracking_follow（跟随玩家）
• 镜头呼吸扰动：cam_breath_enabled / cam_breath_intensity / cam_breath_seed 运行时叠加随机微晃
• 翻滚角（roll）修复：改为绕相机视线轴旋转，任何朝向下 roll>0 均为屏幕顺时针（画面向右倒）
• 删除景深（dof）字段：原版 MC 无景深能力，全链路移除（代码/schema/文档/测试脚本）
• Fabric Loader 要求降至 0.14.0：兼容主流整合包（原 0.19.3 为开发版本误写）
• 新增 docs/AI_SCRIPTING_GUIDE.md：面向 AI 的脚本编写指南（空间方向体系/速度档位/运镜配方/常见错误）
• 参考脚本：cinematics/example_orbit.json 重写为《第二圆舞曲》配乐脚本，18 段运镜覆盖全部可控字段（静态/直摇/慢推/摇入/环绕/推变焦/微摆/甩镜头/升降/航拍/俯拍/降落/希区柯克变焦/快环绕/荷兰角/拉远/离场/定格）
• 音频文件非 ASCII 命名时输出警告（Windows 下 stb_vorbis fopen 无法解码中文路径）

Changed

• 音频资源统一英文命名规范（写入指南与格式文档）