Immersive Cinematics

2026-09-09 追加 — WebUI 时间头唯一源、独立飞控模块接入、时间轴滚动重构与图标体系

WebUI 时间头唯一源

• 前端 seek / play / pause / stop 不再直接写 state.time / state.playing，只发送命令，时间头与播放状态统一由游戏端 playback.state 回推，消除鼠标拖动与回推互相抢时间
• CameraManager.setTime 立即同步 gameTimeSeconds，修复 handleSeek 后紧接着 pushPlaybackState 读到旧时间导致的回跳
• 移除 ScriptStructure.vue（脚本结构树）；左侧面板（脚本/轨道/预设）移入编辑区内部；ScriptList 增加「刷新」按钮

独立飞控模块

• 新增 FlightModeManager：飞控会话与 EditorScreen 解耦，WebUI / 游戏内编辑器 / 键盘中转统一走同一入口，为后续移除游戏内编辑器后 WebUI 飞控独立工作做准备
• 职责内聚：进入（暂停相机 + 启用直控 + 初始化）、退出（返回最终相机数据）、取消（恢复进入前状态）、每帧 tick、键盘/鼠标事件转发、光学 reset（只恢复 FOV/Zoom/Roll，不动位置与朝向）
• WebUI 完整接入飞控：新增 editor.exit_flight_mode / editor.cancel_flight_mode 协议；进入飞控改用当前实际相机状态作为初始值（与 Java 编辑器行为一致），前端只传保存模式
• WebPreviewScreen 每帧驱动飞控并按 100ms 节流回推相机参数；新增飞控 HUD，展示鼠标/移动/升降/慢速/滚转/FOV/Zoom/模式切换/光学重置/保存退出/取消 的键位提示
• 前端 Preview 增加飞控浮层：实时位置、Yaw/Pitch/Roll、FOV/Zoom，以及「退出并保存 / 取消」按钮
• 修复 RELATIVE 模式落点：世界坐标先减去基准点（玩家位置/触发点）再写入 dx/dy/dz

时间轴

• 拖动会话：拖动中由前端驱动时间头并即时跟手，seek 改为 16ms 高频节流（原为 50ms 尾随防抖），松手后经短暂确认期再交回游戏端唯一源
• 拖动期间忽略游戏端 playback.state 的时间回推，避免互相抢；播放头、标尺、画布空白区域均可拖动
• 统一滚动容器：轨道头与画布合并进同一纵向滚动区，删除手动 scrollTop 同步；轨道头横向吸左（sticky），播放头改为贯穿标尺与全部轨道行的竖线
• 时间轴默认高度 260 → 320，响应式比例 28% → 34%（最小 280，最大 520）

音频 / 示例脚本

• AudioTrackPlayer 新增失败 clip 集合：缺失或无法加载的音频只记录一次并跳过该 clip，不再每帧重试刷异常
• demo 脚本移除音频轨，避免依赖不存在的示例音频

图标体系

• 模组图标 assets/immersive_cinematics/icon.png（256×256）：Fabric 由 fabric.mod.json 的 icon 引用，Forge 启用 mods.toml 的 logoFile 指向同一路径
• 编辑器应用图标：editor/build/icon.png（512×512）与 icon.ico（16/32/48/64/128/256 六尺寸），electron-builder.yml 增加 win.icon
• .gitignore 放行 editor/build/：该目录是 electron-builder 的图标源文件而非构建产物，否则 clone 后打包会退回 Electron 默认图标
• 编辑器标题栏 logo：原本的蓝色文字 IC 方块改为引用图标图片（editor/src/assets/icon.png）

2026-09-01 追加 — 虚拟相机中心：完全接入原版 ChunkMap 差集

预加载核心重构

