# World document format

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](/terrain-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](/downloads/building-kit-v1.glb). See [Build in the game](/in-game-editor/#build-floors-and-structures) 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](/world.schema.json) for structural validation and [catalog](/catalog.json) 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](/game-skin-contract/). 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.