Refactoring, done by @Lisk.

docs/maps.en.md

@@ -4,10 +4,9 @@ HowTo rC3 world maps
 This year's remote event will feature a kind of 2D adventure, the rc3 world. This tutorial is intended to show how content and maps can be contributed.
 If you have any questions after reading this tutorial, or feel like its missing something, please feel free to contact us via [mail](mailto:world@rc3.world), and we'll do our best to extend this tutorial.
 
-## Maintenance
-We are curently working on the test server, expect downtimes.
+## Metainformationen
 
-## Disclaimer
+### Disclaimer
 This tutorial is "work in progess", hence its worth checking it from time to time since it will be changed and extended continuously.
 
 ### Updates
@@ -23,7 +22,7 @@ This tutorial is "work in progess", hence its worth checking it from time to tim
 * 2020-12-22: Cross-Assembly Links added.
 * 2020-12-25: Added [exitUrl List](exitUrls.en.md)
 
-## Known Bugs
+### Known Bugs
 Following bugs are known and worked on:
 * Exits on the outer most right tiles dont work
 * exitUrl in combination wir multiple exits to the same map leads to confusion in starting points.
@@ -31,8 +30,10 @@ Following bugs are known and worked on:
 * Loading a tileset twice (with the same name) results in interesting rendering bugs (e.g. missing tiles in WorkAdventure)
 * Tilesets with dimensions above 4096px may cause problems in some browsers.
 
-## Limitations
-Instances wont scale indefinetly, please keep that in mind while building maps. From our experience the limit is somewhere around 200 players. Maps for 2k players wont make any sense. Please dont try to build lecture halls. There's no sense in idling in the game while watching talks.
+## Quick overview
+
+### Limitations
+Instances wont scale indefinitely, please keep that in mind while building maps. From our experience the limit is somewhere around 200 players. Maps for 2k players wont make any sense. Please dont try to build lecture halls. There's no sense in idling in the game while watching talks.
 
 Regardless of this you can choose the map size relativly fleixble.
 Maps in the ballpark of 128x128 tils run quite smooth, maps with 1000x1000 tiles will come with a significant loading time.
@@ -40,13 +41,30 @@ We hence recomend using a number of smaller maps rather than a single big one.
 
 External links will be sent through a dereferrer.
 
