Node Types

All nodes share the same base structure. Type-specific data lives in a matching named object. See Scene Format for the full scene format and transform/ properties reference.

{
  "name":       "uniqueName",
  "type":       "<node type>",
  "transform":  { ... },
  "properties": { ... },
  "children":   [ ... ]
}

Quick reference

Type	Category	Implemented	Description
`group`	Structure	✅	Invisible container, groups children under a shared transform
`src`	Structure	✅	Imports an external node-collection file (prefab/include)
`model`	Geometry	✅	Mesh from a model descriptor — glTF asset or engine-native primitive
`skydome`	Geometry	✅	Sky backdrop mesh from a skydome model descriptor
`camera`	Camera	✅	Perspective camera
`light`	Lighting	✅	Directional, point, or spot light
`probe`	Lighting	✅	Reflection / IBL capture probe
`environment`	Lighting	✅	IBL environment descriptor + optional skydome blur
`marker`	Gameplay	✅	Invisible named point — spawn, attach, nav target
`trigger`	Gameplay	✅	Invisible volume that fires events on enter/exit
`audio`	Audio	🚧 planned	3D positional audio source
`decal`	Rendering	🚧 planned	Projects a texture onto underlying geometry
`post_process_volume`	Rendering	🚧 planned	Per-zone override for post-processing settings

Structure

`group`

A logical container with no geometry. Useful for organising a scene and applying a shared transform to a set of children.

{
  "name": "roomA",
  "type": "group",
  "transform": { "translate": [10.0, 0.0, 0.0] },
  "children": [ ... ]
}

`src`

Pulls in nodes from an external JSON file — the engine's prefab / include mechanism. The referenced file contains a plain array of nodes using the same format as the root nodes array.

{
  "name":      "candleRig",
  "type":      "src",
  "src":       "scenes://light_rigs/candle_rig.json",
  "transform": { "translate": [2.0, 0.0, -1.0] }
}

Referenced file format (candle_rig.json):

[
  {
    "name": "candle_flame",
    "type": "light",
    "light": { "type": "point", "color": [1.0, 0.6, 0.1], "intensity": 2.0, "radius": 1.5 }
  }
]

Field	Required	Description
`src`	yes	`scenes://`-relative path to the node-collection file
`transform`	no	Positions/orients the entire imported group
`children`	no	Additional local nodes appended after the imported ones

Geometry

`model`

