过场场景数据

过场场景是由服务器加载的时间轴，组合镜头运动、角色指令、世界事件与字幕。位置相对于传入的枢轴，因此同一场景可以在不同地点播放，无须重写坐标。

文件放在哪里

场景 JSON 放在 data/<namespace>/cinematic_scenes/*.json，可包含子目录。默认由资源路径形成场景 ID；显式 id 可覆盖它。高优先级数据包替换同一资源 ID。不同文件若声明相同场景 ID，加载器会记录冲突，但此时后项已替换前项，且资源遍历没有排序。

纯镜头 Gecko 动画属于独立的客户端资源，放在 assets/<namespace>/camera_animations/*.json。场景的 gecko 轨道引用动画注册 ID，而不是 JSON 文件名。原生 spline 轨道不需要这种资源。

最小示例

这个短暂的固定镜头使用与内置 isekaiexpansion:hidden_hud_subtitle_scene 相同的镜头节点字段。保存为 data/example/cinematic_scenes/fixed_shot.json 后，场景 ID 为 example:fixed_shot；以每秒 20 刻计，40 刻为 2 秒。

{
  "schema": 1,
  "length_ticks": 40,
  "camera": {
    "track": {
      "nodes": [
        { "t": 0, "pos": [0, 1.7, 4], "rot": [0, 180, 0], "fov": 60 }
      ]
    }
  }
}

空对象也能解析，但不提供镜头姿态。它仍有默认播放设置，因此加载成功不代表镜头内容可用。

字段

根对象与播放设置

所有场景时间均以刻为单位。总时长会钳制，但不会检查指令时间是否超过总时长；结束后的条目不会执行。播放淡入淡出与混合数值没有解析范围检查，客户端传输会将负值规范化为 0。省略 playback 时混合值为 8；提供空对象时为 10，因为缺失的混合字段会继承淡入淡出值。

枢轴坐标与角色

传入变换的参考姿态中，+X 向右、+Y 向上、−Z 向前。局部偏航 180 表示向前。位置偏移按枢轴偏航减 180 旋转；世界偏航等于枢轴偏航加局部偏航再减 180。位置使用方块单位，旋转使用度。pivot 元数据不会选择或移动实际变换。

triggering_player 直接选择玩家，先于 UUID 与其他筛选。否则，UUID 找到的活体实体优先；找不到时继续最近实体搜索。两种最近选择器都使用轴对齐搜索盒及可选的类型和名称筛选，再从存活且未移除的候选者中选择离枢轴最近者。搜索盒不是球形半径检查。显式类型筛选会将触发玩家排除在该搜索之外。

规范化后相同的角色键会由后项覆盖前项。显式提供的 player 定义会保留，只有缺失时才补入默认触发玩家定义。播放开始时，无法解析的自定义角色会被省略。

镜头轨道与节点

第一张表描述 camera 及其中的 track，第二张表描述每个 track.nodes 条目。

原生轨道按所选方式插值位置，线性插值俯仰，并按环绕角度插值偏航与翻滚。终点节点提供缓动。终点观察目标优先于前一节点的目标，不会在两个角色目标之间混合。

场景传输会重建镜头 JSON。节点有 look_at 时，只写入该目标而省略 rot，客户端因此重新解析出默认旋转。正常服务器播放中，不应依赖带目标节点所制作的翻滚或回退旋转能够保留。没有目标的节点保留旋转。

Gecko 轨道按每秒 20 刻换算场景已过时间，并限制到动画长度。此路径不使用纯镜头 API 的循环或保持选择。缺少动画数据时不产生姿态。

目标

look_at 与 face 接受下列字段组成的对象、含 3 个数字的局部位置数组，或字符串 walk_target。其他字符串不产生目标，null 也表示无目标。

对象优先级依次为移动终点、角色、位置。角色目标使用脚部位置，拍摄面部时应增加向上的偏移。walk_target 对角色指令有意义；镜头节点没有对应移动指令提供终点，因此无法解析它。直接数据解析器不规范化目标角色字符串，而编辑器与客户端传输会规范化；各处应使用同一个已经规范化的键。

镜头效果

多个震动实例合并，最终受强度上限约束；新的扭曲替换当前扭曲。它们是客户端屏幕效果，不改变角色位置。中途加入的观众只播放已开始效果的剩余部分，不会从头重播完整时长。

角色轨道

步行或冲刺需要非零长度的路径。单个路径点或只有 pos，不会自动构成从角色当前位置出发的步行路线。移动不会把偏离路径的角色瞬移到首点；确实需要这种切换时，应显式使用姿态指令。

路径长度除以时长得到请求速度；超出范围时会钳制，并由加载器记录时间警告。此修正不会延长指令窗口或场景时长。角色受阻、偏离路径起步或时长过短，仍可能无法抵达终点。

正时长移动指令从起始刻执行到起始刻加时长，包含两端。重叠指令不会被拒绝或合并，应避免让同一角色同时接受互相竞争的移动指令。缺少角色或动画 ID 时跳过对应动作，不会因此拒绝整个场景。

世界事件

事件在服务器到时后执行一次。声音与粒子通过世界广播；天气和时间改变整个世界，而非只改变观众的画面。粒子事件支持无额外负载的已注册简单粒子类型；方块或物品式粒子的附加参数不属于此格式。

字幕与缓动

同一时间只有一条字幕，新指令会替换当前字幕。文本与说话者按翻译键解析，也可以直接使用字面文本。普通 HUD 隐藏时，字幕覆盖层仍可显示。中途加入的观众会从尚未过期字幕的已播放位置继续显示文字。

缓动名称为 linear、step、ease_in_quad、ease_out_quad、ease_in_out_quad、ease_in_sine、ease_out_sine、ease_in_out_sine、ease_in_cubic、ease_out_cubic、ease_in_out_cubic、ease_in_back、ease_out_back。输入不区分大小写，去除两端空白，并将连字符或空格转为下划线；也识别 easeInOutQuad 等紧凑名称。未知名称回退为 linear。

校验

解析器不检查数值是否有限，不限制最大时间轴长度或关键帧数量，也不会检查所有引用素材是否存在。应使用有限数值与有效 ID；解析成功不代表角色、动画、声音或粒子实际可用。

正常场景启动传输会发送压缩的制作草稿，接收时限制为 262144 压缩字节，最多发送 64 项角色绑定，每个键最多 64 字符。这是压缩体积限制，不是解压后内存上限。客户端重建会将许多向量、旋转及效果数值舍入到 3 位小数，规范化目标键并丢弃未知字段。时间轴应保持在传输预算内，且不要依赖更细的精度。

重载

/reload 重建服务器场景目录并增加修订号，即使重载存在错误也会如此。启动场景时发送当前定义与已解析角色绑定；原生轨道不要求客户端本地持有服务器数据包。Gecko 镜头动画与其他视觉素材仍须放在客户端资源包中。

正在运行的服务器播放保留启动时的场景对象。重载定义影响后续启动，不改变现有时间轴。检查修改时应重新启动场景；修改镜头动画素材后，还需单独重载客户端资源。

相关页面

• 过场场景运行时 — 触发器、观众、演员控制权与存档历史。
• 镜头动画资源 — Gecko 镜头轨道使用的资源格式。

表情数据定义表情指令使用的贴纸。NPC 素材介绍 NPC 动画资源，开发编辑器偏好介绍共享编辑器主题控件。