• 新增 ChunkMapCameraMixin：向 ChunkMap 注入玩家 UUID → 虚拟相机 SectionPos，把 move / updatePlayerPos 的新中心重定向到相机；复用原版 DistanceManager 方形加载 ticket 与 isChunkInRange 客户端发送/遗忘差集
• 新增 CameraVirtualCenterAccess（位于 trigger.server，避免 Mixin 包引用限制）
• ChunkPreloadManager 改为“设置虚拟中心 → 调用原版 ChunkMap.move”，删除自建 desired / playerCovered / sentCamera / sentPlayer / resync / forget / sendCenter 手工链路
• 删除多片段预热：原版虚拟中心在片段激活时按原版规则加载，不再使用冗余 addRegionTicket 预热
• 删除自建 CameraEntitySyncManager：原版虚拟中心自动向真实玩家发送相机区实体
• 修复 Mixin 注入：getBlockX / getBlockZ 实际字节码 owner 为 ServerPlayer，target 改为 ServerPlayer 后正常
• 修复接口放入 mixin package 导致 IllegalClassLoadError，移至普通业务包
• 日志去重：仅相机模式或中心变化时才设置虚拟中心并触发 move；移除旧 [preload status/diff/send/resync/prewarm] 日志
• 清理 ChunkPreloadManager / ServerEventHandler 中全部废弃代码与字段

2026-08-31 追加 — 预加载状态边界统一差集、空片段处理、编辑器收尾与 WebUI 预留

预加载 / 相机区域

• 状态边界统一差集：区块预加载不再使用 far/near 距离门控；客户端按“当前视口”上报（活跃镜头=相机位置，空档=玩家位置），服务端在镜头切换、空档进出、脚本结束统一执行 desired - playerCovered - 已持有 差集
• 下一片段预热：接近下一个 CAMERA 片段起点时提前加 ticket 预热，镜头切过去后直接晋级到当前相机区，不重复加票
• 释放差集复用：脚本结束时按 playerNeed ∩ sentCameraChunks 复用已持有区块，只补发玩家区缺失块；不再强制客户端 allChanged() 全量重建
• 空片段/尾段空档处理：没有活跃 CAMERA 片段时上报玩家位置，让差集自然切回玩家区；尾段有空档的脚本结束后无需强制刷新
• 无 CAMERA 轨道脚本：客户端/服务端双重判断，不再触发预加载/释放
• 配置精简：移除旧预加载配置项（preloadWindowRadius、preloadMaxChunks、preloadMaxWorldgenChunks、preloadTimeoutGenerated/Worldgen、旧 preloadPrewarm、preloadFarViewCenterThreshold、preloadPlayerZoneRadius、preloadRearRadius）

HUD / 输入 / 兼容

• HUD/手臂行为不再依赖相机轨道；脚本命令标识改为 目录:文件名 冒号格式
• Forge/Fabric HUD 白名单工具，补齐 ActionBar/Title/保存提示
• 键鼠屏蔽改用中继层 + 公开 API，移除对私有字段的访问
• 修复相机实体缓存 NPE

触发器 / 测试

• 触发器前置条件改为“播放完成”语义，并支持自定义注册
• 修复 item_use_interrupt 松手时未记录物品，导致该触发器永不匹配
• 触发链测试脚本逐个补充“下一步提示 + 准备命令”

编辑器

• 字段控件按 FieldDef 类型驱动：bool→开关、tristate→三态、enum≤3→循环切换、enum>3→下拉
• 缺失的 bool/enum 字段直接显示正确控件，不再“添加后控件突变”
• 清理 schema.json 残留注释与编辑器 cam_tracking_* 特判
• ScriptPropertiesPanel 暴露 hud_layers、camera_mob_spawn、camera_mob_radius、camera_mob_ai
• 新增 SchemaExporter 与 FieldControl，为 WebUI 迁移预留 schema 导出与控件决策

文档 / 归档

• 0.3.5 计划文档归档到 plans/complete/0.3.5/
• 0.3.6 文档整理：删除被 WebUI 迁移取代的 UI 缩放布局方案；无假人相机区域方案归档到 0.3.5 并标记已实施

2026-08-22 追加 — 渲染优化模组兼容与 Forge 打包修复

Fixed

