镜头规划器
在游戏内的实时工作室中规划多镜头相机卷,并以干净成片的形式播放,供外部录屏软件录制。
镜头规划器在运行中的游戏里编排一卷镜头,再按真实时钟播放,由 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 或同类工具录制游戏窗口。
工作室本身是一个开发者编辑器工作区:面板之间的世界就是自由旁观相机,视口导航、拾取和通用快捷键与其他编辑器完全一致。
步骤
-
打开工作室。 运行
/ise reel,或绑定key.isekaiexpansion.shot_planner(默认未绑定)。工作室会恢复上次会话的文档。 -
给镜头卷命名。 在工具栏输入框中填写 ID。ID 只能使用
a-z、0-9、_、.和-,最多 64 个字符;字母会转成小写,空格会变成下划线。 -
飞到开场视角,按
K。 还没有镜头时,K会创建第一个路径镜头,并在开头设一个关键帧;之后则在播放头所在的镜头、播放头时间处设关键帧。 -
移动播放头、飞行、再按
K。 每按一次新增一个关键帧;若播放头 0.02 秒内已有关键帧,则替换它。在时间轴上拖动关键帧和镜头末端即可重新定时。 -
看看效果。 按
C在播放头处透过镜头相机观看,或按Space从播放头预览。任何视口拖动都会把相机交还给自由视角,并停在你刚才观看的姿态上。 -
添加镜头、标题卡和触发项。 用大纲栏的按钮添加,再在检查器里逐项设置。
-
按
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 的镜头卷在预览和录制时会让你随相机移动:
- 客户端从播放起点开始每 0.25 秒采样一次相机,补齐每个镜头内部的空隙(不跨越剪辑点),并请求服务端加载这些区块及其每侧各一个区块,最多 1024 个。它们以完整状态加载但不运算,所以你到达之前那里不会有任何模拟。
- 服务端把你切换为旁观者,相机每移动至少 1 格就把你移到相机处,于是真实区块、生物和方块更新都会在相机周围加载。
- 播放停在第一帧的黑场并显示加载进度,直到所有路径区块都处理完毕或经过 15 秒,然后才开始计时。等待发生在首部黑场之前,和其余部分一起裁掉即可。
- 播放结束或停止时,你会回到原来的位置、朝向、游戏模式和飞行状态。断开连接或服务端停止时会立即恢复;崩溃后会在你下次加入时恢复。
随相机移动需要权限等级 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": []
}
镜头卷字段
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
format | integer | required | 格式版本,只接受 1。 |
name | string | "" | 显示名称。保存未命名的镜头卷时以其 ID 命名。 |
dimension | identifier | none | 规划时所在的维度,只用于工作室提示和辅助线显示。 |
settings | object | all setting defaults | 画面与录制设置,见设置。 |
shots | array<object> | required | 按播放顺序排列的镜头。空数组也是合法的镜头卷,只播放首尾黑场。见镜头字段。 |
titles | array<object> | [] | 标题卡,加载时按 start 排序。见标题卡字段。 |
cues | array<object> | [] | 触发项,加载时按 time 排序。见触发项字段。 |
设置
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
letterbox | number | 2.39 | 黑条内的画面宽高比。0 或更小关闭黑条;其他值限制在 1–4。 |
bar_slide | number | 0.8 | 黑条滑入、滑出所用的秒数。0 时黑条固定不动。 |
pre_roll | number | 1.0 | 第一个镜头前的黑场秒数。 |
post_roll | number | 1.0 | 最后一个镜头后的黑场秒数。 |
fade_in | number | 0.8 | 片头黑场后画面渐亮的秒数。 |
fade_out | number | 0.8 | 片尾黑场前画面渐暗的秒数。 |
hide_hud | boolean | true | 录制时隐藏 HUD。工作室预览总是隐藏。 |
hide_player | boolean | false | 在播放和透过镜头相机观看时隐藏你自己的模型。此时预览和录制会让你随相机移动。 |
lock_movement | boolean | false | 录制时锁定角色移动。 |
负的秒数会被限制为 0。
镜头字段
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
shots[].name | string | "" | 工作室中的标签。名称为空时显示为 Shot 加序号。 |
shots[].duration | number | required | 镜头时长(秒)。小于 0.05 时整个文件被拒绝。 |
shots[].transition.type | enum(cut, fade, dip_white, blend) | cut | 本镜头如何替换上一个镜头。写了 transition 时必填。 |
shots[].transition.duration | number | 0.5 | 转场时长(秒);cut 强制为 0,其他类型至少 0.05。 |
shots[].camera | object | required | 相机。由 type 决定是路径相机、环绕相机还是跟随相机。 |
shots[].aim.target | object | required | 注视目标,见目标字段。写了 aim 时必填。 |
shots[].aim.offset | array<number> | [0, 0, 0] | 加在目标点上的偏移(格)。 |
shots[].aim.weight | number | 1.0 | 向注视方向混合的程度,限制在 0–1。 |
shots[].dolly_zoom.subject | object | required | 保持取景不变的主体,见目标字段。 |
shots[].dolly_zoom.frame_height | number | required | 主体处保持在画面内的高度(格),至少 0.1。 |
shots[].handheld.rotation | number | 0.6 | 晃动幅度(度),至少 0。 |
shots[].handheld.position | number | 0.03 | 位移幅度(格),至少 0。 |
shots[].handheld.frequency | number | 0.45 | 主要晃动频率(赫兹),至少 0.01。 |
路径相机
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
camera.type | enum(path, orbit, follow) | required | 本表对应 path。 |
camera.interpolation | enum(smooth, linear) | smooth | 穿过关键帧的曲线。 |
camera.keys[] | array<object> | required | 关键帧,加载时按 time 排序。列表为空时该镜头没有相机,期间显示普通视角。 |
camera.keys[].time | number | required | 相对镜头开头的秒数;负数限制为 0。 |
camera.keys[].pos | array<number> | required | 世界坐标 [x, y, z]。 |
camera.keys[].yaw | number | required | 偏航(度),与原版约定一致。 |
camera.keys[].pitch | number | required | 俯仰(度),限制在 −90–90。 |
camera.keys[].roll | number | 0.0 | 翻滚(度);正值让相机向右倾斜。 |
camera.keys[].fov | number | 70.0 | 垂直视野(度),限制在 5–160。 |
camera.keys[].ease | enum(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.center | object | required | 被环绕的目标,见目标字段。 |
camera.radius | array<number> | required | 水平距离 [start, end](格)。 |
camera.height | array<number> | required | 高于取景点的高度 [start, end](格)。 |
camera.angle | array<number> | required | 角度 [start, end](度);0 表示在目标正南。 |
camera.fov | array<number> | required | 视野 [start, end](度)。 |
camera.roll | number | 0.0 | 固定翻滚(度)。 |
camera.ease | enum(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.target | object | required | 被跟随的目标,见目标字段。 |
camera.offset | array<number> | required | 偏移 [x, y, z](格):开启 relative 时依次为右、上、后,否则为世界坐标轴。 |
camera.relative | boolean | true | 让偏移随目标身体偏航转动。 |
camera.lag | number | 0.35 | 追赶时间常数(秒);0 紧贴目标,负数限制为 0。 |
camera.fov | number | 60.0 | 视野(度),限制在 5–160。 |
camera.roll | number | 0.0 | 固定翻滚(度)。 |
目标字段
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
type | enum(point, self, entity) | required | 目标跟随的对象。 |
pos | array<number> | required for point, [0, 0, 0] for entity | 固定点,或实体最后已知的取景点。self 时忽略。 |
uuid | string | required for entity | 实体 UUID。其他类型时忽略。 |
标题卡字段
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
titles[].start | number | required | 卷内时间(秒),包含片头黑场。 |
titles[].duration | number | required | 显示秒数,至少 0.1。 |
titles[].title | string | "" | 主标题:普通文本;若该文本是已有的翻译键,则显示译文。 |
titles[].subtitle | string | "" | 副标题,规则相同。 |
titles[].style | enum(chapter, center, lower_third, caption) | chapter | 布局,见播放与录制中的列表。 |
titles[].fade | number | 0.6 | 淡入和淡出各用的秒数,最多为时长的一半。 |
titles[].color | string | #FFFFFF | 标题颜色,格式为 #RRGGBB。 |
触发项字段
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
cues[].time | number | required | 卷内时间(秒),包含片头黑场。 |
cues[].type | enum(command, sound) | required | 聊天命令或本地音效。 |
cues[].value | string | required | 不带斜杠的命令(开头的斜杠会被去掉),或音效事件 ID。 |
cues[].volume | number | 1.0 | 音效音量,至少 0。命令忽略此项。 |
cues[].pitch | number | 1.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 已恢复。
- 显示玩家时,确认没有琥珀色路径段。隐藏玩家时,在远离你的位置预览,确认近处是真实地形,结束后你会回到原处。
相关页面
- 开发者编辑器工作区:视口导航、拾取、偏好设置和相机优先顺序。
- 场景录制器与可视化编辑器:由服务端播放、玩家在游戏中看到的过场场景。
- 镜头场景 API:由资源驱动的客户端相机动画。