Map Upload Package for WorkAdventure

This package is designed to help you upload maps from Tiled to the map storage of WorkAdventure.

Installation

To install this package, use the following command:

npm install @workadventure/upload-maps

Usage

UPLOAD YOUR MAPS ON MAP-STORAGE

This document will guide you through the process of uploading your own map on the map storage. You can also go to the documentation of WorkAdventure just by clicking here : https://docs.workadventu.re/

To use this package, import it into your project and run the command in your terminal:

node_modules/.bin/upload-wa-map

It will ask you some questions:

1. Your API Key. You can find it on https://admin.workadventu.re On the left panel you can go to Developers tab --> API keys / Zapier. There you can create a new token. (Don't forget to save it !)

2. The URL of your map storage. If you're self-hosted, it will be in the admin on : https://admin.workadventu.re On the left panel you can go to Developers tab --> API keys / Zapier. There you can fine "Map-storage API endpoint" it is the url for uploading map storage

3. Upload Directoy You can add a directory name. If you have github and you forked the repository by default the name of the diretory will be your github name and your github repository name. You can also choose a personal name if you want to. If you don't have github, just put the name when the script will ask you by default it will be maps. It will be the folder where all your uploaded files will be stored in.

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 upload directory

Here is how you can use flags :

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

After answering these question, the script will start to upload your file. You need to see something like this : Upload done successfully !

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

1. First, your map files are "built". During the build phase:
2. 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.
3. 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.
4. The result of the built is written in the dist directory.
5. The content of the public directory is copied to the dist directory.
6. 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...)

WARNING :

If you're uploading on WorkAdventure server, it 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.

If you have any questions or need further assistance, don't hesitate to ask ! ([email protected]) or you can check the documentation of WorkAdventure just here : https://docs.workadventu.re/