场景录制器与可视化编辑器

场景录制器以绑定的触发方块为参照，采集镜头姿态和演员路点。可视化编辑器提供含 5 类关键帧的本地时间线，再将场景定义导出到服务端配置目录；导出不会安装或重载数据包。

你要做的东西

结果是过场场景数据中描述的 JSON。编辑器序列化的是带类型的 SceneAuthoringDraft，不是自由格式 JSON。未知字段不会保留，导出时会先规范化支持的字段，再进行校验。

制作过程中有两份文档：按玩家 UUID 保存的服务端录制样本，以及包含手动编辑的客户端 SceneEditorDocument。服务端会话仅保存在内存中，此录制器没有磁盘保存或断线清理。编辑器界面销毁时，本地文档随之丢弃；重新打开会从服务端样本重建，不会导入上次导出文件或触发器已有的场景。

前置要求

触发器编辑器、录制器动作包和可见制作辅助线均要求创造模式及权限等级 2。/ise dev scene 命令分支要求权限等级 2 和玩家来源，但直接录制方法并非都会再次检查创造模式。这些内部方法不是自带独立权限保护的 API。

绑定真实的 isekaiexpansion:scene_trigger，且与其中心距离不超过 8 方块。绑定命令最远射线检测 32 方块，但实际绑定仍执行较短的距离限制。触发器中心和水平朝向决定采集变换。仅运行 pivot here 或 pivot block 会清除绑定，不能满足采集/导出的绑定要求。

重新绑定会改变变换，但不会清除已有样本。除非有意将旧局部坐标移到新触发器，否则在改换原点或朝向前先清空录制器。会话只保存方块位置，没有维度键；不要将已绑定会话带到另一维度后假定它仍指向原触发器。

步骤

1. 在创造模式放置场景触发器，对准它运行 /ise dev scene bind。
2. 将镜头移到开场位置，运行 /ise dev scene camera add 0；再移到另一位置并采集较晚的刻。回复包采样客户端实际镜头，滚转固定为零，FOV 取自选项设置，不是最终经过动态修正的 FOV。
3. 使用 actor point 或 actor pointEntity 采集演员位置。时间单位为刻，每秒 20 刻。每名演员的首个点生成贴地姿态；有多个点时，还会生成一条步行路径。
4. 打开 /ise dev scene editor，选择时间线关键帧，调整对应检查器，按需添加效果、世界事件或字幕。先完成采集，再精修采集帧，因为后续同步可能替换其值。
5. 设置有效场景 ID，检查播放开关，并选择导出时是否将该 ID 分配给绑定触发器。关闭界面前导出可视化草稿。
6. 在服务端检查导出的 JSON，将确认采用的结果复制到数据包的 data/<namespace>/cinematic_scenes/<path>.json，再重载服务端数据。
7. 用符合条件的生存玩家测试触发器。创造玩家可编辑触发器，但不能触发或观看服务端场景。重播历史可能阻止再次尝试；测试时使用可重复触发器并等待其冷却。

命令

下列命令均接在 /ise dev scene 后；规范入口 /isekaiexpansion dev scene 与之等效。

镜头采集会替换同一刻的旧样本。演员样本按演员键与刻替换，键名使用共享格式进行规范化。选定实体进行采集只记录姿态，不会持久绑定到该实体：生成的非玩家演员使用 nearest、半径 16 方块，且没有类型/名称/UUID 过滤。导出可视化文档前，应配置所需选择器。

工作区与时间线

编辑器包含透明世界视口、分区栏、检查器和时间线，不暂停游戏，也不请求背景模糊。分区涵盖场景设置、演员定义、镜头、演员指令、镜头效果、世界事件和字幕。底层字段、默认值与运行时限制见数据参考。

采集帧带有圆环标记，检查器中不提供删除按钮，但仍可重定时或编辑。同步按排序列表索引合并镜头采集，保留原来编辑后的时间、注视目标与缓动，替换位置、旋转及 FOV。演员采集同步保留编辑后的指令起始时间，但重新生成姿态/路径内容、时长、模式和朝向。因此，插入更早的采集可能使现有已编辑关键帧对应到不同样本。先清空或重建采集，再做最终手动调整。

默认可视化文档从 160 刻（8 秒）开始；录制视图可增加时长，但不会缩短它。纯采集草稿时长为最晚样本刻加 40 刻（2 秒），至少 60 刻（3 秒）。演员路径时长为末点时间减首点时间，至少 1 刻（0.05 秒）。中间样本时间戳决定点顺序，不会成为各段独立时长。

