World document format
Read this page as Markdown · All docs for AI agents
A world document contains version, floor, walls and entities, with optional buildSize, skins, terrain and background. Unknown fields are rejected.
| Field | Format |
|---|---|
version | Integer 1 |
floor, walls | Six-digit hex colors such as #e8ddc6 |
buildSize | Optional integer 56–384; placement square width. Defaults to 56. |
entities | Array of placed props and game stations |
terrain | Optional seeded terrain parameters; see terrain and backgrounds |
background | Optional sky, lobby panorama or owned image hash and rotation |
skins | Optional game skin manifests |
Each entity must contain all seven fields:
| Field | Rules |
|---|---|
id | 1–80 ASCII letters, digits, colon, underscore or hyphen; unique in the world |
kind | prop or game |
asset | Built-in prop/game name, or upload: followed by an owned 64-character lowercase hex hash |
position | [x,y,z]; X/Z within ±buildSize / 2; Y 0…64 |
yaw | Finite radians from −2π through 2π |
scale | Three finite values, each 0.1…12; games require exactly [1,1,1] |
color | Six-digit hex color |
The reserved entrance region rejects origins with abs(x) < 3 and z > buildSize / 2 - 6. NaN, infinities, duplicate IDs, extra script fields, foreign asset hashes and URL-valued asset references are rejected.
Game identity
A game's ID is <asset>:<index>, for example blackjack:0, dice:0 or blackjack_group:0. The index must be available in the live catalog. Games use unit scale and may sit at any floor elevation from Y = 0 to 64. Their native geometry and all interactions move together with the entity. The schema cannot express every cross-field rule; the server enforces these semantics as well.
Ordinary Blackjack stations use indices 0–10. Shared multiplayer seats are generated by the two blackjack_group stations, indices 0–1. Do not place their shared seats as independent Blackjack tables.
Built-in props
Available props are floor, wall, doorway, windowwall, stairs, ramp, block, pillar, carpet, bench, planter and bar. The six modular pieces come from building-kit-v1.glb. See Build in the game for dimensions and openings. Their geometry is supplied by the platform template GLB. Custom GLB props use normalized source geometry; placement scale controls their dimensions.
Props use instanced rendering. Modular doorway/window pieces have open collision, and stairs/ramps use walking slopes. Other props use box-shaped collision. They are static. Build enterable structures from separate wall, floor and stair entities, leaving openings between them; a single uploaded building shell has a solid bounding box. In room mode, the floor expands with buildSize and the ceiling rises for elevated objects. The entrance spawn is [0, 0, buildSize / 2 - 2]. In outdoor mode, terrain must be at least buildSize + 64 wide. Resize the document before moving entities beyond its current bounds. Game models have their platform interaction geometry and controls. Large props can obstruct paths even if their origins are valid, so inspect the playable scene.
Draft and published revisions
Draft revisions start at 1 and increment on successful saves. Every save requires the current revision. Published content changes only when the owner publishes. Players join the published revision, not the latest draft.
Fetch the JSON schema for structural validation and catalog for current supported assets. Budget enforcement, ownership and game semantics remain server-side even if your JSON schema validator accepts a document.
Optional game skins
The top-level strict document accepts optional skins, an array of up to 32 v1 or v2 skin manifests. A game entity may include "skin": "my-skin-id". The definition must exist, its game must equal the entity asset, its fingerprint must match that game, and every referenced model must be in the authenticated creator library. Props cannot use skin. Skin IDs are unique within the document. Unused definitions still undergo schema and ownership validation. Omit the entity field to use native visuals.
Skin definitions are saved and published with the world revision. world_upload, draft PUT and game_skin_save enforce the same ownership, revision and budget constraints. This field never enables scripts, additional action types, dynamic parameter expressions or external asset URLs.