scene.json 格式

scene.json 是包含场景 Actor · 动画片段 · 世界逻辑规则的 JSON 文件。编辑器在生成 .npbuild 时写入（导出窗口「包含场景」），服务器插件 NP Scene 读取并执行。格式名称为 np-scene，版本为 1。

阶段	作用
1. 编辑器	将 Actor · 片段 · 规则保存到世界文件（`.npworld`）中。坐标为编辑器世界坐标。
2. 导出	为每个 `.npbuild` 分块写入 `scene.json`。坐标转换为以该分块的最小角（origin）为基准。
3. 服务器安装	安装 `.npbuild` 时应用旋转 · 翻转 · 位置，转换为服务器坐标。
4. 服务器运行	NP Scene 创建 Actor 并执行规则。

顶层

{
  "format": "np-scene",
  "version": 1,
  "origin": [120, 64, -40],
  "actors": [ … ],
  "animations": [ … ],
  "logic": [ … ],
  "variables": [ … ],
  "enums": [ … ],
  "types": [ … ]
}

键	类型	始终存在	含义
`format`	字符串	是	始终为 `"np-scene"`
`version`	数值	是	始终为 `1`
`origin`	`[x,y,z]`	是	此分块最小角的编辑器坐标。仅供参考。
`actors`	数组	是	场景 Actor
`animations`	数组	是	动画片段（序列器）
`logic`	数组	是	世界逻辑规则
`variables`	数组	有声明时	变量声明
`enums`	数组	有时	enum
`types`	数组	有时	数据类型

若没有任何 Actor · 片段 · 规则，则不会在 .npbuild 中放入 scene.json。

坐标

所有位置（pos、路径点、位置关键帧、所选方块格）都以 origin 为基准，即编辑器坐标减去 origin 后的值。
归入某个分块的 Actor 是 pos 的 X · Z 位于该分块范围内的 Actor。不考虑高度。
不属于任何分块的 Actor 会产生导出警告。
rot 为 [yaw, pitch, roll] 角度，采用 Minecraft 方式：yaw 0 = 南（+Z），90 = 西（−X），pitch + = 向下。

Actor

{"id": "trig_gate", "kind": "trigger", "name": "성문 앞",
 "pos": [10, 64, 5], "rot": [0, 0, 0], "size": [6, 4, 3], "shape": "box",
 "tags": ["gate"], "props": {}}

键	类型	含义
`id`	字符串	在世界中唯一的名称。英文 · 数字 · `_` `.` `-`，1~64 字符
`kind`	字符串	见下表
`name`	字符串	显示名称
`pos`	`[x,y,z]`	位置（含义因种类而异 — 见下表）
`rot`	`[yaw,pitch,roll]`	方向。`trigger` 始终为 `[0,0,0]`
`scale`	`[x,y,z]`	缩放。仅 `display` · `text`
`size`	`[x,y,z]`	整体尺寸（方块）。仅 `trigger` · `blocker`
`shape`	字符串	`box` · `sphere`（`size` = 直径）。只有 `trigger` 可以是 `sphere`
`tags`	字符串数组	标签。为空时为 `[]`
`parent`	字符串	所附加的父 Actor `id`（仅在有时）
`props`	对象	各种类的属性

在编辑器中设为「仅编辑器」的 Actor 不会导出。

kind

`kind`	`pos` 含义	主要 `props`
`trigger`	区域中心	（无） · 若来自交互组件则为 `interactable: true`
`spawn`	脚下	`role`（`player` · `npc` · `mob` · `custom`） · `entity`（npc · mob 时）
`display`	模型中心	`display`（`item` · `block`） · `item_model` 或 `block` · `visible` · `glow` · `glow_color` · `billboard`（`fixed` · `vertical` · `horizontal` · `center`） · `brightness`（-1 = 环境光，0~15）
`text`	文字中心	`text` · `color` · `background`（`#aarrggbb`） · `billboard` · `visible` · `shadow` · `see_through` · `alignment`（`center` · `left` · `right`） · `line_width`
`light`	所在格（`floor(pos)`）	`level`（0~15） · `visible`
`camera`	眼睛	`fov`
`path`	第一个点	`points`（`[[x,y,z], …]`） · `closed`
`sound`	声音位置	`event` · `radius` · `mode`（`random` · `loop`） · `interval_min` · `interval_max` · `volume` · `pitch_min` · `pitch_max` · `time`（`any` · `day` · `night`） · `underground_only`
`blocker`	框中心	`mode`（`barrier` · `push`） · `affects`（`players` · `all`） · `visible_in_editor`