重命名演员会更新指令归属键，但不会更新全部注视/朝向目标引用。移除演员会保留采集指令，草稿构建器可能为残留引用重新创建默认演员。重命名或移除演员后需检查引用。

新关键帧默认值

下表是编辑器插入值，可能与 JSON 省略字段时的默认值不同。

新增非玩家演员默认为 nearest，半径 16；player 使用 triggering_player，半径 0。采集生成的镜头帧使用 ease_in_out_quad；采集移动使用 walk、速度 1 和 walk_target 朝向。中间采集点的偏航不会转换成独立朝向关键帧。

字段输入与辅助线

向量必须由三个数字组成，以逗号或空白分隔。路径用分号分隔向量，例如 0, 0, 0; 0, 0, -4。无效向量行会跳过；若没有任何有效行，则保留现有路径。无效标量输入通常保留原值，整数字段另有各自下限。浮点文本解析不拒绝非有限值，因此制作时应使用有限数字。

可选 ID 或 UUID 留空会清除，非空但无效时保留原值。可空文本留空会清除。字幕颜色接受带可选 # 的十六进制文本；最多 6 位时补上不透明 alpha，无效输入保留原色，颜色 0 继承主题。部分控件显示便于编辑的值：没有 FOV 的镜头节点显示 60，编辑该字段后便成为显式值。

世界辅助线仅在创造模式操作员关闭调试叠层、且当前世界仍存在绑定触发器时显示。它们绘制镜头关键点、直线连接、演员路径和事件点。镜头视锥是示意图，不是按实际 FOV 采样的预览；移动播放头不会求值场景。采集后改变触发器朝向也会改变辅助线方向，而录制器在重新绑定前仍保留原采集变换。

声明它

导出将 UTF-8 格式化 JSON 写到服务端进程的 config/isekaiseries/scene_exports/<namespace>/<path>.json。专用服务器写入服务器机器，而不是作者客户端。相同路径会被覆盖，且写入不是原子替换；替换重要输出前应保留已审阅副本。

服务端应用请求的场景 ID，将草稿转换为 JSON，并在打开输出文件前通过 SceneDefinitionParser 解析。这证明格式可被接受，不证明资源、实体选择器或时序在游戏中一定有效。完整字段表与可加载示例见过场场景数据；导出成功消息不等于数据包已重载。

可视化导出默认将 ID 分配给绑定触发器。分配会保留半径、重播/观众模式、冷却及进度规则，因此匹配的进度规则仍可覆盖新分配的默认 ID。没有绑定或触发器缺失时，会在文件写入后发出警告。未绑定的手工可视化草稿仍可导出，纯采集命令导出则要求绑定会话。

导出响应发送录制快照，不发送已导出的可视化文档。即使导出成功，重新打开仍会失去手动编辑；JSON 文件才是持久结果。

开发者传输与所有权

ModernUI 文档通过 SceneRecorderEditorController 发布不可变草稿快照。发包调度到客户端线程，编辑器动作在服务端线程执行，服务端视图再投递到 UI 线程。视图销毁时，控制器清除片段弱引用和预览。

录制视图传输最多保留 256 个镜头样本、64 条演员轨道，以及每名演员 256 个点。演员键上限为 64 字符，场景 ID 为 256，显示的导出路径为 512。服务端采集列表不受这些视图上限约束，因此超过上限后，纯采集导出可能与从视图重建的可视化文档不同。压缩可视化草稿使用共享场景传输的 262144 字节读取上限。

只要存在绑定会话，镜头回复便会被接受，不匹配待处理请求令牌，也不重复检查编辑器权限。内部录制调用同样依赖调用方权限。若扩展在其他入口暴露这些方法，必须自行提供准入检查，不能假定辅助方法已经处理。

检查清单

• 先绑定，再采集起止镜头姿态，然后用同一演员键采集两个时刻。确认同刻重新采集会替换样本。
• 检查旋转或重新绑定后的局部坐标，并核对导出文件中的演员选择器。
• 编辑采集帧后再次同步，确认哪些值会重新生成，以及手动关键帧仍然保留。
• 关闭前导出。比较命令导出与可视化导出，确认所用路径包含预期编辑。
• 将审阅后的 JSON 安装进数据包，重载后用生存观众测试。按路径长度检查移动时长，确认世界事件仅在真实播放时执行。
• 检查格式错误的字段输入、触发器分配失败和不可用的场景资源。源码校验不能替代这些游戏内检查。

相关页面

• 过场场景数据 — 全部 JSON 字段、枚举与失败行为。
• 过场场景运行时 — 触发规则、观众资格、持久化与清理。
• 镜头动画资源与编辑器偏好 — 可复用轨道和共享 UI 设置。