World and effects

Large-scale world building and simulated effects.

terrain

Large heightfield terrain (islands, beaches, mountains, canyons, dunes) with erosion, up to 8 blended material layers and wet shorelines. Rendered with continuous LOD. Use terrain_create, terrain_sculpt, terrain_paint and terrain_layers; heights are relative to the entity.

Field	Type	Description	Values
data	string	Project-relative .terrain file with heights and layer weights
size	number	Square extent in meters	8 .. 32768
resolution	integer	Height samples per side (2^n+1: 257, 513, 1025, 2049)
generator	object	Generation parameters (shape, seed, minHeight, maxHeight, featureSize, ridges, warp, erosion, thermal, terraces, beachWidth, seaLevel; shape heightmap: heightmap image, detailNoise)
layers	object[]	Material layers, base first. Each: {name, texture, normalMap, ormMap, color, roughness, tiling (m), heightMin, heightMax, slopeMin, slopeMax, noise, sharpness}. Rules auto-paint the weights.
edits	object[]	Recorded hand edits in terrain-local meters, replayed in order over the generator when the terrain cache is rebuilt: {op: sculpt|paint|autopaint, strokes, layer}. Written by terrain_sculpt, terrain_paint and terrain_layers; cleared by terrain_generate.
waterLevel	number	World height of the water line (wet sand/soil just above it)
wetBand	number	Meters above the water line that stay damp	0 .. 20
detail	number	Level-of-detail quality multiplier	0.25 .. 4
macroVariation	number	Large-scale tone and hue variation over the whole landscape (0 = off, 0.5 natural)	0 .. 1
castShadows	boolean	Cast sun shadows
overlay	string	Image draped over the whole terrain (row 0 = -Z edge): political/region maps, borders, paper maps. Alpha masks it; swap it at run time for map modes
overlayOpacity	number	Overlay strength (times the image alpha)	0 .. 1
overlayBlend	string	mix paints over the ground (matte, keeps the relief shading), multiply tints it, glow adds the color unlit (highlights, borders that read at night)	mix multiply glow

Tool callWander

entity_update {"entity": "Crate", "components": {"terrain": {}}}

self.terrain.data          -- read or write any field

foliage

GPU-instanced scattering of grass, flowers, ferns, pebbles, shells, rocks and trees over a terrain (this entity or its parent) or over scene meshes inside area. Wind-animated, deterministic. Use foliage_add with presets.

Field	Type	Description	Values
layers	object[]	Layers: [{preset, mesh | prefab, color, density (/m²), scaleMin, scaleMax, slopeMin, slopeMax, heightMin, heightMax, terrainLayer, wind, cullDistance, castShadows, clumping, alignToNormal, impostors, impostorDistance, impostorResolution, impostorFrames}]. Distant instances of heavy meshes draw as octahedral impostors (see impostor_bake).
seed	integer	Random seed of the placement
density	number	Density multiplier for every layer	0 .. 4
surface	string	What to grow on	terrain scene
area	number[3]	Scene mode: extent in meters around the entity
visible	boolean	Draw the foliage

Tool callWander

entity_update {"entity": "Crate", "components": {"foliage": {}}}

self.foliage.layers          -- read or write any field

water

Water surface with a spectral (FFT) ocean simulation: wind waves, choppy crests, foam, refraction, depth color and reflections. Entity y = water level. Query wave heights with water_query / Wander water_height().

Field	Type	Description	Values
windSpeed	number	Wind speed (m/s): 2 calm lake, 8 breezy sea, 18 storm	0 .. 40
windDirection	number	Direction the waves travel (degrees, 0 = +Z)
choppiness	number	Sharpness of crests (0 = rolling swell)	0 .. 3
waveScale	number	Wave amplitude multiplier	0 .. 5
patchSize	number	Longest simulated wavelength (m)	10 .. 2000
size	number	Square extent in meters (0 = endless ocean)	0 .. 100000
depth	number	Water depth for wave physics (shallow water slows waves)	0.5 .. 5000
deepColor	color	Light scattered inside deep water — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
shallowColor	color	Tint of what you see through shallow water — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
clarity	number	How far you can see into the water (m)	0.1 .. 100
foam	number	Whitecaps and shoreline foam	0 .. 4
reflections	number	Reflection strength	0 .. 2
refraction	number	Refraction distortion	0 .. 4
roughness	number	Micro roughness (sun glint size)	0.005 .. 0.5
seed	integer	Random seed of the wave field