服务器会忽略不认识的 props 字段。
visible: false 的 display · text · light 以隐藏状态开始。通过规则动作 actor_show 显示。
blocker 的 barrier 用 barrier 方块填满框内的空格。push 不放方块，而是推开进入其中的对象。

来自组件的 Actor

Actor 组件（触发器体积 · 阻挡体积 · 交互 · 音源 · 光源 · 文本展示）通常作为一行场景 Actor 导出。

键	值
`id`	`<Actor id>.<组件 id>`（例：`door.interact`）
`kind`	`trigger` · `blocker` · `sound` · `light` · `text`
`parent`	所属 Actor 的 `id`（仅供参考 — 若为方块 Actor，所属 Actor 不在 `actors` 中）
`tags`	所属 Actor 的标签

服务器无需认识新的 kind。

动画

{"id": "gate_open", "name": "성문 열림", "length": 3.0, "loop": false,
 "tracks": [
   {"actor": "npc_guard", "property": "pos",
    "keys": [{"t": 0, "v": [12.5, 64, 8.5], "ease": "smooth"}, {"t": 3, "v": [14.5, 64, 8.5]}]},
   {"actor": "txt_welcome", "property": "visible", "keys": [{"t": 0, "v": true}]}
 ]}

键	含义
`id` · `name`	片段名称
`length`	长度（秒）
`loop`	是否循环
`tracks[].actor`	Actor `id`
`tracks[].property`	`pos` · `rot` · `scale` · `visible` · `text` · `color`
`keys[].t`	时刻（秒）。按 `t` 升序
`keys[].v`	值 — `pos` · `rot` · `scale` = `[x,y,z]`，`visible` = 布尔值，`text` = 字符串，`color` = `"#aarrggbb"`
`keys[].ease`	`linear`（缺省时为此） · `step` · `smooth`。用于从该关键帧到下一关键帧之间。

visible · text 始终为阶梯式。
第一个关键帧之前为第一个值，最后一个关键帧之后为最后一个值。
不循环的片段结束后停留在最后的姿态。
多个片段驱动同一 Actor · 属性时，后开始的片段优先。actor_show · actor_hide 优先于 visible 轨道。

序列器字段

可以向片段添加以下字段，全部为可选。旧版执行器会忽略它们，只运行 tracks。

"cuts":   [{"t": 0, "camera": "cam_a"}, {"t": 3, "camera": "cam_b", "blend": 1}, {"t": 5.5, "camera": ""}],
"events": [{"t": 2, "signal": "intro_mid"}],
"sounds": [{"t": 0.2, "event": "minecraft:block.bell.use", "volume": 1, "pitch": 1, "at": "crystal"}],
"titles": [{"t": 0.6, "title": "광장의 수정", "subtitle": "", "duration": 1.8, "fade_in": 0.3, "fade_out": 0.5}],
"fades":  [{"t": 0, "v": 1}, {"t": 0.9, "v": 0, "ease": "smooth"}],
"fade_color": "#000000"

字段	项目（* 必填）	含义
`cuts`	`t`* · `camera`*（camera Actor，`""` = 玩家视角） · `blend`（秒，0）	从该时刻起切换为该相机视角
`events`	`t`* · `signal`*	在该时刻发送信号 — 与动作 `signal` 相同
`sounds`	`t`* · `event`* · `volume`（1） · `pitch`（1） · `at`（Actor）	在该时刻播放声音
`titles`	`t`* · `title` · `subtitle` · `duration`（2） · `fade_in`（0.5） · `fade_out`（0.5）	在该时刻显示屏幕标题
`fades`	`t`* · `v`*（0~1） · `ease`	屏幕遮罩不透明度
`fade_color`	`"#rrggbb"`（默认黑色）	遮罩颜色

