xrwise-datastructure/data-structure-database.md

# Database Data Structure

This document describes the JSON format saved to and loaded from the database.

---

## Top-level: `RoomExport`

```json
{
  "guid": "string",
  "skybox": "string | null",
  "sky-color": "#rrggbb",
  "jsonversion": 2.0,
  "items": [ ...RoomItem ],
  "groups": { ...SceneGroups },
  "background_sound": "string | null"
}
```

| Field | Type | Description |
|---|---|---|
| `guid` | `string` | Unique room identifier |
| `skybox` | `string \| null` | Skybox asset path (currently unused) |
| `sky-color` | `string` | Background hex color |
| `jsonversion` | `number` | Schema version (`2.0`) |
| `items` | `RoomItem[]` | All objects in the room |
| `groups` | `SceneGroups` (optional) | Item/group hierarchy created via the Grouping feature. Omitted entirely when there are no groups |
| `background_sound` | `string \| null` (optional) | Storage path of the uploaded ambient sound file, set from World Settings → Sound |

---

## `RoomItem`

Every item in the `items` array shares this base shape:

```json
{
  "id": 0,
  "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "rotation": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 },
  "type": "pre-defined | user-defined",
  "resourcename": "string",
  "item-custom-args": [ ...ItemArg ],
  "item-custom-args-adv": null
}
```

> **Coordinate system note:** The X-axis is flipped on save (`x` = `-creator_x`) and un-flipped on load. Y-axis rotation is also negated.

> **`id`:** Stable numeric identifier assigned when the item is created in the Creator (the key of the in-memory `SceneItems` record). It is preserved across save/load rather than derived from array position, so group membership and block-coding references (`sourceItemId`/`targetItemId`) keep pointing at the right item even after items are added or removed. Rooms saved before this field existed fall back to array index on load.

### `ItemArg`

```json
{ "argument": "key", "value": "value_as_string" }
```

All values are serialized as strings.

---

## `SceneGroups`

Top-level `groups` field grouping items (and other groups) so they can be selected/moved together in the Creator. Keyed by numeric group ID, parallel to `items` being keyed by item ID.

```json
{
  "1": {
    "name": "Group 1",
    "children": [
      { "kind": "item", "id": 4 },
      { "kind": "item", "id": 7 },
      { "kind": "group", "id": 2 }
    ]
  }
}
```

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Display name, editable in the Item List |
| `children` | `GroupChild[]` | Members of the group — either an item (`{ "kind": "item", "id": <RoomItem.id> }`) or a nested group (`{ "kind": "group", "id": <group id> }`) |

Group membership references stable `RoomItem.id`s (see the `id` note above), so groups keep pointing at the right items across save/load. The `groups` field is omitted from the export entirely when the room has no groups.

---

## Per-type `resourcename` and custom args

### Basic shapes

| Creator type | `resourcename` | Custom args |
|---|---|---|
| `Cube` | `Cube` | `color` |
| `Sphere` | `Sphere` | `color` |
| `Cylinder` | `Cylinder` | `color` |
| `Cone` | `Cone` | `color` |
| `Floor` | `Plane` | `color`, `opacity` |
| `Wall` | `Wall` | `color`, `opacity` |

### Lights

| Creator type | `resourcename` | Custom args |
|---|---|---|
| `Directional Light` | `Directional Light` | `color`, `intensity`†, `target` (`"x,y,z"`) |
| `Point Light` | `Point Light` | `color`, `intensity`† |

> †`intensity` is the key saved in the database, but Unity reads `brightness` — the args will not apply at runtime until this mismatch is resolved. See individual object docs.

### Room access

| Creator type | `resourcename` | Custom args |
|---|---|---|
| `Entrance` | `Entrance` | _(none)_ |
| `GoToOtherRoom` | `GoToOtherRoom` | `RoomName`, `UUID`, `color` _(❌ not yet implemented in Creator or Unity)_ |

### Streaming / media

