Kzeroko KTM2

镜头规划器

在游戏内的实时工作室中规划多镜头相机卷,并以干净成片的形式播放,供外部录屏软件录制。

更新于 2026/10/4 22 分钟阅读 相机过场录制

镜头规划器在运行中的游戏里编排一卷镜头,再按真实时钟播放,由 OBS 之类的录屏软件直接录下游戏窗口。全程不导出、不离线渲染:你把自由相机飞到每个视角并设关键帧,预览剪辑,然后按下录制,一边操作角色一边完成这一条。

你要做的东西

镜头卷是每份规划一个 JSON 文件,保存在客户端的 config/isekaiseries/shot_reels/<id>.json。它不会发到服务端,也不属于数据包。一卷包含按顺序排列的镜头、一组标题卡和一组触发项,以及作用于整卷的画面设置。

镜头卷的时间依次分三段:片头黑场、按顺序排列的全部镜头、片尾黑场。首尾两段显示纯黑,录完后方便干净地裁剪。

部分内容
镜头一段连续的相机拍摄:path、orbit 或 follow 相机,可选的注视、滑动变焦和手持晃动,以及切入它的转场。
标题卡在某个卷内时间叠在画面上的文字,有四种样式。
触发项播放经过其时间时执行的聊天命令或本地音效。

坐标是绝对世界坐标。镜头卷会记录规划时所在的维度;在其他维度打开时,工作室会给出提示,并隐藏世界中的辅助线。

前置要求

  • 管理员权限。 工作室、/ise reel 和规划器快捷键都要求权限等级 2。权限不足时服务端拒绝 /ise reel,规划器快捷键则提示 The shot planner needs operator permission (level 2),什么也不会打开。
  • 客户端世界。 镜头卷只驱动本地相机。其他玩家看到的是你的角色,不是你的相机。
  • 外部录屏软件。 规划器负责画面,不负责采集。用 OBS 或同类工具录制游戏窗口。

工作室本身是一个开发者编辑器工作区:面板之间的世界就是自由旁观相机,视口导航、拾取和通用快捷键与其他编辑器完全一致。

步骤

  1. 打开工作室。 运行 /ise reel,或绑定 key.isekaiexpansion.shot_planner(默认未绑定)。工作室会恢复上次会话的文档。

  2. 给镜头卷命名。 在工具栏输入框中填写 ID。ID 只能使用 a-z、0-9、_、. 和 -,最多 64 个字符;字母会转成小写,空格会变成下划线。

  3. 飞到开场视角,按 K。 还没有镜头时,K 会创建第一个路径镜头,并在开头设一个关键帧;之后则在播放头所在的镜头、播放头时间处设关键帧。

  4. 移动播放头、飞行、再按 K。 每按一次新增一个关键帧;若播放头 0.02 秒内已有关键帧,则替换它。在时间轴上拖动关键帧和镜头末端即可重新定时。

  5. 看看效果。 按 C 在播放头处透过镜头相机观看,或按 Space 从播放头预览。任何视口拖动都会把相机交还给自由视角,并停在你刚才观看的姿态上。

  6. 添加镜头、标题卡和触发项。 用大纲栏的按钮添加,再在检查器里逐项设置。

  7. 按 Ctrl+S 保存,再按 R。 录制会关闭工作室、从头播放镜头卷,结束后重新打开工作室。按 Esc 可提前结束这一条。

工作室操作

只要没有文本框获得焦点、也没有正在进行的视口拖动,快捷键就生效。

快捷键作用
K以当前视角在播放头处设关键帧
C切换是否在播放头处透过镜头相机观看
Space从播放头预览,再按一次停止
R从卷首录制一条干净成片
F透过所选关键帧观看,并把自由相机移到那里
G切换构图辅助线
Delete / Backspace删除所选的关键帧、镜头、标题卡或触发项
Ctrl+Z / Ctrl+Y / Ctrl+Shift+Z撤销 / 重做 / 重做
Ctrl+S保存镜头卷
Ctrl+D在当前镜头后复制一份
← / →播放头移动 0.05 秒;按住 Shift 移动 1 秒
Home / End播放头移到卷首 / 卷尾

撤销最多保留 200 步。0.9 秒内对同一字段的连续修改合并为一步,所以输入一个数字或拖动一个关键帧只需撤销一次。

