TJ
145 lines
3.8 KiB
Markdown
145 lines
3.8 KiB
Markdown
# 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 ]
|
|
}
|
|
```
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## `RoomItem`
|
|
|
|
Every item in the `items` array shares this base shape:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
### `ItemArg`
|
|
|
|
```json
|
|
{ "argument": "key", "value": "value_as_string" }
|
|
```
|
|
|
|
All values are serialized as strings.
|
|
|
|
---
|
|
|
|
## Per-type `resourcename` and custom args
|
|
|
|
### Basic shapes
|
|
|
|
| Creator type | `resourcename` | Custom args |
|
|
|---|---|---|
|
|
| `Cube` | `Cube` | `color`, `opacity` |
|
|
| `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` |
|
|
|
|
### Room access
|
|
|
|
| Creator type | `resourcename` | Custom args |
|
|
|---|---|---|
|
|
| `Entrance` | `Entrance` | _(none)_ |
|
|
| `Exit` | _(not implemented in save)_ | — |
|
|
| `RoomTeleporter` | _(not implemented in save)_ | `roomid` |
|
|
|
|
### Streaming / media
|
|
|
|
| Creator type | `resourcename` | Custom args |
|
|
|---|---|---|
|
|
| `Billboard` | `Billboard` | `url` (file path) |
|
|
| `LiveKitStream` | `LiveKitStream` | `LiveKitRoomID`, `shader`, `GreenScreenColor`, `GreenScreenBorderSettings`, `GreenScreenColorNear`, `widthcrop`, `heightcrop` |
|
|
| `VideoWall` | `VideoWall` | `file`, `widthcrop`, `heightcrop` |
|
|
| `Presentation` | `PresentationWall` | `file` |
|
|
| `Camera` | `CCTVCamera` | `target` (`"x,y,z"`), `fov` (derived: `zoom * 60`) |
|
|
|
|
### Other
|
|
|
|
| Creator type | `resourcename` | `type` field | Custom args |
|
|
|---|---|---|---|
|
|
| `Text` | `Text` | `pre-defined` | `text`, `color`, `fontSize`, `fontWeight` |
|
|
| `Whiteboard` | _(not implemented in save)_ | `pre-defined` | _(none)_ |
|
|
| `Custom` | _(the asset filename)_ | `user-defined` | `file` |
|
|
|
|
### Common optional arg (all types)
|
|
|
|
| Arg | Type | Description |
|
|
|---|---|---|
|
|
| `grabable` | `"true" \| "false"` | Whether the item can be grabbed in-experience |
|
|
|
|
---
|
|
|
|
## Example — Directional Light
|
|
|
|
```json
|
|
{
|
|
"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
|
|
{
|
|
"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
|
|
}
|
|
```
|