-## Starter-Kit
+### Starter-Kit
 We provide a [starter kit](https://git.cccv.de/rc3/world-map-starterkit) in case you don't know how/where to start with your map.
 Just clone the repository and get your assembly started.
 
-## Tiles / Sprites
+### Tiles / Sprites
 The maps consist of so-called tiles or sprites. There appears to be a historical difference between these 2 terms, however we do use them interchangeably. For the rC3 map 32x32 tiles are recomended, as different tile sizes may lead to problems. Tiles may have transparent parts and should be stored in the png format.
 
+### Layer and attributes
+In order for a tile to have more properties than its look, you have to assign the appropriate attributes.
+This is done using layers: A layer carries attributes, and stores for which fields they should apply.
+
+### How will it be linked into the the rC3 world?
+To be able to contribute maps to the world, you need to [register an assembly](https://signup.c3assemblies.de/) and contact [world@rc3.world](mailto:world@rc3.world) naming your assembly name.
+
+Please store your maps in a git repo of your choice and and notify us in our backend with the URL to clone the repo. Our world infrastructure will then spawn an instance for you and embed the map.
+
+We will pull the maps from your git repo on a regular basis. Players need to reload their page to see the newest version (no live-reload).
+
+### Entrypoint / Lobby / Exit
+We create central Entrymaps to join the world and lead to the different assembly maps. Please drop us an email via [world@rc3.world](mailto:world@rc3.world) naming your assemblyname, that we can reserve an exitpoint to your assembly. Besides that we would ask you to reserve a spot for an exit back to the lobby maps on your map. Tiles and the address for the jump will be provided by us via mail.
+
+
+# Map design
+## Tiles
 ### Finding tiles:
 * There are many tiles available on the internet, often combined into tilesets (multiple tiles for one topic)
 * Some examples of websites offering awesome tiles:
@@ -66,7 +84,15 @@ You can design your own tiles as well as change exisiting tiles, this is usually
 * Use transparency if you have to model transitions between different materials. This is more flexible and saves you time by not modeling every transition.
 * Pixel-Art Workshop by blinry: [media.ccc.de/v/34C3-jugend-hackt-1016-pixel_art_workshop](https://media.ccc.de/v/34C3-jugend-hackt-1016-pixel_art_workshop)
 
-## Tile integration
+### Walls and collision
+To mark tiles as impervious, you have to open the them in the tile editor and set the custom property `collides` (bool true) for the specific tile. (Do not confuse this with a layer property!)
+Tiled provides custom collision shapes for tiles, however these are ignored by our software.
+
+![](img/edit_tileset.png)
+
+![](img/cp_collides.png)
+
+### Tile integration
 Linking to external tilesets in TSX format is not possible, tiles need to be embedded in tiled (see below). (PNG files need to be uploaded to the server as well.)
 
 ## Maps
@@ -80,10 +106,31 @@ When creating a new map please ensure the following conditions are met:
 * When creating a map it might be useful to use a infite size map, however when saving you need to select a fixed size.
 
 ### Map design
-A map may consist of any number of tile layers. Your map needs a start layer which defines where your players spawn. This layer needs to be called "_start_". Additionally you need a layer called "_floorLayer_" of the type object layer on which the players move.
+A map may consist of any number of tile layers. Your map needs a start layer which defines where your players spawn. This layer needs to be called `start`. Additionally you need a layer called `floorLayer` of the type object layer on which the players move.
 
 ![](img/layer.png)
 
+For a better mapping experience, highlight the current layer:
+
+![](img/settings_show_animations.png)
+
+## Special layers
+There are a few special layers which are used for additional features. Except for the start layer these layers are created through the custom properties of individual layers.
+
+
+### Start layer
+Your map needs a start layer named `start`. All locations in this layer that contain a tile (no matter which) will be spawn points for new players. A random tile of this layer will be selected upon entry if there are multiple tiles. It's best if you push this layer to the bottom of your stack, this way the layers above will cover the start tiles.
+
+It's possible to create additional start layers to define more entry points, this for example allows users to jump across the map. These layers work in a similar way as the start layer: Just place tiles anywhere you'd like players to spawn. These layers have no naming requirement, but need the custom property `startLayer` (bool true). The name of this layer will also function as the jump address that is needed for spawning there. E.g. if your map is called `foo.json` and the start layer that you want to jump to is called `bar`, then the jump address/marker is called `foo.json#bar`.
+
+![](img/cp_startlayer.png)
+
+### Exit Layer
+Similar to the start layer you can define exits. You create a layer, put a tile on the areas you want the exits to be and give the layer the custom property `exitUrl` (string). The value of the property should be the map and start layer of the map you want to join to, for example `foo.json#bar` to get to the map `foo.json` and the layer `bar`.
+
+![](img/cp_exiturl.png)
+
+
 #### World Exit
 We recommend the following tile for your exit(s) back to the lobby map for a more consistent user experience.
 
@@ -91,50 +138,40 @@ We recommend the following tile for your exit(s) back to the lobby map for a mor
 
 You individual exitUrls are listed [here](exitUrls.en.md)
 
-#### Highlight current layer
-For a better mapping experience, highlight the current layer:
 
-![](img/settings_show_animations.png)
+There will probably placeholders for links to other assemblies. Once there are news we will add them here. [TODO]
 
-#### Special layers
-There are a few special layers which are used for additional features. Except for the start layer these layers are created through the custom properties of individual layers.
+#### Crossy-Assembly links
+There will be placeholders which get automatically replaced by the right url. Example for a placeholder: `{<SLUG>/map.json#YourStartLayer}`. **< and > are important and need to stay in the placeholder!**
 
-##### Start layer
-Your map needs a start layer named "_start_". All locations in this layer that contain a tile (no matter which) will be spawn points for new players. A random tile of this layer will be selected upon entry if there are multiple tiles. It's best if you push this layer to the bottom of your stack, this way the layers above will cover the start tiles. It's possible to create additional start layers to define more entry points, this for example allows users to jump across the map. These layers work in a similar way as the start layer: Just place tiles anywhere you'd like players to spawn. These layers have no naming requirement, but need the custom property "_startLayer_" (bool true). The name of this layer will also function as the jump address that is needed for spawning there. E.g. if your map is called _foo.json_ and the start layer that you want to jump to is called "_bar_", then the jump address/marker is called _foo.json#bar_.
+You can find _your slug_ in the Maschinenraum under Organisational Data -> Basic Data -> "Slug".
 
-![](img/cp_startlayer.png)
+If you want to link to the foobar assembly for example and the foobar assemblys slug is `foobar`, the value for the exit layer would be `{<foobar>/main.json}`.
 
-##### Exit Layer
-Similar to the start layer you can define exits. You create a layer, put a tile on the areas you want the exits to be and give the layer the custom property "_exitUrl_" (string). The value of the property should be the map and start layer of the map you want to join to, for example "_foo.json#bar_" to get to the map _foo.json_ and the layer _bar_.
+Attention: This does **not** work for the test instance.
 
-![](img/cp_exiturl.png)
 
-There will probably be a placeholder for links to other assemblies. As soon as there are news about this, we'll put them here. [TODO]
+## Advanced content
 
-##### Embedding websites
-You can embed websites that will open when stepping on certain tiles. To do this, give the layer the property "openWebsite" (string). Use https.
+### Embedding websites
+You can embed websites that will open when stepping on certain tiles. To do this, give the layer the property `openWebsite` (string). Use https.
 
 ![](img/cp_openwebsite.png)
 
-##### Embedding jitsi
-Jitsi rooms may be embedded into maps in the same way. Simple set the custom property "jitsiRoom" (string) and input the room name as the value.
+### Embedding jitsi
+Jitsi rooms may be embedded into maps in the same way. Simple set the custom property `jitsiRoom` (string) and input the room name as the value.
 
 ![](img/cp_jitsiroom.png)
 
-By default jitsi rooms will be bound to the instance, this is to ensure that everyone has their own "hackcenter". Please prefix your room with "shared", should you want to share a jitsi room across instaces. (e.g. "shared our jitsiroom"). No external jitsi rooms will be allowed only the ones provided by us.
+By default jitsi rooms will be bound to the instance, this is to ensure that everyone has their own "hackcenter". Please prefix your room with `shared`, should you want to share a jitsi room across instaces. (e.g. `shared our jitsiroom`). No external jitsi rooms will be allowed only the ones provided by us.
 
-##### Silent areas
-Should you not want audio and video communication between participants in certain areas, you can set the custom property "silent" bool true in a layer defining the area.
+### Silent areas
+Should you not want audio and video communication between participants in certain areas, you can set the custom property `silent` bool true in a layer defining the area.
 
 ![](img/cp_silent.png)
 
-#### Walls and collision
-To mark tiles as impervious, you have to open the them in the tile editor and set the custom property "collides" (bool true) for the specific tile. (Do not confuse this with a layer property!)
-Tiled provides custom collision shapes for tiles, however these are ignored by our software.
-
-![](img/edit_tileset.png)
-
-![](img/cp_collides.png)
+### Walls / non-accessible areas
+For a change, this is not a layer property, but a tile property.  For a description, see the Tiles section above.
 
 ### Animated Tiles
 Tiles can be combined to animations (loops), for example to make floating water or bliking lights look better. Therefore all frames need to be a single 32x32 tile.
@@ -156,28 +193,24 @@ Bigger animations need to animated in tiled tile by tile. This however is relati
 (Occationally some tiles dont run in sync with the rest, Cthulu knows why...)
 
 ### Sound
-Layers with the property "playAudio" (String) will play a sound associated with the tile. Only mp3 files included via a relativ path to your map are supported. External files can not be included. If you want to include streams, please write an email to [world@rc3.world](mailto:world@rc3.world). If you want to loop the audio please use the property "playAudioLoop" (string) instead.
+Layers with the property `playAudio` (String) will play a sound associated with the tile. Only mp3 files included via a relativ path to your map are supported. External files can not be included. If you want to include streams, please write an email to [world@rc3.world](mailto:world@rc3.world). If you want to loop the audio please use the property `playAudioLoop` (string) instead.
 
 ![](img/cp_playaudio.png)
 
 Please only use **GEMA-free** sound snippets! If you embed streams you will also be required to keep a tracklist to be able to proove to GEMA that you only played "gema-free music".
 
-### Saving and exporting maps
-Maps need to be saved as json files, tilesets should be embedded prior to this. The relevant files the will be you map in json format and will use the tilesets in png format. Infinite maps need to be converted to finite dimension maps before exporting. To do so just untick the "infinite" tick box and safe.
 
-![](img/map_properties.png)
-
-### Licenses
-If you use CC-BY tiles or pictures or want to use your own license, you can add a file named "_COPYRIGHT_". This file has to be on the same level as your map file.
+# Packaging, Deployment and Infrastructure
 
-## How will it be linked into the the rC3 world?
-To be able to contribute maps to the world, you need to [register an assembly](https://signup.c3assemblies.de/) and contact [world@rc3.world](mailto:world@rc3.world) naming your assembly name.
+## Saving and exporting maps
+Maps need to be saved as json files, tilesets should be embedded prior to this. The relevant files the will be you map in json format and will use the tilesets in png format. Infinite maps need to be converted to finite dimension maps before exporting. To do so just untick the "infinite" tick box and safe.
 
-Please store your maps in a git repo of your choice and and notify us in our backend with the URL to clone the repo. Our world infrastructure will then spawn an instance for you and embed the map.
+![](img/map_properties.png)
 
-We haven't worked out how maps will be updated, but it is likely that the map will be pulled every few minutes.
+## Licenses
+If you use CC-BY tiles or pictures or want to use your own license, you can add a file named `COPYRIGHT`. This file has to be on the same level as your map file.
 
-### Folder structure
+## Folder structure
 Please ensure that the right folder structure is used when saving your maps:
 
 * The start map needs to be called main.json and be in the main dir
@@ -190,29 +223,19 @@ A example map might look like this:
 .
 ├── bla
 │   ├── COPYRIGHT
-│   └── keks.json
+│   └── keks.json
 ├── blubb.json
 ├── COPYRIGHT
 ├── foo
-│   ├── bar.json
-│   └── tileset2.png
+│   ├── bar.json
+│   └── tileset2.png
 ├── main.json
 └── tileset.png
 ```
 
-### Entrypoint / Lobby / Exit
-We create central Entrymaps to join the world and lead to the different assembly maps. Please drop us an email via [world@rc3.world](mailto:world@rc3.world) naming your assemblyname, that we can reserve an exitpoint to your assembly. Besides that we would ask you to reserve a spot for an exit back to the lobby maps on your map. Tiles and the address for the jump will be provided by us via mail.
 
-### Crossy-Assembly links
-There will be placeholders which get automatically replaced by the right url. Example for a placeholder: `{<SLUG>/map.json#YourStartLayer}`. **< and > are important and need to stay in the placeholder!**
-
-You can find _your slug_ in the Maschinenraum under Organisational Data -> Basic Data -> "Slug".
-
-If you want to link to the foobar assembly for example and the foobar assemblys slug is `foobar`, the value for the exit layer would be `{<foobar>/main.json}`.
-
-Attention: This does **not** work for the test instance.
 
-### Testing
+## Testing
 For testing you may put the map on any server reachable by https and embed the URL in our test instance. Lets assume your map is stored under _https://example.com/mymaps/foo.json_ then the URL to test it would be *https://test.visit.at.wa-test.rc3.cccv.de/_/global/example.com/mymaps/foo.json*. The option to load external maps is just for testing and will be disabled for rC3.
 
 You might need to set the matching CORS Headers on the server serving the map.