时间轴有四条轨道:镜头、路径关键帧、标题卡和触发项。拖动会吸附到 0.05 秒;按下时按住 Shift 可自由放置。滚轮平移,Ctrl 加滚轮在每秒 6 到 600 像素之间缩放。两端的阴影区就是片头和片尾黑场。

在世界中,每个镜头的相机路径画成 48 段折线,每个路径关键帧画出与其视野和窗口宽高比一致的视锥,播放头处的姿态画成粉色。左键点击距某个关键帧视锥顶点 18 像素以内的位置,会选中该关键帧并把播放头移过去。镜头卷本身在驱动相机时,辅助线会隐藏。

构图辅助线会在遮幅内的画面区域画出三分线、中心十字和画面边框。透过镜头相机观看时,遮幅黑条以 70% 不透明度绘制,被裁掉的部分仍然可见。

镜头相机

路径

路径相机依次经过各关键帧。每个关键帧记录相对镜头开头的时间、位置、偏航、俯仰、翻滚、视野,以及从上一个关键帧到达它所用的缓动。

插值位置旋转与视野
smooth向心 Catmull-Rom 曲线穿过每个关键帧偏航、俯仰、翻滚和视野走 Catmull-Rom
linear关键帧之间走直线线性

偏航沿关键帧顺序展开,相邻关键帧之间总是走较短的方向。第一个关键帧之前和最后一个之后,相机停在该关键帧上。

缓动按段生效,带缓动的关键帧会让相机在它上面停稳。检查器里有两个动作可以重塑多关键帧运动:

  • 流畅缓动:第二个关键帧设为 ease_in_sine,最后一个设为 ease_out_sine,中间全部设为 linear。只有两个关键帧时设为 ease_in_out_sine。
  • 匀速重定时:按第一个到最后一个关键帧之间走过的距离,重新分配中间关键帧的时间(取整到 0.01 秒),并把第一个之后的关键帧全部设为 linear。至少需要三个关键帧。

环绕

环绕相机在整个镜头时长内绕目标转动。半径、高度、角度和视野各自从起始值走到结束值,共用一条缓动。角度 0 时相机在目标正南;相机位于目标取景点加 (−sin θ × radius, height, cos θ × radius) 处,并始终看向目标。以当前视角作为环绕起点会从你当前的视角读取起始半径、高度、角度和视野。

跟随

跟随相机与移动中的目标保持偏移,并始终看向它。开启 relative 时偏移随目标身体朝向转动:x 是目标右侧,y 向上,z 向后。延迟按给定时间常数让相机追上该点;为零时紧贴目标。拖动播放头和固定观看镜头相机时不计延迟。以当前视角设置偏移会从当前视角读取偏移和视野。

目标

环绕中心、跟随目标、注视目标和滑动变焦主体使用同一种目标结构。

类型解析为
self你自己的眼睛
entity按 UUID 找到的该实体的眼睛;未加载时使用记录的位置
point固定的世界坐标

从视口拾取:点击自己得到 self,点击其他实体得到 entity,点击方块得到 point。

修饰

修饰效果
注视把偏航和俯仰转向目标加偏移,按 weight(0 到 1)混合。翻滚保持不变。
滑动变焦替换视野,让主体周围 frame_height 格高度正好占满画面高度:FOV = 2 × atan(frame height ÷ (2 × distance))。匹配当前构图会从当前视角读取这个高度。
手持晃动叠加由三条失谐正弦波合成的平滑噪声:偏航最多 rotation 度,俯仰为其 0.8×,翻滚为其 0.5×,另有最多 position 格的位移,频率在 frequency 赫兹左右。噪声只取决于镜头内时间,所以预览和正式录制完全一致。

最终视野限制在 5–150 度。

播放与录制

播放跟随真实时钟而不是游戏刻,服务端卡顿时相机依然顺滑。游戏暂停时时钟停止。预览速度可选 0.25×、0.5×、1× 或 2×;录制始终为 1×。

转场剪辑点处的效果
cut直接切换
fade经过黑场,剪辑点最暗;时长平分在剪辑点两侧
dip_white经过白场,剪辑点最亮;时长平分在剪辑点两侧
blend在转场时长内,相机从上一个镜头结束的位置滑入本镜头