| Creator type | `resourcename` | Custom args |
|---|---|---|
| `Billboard` | `Billboard` | `url` (Supabase storage path, signed at runtime) |
| `LiveKitStream` | `LiveKitStream` | `LiveKitRoomID`, `shader`, `GreenScreenColor`, `GreenScreenBorderSettings`, `GreenScreenColorNear`, `widthcrop`, `heightcrop` |
| `VideoWall` | `VideoWall` | `file`, `shader`, `volume`, `controls`, `autoplay`, `widthcrop`, `heightcrop` |
| `Presentation` | `PresentationWall` | `file`, `widthcrop`, `heightcrop`, `controls` _(❌ not in Creator)_ |
| `Camera` | `CCTVCamera` | `target` (`"x,y,z"`), `fov` (derived: `zoom * 60`) |

### Logic

| Creator type | `resourcename` | Custom args |
|---|---|---|
| `Area` | `Area` | `color`, `opacity` _(serialized but not user-editable; the area is always rendered as an orange glow in the editor)_ |

> The Area Collider is an editor-only helper zone with no Unity-side visual — its footprint is defined by `scale.x`/`scale.z`. It is picked as the `sourceItemId` of an `"in_area"` Block Coding trigger (see [Block Coding data structure](./data-structure-block-coding.md)).

### Other / Props

| Creator type | `resourcename` | `type` field | Custom args |
|---|---|---|---|
| `Text` | `Text` | `pre-defined` | `text`, `color`, `fontSize`, `fontWeight` |
| `Whiteboard` | `WhiteboardWall` | `pre-defined` | _(none — not serialized by Creator)_ |
| `Custom` | _(asset filename)_ | `user-defined` | `file`, `color`, `material` |

#### `material` values (Custom, Speaker)

| Value | Shader |
|---|---|
| `0` | Metallic |
| `1` | Unlit |
| `2` | Specular |
| `3` | FakeEmission |

### Common optional arg (all types)

| Arg | Type | Description |
|---|---|---|
| `grabable` | `"true" \| "false"` | Whether the item can be grabbed in-experience |
| `locked` | `"true" \| "false"` | Whether the item is locked against moving/deleting in the Creator. Editor-only concern — Unity/runtime does not read this arg |

> `grabable` and `locked` are both written by the shared `buildCustomArgs()` helper, so they are present on every type **except** `Text`, `Billboard`, and `Entrance`, which build their `item-custom-args` array by hand and currently omit both.

---

## Example — Directional Light

```json
{
  "id": 0,
  "position": { "x": 0, "y": 5, "z": 0 },
  "rotation": { "x": 0, "y": 0, "z": 0 },
  "scale":    { "x": 1, "y": 1, "z": 1 },
  "type": "pre-defined",
  "resourcename": "Directional Light",
  "item-custom-args": [
    { "argument": "color",     "value": "#ffffff" },
    { "argument": "intensity", "value": "20" },
    { "argument": "target",    "value": "0,0,0" }
  ],
  "item-custom-args-adv": null
}
```

## Example — CCTV Camera

```json
{
  "id": 1,
  "position": { "x": 0, "y": 4, "z": 0 },
  "rotation": { "x": 0, "y": 0, "z": 0 },
  "scale":    { "x": 1, "y": 1, "z": 1 },
  "type": "pre-defined",
  "resourcename": "CCTVCamera",
  "item-custom-args": [
    { "argument": "target", "value": "0,0,0" },
    { "argument": "fov",    "value": "60" }
  ],
  "item-custom-args-adv": null
}
```

## Example — Custom (user-uploaded GLB)

```json
{
  "id": 2,
  "position": { "x": -4.0, "y": 1.0, "z": 0.0 },
  "rotation": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 },
  "type": "user-defined",
  "resourcename": "b83a17ab-92bf-4122-a4d0-7b467a105ae0/podest.glb",
  "item-custom-args": [
    { "argument": "file",     "value": "b83a17ab-92bf-4122-a4d0-7b467a105ae0/podest.glb" },
    { "argument": "color",    "value": "#ffffff" },
    { "argument": "material", "value": "0" }
  ],
  "item-custom-args-adv": null
}
```