Map Building Admin User Developer Tutorials Login Get Started Search ctrl K

Api Reference

Camera Map Storage API

WAM vs TMJ files, the 2 sides of
WorkAdventure maps
Chat

Controls Map Storage API Getting the endpoint and the authentication
token

Event Passing the authentication token to your request

SELF HOSTED FREE PLAN PREMIUM PLAN Creating a new room

Map Editor API
Minimal WAM file
Metadata The Map Storage API is an HTTP REST API used by developers to create and update rooms stored in the WorkAdventure server.
WAM file format
Navigation
Reading a WAM file

Player Editing a WAM file

Players Deleting a WAM file

Storing other kind of files

Room

Sound

Start

State

UI

Deprecated Functions
WAM vs TMJ files, the 2 sides of WorkAdventure maps
Extended utility functions
If you have already created a map for WorkAdventure, you already know that maps are designed in Tiled. Tiled produces TMJ files,
Tiled Layers
which are JSON files that describe the map. Those files can be hosted on any web server.
Tiled Properties

Svelte You might also have noticed that WorkAdventure has an inline map editor. This editor allows you to add objets to the map such as
tables, chairs... and also interactive areas.
Variables

Scripting Internals Because the TMJ file can be hosted anywhere on the web, WorkAdventure does not have write access to the TMJ file. Therefore, the
inline map editor cannot modify the TMJ file. Instead, the inline map editor edits WAM files.
Using Typescript

Map Storage API

Room API

Webhooks

There is one WAM file for each room of your world.

The WAM file is a JSON file that contains the list of objects and interactive areas. It also points to the TMJ file that should be used to
render the map.

Those WAM files are stored (along other regular files) in the map-storage container. The map-storage API allows you to create, update
and delete any file within that container.

So in order to create a new room for your users, you will just need to create a new WAM file in the map-storage container.

Getting the endpoint and the authentication token

SAAS Self-hosted

The map-storage API is protected by an authentication token. You can find this token, along the URL of the endpoint in the
administration dashboard of WorkAdventure.
Connect to your dashboard, and go to Developers > API keys / Zapier.

If you do not already have an API key, click on "Create new token".

Passing the authentication token to your request

The Map Storage API is a REST API. Therefore, you need to pass the authentication token using the Authorization HTTP header, as a
"Bearer" token (you need to prefix the token with the word "Bearer " in the Authorization HTTP header).

Sample query:

PUT /my_office.wam
Authorization: Bearer [your_token]

{
// WAM file content
}

Creating a new room

To create a new room, you will use the PUT HTTP method on the map-storage API. The path of the request is the name of the WAM file
you want to create.

For instance, if you want to create a new room called office/first_floor.wam , you will send a PUT request to the following URL:

PUT /office/first_floor.wam

SAAS Self-hosted

Your map can then be accessed at the following URL:

https://play.workadventu.re/@/[organization_slug]/[world_slug]/office/first_floor.wam

If you are using a custom domain, the map URL will be:

https://[your_domain]/@/office/first_floor.wam

Minimal WAM file

Here is a minimal WAM file:

{
"version": "1.0.0",
"mapUrl": "https://your_server/your_map.tmj",
"entities": {},
"areas": [],
"entityCollections": [
{
"url": "https://play.workadventu.re/collections/FurnitureCollection.json",
"type": "file"
},
{
"url": "https://play.workadventu.re/collections/OfficeCollection.json",
"type": "file"
}
],
"metadata": {
"name": "The map name",
"description": "A description displayed when sharing the map",
"thumbnail": "https://your_server/thhumbnail.png",
"copyright": "Credits: ..."
}
}

The mapUrl property is the URL of the TMJ file that will be used to render the map.

The entityCollections property is the list of collections of objects that will be available in the inline map editor. You can learn more
about the file format of those collections in the inline map editor documentation.

WAM file format

If you are interested in the JSON schema of the WAM file, you can find it here:
https://github.com/workadventure/workadventure/blob/master/docs/schema/1.0/wam.json

Reading a WAM file

To read a WAM file, you will use the GET HTTP method on the map-storage API.

GET /office/first_floor.wam

Editing a WAM file

You can modify special parts of a WAM file using the PATCH HTTP method.

The PATCH HTTP method expects a valid JSON Patch document as the body of the request.

PATCH /office/first_floor.wam
Content-Type: application/json-patch+json'
Authorization: Bearer [your_token]

{
"op": "add",
"path": "/metadata/name",
"value": "The new name of the map"
}

Deleting a WAM file

You can delete a room using the DELETE HTTP method.

DELETE /office/first_floor.wam
Authorization: Bearer [your_token]

Storing other kind of files

Although the map-storage API is primarily for WAM files, it can store various file types, including TMJ files, tilesets, and more. However,
it's often easier to store these files on a regular web server, utilizing platforms like GitHub Pages or GitLab Pages for deployment.

INFO

Need help 🆘

Contact us or write us to [email protected]

Edit this page

Previous Next
« Using Typescript Room API »

Docs Need help ? Follow us

Map Building Book a demo Linkedin

Admin Discord Twitter

Developer GitHub Facebook

Copyright © 2024 workadventu.re - All Rights Reserved