Tool callWander

entity_update {"entity": "Crate", "components": {"water": {}}}

self.water.windSpeed          -- read or write any field

particles

Particle emitter: fire, smoke, embers, sparks, rain, snow, mist, magic. Simulated by the engine and drawn as soft HDR particles. Easiest start: fx_create with a preset, then tweak fields.

Field	Type	Description	Values
preset	string	Preset it was made from (informational)
emitting	boolean	Emit new particles (existing ones finish their life)
look	string	glow = soft light points; flame = animated fire tongues; smoke = lit billowing volume; spark = glowing streaks; rain = lit falling streaks; snow = soft flakes; mist = drifting fog; sprite = textured / flipbook sheet (texture, gpu only)	glow flame smoke spark rain snow mist sprite
rate	number	Particles per second	0 .. 4000000
burst	integer	Particles emitted at once when it starts (explosions); Wander burst(n) emits more
maxParticles	integer	Upper bound of live particles (cpu: up to 50000; gpu: up to 4000000)
lifetime	number	Seconds each particle lives	0.01 .. 120
lifetimeJitter	number	Random lifetime variation (fraction)	0 .. 1
shape	string	Where particles are born (scaled by shapeSize)	point sphere box disc cone
shapeSize	number[3]	Size of the emission shape (m)
direction	number[3]	Emission direction in the entity's space
speed	number	Initial speed (m/s)	0 .. 500
speedJitter	number	Random speed variation (fraction)	0 .. 1
spread	number	Cone half-angle around direction (degrees)	0 .. 180
gravity	number	Downward acceleration (m/s^2); negative = rises like hot gas	-50 .. 50
drag	number	Air resistance (per second)	0 .. 20
turbulence	number	Curl-noise swirl strength (m/s)	0 .. 50
turbulenceScale	number	Swirl size (m)	0.01 .. 100
wind	number	How strongly the environment wind carries particles	0 .. 5
sizeStart	number	Size at birth (m)	0 .. 100
sizeEnd	number	Size at death (m)	0 .. 100
sizeJitter	number	Random size variation (fraction)	0 .. 1
colorStart	color	Color at birth (alpha = opacity) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
colorEnd	color	Color at death (alpha = opacity) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
intensity	number	HDR brightness (glows with bloom above ~1)	0 .. 200
stretch	number	Streak length along velocity (seconds of motion)	0 .. 1
spin	number	Random rotation speed (degrees/s)	0 .. 1440
softness	number	Fade where particles meet geometry (m)	0 .. 10
worldSpace	boolean	Particles stay behind when the emitter moves (trails)
collide	boolean	Collide with the floor plane at floorHeight
floorHeight	number	World height of the collision floor
bounce	number	Bounciness on impact (0 = die)	0 .. 1
splash	integer	Droplets spawned per impact (rain splashes)
light	number	Light cast on the scene (flickers with the particles)	0 .. 100
lightColor	color	Color of the cast light — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
lightRange	number	Reach of the cast light (m)	0.1 .. 200
prewarm	boolean	Start fully developed instead of from nothing
seed	integer	Random seed (variations of the same effect)
simulation	string	cpu = deterministic engine simulation (gameplay, countable); gpu = compute shaders, millions of particles, depth collisions, sub-emitters, ribbons, mesh particles (visuals only)	cpu gpu
facing	string	gpu: camera = billboards; velocity = stretched along motion (stretch); horizontal = flat on the ground plane (ripples, decals); ribbon = trails (trailLength); mesh = instanced lit meshes (mesh)	camera velocity horizontal ribbon mesh
mesh	string	gpu facing mesh: primitive (cube, sphere...), "asset:<path>", or built-in fx:leaf, fx:shard, fx:pebble
roughness	number	gpu mesh particles: surface roughness	0.02 .. 1
metallic	number	gpu mesh particles: metalness	0 .. 1
texture	string	gpu look sprite: sprite or flipbook sheet (png/jpg), project-relative
flipbookColumns	integer	Flipbook sheet columns
flipbookRows	integer	Flipbook sheet rows
flipbookFps	number	Flipbook frames per second (0 = once over each life; frames cross-fade)	0 .. 240
colorGradient	string	gpu: color over life, e.g. "#fff6d0@0 #ffa030@0.2 #a01800@0.7 #20000000@1" (overrides colorStart/End)
sizeCurve	string	gpu: size multiplier over life, e.g. "0@0 1@0.1 0.3@1"
opacityCurve	string	gpu: opacity multiplier over life, e.g. "0@0 1@0.2 0@1"
shapeMesh	string	gpu shape mesh: emit from this mesh's surface ("" = this entity's mesh)
field	string	gpu force field: vortex = swirl around fieldAxis (tornado, magic); attractor = pull toward fieldCenter; texture = vector field from fieldTexture (.fga)	none vortex attractor texture
fieldStrength	number	Force field strength (m/s; attractor m/s^2)	-1000 .. 1000
fieldRadius	number	Force field radius (m)	0.01 .. 1000
fieldCenter	number[3]	Force field center (local offset)
fieldAxis	number[3]	Vortex axis (local)
fieldPull	number	Vortex inward pull (m/s)	-100 .. 100
fieldLift	number	Vortex lift along its axis (m/s)	-100 .. 100
fieldTexture	string	Vector field file (.fga from Houdini or EmberGen)
fieldSize	number[3]	Box covered by the vector field (m, centered on fieldCenter)
depthCollision	boolean	gpu: collide with everything visible on screen (scene depth + normals): sparks bouncing off props, rain splashing on roofs
stick	boolean	gpu: particles stick where they collide (paint, snow, blood)
friction	number	gpu: tangential slow-down on bounce	0 .. 1
colliders	array | string | null	gpu: entities particles bounce off: sphere meshes collide as spheres, planes/quads as planes, other meshes as bounding spheres — entity links: ["Hand", "#12", {"id": 7}] (a comma-separated string also works)
subEmitter	object | string | integer | null	gpu: another gpu particles entity spawned where these particles die/hit (sparks -> embers, rockets -> fireworks) — entity link: name ("Door"), "#id", {"id": 12} or null; read back as {"id", "name"} (follows renames; entity_refs lists links)
subEmitOn	string	When sub-emitter particles spawn	death collision both
subEmitCount	integer	Sub-emitter particles per event
subEmitInherit	number	Fraction of the parent's velocity inherited	0 .. 2
trailLength	number	Ribbon trail length (seconds of history)	0.01 .. 10
trailSegments	integer	Ribbon history samples
sort	boolean	gpu blended looks: sort back to front on the GPU (off = faster)
lightShadows	boolean	The cast light (light > 0) is blocked by occluders (torches in caves; costs a cube shadow map)
hueVariation	number	gpu: random hue rotation per particle; sub-emitted particles share their event's hue (fireworks)	0 .. 1

