Room Data Format

Room data is an advanced snapshot format used by the room-data download and import routes. It is not a hand-authored configuration format. Start from a snapshot you downloaded from the exact game you plan to change, then make the smallest possible edit.

Snapshot shape

A successful room-data download serializes these top-level sections:

{
  "roomItems": {},
  "settings": {},
  "roomTasks": { "Tasks": [] },
  "quests": {},
  "logic": {}
}

roomItems and settings can be null when that section is unavailable, but a download fails when both are unavailable. roomTasks defaults to an object with a Tasks array, quests defaults to an object, and logic is an object.

Section	Meaning
roomItems	The placed-item map keyed by item identifier.
settings	The complete runtime settings object for the game.
roomTasks	Game-level task data.
quests	Quest data.
logic	Per-item extraData values separated from roomItems for transport.

How logic works

When a snapshot is downloaded, the service removes extraData from each room item and places it in logic under the same item identifier.

For example, if a room item has extra data, the transport shape is conceptually:

{
  "roomItems": {
    "42": { "prefabName": "Example", "...": "item fields without extraData" }
  },
  "logic": {
    "42": "the original extraData value"
  }
}

Do not normalize, reformat, or invent logic values. Preserve them exactly unless you are intentionally changing a supported interaction through a higher-level workflow.

During import, a logic entry is merged back into the matching roomItems entry as extraData. A logic entry without a matching room item is not applied.

Import behavior is deliberately section-aware

The import route reads a JSON document from a publicly readable location. It does not require every top-level section, but the behavior differs by section:

Included section	Import behavior
roomItems	Reconciles the item set. Missing item identifiers are removed, and changed or new items are written.
settings	Rewrites the complete runtime settings object.
roomTasks	Rewrites game-level task data.
quests	Rewrites quest data.
logic	Is merged into matching items only when roomItems is also present.

This means an import containing only settings can change settings without modifying items. An import containing roomItems is destructive for omitted items, so always start from a full backup.

Backup-first workflow

Call the room-data download route for the target game.
Save the returned JSON attachment unchanged as a backup.
Copy the backup and make one focused change in the copy.
Validate that the copy is valid JSON.
Make it available at a location whose HEAD response includes Content-Length and whose content is 50 MB or smaller.
Call the room-data import route with that location.
Open the game and test the exact player path affected by the change.

Do not use this workflow to change a title, description, or thumbnail. Use Rooms for supported top-level metadata instead.

What not to assume

The snapshot is not a versioned public schema for arbitrary item authoring.
Omitted sections are not automatically reconstructed.
A successful HTTP response does not replace player testing.
A JSON source from the service-managed upload route is removed after a successful import; keep your original backup somewhere you control.

For safer in-game behavior work, use Interactive Studio. For connected guidance and scoped workflows, start with MCP setup.

MCP & API