规则

{"id": "r_gate_enter", "name": "성문 진입", "enabled": true,
 "trigger": {"type": "enter", "actor": "trig_gate"},
 "filter": {"once": false, "once_per_player": true, "cooldown": 10, "permission": ""},
 "conditions": [{"type": "time", "value": "day"}],
 "actions": [
   {"type": "sound", "event": "minecraft:block.bell.use", "at": "trig_gate", "audience": "player"},
   {"type": "anim_play", "anim": "gate_open"},
   {"type": "wait", "seconds": 2},
   {"type": "actor_show", "actor": "txt_welcome"}
 ]}

键	含义
`id` · `name`	规则名称
`enabled`	为关闭时不执行。
`trigger`	一个触发器节点
`filter`	`once` · `once_per_player` · `cooldown`（秒） · `permission`
`conditions`	条件节点数组 — 全部为真时才执行动作
`actions`	动作节点数组 — 按顺序执行

节点是由 type 和该 type 的字段组成的对象。各 type 的字段见世界逻辑 type 列表。

数值字段即使写成字符串也能读取。
节点中的 _graph 字段仅供编辑器使用（逻辑图节点位置 · 断点）。服务器会忽略。
方块触发器（block_break · block_place · block_interact）的 area 为 blocks 时，cells 为 [[x,y,z], …]，以 origin 为基准（最多 4,096 格）。没有 area 时为 zone。

audience

选择接收者的动作（声音 · 屏幕标题 · 消息 · 战斗动作等）使用 audience。

值	接收者
`player`	触发者（默认）
`inside`	动作的 `actor` 区域内的所有人。没有时为规则触发区域内的所有人
`world`	世界中的所有人
`radius`	距 `at` Actor（为空时为触发者）`r`（16）方块以内

变量 · enum · 数据类型

"variables": [{"name": "score", "type": "int", "scope": "player", "default": "0"},
              {"name": "hero", "type": "Hero", "scope": "player"}],
"enums":     [{"name": "Job", "values": ["warrior", "mage", "archer"]}],
"types":     [{"name": "Hero", "fields": [{"name": "hp", "type": "int", "default": "20"},
                                          {"name": "job", "type": "Job"}]}]

字段	键	含义
`variables[]`	`name` · `type` · `scope` · `default`	`type` = `bool` · `int` · `float` · `string` · `player` · `actor` · `position` · enum 名称 · 数据类型名称。`scope` = `global` · `player`。没有 `default` 时为该类型的零值
`enums[]`	`name` · `values`	值列表。初始值 = `default` 或第一个值
`types[]`	`name` · `fields[]`（`name` · `type` · `default`）	字段类型 = 基本类型 · enum · 其他数据类型

所有值都以字符串保存。数值为 0.###，布尔值为 true · false，位置为 "x y z"。
数据类型变量按字段展开后的名称（hero.hp、hero.stats.str）保存即可。
未声明的名称是全局字符串变量，与标志（flag · set_flag）使用同一存储。

自 0.9.7 起新增 variables，自 0.9.11 起新增 enums · types。

兼容规则

np-scene 1 只做追加。新功能以新字段 · 新 type 的形式添加，不更改 format · version。

情况	执行器的处理
未知的顶层字段 · 片段字段 · `props` 字段	忽略。
未知的触发器 type	跳过该规则（警告一次）。
未知的条件 type	将该条件视为假（警告一次）。
未知的动作 type	只跳过该动作，继续执行下一个动作（警告一次）。
未知的节点字段	忽略。

编辑器不会删除未知的 type · 字段，而是原样保留。其他事件插件添加的 type 也会在装有该插件的服务器上执行。