Erg patch (erg-patch/2)

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

An edit that uses level objects, a Survivor twin, a level script, new terrain blocks or a painted surround; a patch without any of them is written as erg-patch/1, and a Melange that only knows /1 refuses a /2 patch by its format. An edit against a pinned base level: the Erg project file, the payload of level.save and what a source map pack ships in src/. It holds only identifiers and the author’s own values. The server applies the ops in order and refuses a patch whose base hashes differ.

Top level

Property	Type	Required	Default	Description
format	string	Yes		Must be "erg-patch/2".
stem	string	Yes		<prefix>_<slug>; never a vanilla level stem. Pattern: ^[a-z0-9_]{1,48}$.
title	string	Yes		Pattern: ^[ -~]+$. 1 to 40 characters.
base	object	Yes
kind	kind
databank	object			Only the keys that differ from the base.
water	water
spawns	spawns
hmp	hmp
ops	array of one of: op = “set”, op = “add”, op = “remove”, op = “voxels”, op = “addFrame”, op = “hmp”	Yes		At most 20000 items.
objects	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.
script	script			Metadata only: the text is script.lua next to the project patch (sim/<slug>.lua in a pack).

base

Property	Type	Required	Default	Description
key	string	Yes		1 to 79 characters.
source	string	Yes		One of: "game", "pack".
sha256	sha256	Yes

databank

Only the keys that differ from the base.

Property	Type	Required	Default	Description
theme	theme
timeOfDay	string			One of: "DAY", "EVENING", "NIGHT".
materialFile	string			A relative path that must exist in the install. Pattern: \.[tT][xX][tT]$. 5 to 120 characters.
heightmapBase	string			1 to 64 characters.
heightmapSecond	string			1 to 64 characters.

ops[] with op = “set”

At least 3 properties.

Property	Type	Required	Default	Description
op	string	Yes		Must be "set".
src	index	Yes
name	label
resource	label
pos	vec3
rot	rot3			Euler angles in radians.
scale	vec3
voxelPos	vec3

ops[] with op = “add”

Property	Type	Required	Default	Description
op	string	Yes		Must be "add".
frame	index	Yes		A folder frame (1x1x1, identity rotation and scale).
detail	object	Yes

ops[] with op = “remove”

Property	Type	Required	Default	Description
op	string	Yes		Must be "remove".
src	index	Yes

ops[] with op = “voxels”

Terrain: runs of voxel words over the frame’s index order, at most 2000 per frame. Accepted only by servers with terrain sculpting. Every word written must be a carve, fill or paint of the base word: bits 8-23 (second-material flags, second material and corner mask) equal to the base word’s or zero, unless the server has second-material paint (then bits 8-23 are free; bits 24-31 stay clear).

Property	Type	Required	Default	Description
op	string	Yes		Must be "voxels".
frame	integer	Yes		A frame of the base, or the tmp id of a frame added by an earlier op. From -64 to 16777216. Not 0.
runs	array of array [integer, integer, integer]	Yes		1 to 2000 items. Items: Exactly 3 items. Item 1: From 0 to 262143. Item 2: From 1 to 262144. Item 3: Bits 24-31 clear; bits 0-1 are 0 (empty) or 3 (solid). From 0 to 16777215.

ops[] with op = “addFrame”

A new terrain block under the Scene frame (or a frame under it), identity rotation and scale, all voxels empty until voxels ops fill it. pos is its centre in the parent’s space: the engine centres a frame’s voxels on its position. The name is unused by any frame and holds none of SLIPPY, PERM or TEAMBASE (any case). At most 64.

Property	Type	Required	Default	Description
op	string	Yes		Must be "addFrame".
tmp	integer	Yes		From -64 to -1.
parent	index	Yes
name	string	Yes		Pattern: ^[A-Za-z0-9_]{1,31}$.
pos	vec3	Yes
size	array of integer	Yes		Exactly 3 items. Items: From 1 to 32.

ops[] with op = “hmp”

Surround painting (hmp.mode paint): runs over the 100x100 cells, row-major.

At least 2 properties.

Property	Type	Required	Default	Description
op	string	Yes		Must be "hmp".
heights	array of array [integer, integer, number]			Items: Exactly 3 items. Item 1: From 0 to 9999. Item 2: From 1 to 10000. Item 3: From 0 to 1.
blend	array of array [integer, integer, integer]			Items: Exactly 3 items. Item 1: From 0 to 9999. Item 2: From 1 to 10000. Item 3: From 0 to 255.

ops[].detail

Property	Type	Required	Default	Description
name	label	Yes
resource	label	Yes
pos	vec3	Yes
rot	rot3			Euler angles in radians.
scale	vec3
voxelPos	vec3

Definitions

Definition: label

Type: string. Pattern: ^[ -~]+$. 1 to 63 characters.