HowTo rC3 world maps
As last year's, this year's rC3 will feature a kind of 2D adventure, the rc3.world. This tutorial is intended to explain how assemblies can contribute their own maps and content. For any remaining questions, don't hesitate to contact us via mail; we'll do our best to extend this page.
To exchange with others there is a channel in the public chat.
Meta Information
Disclaimer
This tutorial is "work in progess" and may be occasionally updated, checking it from time to time is recommended.
Known Bugs
The following bugs are already known, and we're working on resolving them:
- Exits on the far right end of a map don't work.
- Loading a tileset twice (with the same name) results in interesting rendering bugs (e.g. missing tiles in WorkAdventure)
Quick overview
Limitations
Instances wont scale indefinitely, please keep that in mind while building maps. Even if the infrastructure itself could handle a high number of clients on a single map, workadventure will still attempt to render all avatars at the same time, to the point that browsers (and network connections) won't be able to keep up. From experience, the limit appears to be around 200 players. Please keep that in mind when designing maps.
Even so, map size is relatively independent from simple user count, and can be set flexibly. Maps at around 50x50 tiles seem to be pretty fine; maps at around 500x500 tiles will take a non-trivial time to load. In general we recommend against unreasonably large maps, so visitors won't get "lost" in them and still have a chance to stumble across each other.
Please don't use any tilesets whose textures are larger than 4096x4096 pixels; rendering errors may occur otherwise, depending on browser and WebGL support
As last year, links leaving the event will be prefixed with a dereferrer ("you are now leaving the event area").
Scripts
You can use all features included in workadventure's
"scripting api extra";
these will all be supported by rc3.world, except for using variables within links
to any kind of ressource (e.g. in the openWebsite property). Additionally,
please note that due to the large amount of review this would necessitate,
including your own self-written javascript will only be possible upon request
(send an email to world@rc3.world).
Starter-Kit
We will again offer a map building starter kit containing a simple map repository which you can clone, use as inspiration, or fork and use as the basis for your own map. However, it is — as well as corresponding tilesets — still a work in progress and will be published here once it is done.
Best Practices
To make visiting the world as comfortable as possible, a set of best practices for designing maps has emerged after last year's rC3 and subsequent divocs. Please read them carefully and keep them in mind when building your new (or updating your old) maps.
The back office will also automatically alert you in case of some especially obvious violations (e.g. exits to nonexistant maps), or suggest improvements.
How does it end up in the world?
To contribute maps to the world, you have to register an assembly.
Please store your maps in a git repo of your choice. Then add a new room to your assembly. Click the button "create" in the "2D map" field. In the next window you can enter the (publicly clonable) URL of the git repo.
Our infrastructure will then periodically pull your map in, run a rudimentary linter on it to check for a few requirements and general consistency, and then deploy it to rc3.world.
Please note that your map may also be rejected in case it contains errors (e.g. exits pointing to maps that do not exist) or is simply in the wrong format. If that is the case, the back office will notify you and show you an appropriate error along with a short explanation — so in case your map doesn't change even after waiting and multiple reloads, please take a look there and check.
Automatic notification
You can also be notified automatically when there is a new linter result.
To do this, create a file named .mapservice in the root directory of your repo.
In this file you enter in which channel of the CCCV rocket chat the bot should write:
{"rocket_channel" : "#<CHANNEL>"}. The channel can also be a person,
in this case you enter {"rocket_channel" : "@nick"} in the file.
Important: The account Rocket.Cat needs to be able to access your channel.
Links between maps
Within your repository you can use normal, relative links — e.g. to get from
one map in main.json to another at garden/secret-base.json, just enter the
corresponding path (same for the other direction: ../main.json will take you
back).
The same also holds for links to tilesets etc.
Please do not use absolute paths (i.e. paths starting with a /), since — on
the rc3.world – these paths would be outside of your repository.
Links to places outside your own assembly
Attention: Does not work as it did last year!
To get to other assemblies or other places in general (e.g. the lobby), use the following link schema:
world://<assembly>/<map>.json
Where assembly is the "technical name" (i.e. slug) of the target assembly, as
set in the Maschinenraum for your own assembly. The remaining path is then relative
to the map repository of the linked assembly.
To get back to the lobby, just use lobby as the slug. The link you'll have to use to connect your map to the lobby will be shown in the Maschinenraum.
Since the validity of such links does not just depend on your own repository but also the entire event (and may even change over time), we cannot check such links statically when pulling in your repository. So please take extra care that these links don't lead into nothingness.
Entrypoint / Lobby / Exit
We will create central entry maps, through which one can reach everyone's assembly maps.
Obviously, your own map should contain at least one exit back to the lobby. As a recognisable and consistent exit, we recommend you use the following tile to mark it:
Map design
Tiles
Fundamentally, maps consist of so-called tiles or sprites (there are differences between these two terms, but they will in the following be used as synonyms). Please only use tiles that are 32x32 pixels large.
Tiles can also be transparent, and are saved in the PNG format.
Finding tiles:
- We provide many tiles created for the event in our
Shared Tiles Repo. These are also available as a git
repository at
https://git.cccv.de/rc3/world-tiles.git. However, please note that we do not support git submodules; please add the files you need to your own repository directly. - Countless tiles are available on the internet, often combined into tilesets (multiple tiles for one topic).
- Some examples of websites offering awesome tiles:
- Be sure to check that the tiles have the correct size (32x32)!
- Check the license of the tiles!
- We will not actively check the licenses of your tiles, but react to violations on a "takedown on notice" principle!
- Document the license of your tiles via the custom property
tilesetCopyright(type string) on the tileset.
How to design / "pixel" tiles
You can also design your own tiles (or edit exisiting ones); this is frequently referred to as "pixeling". We recommend using the editor krita, though of course the principle is the same for other programs.
- Please double check that your tiles are 32x32 pixels in size. You can enable a grid under view -> show grid, and under settings -> dockers -> grid you can select the grid size.
- Use transparency for modelling transitions between different materials. This is more flexible and saves you time by not modeling every possible transition between all materials.
- You can also watch blinry's pixel-art on media.ccc.de
Maps
Map are created with the editor Tiled. As in many graphics editors, a map consists of multiple layers, which are stacked on top of each other when rendering. Layers can also be (partially or wholly) transparent.
Creating a new map in tiled
When creating a new map, please ensure the following:
- The map must be orthogonal, and its tile size 32x32 pixels
- When editing a map, it may be useful to set its size to be infinite instead of deciding a fixed size beforehand. However, you will have to set its size back to some (finite) fixed size when saving it before you can load it into workadventure!
Map design - Layer
A map can consist of an arbitrary number of tile layers, which are stacked on top
of each other. Each map will need at least one tile layer named start. Visitors
to your map will then spawn on a random tile of this layer by default (you can
move this layer to the bottom of the stack, and let its tiles be covered by other
layers). You will also need another layer named floorLayer of the type
Object Layer, which defines on which layer avatars will move (i.e. which layers
will be rendered above or below them).
For a better mapping experience, highlight the current layer:
Walls and collision
To mark tiles as impervious, open them in the tile editor and set the custom
property collides to the boolean value true for the specific tile (not the
containing layer!). Although Tiled allows defining custom collision shapes for
tiles, these are unsupported and simply ignored by our software.
