Map format

A map is a Tiled document plus a layout of our own. The Tiled document draws the map: tiles, layers, collisions and text. The layout holds what people interact with: areas and their behaviours, placed entities, room settings and metadata. Authors draw in Tiled, upload a package, and place or change the rest with the editor in the game.

This page describes version 1. The files in schema/ are its machine-readable half:

go test ./schema checks that the reference maps and the examples on this page are valid, that each rule in the error tables rejects a broken document, and that the custom types match the vocabulary.

Packages

A package is a zip archive that holds one map:

manifest.json      required
plaza.tmj          the Tiled document, at the root
layout.json        an optional layout document, at the root
tiles.png          tileset images, sounds, documents and other assets, in any folder
sounds/chime.wav

Manifest

{ "version": 1, "map": "plaza.tmj", "layout": "layout.json" }

Files

Paths use letters, digits, spaces and ._()+-, with / between folders. The upload skips files and folders whose name starts with a dot, the __MACOSX folder, and Tiled's .tiled-project and .tiled-session files. Every other file needs one of the extensions above. Tiled's XML formats and its external tileset and template files are refused with a hint: save the map as JSON, embed the tilesets and detach the templates.

Limits

The upload measures the bytes it unpacks, not the sizes the archive claims. Tenant quotas apply on top.

Upload

Admins of a tenant upload a package with POST /api/v1/maps to create a map, or with PUT /api/v1/maps/{map}/package to replace its package, as the multipart field package; so does an API key of the tenant with the scope maps:write (Partner API), sent as the bearer token to one of the tenant's hosts, which suits a build pipeline: no person's session expires under it. Each upload goes to the audit log as map.created or map.replaced, with the admin or the key as its actor. An Idempotency-Key header makes a repeated upload answer what the first one did, for a day. Authors push a folder or a zip archive from the command line:

vws maps push --url https://acme.example.com --token "$TOKEN" ./plaza
vws maps push --url https://acme.example.com --key "$KEY" --map <map id> ./plaza

--token is an access token of an admin of the site's tenant, and --key an API key with maps:write; without either, the command takes VWS_API_KEY, else VWS_ACCESS_TOKEN. The upload:

• The Tiled document is validated and its areas are imported into the layout, as Areas drawn in Tiled describes.
• A new map without a layout document gets a layout made of the imported areas, with metadata from the Tiled map properties.
• A package with a layout document replaces the stored layout. Areas in it whose id starts with tiled- are replaced by the import, so a downloaded package uploads again unchanged.
• A replacement without a layout document keeps the stored layout: areas made in the game stay, imported areas are replaced, and the Tiled map properties name, description, copyright and thumbnail overwrite the metadata fields they set.
• The package's files replace the map's files, and rooms using the map reload it: each sends its members a notice of kind NOTICE_KIND_REFRESH_REQUIRED.

An error rejects the whole package; warnings come back with the result. Both use the error document.

GET /api/v1/maps lists the tenant's maps, newest first, for its admins; every map the API answers, from the listing, GET /api/v1/maps/{map} or an upload, names the rooms that use it with their paths, so that the administration shows what a replacement reloads.

Storage

A map's files live in object storage under tenants/<tenant id>/maps/<map id>/<version>/, where the version is the first 16 hexadecimal digits of a SHA-256 over the package's paths and contents. A folder therefore never changes, and GET /api/v1/maps/{map}/files/<version>/<path> serves its files as cacheable for a year. The room snapshot's tiled_url names the current version's Tiled document, whose relative paths resolve inside the same folder. A replacement keeps the previous version for the clients still loading it and deletes older ones. Every stored file has a file_object row of kind map_asset, deleted with the file. GET /api/v1/maps/{map}/layout serves the layout with an ETag that changes with the map.

layout.unknown-prefab and layout.unknown-collection check a layout against the tenant's entity catalogue.

Tiled documents

Tiled is a third-party editor with an open JSON format. The format accepts what Tiled 1.9 and later save, with these conventions.

Map

• Orthogonal and finite, with tiles of 32 × 32 pixels, at most 512 × 512 tiles.
• Tile layers saved as CSV, which Tiled writes as a JSON array; base64 and compression are refused.
• Tilesets embedded in the map, each based on one image. Tiles larger than the grid sit on the bottom-left corner of their cell, as in Tiled.
• No object templates: detach template instances before saving.