Tool callWander

entity_update {"entity": "Crate", "components": {"particles": {}}}

self.particles.preset          -- read or write any field

fluid

Volumetric fluid simulation for fire, smoke, steam and explosions (GPU 3D solver, ray-marched): fuel burns into heat and soot, hot gas rises and swirls. The box sits on the entity (bottom center). Start with fx_create (volume_fire, volume_smoke, steam_vent, explosion_volume...).

Field	Type	Description	Values
preset	string	Preset it was made from (informational)
emitting	boolean	Feed the source (off: the fire dies down)
size	number[3]	Simulation box in meters (fire lives inside it)
resolution	integer	Cells along the longest side (detail vs. cost)
sourceOffset	number[3]	Source position from the box's bottom center (m)
sourceRadius	number	Source radius (m)	0.01 .. 50
fuel	number	Fuel fed per second (0 = smoke/steam only)	0 .. 20
heat	number	Heat released (drives flames and lift)	0 .. 20
smoke	number	Soot / vapour produced	0 .. 20
buoyancy	number	How fast hot gas rises	0 .. 20
vorticity	number	Swirl: licking flames, curling smoke	0 .. 5
turbulence	number	Noise injected at the source	0 .. 5
burnRate	number	How fast fuel burns (lower = taller flames)	0.05 .. 20
cooling	number	How fast heat fades	0 .. 20
smokeFade	number	How fast smoke thins out	0 .. 20
speed	number	Upward speed at the source (m/s)	0 .. 50
wind	number	Environment wind influence	0 .. 5
flameIntensity	number	Fire brightness	0 .. 50
flameTemperature	number	Flame color temperature in Kelvin (blackbody)	800 .. 6000
smokeColor	color	Smoke albedo (dark soot .. white steam) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
smokeDensity	number	Smoke opacity	0 .. 20
light	number	Light the fire casts on the scene	0 .. 200
lightColor	color	Color of the cast light — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
lightRange	number	Reach of the cast light (m)	0.1 .. 300
burst	number	Seconds of heavy fuel at start (explosions, fireballs)	0 .. 10
seed	integer	Random seed (variation)
lightShadows	boolean	The fire's light is blocked by occluders (campfires in caves and rooms; costs a cube shadow map)

