Initial commit: creator and database data structure docs

2026-06-09 08:46:59 +02:00
commit 9c5f8dde79
2 changed files with 281 additions and 0 deletions
@@ -0,0 +1,139 @@
+# 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>`.
+
+```ts
+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:
+
+```ts
+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` | — |