Scene Format

The Yugma scene format is JSON that describes all objects, transforms, materials, metadata, and relationships.

Top-Level Structure

{
  "objects": { "id1": {...}, "id2": {...} },
  "objectOrder": ["id1", "id2", "id3"],
  "environment": {
    "hdriPreset": "city",
    "backgroundColor": "#1a1a2e",
    "ambientIntensity": 0.4,
    "fogEnabled": false,
    "fogColor": "#000000",
    "fogNear": 10,
    "fogFar": 50
  }
}

SceneObject (v1.5)

{
  "id": "abc1234567",
  "name": "wall_north",
  "type": "box",
  "visible": true,
  "locked": false,
  "castShadow": true,
  "receiveShadow": true,
  "tags": ["wall", "structural"],
  "parentId": null,

  "transform": {
    "position": [0, 1.5, -5],
    "rotation": [0, 0, 0],
    "scale": [10, 3, 0.15]
  },

  "material": {
    "color": "#808080",
    "roughness": 0.9,
    "metalness": 0.0,
    "opacity": 1.0,
    "wireframe": false,
    "emissive": "#000000",
    "emissiveIntensity": 0
  },

  "geometry": {
    "width": 1,
    "height": 1,
    "depth": 1
  },

  "userData": { "customKey": "customValue" },
  "semanticRole": "wall",
  "relationships": {
    "nextTo": ["def4567890"],
    "supports": ["ghi7890123"]
  },

  "createdAt": 1712678400000,
  "updatedAt": 1712678400000
}

Object Types

Type	Description	Key Geometry Params
box	Rectangular prism	width, height, depth
sphere	UV sphere	radius, widthSegments, heightSegments
cylinder	Cylinder	radiusTop, radiusBottom, cylinderHeight
cone	Cone	radius, cylinderHeight
torus	Donut	torusRadius, tube, torusSegments
plane	Flat plane	width, height
capsule	Capsule	radius, cylinderHeight
tetrahedron	Tetrahedron	radius, detail
dodecahedron	Dodecahedron	radius, detail
custom_gltf	Imported model	gltfUrl

Transform

• position — [x, y, z] in meters, world space, Y-up
• rotation — [x, y, z] in degrees, Euler XYZ order
• scale — [x, y, z] multiplier (1.0 = default)

Material

Property	Range	Description
color	hex	Base color
roughness	0.0–1.0	0 = mirror, 1 = chalk
metalness	0.0–1.0	0 = plastic, 1 = metal
opacity	0.0–1.0	Transparency (glass ≈ 0.3)
emissive	hex	Glow color (#000000 = off)
emissiveIntensity	0–10	Glow strength
wireframe	boolean	Wireframe rendering

YSL v1.5 Fields (Optional, Additive)

Field	Type	Description
userData	Record<string, unknown>	Extension point for custom data
semanticRole	string	"wall", "floor", "hero", "prop", "light-source"
relationships.parentOf	string[]	IDs of child objects
relationships.nextTo	string[]	Adjacent objects
relationships.supports	string[]	Objects this one holds up
relationships.references	string[]	Semantic references

All v1.5 fields are optional. Documents saved before v1.5 load unchanged — fields default to undefined.

Environment

Field	Type	Description
hdriPreset	string	city, sunset, dawn, night, forest, studio, warehouse, apartment
backgroundColor	hex	Scene background
ambientIntensity	number	Ambient light (0–2)
fogEnabled	boolean	Volumetric fog
fogColor	hex	Fog color
fogNear / fogFar	number	Fog distance range

Storage

Firestore (Cloud)

Scenes are stored in projects/{projectId} with metadata:

{
  "meta": { "name": "My Project", "ownerId": "firebase-uid" },
  "scene": { "objects": {...}, "objectOrder": [...], "environment": {...} }
}

Share Links

URL-encoded scenes using lz-string compression in the URL hash. Decoded client-side.

GLB Export

Scenes can be exported as GLB via the export menu or the exportScene Cloud Function.