Skip to content

Creating a map

(This page is work in progress.)

Creating a Waytale map is a wonderfully creative process, but it also involves some technicalities. This section will walk you through the necessary steps.

  • First we look at existing resources as examples to see where the journey goes.
  • We start with designing a map in the Tiled map editor from scratch. This includes adding meta information like which tiles cannot be walked over (collision) or where interactive functionality (gadgets) should happen.
  • Finally a Tiled map needs to be exported as a Waytale map and integrated into a Waytale space, which is described further below.

Examples and using existing resources

Coming soon.

Designing a map in the Tiled map editor

Coming soon.

Exporting to a Waytale map

When you are done designing your map in Tiled or want to try out the current state, you can export the Tiled map (tmx) into the Waytale map format. The requirements to do this include an installed Waytale Toolbox as well as the Tiled map editor. Please see the hints below for details on the Tiled dependency and how to install.

Let's assume you have saved your Tiled maps as village.tmx, castle.tmx, and dungeon.tmx. Then you could either export each map individually (and possibly change the name of the target map directory).

waytale export --write-all /path/to/my/maps/village.tmx /path/to/my/space/village/
waytale export --write-all /path/to/my/maps/castle.tmx /path/to/my/space/castle/
waytale export --write-all /path/to/my/maps/dungeon.tmx /path/to/my/space/dungeon/

Or export all map files in the source directory in one go. The name of the target map directory will be derived from the source file.

waytale export --write-all /path/to/my/maps/ /path/to/my/space/

Note that this only exports map files. Unless you haven't done so before, you very likly need to update the space configuration (space.json). See the next section for details. To verify that your space configuration is consistent, it is recommended to run the following command.

waytale check /path/to/my/space/

Integrating into a waytale space

To add a map to a space, not only the files need to exist, but also the space configuration needs to be updated. In particular, the new map needs listed to be listed and gadgets you might have defined in one or more maps need to be enabled in the Waytale space configuration (i.e. space.json).

Continuing with the example from the previous section and assuming you are only using the official Jitsi (identifier: waytale/jitsi) and Markdown (identifier: waytale/markdown) gadgets, you would add the following highlighted lines to the space configuration.

 {
   "version": 1.0,
   "info": {
     /* ... */
     "maps": [
>      "village",
>      "castle",
>      "dungeon",
   ]
   },
   "gadgets": [
>    "waytale/jitsi",
>    "waytale/markdown"
   ],
   /* ... */
 }

It is recommended to check your space configuration for consistency with the following command.

waytale check /path/to/my/space/

Hints on installing Tiled

If you want to export a Tiled map to Waytale maps, then the tmxrasterizer program is required, which comes as part of the Tiled map editor. You can find installation instructions on Tiled's website.

The Waytale Toolbox expects the tmxrasterizer program to be installed in standard locations. If you have performed a normal installation of Tiled, you should be ready to go.

Note for Linux users. Tiled is widely available through the package repositories of many Linux distributions. Installing using your package manager should be all that is needed. For example, on Ubuntu installing Tiled should not involve more than running sudo apt-get install tiled.

If you have installed Tiled in a non-standard location or the Toolbox command cannot find the tmxrasterizer program for other reasons, then you need to tell the Toolbox's export command where to find the program. This can be done using the --tmxrasterizer-path command line argument, e.g.:

waytale export --tmxrasterizer-path /path/to/tiled/bin/tmxrasterizer --write-all /path/to/my/maps/village.tmx /path/to/my/space/village/

Tiled is also distributed as a one-file AppImage, which comes with tmxrasterizer integrated. If you have installed Tiled as an AppImage, you can also specify the path to the AppImage instead in --tmxrasterizer-path.

waytale export --tmxrasterizer-path /path/to/apps/Tiled-1.12.1_Linux_x86_64.AppImage --write-all /path/to/my/maps/village.tmx /path/to/my/space/village/