scene.json format

scene.json is a JSON file containing scene actors, animation clips and world logic rules. The editor includes it when building a .npbuild (Include scene in the export window), and the server plugin NP Scene reads and runs it. The format name is np-scene and the version is 1.

Stage	What happens
1. Editor	Actors, clips and rules are saved in the world file (.npworld). Coordinates are editor world coordinates.
2. Export	A scene.json is written for each .npbuild piece. Coordinates are converted to be relative to that piece’s minimum corner (origin).
3. Server install	When the .npbuild is installed, rotation, mirroring and position are applied to convert to server coordinates.
4. Server run	NP Scene creates the actors and runs the rules.

Top level

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

Key	Type	Always present	Meaning
format	string	Yes	Always "np-scene"
version	number	Yes	Always 1
origin	[x,y,z]	Yes	Editor coordinates of this piece’s minimum corner. Informational only.
actors	array	Yes	Scene actors
animations	array	Yes	Animation clips (Sequencer)
logic	array	Yes	World logic rules
variables	array	When declarations exist	Variable declarations
enums	array	When present	Enums
types	array	When present	Data types

If there are no actors, clips or rules at all, scene.json is not included in the .npbuild.

Coordinates

• Every position (pos, path points, position keys, selected block cells) is relative to origin. It is the editor coordinate minus origin.
• An actor belongs to a piece if the X and Z of its pos are within that piece’s range. Height is not considered.
• An actor that falls into no piece produces an export warning.
• rot is [yaw, pitch, roll] in degrees, the Minecraft way: yaw 0 = south (+Z), 90 = west (−X), pitch + = down.

Actors

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

Key	Type	Meaning
id	string	Name unique within the world. Letters · digits · _ . -, 1–64 characters
kind	string	See the table below
name	string	Display name
pos	[x,y,z]	Position (meaning differs by kind — see the table below)
rot	[yaw,pitch,roll]	Direction. Always [0,0,0] for trigger
scale	[x,y,z]	Scale. display · text only
size	[x,y,z]	Full size (blocks). trigger · blocker only
shape	string	box · sphere (size = diameter). Only trigger can be sphere
tags	string array	Tags. [] if empty
parent	string	id of the attached parent actor (only when present)
props	object	Kind-specific properties

Actors set to Editor only in the editor are not exported.

kind

kind	Meaning of pos	Main props
trigger	Zone center	(none) · interactable: true if it comes from an interaction component
spawn	Feet	role (player · npc · mob · custom) · entity (for npc · mob)
display	Model center	display (item · block) · item_model or block · visible · glow · glow_color · billboard (fixed · vertical · horizontal · center) · brightness (-1 = ambient light, 0–15)
text	Text center	text · color · background (#aarrggbb) · billboard · visible · shadow · see_through · alignment (center · left · right) · line_width
light	That cell (floor(pos))	level (0–15) · visible
camera	Eye	fov
path	First point	points ([[x,y,z], …]) · closed
sound	Sound position	event · radius · mode (random · loop) · interval_min · interval_max · volume · pitch_min · pitch_max · time (any · day · night) · underground_only
blocker	Box center	mode (barrier · push) · affects (players · all) · visible_in_editor

• The server ignores unknown props fields.
• display · text · light with visible: false start hidden. They appear with the rule action actor_show.
• barrier for blocker fills the empty cells in the box with barrier blocks. push pushes out anything that enters, without blocks.

Actors from components

Actor components (trigger volume · blocking volume · interaction · sound emitter · light · text display) are usually exported as one scene actor row.

Key	Value
id	<actor id>.<component id> (for example door.interact)
kind	trigger · blocker · sound · light · text
parent	id of the owner actor (informational — for a block actor, the owner is not in actors)
tags	The owner actor’s tags

The server does not need to know any new kind.

Animations

{"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}]}
 ]}

Key	Meaning
id · name	Clip name
length	Length (seconds)
loop	Whether it loops
tracks[].actor	Actor id
tracks[].property	pos · rot · scale · visible · text · color
keys[].t	Time (seconds). Ascending t
keys[].v	Value — pos · rot · scale = [x,y,z], visible = boolean, text = string, color = "#aarrggbb"
keys[].ease	linear (if omitted) · step · smooth. Applies from that key to the next key.

• visible · text are always stepped.
• Before the first key, the first value applies; after the last key, the last value.
• A non-looping clip stays at its last pose when it ends.
• If several clips animate the same actor and property, the clip that started later wins. actor_show · actor_hide take precedence over visible tracks.

Sequencer fields

You can add the fields below to a clip. All are optional. Older runners ignore them and play only 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"

Field	Items (* required)	Meaning
cuts	t* · camera* (camera actor, "" = player view) · blend (seconds, 0)	From that time, the view of that camera
events	t* · signal*	Signal at that time — same as the action signal
sounds	t* · event* · volume (1) · pitch (1) · at (actor)	Sound at that time
titles	t* · title · subtitle · duration (2) · fade_in (0.5) · fade_out (0.5)	On-screen title at that time
fades	t* · v* (0–1) · ease	Screen overlay opacity
fade_color	"#rrggbb" (default black)	Overlay color

Rules

{"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"}
 ]}

Key	Meaning
id · name	Rule name
enabled	If off, the rule does not run.
trigger	One trigger node
filter	once · once_per_player · cooldown (seconds) · permission
conditions	Array of condition nodes — actions run only when all are true
actions	Array of action nodes — run in order

A node is an object made of type and that type’s fields. The fields for each type are in World logic type list.

• Number fields are read even when written as strings.
• The _graph field inside a node is editor-only (Logic graph node positions · breakpoints). The server ignores it.
• For block triggers (block_break · block_place · block_interact), if area is blocks, cells is [[x,y,z], …] relative to origin (up to 4,096 cells). If area is missing, it is zone.

audience

Actions that choose recipients (sound · on-screen title · message · combat actions and so on) use audience.

Value	Recipients
player	The player who triggered it (default)
inside	Everyone inside the action’s actor zone. If none, everyone inside the rule’s trigger zone
world	Everyone in the world
radius	Within r (16) blocks of the at actor (if empty, the triggering player)

Variables · enums · data types

"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"}]}]

Field	Keys	Meaning
variables[]	name · type · scope · default	type = bool · int · float · string · player · actor · position · an enum name · a data type name. scope = global · player. If default is missing, the type’s zero value
enums[]	name · values	List of values. Initial value = default or the first value
types[]	name · fields[] (name · type · default)	Field type = a basic type · an enum · another data type

• All values are stored as strings. Numbers are 0.###, booleans are true · false, positions are "x y z".
• Data type variables can be stored under expanded names per field (hero.hp, hero.stats.str).
• Undeclared names are global string variables. They share the same store as flags (flag · set_flag).

variables was added in 0.9.7, and enums · types in 0.9.11.

Compatibility rules

np-scene 1 is additive only. New features are added as new fields and new types; format and version do not change.

Case	What the runner does
Unknown top-level field · clip field · props field	Ignores it.
Unknown trigger type	Skips that rule (one warning).
Unknown condition type	Treats that condition as false (one warning).
Unknown action type	Skips only that action and continues with the next (one warning).
Unknown node field	Ignores it.

The editor does not delete unknown types or fields; it preserves them as-is. Types added by other event plugins also run on servers that have those plugins.

Related pages

• World logic
• Scene actors and Outliner
• Sequencer
• Variables, functions and data types
• World logic type list
• Export and import