Layers

• Group layers flatten into group/child names, and children inherit the group's opacity, visibility and offset. Names should be unique after flattening, because scripts address layers by name.
• Exactly one top-level object layer is named avatars, and it stays empty. Layers before it draw under avatars, layers after it draw over them.
• Hidden layers load but neither draw nor collide; scripts can show them.
• Image layers are not drawn.

Collisions

A cell blocks avatars when a visible tile layer has a tile in it whose tileset tile sets the property collides to true, or when the tile layer itself sets collides to true. A collision layer that nobody sees is a visible tile layer with collides and an opacity of 0. The layout's entities block the cells their prefabs' collision grids cover (Entities). Players never collide with each other.

Objects

Tiled 1.10 and later save an object's class as type, Tiled 1.9 as class; both work.

Areas drawn in Tiled

An area is a rectangle of class area, not rotated. Its name is the area's name. Each behaviour is a custom property whose type is the behaviour's class from the vocabulary:

{
  "id": 8,
  "name": "meeting-room",
  "type": "area",
  "x": 96,
  "y": 96,
  "width": 160,
  "height": 128,
  "rotation": 0,
  "visible": true,
  "properties": [
    { "name": "capacity", "type": "class", "propertytype": "capacity", "value": { "max": 6 } },
    { "name": "meeting", "type": "class", "propertytype": "meeting", "value": { "name": "plaza-meeting", "hostTags": "staff, facilities" } }
  ]
}

• The class members are the behaviour's fields, with the same names and defaults.
• The property's name becomes the behaviour's id, so it follows the id rules.
• A list of tags is text, with the tags separated by commas.
• A colour may be #RRGGBB or Tiled's #AARRGGBB; the alpha is dropped.
• A module area's settings are JSON text, such as {"title": "Welcome"}; empty text sets none.
• Tiled does not save a member that equals its default. A required field therefore has no useful default in Tiled, and leaving it unset is an error.

Import schema/tiled-types.json with Tiled's Custom Types Editor to get the class area and every behaviour class with its members and defaults.

The upload copies each area into the layout with the id tiled- followed by the object id, its coordinates rounded to whole pixels. The area above becomes:

{
  "id": "tiled-8",
  "name": "meeting-room",
  "x": 96,
  "y": 96,
  "width": 160,
  "height": 128,
  "properties": [
    { "id": "capacity", "type": "capacity", "data": { "max": 6 } },
    { "id": "meeting", "type": "meeting", "data": { "name": "plaza-meeting", "hostTags": ["staff", "facilities"] } }
  ]
}

Imported areas belong to the Tiled document: the editor in the game shows them but cannot change them, and the next upload replaces them.

Map, tileset and tile properties

The upload warns about every other property and ignores it.

Variables

A map property of class variable declares a room variable. The property's name is the variable's name: letters, digits and _.-, starting with a letter or _.

Scripts can only set declared variables. The tags are those of a player's membership of the room's world; the realtime protocol describes how variables are read, written and kept.

Layout documents

{
  "version": 1,
  "areas": [
    {
      "id": "6f1d2c1e-5a43-4c0e-9d7a-3b8e2f4a9c10",
      "name": "kiosk",
      "x": 704,
      "y": 544,
      "width": 64,
      "height": 64,
      "properties": [
        { "id": "kiosk-website", "type": "website", "data": { "url": "https://example.com/kiosk", "trigger": "action" } },
        { "id": "kiosk-hint", "type": "tooltip", "data": { "text": "Press space for the kiosk" } }
      ]
    }
  ],
  "entities": [
    {
      "id": "3d0c3a43-91a4-4f0b-8a51-2f3a6c1b9e70",
      "prefab": { "collection": "lounge", "id": "0f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" },
      "x": 512,
      "y": 320,
      "properties": [
        { "id": "radio-music", "type": "audio", "data": { "url": "sounds/lounge.mp3", "loop": true, "radius": 160, "shared": true } }
      ]
    }
  ],
  "collections": ["lounge"],
  "settings": { "broadcast": { "enabled": true, "title": "Town hall", "tags": ["staff"] } },
  "metadata": { "name": "Plaza", "thumbnail": "thumbnail.png", "tags": ["reference"] }
}

