Erg scene (erg-scene/1)

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

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/1".
stem	string	Yes		Pattern: ^[^.]+$. 1 to 48 characters.
title	string	Yes		Pattern: ^[ -~]+$. 1 to 40 characters.
base	object	Yes
registry	object	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.
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	index	Yes
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		One of: "voxels", "heightMap".
frame	index	Yes
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".