第一个镜头的转场不生效。淡入、淡出让画面从片头黑场渐亮、渐暗进入片尾黑场。遮幅黑条从第一个镜头开始,用 bar_slide 秒滑入;在最后一个镜头结束前,用同样时间滑出。窗口比画面比例更宽时,黑条改为出现在左右两侧。

标题卡有四种样式:

样式布局
chapter居中大标题,上下各一条细线,副标题在下方
center居中标题和副标题,没有细线
lower_third左下角名牌,带一条强调色竖条
caption底部一行字,衬在深色底板上

播放经过触发项的时间时执行它。command 以你自己的身份发送聊天命令,按你的权限执行;sound 在本地播放、不带方位,会被录进视频,但不会传给其他玩家。录制和 /ise reel play 总会执行触发项;工作室预览只在开启 预览时触发 时执行。

录制期间,开启 hide_hud 时隐藏 HUD;除非开启 lock_movement 或这一条正带着你随相机移动,角色仍可正常操作。hide_player 会在播放和透过镜头相机观看时隐藏你自己的模型。这一条结束后,你原来的视角和 HUD 状态会恢复。

相机周围的区块

服务端只发送你所在位置视距内的真实区块。整合包里的第三方 LOD 渲染模组 Voxy 会在客户端没有区块的地方绘制 LOD 地形,所以离你很远的相机会拍到 LOD 地形,也看不到那里的生物。

因此,开启 hide_player 的镜头卷在预览和录制时会让你随相机移动:

  1. 客户端从播放起点开始每 0.25 秒采样一次相机,补齐每个镜头内部的空隙(不跨越剪辑点),并请求服务端加载这些区块及其每侧各一个区块,最多 1024 个。它们以完整状态加载但不运算,所以你到达之前那里不会有任何模拟。
  2. 服务端把你切换为旁观者,相机每移动至少 1 格就把你移到相机处,于是真实区块、生物和方块更新都会在相机周围加载。
  3. 播放停在第一帧的黑场并显示加载进度,直到所有路径区块都处理完毕或经过 15 秒,然后才开始计时。等待发生在首部黑场之前,和其余部分一起裁掉即可。
  4. 播放结束或停止时,你会回到原来的位置、朝向、游戏模式和飞行状态。断开连接或服务端停止时会立即恢复;崩溃后会在你下次加入时恢复。

随相机移动需要权限等级 2,并且要处在镜头卷所在的维度;否则播放会在你所站的位置进行。移动期间,命令触发项里的 ~ 以相机位置为准。场景触发器、地牢传送门和地牢脚本触发器都会忽略旁观者,所以路径不会触发它们。

关闭 hide_player 时你会留在原地,工作室会把位于已加载区块之外的路径段画成琥珀色。录制前请靠近一些,或者隐藏玩家。

声明它

镜头卷由工作室写入,你也可以手写或修改文件。加载器接受的最小文件:

{
  "format": 1,
  "shots": []
}

包含一个路径镜头和一张标题卡的镜头卷:

{
  "format": 1,
  "name": "ashen_gate",
  "dimension": "minecraft:overworld",
  "settings": { "letterbox": 2.39, "pre_roll": 1.0, "post_roll": 1.0 },
  "shots": [
    {
      "name": "Establishing",
      "duration": 6.0,
      "camera": {
        "type": "path",
        "interpolation": "smooth",
        "keys": [
          { "time": 0.0, "pos": [10.5, 72.0, -4.0], "yaw": 160.0, "pitch": 8.0, "fov": 60.0 },
          { "time": 6.0, "pos": [2.5, 70.0, 6.0], "yaw": 200.0, "pitch": 4.0, "fov": 50.0 }
        ]
      },
      "handheld": { "rotation": 0.6, "position": 0.03, "frequency": 0.45 }
    }
  ],
  "titles": [
    { "start": 1.5, "duration": 4.0, "title": "Chapter One", "style": "chapter" }
  ],
  "cues": []
}

镜头卷字段