Every field but version is optional. Coordinates are whole map pixels from the top-left corner.

Ids

Areas, entities and properties have ids of 1 to 64 letters, digits and _.-, starting with a letter or a digit. Area and entity ids are unique in the layout, and property ids within their area or entity. The editor creates UUIDs; hand-written layouts may use readable ids. Ids that start with tiled- belong to areas imported from Tiled.

Areas

Entities

A player reaches an entity standing within 48 pixels of its image, and activates it there with the action key or a click on it, whatever the triggers of its behaviours. Its websites and files open as an area's do and close once the player walks out of reach, and its meeting holds the player until then. Its sounds fade to silence over their radius as the player walks away and stop beyond it; without a radius, a sound plays at full volume until the player walks out of reach. A shared sound plays for everyone in the room whom its radius reaches, or for everyone without a radius. An entity that an access area hides from a player does not act for it.

Properties

A property is { "id": ..., "type": ..., "data": { ... } }, where type names a behaviour of the vocabulary and data holds its fields. Fields left out take their defaults.

Settings

Metadata

Assets

An asset field takes a path in the package or an absolute http or https URL. Paths are served from the map's files. website.url and embed.url take URLs only, because a page served from a package would run on the product's own origin.

Vocabulary

An area or entity holds any number of website, file and audio properties and at most one of each other type. start and exit exclude each other, and so do meeting, speaker and listener.

Triggers decide when a behaviour acts: enter when the player enters the area, action when the player presses the action key after a prompt, and icon by adding the panel collapsed, as an icon. A user setting turns enter into action for websites and files. On entities, behaviours act when the player activates the entity, whatever the trigger.

start

exit

An exit needs room, start or both.

website

The panel closes when the player leaves the area.

embed

Shows the page inside the area's rectangle on the map, whether anyone stands there or not.

file

audio

In an area, the sound stops when the player leaves.

meeting

With a provider, the meeting takes place in the outside tool. The room starts no meeting of its own there, its players stay out of bubbles as in any meeting, and the action key opens link in a new browser tab, whatever the trigger, since browsers open a tab only on a gesture of the player's. A player who opened it shows as in a meeting while it stands in the area. A zoom link's host is zoom.us, zoomgov.com or one of their subdomains, a teams link's teams.microsoft.com or teams.live.com, and a meet link's meet.google.com, written in lower case as browsers write them; other takes any https address.

A meeting scheduled in a meeting area with an outside link (Identity) takes the area over the same way from 15 minutes before its start until its end, and the platform's meeting returns afterwards. The room tells its players the link as the meeting property's link state, checks every minute which scheduled meetings run, and learns at once of a meeting in an outside tool scheduled or cancelled.

speaker

listener

Speaker and listener areas with the same stage form one broadcast: the players in a speaker area broadcast to those in its listener areas, who see and hear them while one speaks and the waitingUrl while nobody does. Players in either area stay out of bubbles; their status shows as broadcasting or listening.

silent

Players inside show as silent and never join proximity bubbles. It has no fields.

focus

highlight

tooltip

description

chat

access

lock

capacity

desk

module

An area kind of a module the tenant added (Extensions). A player who enters the area opens the module's page for it in the side panel, where the room turns the module on; elsewhere the area does nothing.

Runtime rules

Players and areas

• A player's position is the point under the avatar's feet, in map pixels. A player is in an area when x ≤ px < x + width and y ≤ py < y + height.
• Every area that contains the player applies its behaviours. Where several do, focus and highlight come from the smallest, and from the later one in the layout when sizes are equal; so does the meeting or stage the player talks in, of its meeting, speaker and listener areas, so that a speaker area inside a meeting room is a stage while the player stands in it.
• Entering an area that has a name shows the name briefly.
• Editors are members with the editor, admin or owner role. They pass every tag check of this page.

Start position

The first of these that applies places a joining player:

