xrwise-datastructure/data-structure-creator.md

Creator Data Structure

This document describes the internal data structures used by the XRWise Creator editor.

---

SceneItem

A single object in the scene. Stored in the Zustand store as Record<number, SceneItem>.

type SceneItem = {
  // --- always present ---
  type:       ItemType                    // e.g. "Cube", "Camera", "Directional Light"
  category:   string                      // e.g. "Basic", "Light", "Streaming"
  position:   [number, number, number]    // world-space XYZ

  // --- transform ---
  rotation?:  number[]                    // Euler degrees [x, y, z]
  dimensions?: number[]                   // XYZ scale / size in metres

  // --- appearance ---
  color?:     string                      // hex color e.g. "#ffffff"
  opacity?:   number                      // 0–1

  // --- lights ---
  intensity?: number | string             // light intensity
  target?:    number[]                    // look-at point [x, y, z]

  // --- media / streaming ---
  file?:              string              // asset path or storage key
  LiveKitRoomID?:     string
  shader?:            string              // "unlit" | "lit" | "greenscreen"
  GreenScreenColor?:  string              // hex color
  GreenScreenBorderSettings?: string      // numeric string
  GreenScreenColorNear?:      string      // numeric string (0–1)
  widthcrop?:         number
  heightcrop?:        number
  videoJobId?:        string              // in-progress conversion job ID

  // --- text ---
  text?:       string
  fontWeight?: "light" | "regular" | "bold"
  fontSize?:   number

  // --- camera ---
  zoom?:       number                     // 1–10; maps to FOV = 50 / zoom

  // --- interactions ---
  grabable?:   boolean
}

Fields by item type

Type	Required fields	Optional fields
Cube / Sphere / Cylinder / Cone	position	color, opacity, dimensions, rotation
Floor	position	color, opacity, dimensions, rotation
Wall	position	color, opacity, dimensions, rotation
Directional Light	position, target	color, intensity
Point Light	position	color, intensity
Entrance / Exit	position	—
Billboard	position, file	dimensions, rotation
LiveKitStream	position, LiveKitRoomID	shader, GreenScreenColor, GreenScreenBorderSettings, GreenScreenColorNear, widthcrop, heightcrop, dimensions, rotation
VideoWall	position	file, videoJobId, widthcrop, heightcrop, dimensions, rotation
Presentation	position	file, dimensions, rotation
Camera	position, target	zoom, rotation
Text	position, text	color, fontSize, fontWeight, dimensions, rotation
Custom	position, file	dimensions, rotation

Common optional field (all types)

Field	Type	Description
grabable	boolean	Whether the item is interactable in-experience

---

SceneItems

The full scene is stored as a flat map keyed by numeric ID:

type SceneItems = Record<number, SceneItem>

IDs are assigned sequentially when items are spawned and do not change.

---

SceneStore (Zustand)

The complete editor state. Fields marked 💾 are persisted to localStorage under the key scene-storage.

Field	Type	Default	💾	Description
items	SceneItems	{}	✅	All scene objects
selected	number | null	null	✅	Currently selected item ID
skyColor	string	"#ffffff"	✅	Background color
showGrid	boolean	true	✅	Grid visibility
customItems	CustomItem[]	[]	✅	User-uploaded GLB assets
showLights	boolean	true	✅	Light helper visibility
showWalls	boolean	true	✅	Wall visibility
showDummy	boolean	false	✅	Stickman dummy visibility
cameraTarget	number[]	[0,0,0]	✅	OrbitControls look-at point
cameraRotation	number[]	[0,0,0]	✅	Editor camera rotation
cameraQuaternion	[x,y,z,w]	[0,0,0,0]	✅	Editor camera quaternion
message	string | null	null	—	Transient toast message
isDragging	boolean	false	—	Pointer drag state
isTyping	boolean	false	—	Text input focus state
orbitControls	OrbitControlsImpl | null	null	—	Live OrbitControls ref
api	ScreenshotAPI | null	null	—	Screenshot renderer ref

---

ITEMS_CONFIG spawn defaults

When an item is added to the scene, it is initialized with these values from items-config.tsx:

Type	dimensions	color	rotation	spawnY	customAttributes
Cube	[1,1,1]	#ffffff	[0,0,0]	0.5	—
Sphere	[1,1,1]	#ffffff	[0,0,0]	0.5	—
Cylinder	[1,1,1]	#ffffff	[0,0,0]	0.5	—
Cone	[1,1,1]	#ffffff	[0,0,0]	0.5	—
Floor	[10,0.1,10]	#ffffff	[0,0,0]	0	—
Wall	[20,5,0.1]	#ffffff	[0,90,0]	2.5	—
Point Light	[1,1,1]	#ffffff	[0,0,0]	5	intensity: 50, target: [0,0,0]
Directional Light	[1,1,1]	#ffffff	[0,0,0]	5	intensity: 20, target: [0,0,0]
Entrance	[1,1,1]	#ffffff	[0,0,0]	0.1	—
Exit	[1,1,1]	#962929	[0,0,0]	0.1	—
Billboard	[1,1,1]	#ffffff	[0,0,0]	4	file: "/img/default-img.png"
LiveKitStream	[1,1,1]	#ffffff	[0,0,0]	4	LiveKitRoomID: "Gas Station"
VideoWall	[1,1,1]	#ffffff	[0,0,0]	4	—
Presentation	[1,1,1]	#ffffff	[0,0,0]	4	—
Camera	[1,1,1]	#444444	[0,0,0]	4	zoom: 1, target: [0,0,0]
Text	[0.5,0.5,0.5]	black	[0,0,0]	2	text: "Text", fontWeight: "regular", fontSize: 5
Custom	[1,1,1]	#ffffff	[0,0,0]	1	—