字段类型默认值作用
formatintegerrequired格式版本,只接受 1。
namestring""显示名称。保存未命名的镜头卷时以其 ID 命名。
dimensionidentifiernone规划时所在的维度,只用于工作室提示和辅助线显示。
settingsobjectall setting defaults画面与录制设置,见设置。
shotsarray<object>required按播放顺序排列的镜头。空数组也是合法的镜头卷,只播放首尾黑场。见镜头字段。
titlesarray<object>[]标题卡,加载时按 start 排序。见标题卡字段。
cuesarray<object>[]触发项,加载时按 time 排序。见触发项字段。

设置

字段类型默认值作用
letterboxnumber2.39黑条内的画面宽高比。0 或更小关闭黑条;其他值限制在 1–4。
bar_slidenumber0.8黑条滑入、滑出所用的秒数。0 时黑条固定不动。
pre_rollnumber1.0第一个镜头前的黑场秒数。
post_rollnumber1.0最后一个镜头后的黑场秒数。
fade_innumber0.8片头黑场后画面渐亮的秒数。
fade_outnumber0.8片尾黑场前画面渐暗的秒数。
hide_hudbooleantrue录制时隐藏 HUD。工作室预览总是隐藏。
hide_playerbooleanfalse在播放和透过镜头相机观看时隐藏你自己的模型。此时预览和录制会让你随相机移动。
lock_movementbooleanfalse录制时锁定角色移动。

负的秒数会被限制为 0。

镜头字段

字段类型默认值作用
shots[].namestring""工作室中的标签。名称为空时显示为 Shot 加序号。
shots[].durationnumberrequired镜头时长(秒)。小于 0.05 时整个文件被拒绝。
shots[].transition.typeenum(cut, fade, dip_white, blend)cut本镜头如何替换上一个镜头。写了 transition 时必填。
shots[].transition.durationnumber0.5转场时长(秒);cut 强制为 0,其他类型至少 0.05。
shots[].cameraobjectrequired相机。由 type 决定是路径相机、环绕相机还是跟随相机。
shots[].aim.targetobjectrequired注视目标,见目标字段。写了 aim 时必填。
shots[].aim.offsetarray<number>[0, 0, 0]加在目标点上的偏移(格)。
shots[].aim.weightnumber1.0向注视方向混合的程度,限制在 0–1。
shots[].dolly_zoom.subjectobjectrequired保持取景不变的主体,见目标字段。
shots[].dolly_zoom.frame_heightnumberrequired主体处保持在画面内的高度(格),至少 0.1。
shots[].handheld.rotationnumber0.6晃动幅度(度),至少 0。
shots[].handheld.positionnumber0.03位移幅度(格),至少 0。
shots[].handheld.frequencynumber0.45主要晃动频率(赫兹),至少 0.01。

路径相机

字段类型默认值作用
camera.typeenum(path, orbit, follow)required本表对应 path。
camera.interpolationenum(smooth, linear)smooth穿过关键帧的曲线。
camera.keys[]array<object>required关键帧,加载时按 time 排序。列表为空时该镜头没有相机,期间显示普通视角。
camera.keys[].timenumberrequired相对镜头开头的秒数;负数限制为 0。
camera.keys[].posarray<number>required世界坐标 [x, y, z]。
camera.keys[].yawnumberrequired偏航(度),与原版约定一致。
camera.keys[].pitchnumberrequired俯仰(度),限制在 −90–90。
camera.keys[].rollnumber0.0翻滚(度);正值让相机向右倾斜。
camera.keys[].fovnumber70.0垂直视野(度),限制在 5–160。
camera.keys[].easeenum(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)ease_in_out_sine到达该关键帧所用的缓动。

环绕相机

字段类型默认值作用
camera.centerobjectrequired被环绕的目标,见目标字段。
camera.radiusarray<number>required水平距离 [start, end](格)。
camera.heightarray<number>required高于取景点的高度 [start, end](格)。
camera.anglearray<number>required角度 [start, end](度);0 表示在目标正南。
camera.fovarray<number>required视野 [start, end](度)。
camera.rollnumber0.0固定翻滚(度)。
camera.easeenum(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)ease_in_out_sine整段环绕在镜头内的缓动。

跟随相机

字段类型默认值作用
camera.targetobjectrequired被跟随的目标,见目标字段。
camera.offsetarray<number>required偏移 [x, y, z](格):开启 relative 时依次为右、上、后,否则为世界坐标轴。
camera.relativebooleantrue让偏移随目标身体偏航转动。
camera.lagnumber0.35追赶时间常数(秒);0 紧贴目标,负数限制为 0。
camera.fovnumber60.0视野(度),限制在 5–160。
camera.rollnumber0.0固定翻滚(度)。

