World model v1

Scenes are JSON documents loaded by UniverseWorld.loadScene(). The validator requires version === 1.

Top-level fields

Field	Type	Required	Description
version	number	yes	Must be 1.
title	string	no	Human label for tooling.
nodes	array	yes	Solid instances in the scene.
camera	object	yes	Default viewpoint for perspective renderers.
sim	object	no	Physics config (dt, integrator, gravity, ground, bodies).

Node object

Field	Type	Required	Description
id	string	yes	Stable identifier (used in DOM data-node-id).
type	string	yes	Solid type (see below).
pose	object	yes	Position and rotation.
size	number or [w,h,d]	no	Edge length for polyhedra (default half-size 0.5).
radius	number	no	Sphere radius (default 0.5).

Solid types

type	Alias	Size field
tetrahedron	—	size
hexahedron	cube → hexahedron	size
octahedron	—	size
dodecahedron	—	size
icosahedron	—	size
sphere	—	radius

Pose object

Field	Type	Default	Description
x, y, z	number	0	Translation in scene units.
rx, ry, rz	number	0	Euler rotation in degrees (X, then Y, then Z).

Camera object

Used by perspective projection and WebGL demos.

Field	Type	Default	Description
kind	string	—	"perspective" (informational in v1).
eye	[x,y,z]	[3,2,5]	Camera position.
target	[x,y,z]	[0,0,0]	Look-at point.
fov	number	50	Vertical field of view in degrees.
up	[x,y,z]	[0,1,0]	Up vector for basis construction.

Sim block

Optional physics configuration consumed by UniverseSim.createSim(). When bodies is empty or omitted, the scene is visual-only; renderers ignore sim. When bodies are present, each step updates linked node poses.

Top-level sim fields

Field	Type	Default	Description
dt	number	0.016	Integration timestep (seconds).
integrator	string	"semi_implicit_euler"	Declared in JSON; runtime uses semi-implicit Euler only.
gravity	[x, y, z]	[0, -9.81, 0]	Constant acceleration on awake bodies.
ground	object	{ y: 0, restitution: 0.4 }	Horizontal ground plane (see below).
bodies	array	[]	Rigid bodies bound to nodes (see below).

ground

Field	Type	Default	Description
y	number	0	Ground height in world units (Y-up).
restitution	number	0.4	Bounce on ground impact (clamped to 0.6 at runtime).

bodies[]

Field	Type	Required	Default	Description
id	string	yes	—	Body id (independent of nodeId).
nodeId	string	yes	—	Target nodes[].id; pose sync writes x, y, z.
mass	number	no	1	Mass for impulse resolution.
restitution	number	no	0.4	Bounce coefficient (clamped to 0.6).
velocity	[x, y, z]	no	[0, 0, 0]	Initial linear velocity.
angularVelocity	[x, y, z]	no	[0, 0, 0]	Stored; not applied to pose.rx/ry/rz in v1.
shape	"sphere" | "aabb"	no	inferred	sphere for sphere nodes; aabb for polyhedra.
awake	boolean	no	true	Skip integration when false.

Full behaviour and API: Simulation.

Example (visual-only)

"sim": {
  "dt": 0.016,
  "integrator": "semi_implicit_euler",
  "bodies": []
}

Example (sim bounce fixture)

"sim": {
  "dt": 0.016,
  "integrator": "semi_implicit_euler",
  "gravity": [0, -9.81, 0],
  "ground": { "y": 0, "restitution": 0.35 },
  "bodies": [
    { "id": "b1", "nodeId": "ball-a", "mass": 1, "restitution": 0.45, "velocity": [0.4, 0, 0.1], "shape": "sphere" }
  ]
}

Example scene

{
  "version": 1,
  "title": "Hexahedron and sphere projections",
  "camera": {
    "kind": "perspective",
    "eye": [3, 2, 5],
    "target": [0, 0.5, 0],
    "fov": 50
  },
  "nodes": [
    {
      "id": "hexahedron",
      "type": "hexahedron",
      "pose": { "x": -0.8, "y": 0.5, "z": 0, "ry": 35, "rx": 10 },
      "size": 1
    },
    {
      "id": "sphere",
      "type": "sphere",
      "pose": { "x": 0.8, "y": 0.5, "z": 0 },
      "radius": 0.55
    }
  ],
  "sim": {
    "dt": 0.016,
    "integrator": "semi_implicit_euler",
    "gravity": [0, -9.81, 0],
    "ground": { "y": 0, "restitution": 0.4 },
    "bodies": []
  }
}

Programmatic scene factory

var scene = UniverseWorld.createPlatonicScene();
// six nodes: all Platonic solids + sphere with default layout

createFiveSolidsScene() is an alias for the same factory.