Aug[m]entile – Augment Matrix rooms with a tile map game

Augment Matrix rooms with a tile map game

Introduction

Aug[m]entile is a Matrix-based tile map game player, meaning that it uses Matrix rooms as backend for players moving around and playing on a two-dimensional tile map. It is inspired Work Adventure and the decentralisation efforts by the people around Fediventure.

Primarily, Aug[m]entile is intended to be added as a widget, and the game subsequently be played inside a Matrix client with widget support, e.g. the Element web client. It can also be run stand-alone, taking the place of a Matrix client in that case. Join your favourite room here!

Use cases

The use cases are basically the same as for Work Adventure. Aug[m]entile is especially useful and a considerable alternative for groups or events that already use Matrix for other parts of their event or infrastructure, like to use and foster open standards and protocols, or are looking for a free software alternative to the non-free Work Adventure in general.

Examples include:

• Hack spaces with virtual spaces and meetups
• Team or company hangout
• Conferences, e.g. FOSS or hacker conferences

Making maps

Maps can be created with the Tiled map editor, and Aug[m]entile strives for compatibility with Work Adventure map building features.

Deviations from Work Adventure maps

In order to integrate better with Matrix, some deviations and extensions have been made to the map concepts.

• Exits: exitUrl can contain a simple name of another map in the same room, if maps are added to the room state
• Special zones: Not supported for now, as this requires interaction with other widgets in the room
• Scripts: Scripts in iframes are not supported, and instead of the Work Adventure client API, the Matrix Widget API is available to scripts
• Resources: Resources like images, tilesets, and media can be referenced using mxc:// URLs

Managing game and maps in a room

For now, there is no frontend for game management. Since Matrix uses a simple HTTP client-server API, management can be done using any HTTP client, like cURL.

You will need an access token for a nauthenticated server session and for a user that has sufficient power in the room. Normally, this means you need to be a room admin, or the room needs to have specific power levels configured for the respective events.

Some parts allows users to define their own data in a state by using their Matrix ID as state key. By default, these states can be set by each user for themselves.

Adding maps to a room

Any Matrix room can be augmented with an arbitrary number of maps, by adding the JSON formatted map to the room state under the team.auglement.augmentile.map event. The state key is the map name, which can be used as exitUrl in other maps.

To add a Tiled map to a Matrix room, export your map in JSON format (we will assume you saved it to mymap.json). Then, use cURL to set the state:

curl \
  -X PUT \
  -H "Authorization: Bearer AccessToken" \
  -H "Content-Type: application/json" \
  -d @mymap.json \
  https://matrix.org/_matrix/client/r0/rooms/%21roomid%3Amatrix.org/state/team.auglement.augmentile.map/mymap

You need at least Tiled version 1.6 for this to work due to an incompatible type used before.

Personal maps

Each user in a room can add a personal map under their personal state key. To do this, they simply use their full Matrix ID as the map name in the URL instead of the mymap name in the example above.

Care should be taken when referencing such maps from other maps in the room, or using such maps as starting map in the widget. Users could abuse this possibility to add inappropriate content or even scripts that introduce security risks.

Referencing URLs to maps

Instead of loading the entire map JSON into the room state, maps can be referenced as URLs.

To link an external map to a map name, simply put a JSON object containing only the key url:

curl \
  -X PUT \
  -H "Authorization: Bearer AccessToken" \
  -H "Content-Type: application/json" \
  -d "{'url': 'https://example.com/mymap.json'} \
  https://matrix.org/_matrix/client/r0/rooms/%21roomid%3Amatrix.org/state/team.auglement.augmentile.map/mymap

URLs can also be used everywhere else where maps are referenced, e.g. in exitUrl in other maps or in URL parameters of Aug[m]entile.

Apart from regular https:// URLs, mxc:// URLs are also allowed to reference files uploaded as media to Matrix.

Adding the game as room widget

Using the Element client, the widget can be added with the /addwidget command.

The Aug[m]entile widget can be self-hosted on any webspace (it does not need any active server component), or loaded from the central Augle[m]ent webserver if that does not raise privacy concerns.

Pass the map name to use as GET parameter map, and use placeholders for Element to pass the widget and user IDs into. For the centrally hosted code, this looks like:

/addwidget https://augmentile.auglement.team/augmentile-widget.html?map=mymap&widgetId=$matrix_widget_id&userId=$matrix_user_id

Development and license

Aug[m]entile is developed as part of the Augle[m]ent collection on the EduGit platform.

The project is free and open software, licensed under the Apache License, Version 2.0 or newer.