scene.json 形式

scene.json は、シーンアクター・アニメーションクリップ・ワールドロジックのルールを含む JSON ファイルです。エディターが .npbuild を作成するときに含め (エクスポートウィンドウの「シーンを含める」)、サーバープラグイン NP Scene が読み込んで実行します。形式名は np-scene、バージョンは 1 です。

段階	処理
1. エディター	アクター・クリップ・ルールをワールドファイル (`.npworld`) に保存します。座標はエディターのワールド座標です。
2. エクスポート	`.npbuild` のピースごとに `scene.json` を書き出します。座標はそのピースの最小の角 (origin) を基準に変換します。
3. サーバーへのインストール	`.npbuild` をインストールするときに、回転・反転・位置を適用してサーバー座標に変換します。
4. サーバーでの実行	NP Scene がアクターを作成し、ルールを実行します。

最上位

{
  "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`	配列	はい	シーンアクター
`animations`	配列	はい	アニメーションクリップ (シーケンサー)
`logic`	配列	はい	ワールドロジックのルール
`variables`	配列	宣言があるとき	変数の宣言
`enums`	配列	あるとき	enum
`types`	配列	あるとき	データ型

アクター・クリップ・ルールが 1 つもない場合、.npbuild に scene.json は含めません。

座標

すべての位置 (pos、パスの点、位置キー、選択したブロックのマス) は origin 基準です。エディター座標から origin を引いた値です。
1 つのピースに含まれるアクターは、pos の X・Z がそのピースの範囲内にあるものです。高さは考慮しません。
どのピースにも含まれないアクターは、エクスポート時に警告が出ます。
rot は [yaw, pitch, roll] の度です。Minecraft の方式です: yaw 0 = 南 (+Z)、90 = 西 (−X)、pitch + = 下。

アクター

{"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` = 直径)。`sphere` は `trigger` のみ可能
`tags`	文字列の配列	タグ。空の場合は `[]`
`parent`	文字列	アタッチした親アクターの `id` (ある場合のみ)
`props`	オブジェクト	種類ごとのプロパティ

エディターで「エディター専用」にしたアクターは出力されません。

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 はブロックを置かずに、中に入ったものを押し出します。

コンポーネントから出たアクター

アクターコンポーネント (トリガーボリューム・ブロッカーボリューム・インタラクト・サウンドエミッター・ライト・テキスト表示) は、通常シーンアクター 1 行として出力されます。

キー	値
`id`	`<アクター id>.<コンポーネント id>` (例: `door.interact`)
`kind`	`trigger` ・ `blocker` ・ `sound` ・ `light` ・ `text`
`parent`	所有アクターの `id` (情報用 — ブロックアクターの場合、所有者は `actors` にない)
`tags`	所有アクターのタグ

サーバーは新しい 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`	アクターの `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_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 アクター、`""` = プレイヤー視点)・`blend` (秒、0)	その時刻からそのカメラの視点
`events`	`t`* ・ `signal`*	その時刻にシグナル — アクション `signal` と同じ
`sounds`	`t`* ・ `event`* ・ `volume` (1)・`pitch` (1)・`at` (アクター)	その時刻にサウンド
`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`	トリガーノード 1 つ
`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` アクター (空ならトリガーした人) から `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	そのルールをスキップします (警告 1 回)。
不明な条件 type	その条件を偽とみなします (警告 1 回)。
不明なアクション type	そのアクションだけをスキップし、次のアクションを続けます (警告 1 回)。
不明なノードの項目	無視します。

エディターは不明な type・項目を削除せず、そのまま保持します。他のイベントプラグインが追加した type も、そのプラグインがあるサーバーで実行されます。