Erg scene (erg-scene/2)

Generated from docs/erg-scene-2.schema.json (https://melange.dev/schema/erg-scene-2.json). The guide is erg.md.

The editable scene of a level that uses level objects, a Survivor twin, a level script, new terrain blocks or a painted surround; a scene without any of them is written as erg-scene/1. The editable scene the level service sends to the Erg editor, followed by one binary frame per blob. Positions, scales and voxel coordinates are .xan units as stored; the editor shows world units (x20). Never written into a pack.

Top level

Property	Type	Required	Default	Description
format	string	Yes		Must be "erg-scene/2".
stem	string	Yes		Pattern: ^[^.]+$. 1 to 48 characters.
title	string	Yes		Pattern: ^[ -~]+$. 1 to 40 characters.
base	object	Yes
registry	object	Yes
kind	kind	Yes
databank	object	Yes
water	water	Yes
spawns	spawns	Yes
hmp	hmp	Yes
units	object	Yes
frames	array of object	Yes		At most 4096 items.
details	array of object	Yes		At most 65536 items.
blobs	array of object	Yes		At most 8192 items.
objects	objects	Yes		Level objects. Each is a detail added to the level and named by its knot; deleting the detail deletes the object. Knots: CRATE_<n>, TP_<g>_<n> (g = the group), TRIG_<n> (n 0-255, no leading zeros) and minefactory; a detail named telepad is never written. At most 8 telepad groups and 1 mine factory.
script	script	Yes		Metadata only: the text is script.lua next to the project patch (sim/<slug>.lua in a pack).
previews	object of string			level.load only, not part of the saved document: resource name -> preview asset key, for every distinct detail resource in the scene.

base

Property	Type	Required	Default	Description
key	string	Yes		Registry name, e.g. Multi.DinerMight. 1 to 79 characters.
source	string	Yes		One of: "game", "pack".
file	string	Yes		Level file stem of the base. 1 to 63 characters.
sha256	sha256	Yes

registry

Property	Type	Required	Default	Description
levelType	integer	Yes		From 0 to 16.
themeType	integer	Yes		5 = the databank’s theme. From 0 to 11.
scripts	array of string	Yes		1 to 8 items. Items: Pattern: ^[^,]+$. 1 to 63 characters.
previewType	integer			From 0 to 16.

databank

Property	Type	Required	Default	Description
theme	"" or theme
timeOfDay	string			One of: "", "DAY", "EVENING", "NIGHT".
materialFile	string			At most 120 characters.
heightmapBase	string			At most 64 characters.
heightmapSecond	string			At most 64 characters.

units

Property	Type	Required	Default	Description
worldPerXan	integer	Yes		Must be 20.

frames[]

Property	Type	Required	Default	Description
id	integer	Yes		An object index of the base; -1..-64 for a new frame. From -64 to 16777216.
new	boolean			An added terrain block: under the Scene frame, identity rotation and scale, each size 1-32, no heightMap.
parent	index or null	Yes		null for the root only.
name	string	Yes		At most 127 characters.
pos	vec3	Yes
rot	rot3	Yes		Euler angles in radians.
scale	vec3	Yes
size	array of integer	Yes		X, Y, Z voxels; at most 262144 in all. Exactly 3 items. Items: From 0 to 255.
voxels	ref or null	Yes		Blob of X*Y*Z u32 LE words, index (z*X + x)*Y + y.
heightMap	ref or null	Yes		Blob of (X+1)*(Z+1) f32 LE corner offsets, index z*(X+1) + x.
folder	boolean	Yes		1x1x1 with identity rotation and scale.

details[]

Property	Type	Required	Default	Description
id	index	Yes
src	index or null	Yes		Object index in the base .xan; null for an added detail.
frame	index	Yes
name	string	Yes		At most 127 characters.
resource	string	Yes		At most 127 characters.
pos	vec3	Yes
rot	rot3	Yes		Euler angles in radians.
scale	vec3	Yes
voxelPos	vec3	Yes
role	string	Yes		Derived by the server; read-only. One of: "scenery", "spawn", "object", "camera", "light", "emitter", "sound", "collision", "marker", "other".

blobs[]

Property	Type	Required	Default	Description
ref	ref	Yes
kind	string	Yes		hmp: the surround (hmp.ref), 100x100 f32 heights 0..1 then 100x100 u8 blend (50000 bytes), frame 0. One of: "voxels", "heightMap", "hmp".
frame	integer	Yes		From -64 to 16777216.
bytes	integer	Yes		From 0 to 1048576.

Definitions

Definition: index

Type: integer. From 1 to 16777216.

Definition: ref

Type: integer. From 0 to 16777216.

Definition: vec3

Type: array of number. Exactly 3 items. Items: From -1000000 to 1000000.

Definition: rot3

Euler angles in radians. Type: array of number. Exactly 3 items. Items: From -1000 to 1000.

Definition: sha256

Property	Type	Required	Default	Description
xan	string	Yes		Pattern: ^[0-9a-f]{64}$.
xom	string	Yes		Pattern: ^[0-9a-f]{64}$.
hmp	string (Pattern: ^[0-9a-f]{64}$) or null

Definition: theme

Type: string. One of: "ARABIAN", "WILDWEST", "CAMELOT", "PREHISTORIC", "BUILDING", "ARCTIC", "ENGLAND", "HORROR", "LUNAR", "PIRATE", "WAR".

Definition: water

Property	Type	Required	Default	Description
level	number (From -1000 to 1000) or null			World units, sea level 0; null keeps the default.

Definition: spawns

Property	Type	Required	Default	Description
mode	string	Yes		One of: "random", "knots".

Definition: hmp

Property	Type	Required	Default	Description
mode	string	Yes		One of: "copy", "none", "flat", "paint".
ref	ref			paint: the blob of the painted surround; copy: the base’s surround, when level.load was asked for it.

Definition: kind

Property	Type	Required	Default	Description
survivor	boolean		false	Also registered as a Survivor map (Multi.<stem>.S).

Definition: script

Metadata only: the text is script.lua next to the project patch (sim/<slug>.lua in a pack).

Property	Type	Required	Default	Description
present	boolean	Yes
sha256	string (Pattern: ^[0-9a-f]{64}$) or null

Definition: count

Type: integer. From 1 to 99.

Definition: objects

Level objects. Each is a detail added to the level and named by its knot; deleting the detail deletes the object. Knots: CRATE_<n>, TP_<g>_<n> (g = the group), TRIG_<n> (n 0-255, no leading zeros) and minefactory; a detail named telepad is never written. At most 8 telepad groups and 1 mine factory. Type: array of one of: type = “crate”, type = “telepad”, type = “trigger”, knot = “minefactory”. At most 256 items.

objects[] with type = “crate”

Property	Type	Required	Default	Description
knot	string	Yes		Pattern: ^CRATE_(0|[1-9][0-9]{0,2})$.
type	string	Yes		Must be "crate".
crate	one of: variant 1, kind = “health”	Yes

objects[] with type = “telepad”

Property	Type	Required	Default	Description
knot	string	Yes		Pattern: ^TP_[1-8]_(0|[1-9][0-9]{0,2})$.
type	string	Yes		Must be "telepad".
group	integer	Yes		The group in the knot name; a pad sends a worm to another pad of its group. From 1 to 8.

objects[] with type = “trigger”

Property	Type	Required	Default	Description
knot	string	Yes		Pattern: ^TRIG_(0|[1-9][0-9]{0,2})$.
type	string	Yes		Must be "trigger".
trigger	object	Yes

objects[] with knot = “minefactory”

Property	Type	Required	Default	Description
knot	string	Yes		Must be "minefactory".
type	string	Yes		Must be "minefactory".

objects[].crate variant 1

Property	Type	Required	Default	Description
kind	string	Yes		One of: "weapon", "utility".
contents	string	Yes		A weapon or utility name of the install (level.objects). Pattern: ^[A-Za-z][A-Za-z0-9_]{0,62}$.
count	count
hitpoints	integer		25	From 1 to 1000.
parachute	boolean		false

objects[].crate with kind = “health”

Property	Type	Required	Default	Description
kind	string	Yes		Must be "health".
amount	integer	Yes		From 1 to 500.
hitpoints	integer		25	From 1 to 1000.
parachute	boolean		false

objects[].trigger

Property	Type	Required	Default	Description
index	integer	Yes		From 0 to 255.
radius	number		60	From 1 to 1000.
teamCollect	integer		0	From 0 to 8.
teamDestroy	integer		4	From 0 to 8.
hitpoints	integer		1	From 0 to 1000.
wormCollect	boolean		false