A mesh loaded from a model descriptor (models:// path). The descriptor determines the mesh source — a glTF asset or a glitter_primitive procedural shape. See Model Descriptors for the full descriptor format.

The scene node holds only the instance-specific data: transform and flags. Shape, material, and texture data live in the descriptor, which means the same descriptor can be instanced many times with different transforms.

{
  "name":  "sponza",
  "type":  "model",
  "model": "models://s0001_sponza.json",
  "properties": {
    "mobility":   "static",
    "cast_shadow": true
  }
}

{
  "name":  "pillar_A",
  "type":  "model",
  "model": "models://pg_pillar.json",
  "transform": { "translate": [-3.5, 1.75, 11.0] },
  "properties": { "mobility": "static", "cast_shadow": true }
}

properties.mobility

Value	Meaning
`"static"`	Never moves — eligible for static batching and baked shadows
`"dynamic"`	May move every frame — updated in the render loop (default)
`"kinematic"`	Driven by animation or script, not free physics (reserved)

`skydome`

A sky backdrop mesh. References a skydome model descriptor (models:// path to a glitter_skydome descriptor). Use together with an environment node to set up a complete sky setup.

{
  "name":  "sky",
  "type":  "skydome",
  "model": "models://d001_sun_and_clouds.json"
}

Field	Required	Description
`model`	yes	`models://` path to a `glitter_skydome` descriptor

Camera

`camera`

Glitter supports both a legacy (direct FoV) and a physically-based (focal length + sensor size) camera model. See Camera System for the full reference including the sensor profile database.

Legacy — field of view:

{
  "name": "mainCamera",
  "type": "camera",
  "camera": {
    "fov_deg": 75.0,
    "near":    0.1,
    "far":     200.0
  },
  "transform": {
    "translate": [1.0, 1.0, 0.0],
    "look_at":   [0.0, 0.5, 0.0]
  }
}

Physically-based — inline sensor:

{
  "name": "filmCamera",
  "type": "camera",
  "camera": {
    "sensorSize":   [36, 24],
    "focalLength":  50.0,
    "aperture":     2.8,
    "near":         0.1,
    "far":          1000.0
  }
}

Physically-based — sensor database:

{
  "name": "alexaCamera",
  "type": "camera",
  "camera": {
    "sensor":       "cameras://physicallybased/arri_alexa_35.json",
    "sensorFormat": "4K 16:9",
    "focalLength":  35.0,
    "near":         0.1,
    "far":          1000.0
  }
}

Field	Description
`fov_deg`	Vertical field of view in degrees (legacy mode)
`sensorSize`	`[width, height]` in mm — enables physical FoV calculation
`focalLength`	Lens focal length in mm — used with `sensorSize`
`sensor`	`cameras://` URI to a real-world sensor profile
`sensorFormat`	Format name to pick from the sensor profile's `formats` array
`aperture`	f-stop number (default `2.8`)
`focusDistance`	Focus distance in metres (default `1e6`)
`exposureCompensation`	EV offset (default `0.0`)
`near`	Near clip plane
`far`	Far clip plane

Lighting

`light`

See Lighting System for the full reference including physical units, colour temperature, and the real-world light source database.

{
  "name": "sun",
  "type": "light",
  "light": {
    "type":        "directional",
    "direction":   [-0.4, -1.0, -0.6],
    "temperature": 5778.0,
    "intensity":   400.0,
    "unit":        "lx",
    "castShadow":  true
  }
}

{
  "name": "torch",
  "type": "light",
  "light": {
    "type":        "point",
    "temperature": 2700.0,
    "intensity":   800.0,
    "unit":        "lm",
    "radius":      5.0
  },
  "transform": { "translate": [3.0, 2.0, 0.0] }
}

{
  "name": "spotlight",
  "type": "light",
  "light": {
    "type":           "spot",
    "color":          [1.0, 1.0, 1.0],
    "intensity":      12.0,
    "radius":         10.0,
    "cone_inner_deg": 15.0,
    "cone_outer_deg": 30.0
  },
  "transform": { "translate": [0.0, 4.0, 0.0], "rotate": [-90.0, 0.0, 0.0] }
}

Field	Applies to	Description
`type`	all	`"directional"`, `"point"`, or `"spot"`
`color`	all	RGB colour (0–1)
`intensity`	all	Brightness value (see units below)
`unit`	all	Physical unit: `"artist"` (default), `"lm"` (lumens), `"lx"` (lux), `"cd/m2"` (nits)
`direction`	directional	World-space direction vector
`radius`	point, spot	Influence radius / attenuation falloff
`cone_inner_deg`	spot	Inner (full-brightness) cone half-angle
`cone_outer_deg`	spot	Outer (falloff-to-zero) cone half-angle

Physical light units

When "unit" is set, the engine converts intensity to its internal representation:

Unit	Meaning	Conversion
`"artist"`	Engine-scaled (no conversion)	Pass-through
`"lm"`	Lumens — luminous flux	Point: `lm / 4π` → candela; Spot: adjusted for cone solid angle
`"lx"`	Lux — illuminance (lm/m²)	Pass-through (used directly for directional lights)
`"cd/m2"`	Nits — luminance	Pass-through

`probe`

A reflection / IBL capture probe. The engine captures a cubemap from this position and uses it for local reflections and ambient light.

{
  "name": "probe_south",
  "type": "probe",
  "probe": { "radius": 8.0 },
  "transform": { "translate": [0.0, 1.5, 4.0] }
}

Field	Description
`radius`	Influence sphere radius — objects outside this radius use a different probe

`environment`

Loads and bakes an IBL environment (irradiance map, pre-filtered specular, etc.). Only one environment node per scene is meaningful; additional ones are ignored.

{
  "name":  "outdoor_ibl",
  "type":  "environment",
  "environment": "environments://neutral.json",
  "properties": {
    "blur": 0.0
  }
}

Field	Required	Description
`environment`	yes	`environments://` URI to an IBL environment descriptor
`properties.blur`	no	Skydome blur amount — `0.0` = sharp panorama, `1.0` = fully blurred (default `0.0`)

See Model Descriptors and the environments folder for available descriptors.

Gameplay

`marker`

An invisible named point in the world. Used by scripts and the engine to locate spawn points, attach points, camera anchors, waypoints, and similar logical positions.

{
  "name": "spawn_player",
  "type": "marker",
  "transform": { "translate": [0.0, 0.1, 0.0] }
}

Markers have no visual representation at runtime. They can be children of other nodes (e.g. a weapon attach point parented to a character mesh).

`trigger`

An invisible volume that fires a named event when an object enters or exits it. The Lua script system will listen for these events by marker name.

{
  "name":    "door_proximity",
  "type":    "trigger",
  "trigger": {
    "shape":  "box",
    "size":   [2.0, 2.5, 0.5],
    "on_enter": "door_open",
    "on_exit":  "door_close"
  },
  "transform": { "translate": [0.0, 1.25, 3.0] }
}

Field	Description
`shape`	`"box"` or `"sphere"`
`size`	`[x,y,z]` for box, or `radius` for sphere
`on_enter`	Event name broadcast when an object enters the volume
`on_exit`	Event name broadcast when an object exits the volume

Audio

`audio`

Planned

The audio node type is parsed by the scene loader but has no runtime implementation yet. The JSON format below is forward-compatible — scenes can include it without errors.

A 3D positional audio source. Attenuates with distance.

{
  "name": "fireplace_crackle",
  "type": "audio",
  "audio": {
    "src":        "sounds://ambience/fireplace.ogg",
    "loop":       true,
    "volume":     0.8,
    "radius_min": 1.5,
    "radius_max": 8.0
  },
  "transform": { "translate": [2.0, 0.5, -1.0] }
}

Field	Description
`src`	`sounds://`-relative path to the audio file
`loop`	Loop playback
`volume`	0–1 gain
`radius_min`	Full-volume distance
`radius_max`	Silence distance (linear falloff between min and max)

Rendering

`decal`

Planned

The decal node type is parsed by the scene loader but has no runtime implementation yet. The JSON format below is forward-compatible.

Projects a texture onto the geometry beneath it. Good for damage marks, dirt, wet patches, and decor without modifying base meshes.

{
  "name": "blood_splat_01",
  "type": "decal",
  "decal": {
    "material": "shaders://decal_pbr.json",
    "texture":  "textures://decals/blood_01.png",
    "size":     [0.6, 0.6, 0.2]
  },
  "transform": { "translate": [1.0, 0.01, 2.0], "rotate": [0.0, 45.0, 0.0] }
}

Field	Description
`material`	Shader/material package for the decal
`texture`	Diffuse texture to project
`size`	`[x,y,depth]` — projection box extents

`post_process_volume`

Planned

The post_process_volume node type is parsed by the scene loader but has no runtime implementation yet. The JSON format below is forward-compatible.

Overrides post-processing settings for objects inside its bounds. Useful for mood changes between areas — a dark cave vs. a bright exterior.

{
  "name": "cave_interior",
  "type": "post_process_volume",
  "post_process_volume": {
    "global": false,
    "size":   [20.0, 8.0, 30.0],
    "blend_distance": 2.0,
    "tonemap": {
      "exposure": 0.4
    },
    "ssao": {
      "radius": 0.3,
      "bias":   0.02
    }
  },
  "transform": { "translate": [0.0, 4.0, 0.0] }
}

Field	Description
`global`	`true` → affects the whole scene regardless of position
`size`	Box extents of the influence volume (ignored when `global: true`)
`blend_distance`	Distance over which settings fade in at the volume boundary
`tonemap.*`	Overrides for tonemap settings (e.g. `exposure`)
`ssao.*`	Overrides for SSAO settings

Any field omitted inside a volume block falls back to the engine config value.

Quick reference​

Structure​

group​

src​

Geometry​

model​

skydome​

Camera​

camera​

Lighting​

light​

Physical light units​

probe​

environment​

Gameplay​

marker​

trigger​

Audio​

audio​

Rendering​

decal​

post_process_volume​

Quick reference

Structure

`group`

`src`

Geometry

`model`

`skydome`

Camera

`camera`

Lighting

`light`

Physical light units

`probe`

`environment`

Gameplay

`marker`

`trigger`

Audio

`audio`

Rendering

`decal`

`post_process_volume`