1. A resumed session keeps its position.
2. An entry point, from an exit or the URL fragment (#name), picks a start area with that name, at random when several share it; an exit without start uses the rules below from step 3.
3. The position where the player last left this room, when it was saved less than an hour ago and can still be entered.
4. The player's own desk.
5. A start area with default, at random.
6. Any start area, at random.
7. The centre of the map.

The server saves each account's position per room in Postgres whenever the player leaves the room, and keeps it until the account or the room is deleted.

In an area, the player lands on a random walkable point at least 16 pixels from its edges, or on the middle of a side too short for that; an area without a walkable point is passed over. A blocked centre of the map gives way to the walkable cell nearest to it. Walkable means free of the Tiled document's collisions and of the cells the layout's entities block, as their prefabs' collision grids mark them (Entities); a player who returns within the hour to a point an entity now covers enters by these rules instead.

The server applies steps 2, 3, 5, 6 and 7, from the start area that Join.spawn names; resume brings step 1, and desks step 4. A join through an exit without start looks the same as any other join in protocol v1, so it starts from step 3.

Exits

Walking into an exit area switches rooms without reloading the page and places the player at the exit's start. An exit without room, or to the current room, moves the player to that start area. When the player may not enter the destination, a notice says so and the player stays. Standing in an exit area when the room loads does not count as walking into it.

Access, locks and capacity

• An access area blocks players without one of its enterTags like a wall, and they do not see the entities whose centre it holds.
• The people in a conversation can lock it: those inside a meeting area, the owner of a desk, and players inside a lock area with one of its tags. They lock and unlock with the action key. A locked area blocks players outside it, while players inside may stay, and the players in any area of a locked meeting walk between its areas; guests with a valid link to a scheduled meeting still enter its room (Identity).
• A capacity area blocks players outside it while max players are inside.
• A blocked entry flashes the area and shows a notice. The client keeps the player out like a wall; a move the room refuses all the same, from a client that had not heard of a lock yet, returns the player to where the room keeps it.

Room-wide state of a property travels in the realtime protocol's AreaState, keyed by area id, property id and key:

Behaviours in the client

The client applies what concerns only the player: it opens websites and files in a panel or a browser tab and closes the panel when the player leaves, plays sounds, joins meetings with the action key where they wait for it, opens the outside tools of meetings in a browser tab, shows silence, tooltips and the names of areas, fits the camera to focus areas, darkens the map round highlight areas and shows embeds over the map. Space is the action key.

Desks

A desk belongs to at most one member, who returns there after an absence of more than an hour, can walk back to it, and can lock it for a private meeting. Guests and anonymous users cannot own desks. Ownership is stored apart from the layout, so copying a map does not copy claims, and claims survive uploads as long as the area and property ids stay the same.

Errors

The upload answers an invalid package with an RFC 9457 problem whose issues list every finding: status 413 when the upload is too large, 422 otherwise. A valid package's result lists its warnings the same way.

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The package was refused. Errors: 2, warnings: 1.",
  "issues": [
    { "severity": "error", "code": "tiled.finite", "file": "plaza.tmj", "pointer": "/infinite", "message": "Infinite maps are not supported." },
    { "severity": "error", "code": "layout.website", "file": "plaza.tmj", "pointer": "/layers/7/objects/3/properties/2/value", "message": "The website behaviour needs a url." },
    { "severity": "warning", "code": "tiled.unknown-property", "file": "plaza.tmj", "pointer": "/properties/6", "message": "The property mood is not part of the format and is ignored." }
  ]
}

A failed schema rule has the code <document>.<rule>, where the rule is the schema's $defs entry that holds the failed keyword, or document for the top level. A rule that requires an array to contain an item is reported once, at the array. Behaviours of areas drawn in Tiled fail with the layout code of their type. The upload performs the checks marked "upload", which need more than one document or the files themselves.

Package and manifest

Tiled document

Layout document

Versions

• The manifest and the layout carry a version, which changes only with a breaking change. The Tiled conventions follow the manifest's version, and stored layouts record theirs in map.layout_version.
• An addition keeps the version: a new behaviour, a new optional field with a default, a new setting. Servers reject fields and types they do not know, so a package that uses an addition needs a server that has it.
• A breaking change raises the version: a field renamed or removed, or given another meaning or default. Servers then accept packages of earlier versions and migrate them on upload, migrate stored layouts in the release that brings the change, and serve only the current version.
• Each migration is listed below with test fixtures of both versions, and schema/ keeps the schemas of every version still accepted.

There are no migrations yet.