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

{
  "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:

{
  "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

{ "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	Presentation	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

{
  "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

{
  "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
}