Scene Format

A scene is a JSON file inside the scenes/ directory.
It describes a hierarchy of nodes — cameras, lights, model references, probes, skydomes, and logical groups.

Scenes are reference-only: they contain no geometry, texture, or material data. All of that lives in model descriptors (see Model Descriptors). A scene node is a transform + a pointer to a descriptor.

---

Top-level structure

{
  "version": "1.0",
  "description": "Optional human-readable description",

  "settings": {
    "ambient": [r, g, b]
  },

  "nodes": [ ... ]
}

Field	Type	Description
version	string	Schema version ("1.0")
description	string	Optional scene description
settings.ambient	[r, g, b]	Scene-wide ambient light colour (0–1 each channel)
nodes	array	Root-level node list (see below)

---

Nodes

Every node shares a common base, then adds type-specific fields.

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

Field	Required	Description
name	yes	Unique identifier within the scene
type	yes	Node type — see Node Types for the full reference
transform	no	Position / orientation (see Transform)
properties	no	Type-agnostic flags (e.g. cast_shadow, mobility)
children	no	Nested child nodes — same format as the root nodes array

Nodes can be nested to any depth. Children inherit their parent's transform (applied top-down). This is useful for grouping an entire level under a single anchor so it can be repositioned with one transform change.

---

Transform

"transform": {
  "translate": [x, y, z],
  "rotate":    [pitch_deg, yaw_deg, roll_deg],
  "scale":     [x, y, z]
}

All fields are optional. Omitted fields default to identity (zero translation, zero rotation, unit scale). Children accumulate their parent's transform.

---

Properties

"properties": {
  "mobility":       "static",
  "cast_shadow":    true,
  "receive_shadow": true,
  "visible":        true
}

All are optional and default to sensible engine defaults. mobility defaults to "dynamic". Shape, material, and texture overrides do not belong here — put them in the model descriptor.

mobility	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)