Tool callWander

entity_update {"entity": "Crate", "components": {"fluid": {}}}

self.fluid.preset          -- read or write any field

groom

Strand hair and fur grown on the entity's mesh (or target's), or loaded from a .hair/.groom.json/.skygroom file. Rendered as real strands (Marschner shading, deep opacity self-shadowing, multiple scattering) and simulated on the GPU (gravity, wind, collisions). Easiest start: groom_create with a preset (hair_straight, hair_wavy, hair_curly, hair_ponytail, hair_short, fur_short, fur_long), then tweak fields.

Field	Type	Description	Values
preset	string	Preset it was made from (informational)
visible	boolean	Draw the groom
source	string	Groom file (.hair = Cem Yuksel's format, .groom.json, .skygroom), project-relative; "" = grow procedurally on the mesh
target	object | string | integer | null	Entity whose mesh grows the hair (empty = this entity) — entity link: name ("Door"), "#id", {"id": 12} or null; read back as {"id", "name"} (follows renames; entity_refs lists links)
importScale	number	Imported files: scale to meters (0.01 for centimeters)	1e-05 .. 1000
importZUp	boolean	Imported files: the source is Z-up
strands	integer	Rendered strands (head of hair 50k-150k; fur 100k+). Imported files: cap
guides	integer	Simulated guide strands (0 = automatic, ~4*sqrt(strands))
segments	integer	Segments per strand (smoothness of curls; 4 for fur, 16-31 for long hair)
length	number	Strand length in meters	0.001 .. 5
lengthVariation	number	Random length variation (fraction)	0 .. 0.95
widthRoot	number	Strand width at the root in millimeters (human hair 0.05-0.1)	0.001 .. 10
widthTip	number	Strand width at the tip in millimeters	0 .. 10
direction	number[3]	Comb direction in the mesh's space (e.g. [0,-1,-0.4] = down and back)
directionBlend	number	0 = grow along the surface normal, 1 = along direction	0 .. 1
gravity	number	Droop: 0 = stands up (fur, crew cut) .. 1 = hangs down	0 .. 2
curlRadius	number	Curl (helix) radius in meters (0.005-0.02 for curly hair)	0 .. 0.2
curlFrequency	number	Curl turns per meter of strand	0 .. 200
wave	number	Wave amplitude in meters	0 .. 0.2
waveFrequency	number	Waves per meter of strand	0 .. 100
clumps	integer	Clumps strands gather into (0 = none; hundreds for a head)
clumpStrength	number	How far strands pull into their clump	0 .. 1
clumpShape	number	Clump profile: > 1 tips clump more than roots, < 1 clump early	0.1 .. 8
frizz	number	Noise / flyaways in meters	0 .. 0.1
frizzScale	number	Frizz noise frequency (per meter)	0.1 .. 1000
ponytail	boolean	Comb every strand to ponytailPosition, then let them hang as one bundle
ponytailPosition	number[3]	Where the ponytail is tied (mesh space, meters; just outside the scalp)
maskChannel	string	Vertex-color channel that controls density (scalp painting)	none r g b a
maskDirection	number[3]	Grow only where the surface faces this way (mesh space; with maskAngle)
maskAngle	number	Degrees around maskDirection that grow hair (180 = everywhere)	0 .. 180
maskSoftness	number	Soft hairline width in degrees	0 .. 90
melanin	number	Pigment (physically based absorption): 0 white, 0.1 platinum, 0.2 blond, 0.35 dark blond, 0.5 light brown, 0.7 brown, 0.85 dark brown, 0.95+ black	0 .. 1
redness	number	Red pigment (pheomelanin) fraction: 0.5 auburn, 0.9 ginger	0 .. 1
dye	color	Dye tint (white = natural) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
rootColor	color	Color multiplier at the roots (root-to-tip gradient, e.g. dark roots) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
tipColor	color	Color multiplier at the tips (sun-bleached or dyed tips) — hex string "#rrggbb[aa]" or [r,g,b(,a)] in 0..1
colorVariation	number	Per-strand pigment variation	0 .. 1
roughness	number	Longitudinal roughness: highlight width (0.2 silky .. 0.6 dull)	0.02 .. 1
radialRoughness	number	Azimuthal roughness: softness of light through the strand	0.05 .. 1
specular	number	Primary (white) highlight strength	0 .. 4
scatter	number	Multiple scattering: light hair glows, dark hair stays rich	0 .. 4
cuticleTilt	number	Cuticle tilt in degrees (separates the two highlights)	0 .. 10
density	number	Coverage per strand (2 = a full head of hair at typical strand counts; lower for wispy, higher for thick)	0.05 .. 8
simulate	boolean	Simulate on the GPU (gravity, wind, collisions)
stiffness	number	How strongly strands keep their groomed shape	0 .. 1
rootStiffness	number	Stiffness near the roots	0 .. 1
damping	number	Velocity damping	0 .. 1
wind	number	Environment wind influence	0 .. 10
collide	boolean	Collide with the mesh (sphere/capsule proxy) and colliders
colliders	array | string | null	Entities the hair collides with (shoulders, hands) — entity links: ["Hand", "#12", {"id": 7}] (a comma-separated string also works)
lod	string	auto = strands up close, cards far away; strands; cards (cheapest)	auto strands cards
cardsBelow	number	auto LOD: draw cards when the groom is smaller than this (pixels)	0 .. 4096
castShadows	boolean	Cast sun shadows on the scene
seed	integer	Random seed (a different head of the same style)
attach	string	auto = roots follow the animated skin when the mesh is rigged (characters, creatures); rigid = follow the entity only; skinned = always bind to the skin	auto rigid skinned
follow	number	Skinned: share of the skin's motion strands take rigidly before simulating (0 = all inertia, floppy; 1 = stiff); 0.5-0.8 keeps hair stable on running characters	0 .. 1
maxSpeed	number	Strand points never move faster than this relative to their roots (m/s)	0.1 .. 100
bodyColliders	boolean	Skinned: collide with capsules fitted to the character's skeleton (head, neck, torso, arms, legs)
maskBone	string	Grow only on vertices skinned to this bone and its children (e.g. Head for scalp hair, beard and brows on a full-body mesh); character_inspect lists bones
maskSpace	string	Coordinates of maskCenter / maskRadius: bounds = -1..1 across the bounding box of maskBone's vertices (rig independent: a beard is about [0, -0.6, -0.8] on a head facing -Z); bone = meters from maskBone's rest position; mesh = meters in the mesh; auto = bone with a maskBone, else mesh	auto mesh bone bounds
maskCenter	number[3]	Region center (see maskSpace; mesh axes): imported characters face -Z, so a beard is at negative Z
maskRadius	number[3]	Region ellipsoid radii (see maskSpace; 0 = no region): beards, eyebrows, sideburns
maskMirror	boolean	Also grow in the region mirrored across the mesh's X = 0 plane (both eyebrows)
lodBias	number	Real time: > 1 keeps more strands at a distance, < 1 fewer (stills draw all)	0.05 .. 8

Tool callWander

entity_update {"entity": "Crate", "components": {"groom": {}}}

self.groom.preset          -- read or write any field