Skip to main content

Upload your Map to WorkAdventure

info

As of May 2024, this is the recommended way of hosting your maps

The WorkAdventure server can host your map files.

In the following sections, we will explain how to upload your map to the WorkAdventure server from the command line (on your local computer), or from a CI/CD pipeline.

Using the command line​

The map starter kit is designed to help you upload maps from your computer to the map storage of WorkAdventure.

In order to use this package run the command in your terminal :

npm run upload

On the first run, the command will ask you the URL to the server and your Map Storage API key and if you want to push your map inside a directory. Where you get this depends on the kind of WorkAdventure server you are using.

You can also use it with flags to upload your map but keep in mind that the secret variables will not be saved in .env and .env.secret files. This are the differents flags :

  • -k for the map storage API KEY
  • -u for the map storage URL
  • -d for the directory

Here is how you can use flags :

npm run upload -- -k your-api-key -u your-mapstorage-url -d your-directory

  1. The URL of your map storage: You can find it in your admin account. Log in. In the left panel, click on "Developers" tab then "API keys / Zapier". There are 3 links, be careful to take the Map-storage API endpoint, it is the url for uploading files to the map storage service of WorkAdventure.

    Get your API Key Get your API Key

    Select the World

    Be careful to select the good world just above before copying your map storage url and create your key

    Choose your world

  2. Your Map Storage API Key: You can find it in in the same section as the map storage url just below. There you can create a new token. (Don't forget to save it !)

  3. Directory: You also have to add a directory name, it will be the folder where all your uploaded files will be stored in. If you want ot store your map in a specific directory, you can edit this in the .env file.

    By default it will be your github name and github repository like this : githubname-githubrepository. This is if you're using github and you forked the map starter kit repository.

    If you're not using github, the script will ask you a directory name and if you leave it empty, by default the directory will be named "maps"

    The directory name appear in the URL of your map.

    Be careful if your not using github and you upload two separate maps with the same directory name, this will erase the first one so we recommand you to set a personal directory name.

Uploading maps overwrites existing files !

When you upload files to the WorkAdventure server, all the files in the directory specified will be removed and replaced by your new files. If you keep the "directory" empty, this means that all the files in your world will be removed and replaced by your new files.

After answering these questions, the script will start to upload your directory. To be sure that it worked, you need to see something like this in your terminal : Upload done successfully !

Now for every change you only just have to commit and push all your changes ! Just wait a few minutes, and your map will be propagated automatically on your server.

info

Your settings have been saved in a .env file (except the map storage API key that was saved in the .env.secret file). If you need to change them, you can edit these files.

Understanding what is happening​

When you run the npm run upload command, the following things happen:

  • First, your map files are "built". During the build phase:
    • the tilesets of your map are optimized. Any tile that is not used is removed. This is done to reduce the total size of the map and results in faster loading times.
    • the scripts of your map are compiled and bundled. This happens if you developed some specific features on your map using the Scripting API. The compilation phase translates files from Typescript to Javascript. The bundling phase takes all the Javascript files and merges them into a single file.
    • the result of the built is written in the dist directory.
    • the content of the public directory is copied to the dist directory.
  • Then, a ZIP file of the dist directory is created and sent to the WorkAdventure "map-storage" server. This server is in charge of hosting the map files. When it receives the ZIP file, it unzips it and stores the files in the directory you configured when you first ran the npm run upload command. For each tmj file the server finds, it will check if there exists a matching wam file. If not, it will create one. wam files are used to store any part of the map edited in the inline map editor of WorkAdventure (like the list of objects or areas, the microphone settings, etc...)
Backup your original files!

The WorkAdventure server only stores the "build" you send to it. It does not store the original files you used to create the map. If you want to update your map, you need to update the original files on your computer and run the npm run upload command again. Do not think you can get back the original files from the WorkAdventure server, because it stores only the "build". It is your responsibility to store the original map files in a safe place in case you want to modify those.

Wrapping things up

In this chapter, we saw how to upload your map from your local computer to the WorkAdventure server using the command line. This works well and for small projects, this is probably the best way to go. In the next chapter, a more robust way to store and work on your map files: a Git repository.

Using Git and a CI/CD pipeline​

A great place to store your original files is in a Git repository (like GitHub or Gitlab). If you are a developer, you probably already know Git. The Git repository offers the following advantages:

  • you store your files in a safe place
  • you can work with other people on the same map
  • you can track the changes you made to the map
  • you can revert to a previous version of the map if you made a mistake
  • you can use a CI/CD pipeline (like "GitHub Actions") to automatically upload your map to the WorkAdventure server when you push changes to the repository.

The map starter kit comes with a GitHub Actions workflow that is designed to upload your map to the WorkAdventure server when you push changes to the master branch of your repository. And now upload on the WA server allows you to push and upload form a private repository

Git is complex

Git is a powerful tool, but it can be complex to use and is very targeted at developers. If you are not familiar with Git, you should probably start with the "command line" solution explained in the previous chapter.

Configuring you project for CI/CD​

If you used the command line solution explained in the previous chapter, you will notice that the upload command generates 2 files:

  • .env that contains the URL of the map storage
  • .env.secret that contains the map storage API key

The .env file can be commited to your Git repository. However, the .env.secret file should never be commited. Indeed, it contains your map storage API key, and if someone gets access to it, they can upload files to your map storage.

Instead, you should use the "secrets" feature of GitHub to store the API key. This way, the API key is not stored in the repository.

Learn how to configure a secret in GitHub

  • Go to your GitHub repository

  • Click on the "Settings" tab The settings tab

  • Click on the "Secrets and variables" link in the left panel The secrets link

  • Click on the "Actions" link The actions button

  • Finally, click on the "New repository secret" button The new repository secret button

You should create a secret named MAP_STORAGE_API_KEY and paste your map storage API key there. See the previous section to know how to get your API key.

Troubleshooting​

Typescript error​

If you are doing some development with the Scripting API, you may encounter Typescript errors when you run the npm run upload command. Indeed, the npm run upload command first performs a build of your Typescript files. If there is a Typescript error, the build will fail.

The error message will be displayed in your terminal. You should fix the error and run the npm run upload command again.

note

When testing your script locally, you are using Vite. Vite is only transpiling Typescript files. It turns them into Javascript without doing any actual type checking. This is why you can have a working script locally and a failing build.

Checking the dist directory​

Remember the map uploaded to the WorkAdventure server is the content of the dist directory. If things are working locally, but act strangely on the server (sound files not playing, HTTP 404 errors, etc...), you should check the content of the dist directory.

You can trigger a build of your map by running the following command:

npm run build

Do not forget that if you want to put random files in the dist directory, you should put them in the public directory. The content of the public directory is copied to the dist directory during the build phase.

My map is not updated (using Git)​

When you push changes to your repository, the GitHub Actions workflow is triggered. It will build your map and upload it to the WorkAdventure server. If you see that your map is not updated, you should check the "Actions" tab of your repository to see if the workflow was triggered and if it failed.

Common reasons for the workflow to fail:

  • the API key is not set in the secrets of your repository
  • the URL of the map storage is not set in the secrets of your repository or in the .env file
  • the build of the map failed (Typescript error, etc...)
  • the workflow did not trigger (you are not pushing to the master branch, etc...)

Need some help?​

WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing. If you are facing any troubles, do not hesitate to seek help in our Discord server or open an "issue" in the GitHub WorkAdventure account.