目标字段

字段类型默认值作用
typeenum(point, self, entity)required目标跟随的对象。
posarray<number>required for point, [0, 0, 0] for entity固定点,或实体最后已知的取景点。self 时忽略。
uuidstringrequired for entity实体 UUID。其他类型时忽略。

标题卡字段

字段类型默认值作用
titles[].startnumberrequired卷内时间(秒),包含片头黑场。
titles[].durationnumberrequired显示秒数,至少 0.1。
titles[].titlestring""主标题:普通文本;若该文本是已有的翻译键,则显示译文。
titles[].subtitlestring""副标题,规则相同。
titles[].styleenum(chapter, center, lower_third, caption)chapter布局,见播放与录制中的列表。
titles[].fadenumber0.6淡入和淡出各用的秒数,最多为时长的一半。
titles[].colorstring#FFFFFF标题颜色,格式为 #RRGGBB。

触发项字段

字段类型默认值作用
cues[].timenumberrequired卷内时间(秒),包含片头黑场。
cues[].typeenum(command, sound)required聊天命令或本地音效。
cues[].valuestringrequired不带斜杠的命令(开头的斜杠会被去掉),或音效事件 ID。
cues[].volumenumber1.0音效音量,至少 0。命令忽略此项。
cues[].pitchnumber1.0音效音调,至少 0。命令忽略此项。

校验

加载器对已写的内容很严格,对没写的内容不追究:

  • 缺少必填键:拒绝整个文件并给出 JSON 路径,例如 $.shots[0].camera.type is required。
  • 类型错误、未知枚举值,或无效的缓动、UUID、颜色、音效 ID:拒绝整个文件并给出路径。
  • 非有限数字:拒绝整个文件。
  • 未知键:忽略,下次保存时丢弃。
  • 超出范围的数字:按上表限制,shots[].duration 除外——小于 0.05 时拒绝。
  • 格式错误的 JSON:拒绝整个文件。被拒绝的文件不会被改动;工作室和 /ise reel 会报告原因。

保存时先把带缩进的 UTF-8 写到临时文件,再移动到目标位置;文件系统支持时为原子替换。

命令与 API

reel 分支位于模组命令根下:/isekaiexpansion reel,或通过短别名使用 /ise reel。服务端检查权限等级 2 后,把命令交给持有镜头卷文件的你的客户端执行。镜头卷 id 的补全来自你自己的镜头卷文件夹。

命令作用
/ise reel, /ise reel studio打开工作室并恢复上次的文档
/ise reel open <id>把已保存的镜头卷载入工作室
/ise reel play <id>以成片方式播放已保存的镜头卷;结束后不重新打开工作室
/ise reel stop停止任何镜头卷播放或预览
/ise reel list列出已保存的镜头卷;点击即可打开

其他客户端代码可以通过 net.kzeroko.isekaiexpansion.api.client.camera.ShotPlannerAPI 调用规划器,需在客户端线程调用。

ShotReel reel = ShotPlannerAPI.load("ashen_gate");
ShotPlannerAPI.record(reel);
方法作用
load(String id)读取并校验已保存的镜头卷;文件缺失、无法读取或无效时抛出 IOException
record(ShotReel reel)从卷首以成片方式播放
stop()停止播放或工作室预览
isPlaying()是否有预览或成片在播放
openStudio()玩家有权限时打开工作室

播放期间,镜头卷的相机优先于其他所有相机来源,包括服务端过场场景。具体顺序见开发者编辑器工作区。

检查清单

  • 在规划时所在的维度打开镜头卷,确认辅助线出现。
  • 开启 C 拖动播放头逐个检查镜头,再用 Space 以 1× 预览。
  • 在各自的卷内时间检查标题卡和触发项;命令很重要时开启 预览时触发。
  • 保存,在 OBS 运行时录一条,再裁掉首尾黑场。
  • 确认这一条结束后视角和 HUD 已恢复。
  • 显示玩家时,确认没有琥珀色路径段。隐藏玩家时,在远离你的位置预览,确认近处是真实地形,结束后你会回到原处。

相关页面