• 修复与 Sodium / Rubidium / Embeddium 的 LevelRendererMixin 注入冲突：检测到这三类渲染优化模组时跳过 LevelRendererMixin，由它们的 Camera/Frustum 管线接管渲染中心；CameraMixin 仍驱动虚拟相机，远端画面渲染功能保留
• 修复 Forge 普通 jar 因缺少 MixinExtras 无法启动的问题：Forge SoundEngineMixin 拆分为平台专属实现（Forge 用原版 @Redirect，Fabric 保留 @WrapOperation），Forge 不再依赖/内置 MixinExtras，普通 jar 可直接运行
• 新增跨平台 Mixin 配置插件 ImmersiveCinematicsMixinPlugin，用于按平台/环境条件跳过冲突 mixin
• 新增脚本 meta 开关 suppress_distortion：独立控制是否屏蔽屏幕扭曲（反胃/传送门旋转）；未设置时兼容旧行为（跟随 suppress_bob → hide_hud）
• 移除 GameRendererMixin 对 Mth.lerp 的 @Redirect：扭曲屏蔽改为播放期间临时设置原版 screenEffectScale 为 0，播放结束恢复；同时解决与 SecurityCraft GameRendererMixin 的注入冲突
• 安全化三处 @Redirect：SoundManagerMixin → @ModifyArg、LevelRendererMixin → @ModifyVariable、BubbleColumnAmbientSoundHandlerMixin → @ModifyArg，功能不变且降低与其他模组注入冲突的概率
• Mixin 配置插件去反射：ImmersiveCinematicsMixinPlugin 拆分为 Forge / Fabric 平台专属实现，分别直接使用 FMLLoader / ModList 与 FabricLoader API，不再使用 Java 反射

[0.3.5] - 2026-08-20

0.3.5：世界预加载与运镜体系、音频听者重构、编辑器/预设/GIF 增强、去除 Architectury 第三方依赖。

Added

• 脚本文件夹组织：scripts/ 支持子文件夹递归加载（深度 ≤ 5），编辑器/命令显示相对路径；id 仍全局唯一，子目录仅文件组织
• 触发器前置依赖：triggers[].requires: string[]（AND），全部前置脚本触发过才允许本触发器触发；validator 提示失效引用
• 呼吸扰动 v2：cam_breath_type（perlin / perlin_axis / sine / trauma）、cam_breath_speed，trauma 新增 cam_breath_trauma / cam_breath_decay
• look_at 相对目标：look_at_target 对象（绝对/触发点偏移/实体偏移/坐标偏移），兼容旧字段
• 动态 yaw 基准：yaw_base（world/entity/line）与 pitch_base，yaw 变为相对偏移，与 look_at 互斥；基准空间系 fwd/up/right
• 区块预加载统一：preload-camera-region-unified 设计落地——far-view 由隐藏假人驱动原版区块/实体追踪，退出时玩家区对账补发，实体中继与区块同源时序；脚本级 meta.preload 开关
• 预加载预热与释放复用：下一 CAMERA 片段按 prewarmLeadSeconds 提前加 ticket 预热；脚本结束用 playerNeed ∩ sentCameraChunks 差集复用，只需补发玩家区缺失块，近距离结束不再全量重发
• 预加载配置平台持久化：ForgeConfigSpec / Fabric JSON 接入全部预加载字段（cap/force/prewarm/playerZone 等），配置修改后跨重启生效
• 音频体系重构：meta.listener（player/camera）听者模式；AUDIO 轨道回归原版 SoundEngine，相对/绝对位置语义 + 默认衰减；环境音（群系/水下/气泡柱/animateTick）在 camera 模式采样到相机；编辑器音频联动重写
• 编辑器飞行取景：F6 + WASD/鼠标操控相机取景，可记录/取消；编辑器模块化 + 面板重构
• Schema Java 元数据化：schema.json 迁移为 Java FieldDef / TrackSchemas / SchemaRegistry，编辑器/解析器/默认值共用
• GIF Overlay：stbi_load_gif 拆帧 + 单帧 DynamicTexture 轮播，带内存上限与释放
• 预设系统：参数 schema + 生成函数注册，初版预设库（环绕轨道等），生成结果可编辑
• 去除 Architectury：MultiLoader 重构，common/forge/fabric 三模块，无第三方前置依赖

Changed

• README/README_CN 版本更新为 0.3.5；文档补充 meta.preload、目录组织、触发器前置依赖
• 预加载日志节流：高频包按秒聚合，关键包（AddEntity/chunk/center/remove）保留逐条
• Forge 假人就位时序：先 moveTo 相机坐标再 bootstrap，初始实体与区块按原版 addNewPlayer 顺序送达

Fixed

• Forge 远距离实体数量偏少：同一村庄位置下客户端 radius=64 实体数从 ~20 提升到 ₆₀66，与 Fabric 同区间
• 修复 Forge 实体中继中 ClientboundBundlePacket 解包转发时序
• 清理 ChunkPreloadManager 死代码（requestTickets/sendReady/desired/ticketed/sent 残留）