Merge pull request #1417 from thecodingmachine/doc_special_zones

Migrating documentation to this repository

docs/maps/entry-exit.md

@@ -0,0 +1,67 @@
+{.section-title.accent.text-primary}
+# Entries and exits
+
+https://www.youtube.com/watch?v=MuhVgu8H7U0
+
+## Defining a default entry point
+
+In order to define a default start position, you MUST create a layer named "`start`" on your map. This layer MUST contain at least one tile. The players will start on the tile of this layer. If the layer contains many tiles, the players will start randomly on one of those tiles.
+
+![Start layer screenshot](images/start_layer.png)
+
+In the screenshot above, the start layer is made of the 2 white tiles. These tiles are not visible to the end user because they are hidden below the "bottom" layer that displays the floor of the map.
+
+{.alert.alert-info}
+**Pro tip**: if you expect many people to connect to your map at the same time (for instance, if you are organizing a big event), consider making a large start zone. This way, users will not all appear at the same position and will not pop randomly in a chat with someone connecting at the same moment.
+
+## Defining exits
+
+In order to place an exit on your scene that leads to another scene:
+
+*   You must create a specific layer. When a character reaches ANY tile of that layer, it will exit the scene.
+*   In layer properties, you MUST add "`exitUrl`" property. It represents the URL of the next scene. You can put relative or absolute URLs.
+*   If you want to have multiple exits, you can create many layers. Each layer has a different key `exitUrl` and has tiles that represent exits to another scene.
+
+![](images/exit_layer_map.png)
+
+{.alert.alert-warning}
+**Note:** in older releases of WorkAdventure, you could link to a map file directly using properties `exitSceneUrl` and `exitInstance`. Those properties are now **deprecated**. Use "`exitUrl`" instead.
+
+## Understanding map URLs in WorkAdventure
+
+There are 2 kinds of URLs in WorkAdventure:
+
+*   Public URLs are in the form `https://play.workadventu.re/_/[instance]/[server]/[path to map]`
+*   Private URLs (used in paid accounts) are in the form `https://play.workadventu.re/@/[organization]/[world]/[map]`
+
+Assuming your JSON map is hosted at "`https://example.com/my/map.json`", then you can browse your map at "`https://play.workadventu.re/_/global/example.com/my/map.json`". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.
+
+## Defining several entry points
+
+Often your map will have several exits, and therefore, several entry points. For instance, if there is an exit by a door that leads to the garden map, when you come back from the garden you expect to come back by the same door. Therefore, a map can have several entry points. Those entry points are "named" (they have a name).
+
+In order to create a named entry point:
+
+You can create a new layer for your entry point or use an existing layer with named tiles.
+
+*   If you don't use the layer named "`start`", you MUST add a boolean "`startLayer`" property to the layer properties. It MUST be set to true.
+*   If you use this method, when a character enters the map by this entry point, it will enter randomly on ANY tile of that layer. The name of the entry point is the name of that layer.
+
+![](images/layer-entry-point.png)
+
+You can also use the tiles properties to create entry point.
+
+*   To do that, you will need to have a layer named "`start`" or with the "`startLayer`" property. Then you MUST add a string "`start`" property to a tile than you use in that layer. The name of the entry point is the value that property.
+*   If you use this method, when a character enters the map by this entry point, it will enter on ANY tile of the same kind in that layer.
+
+![](images/tile-entry-point.png)
+
+Notes :
+
+*   Two tiles with a string "start" property with different value can be in the same layer of entries.
+*   A tile with a string "start" property that is not in a layer of entries won't usable as an entry point.
+
+How to use entry point :
+
+*   To enter via this entry point, simply add a hash with the entry point name to the URL ("#[_entryPointName_]"). For instance: "`https://workadventu.re/_/global/mymap.com/path/map.json#my-entry-point`".
+*   You can of course use the "#" notation in an exit scene URL (so an exit scene URL will point to a given entry scene URL)

docs/maps/hosting.md

@@ -0,0 +1,25 @@
+{.section-title.accent.text-primary}
+# Hosting your map
+
+The [Getting Started](.) page proposes to use a "starter kit" that is relying on GitHub pages for hosting the map. This is a fairly good solution as GitHub pages offers a free and performant hosting.
+
+But using GitHub pages is not necessary. You can host your maps on any webserver.
+
+{.alert.alert-warning}
+If you decide to host your maps on your own webserver, you must **configure CORS headers** in your browser to allow access from WorkAdventure.
+
+## Configuring CORS headers
+
+CORS headers ([Cross Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) are useful when a website want to make some resources accessible to another website. This is exactly what we want to do. We want the map you are designing to be accessible from the WorkAdventure domain (`play.workadventu.re`).
+
+### Enabling CORS for Apache
+
+In order to enable CORS in your Apache configuration, you will need to ensure the `headers` module is enabled.
+
+In your Apache configuration file, simply add the following line inside either the `<Directory>`, `<Location>`, `<Files>` or `<VirtualHost>` sections, or within a `.htaccess` file.
+
+    Header set Access-Control-Allow-Origin "*"
+
+### Enabling CORS on another webserver
+
+Check out [enable-cors.org](https://enable-cors.org/server.html) which has detailed instructions on how to enable CORS on many different webservers.

docs/maps/index.md

@@ -0,0 +1,128 @@
+{.section-title.accent.text-primary}
+# Create your map
+
+## Tools you will need
+
+In order to build your own map for WorkAdventure, you need:
+
+*   the [Tiled editor](https://www.mapeditor.org/) software
+*   "tiles" (i.e. images) to create your map
+*   a web-server to serve your map
+
+WorkAdventure comes with a "map starter kit" that we recommend using to start designing your map quickly. It contains **a good default tileset** for building an office and it proposes to **use Github static pages as a web-server** which is both free and performant. It also comes with a local webserver for testing purpose and with Typescript support (if you are looking to use the [map scripting API]({{url('/map-building/scripting')}}).
+
+{.alert.alert-info}
+If you are looking to host your maps on your own webserver, be sure to read the [Self-hosting your map](hosting.md) guide.
+
+[](https://www.youtube.com/watch?v=lu1IZgBJJD4)
+
+## Getting started
+
+Start by [creating a GitHub account](https://github.com/join) if you don't already have one.
+
+Then, go to the [Github map starter kit repository page](https://github.com/thecodingmachine/workadventure-map-starter-kit) and click the **"Use this template"** button.
+
+<figure class="figure my-5">
+    <img src="images/use_this_template.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The "Use this template" button</figcaption>
+</figure>
+
+You will be prompted to enter a repository name for your map.
+
+<figure class="figure my-5">
+    <img src="images/create_repo.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The "create a new repository" page</figcaption>
+</figure>
+
+**Make sure to check the "Include all branches" checkbox, otherwise the Github Pages deployment process will not be setup automatically.**
+
+If you miss that step, don't worry, you can always fix that by clicking on the **Settings tab** of your repository and scroll down to the **GitHub Pages** section. Then select the **gh-pages** branch. It might already be selected, but please be sure to click on it nonetheless (otherwise GitHub will not enable GitHub pages).
+
+{.alert.alert-info}
+If you only see a "master" branch and if the **gh-pages** branch does not appear here, simply wait a few minutes and refresh your page. When you created the project, Github Actions triggered a job that is in charge of creating the **gh-pages** branch. Maybe the job is not finished yet.
+
+<figure class="figure my-5">
+    <img src="images/github_pages.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The GitHub pages configuration section</figcaption>
+</figure>
+
+Wait a few minutes... Github will deploy a new website with the content of the repository. The address of the website is visible in the "GitHub Pages" section.
+
+<figure class="figure my-5">
+    <img src="images/website_address.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">Your website is ready!</figcaption>
+</figure>
+
+Click on the link. You should be redirected directly to WorkAdventure, on your map!
+
+## Customizing your map
+
+Your map is now up and online, but this is still the demo map from the starter kit. You need to customize it.
+
+### Cloning the map
+
+Start by cloning the map. If you are used to Git and GitHub, simply clone the map to your computer using your preferred tool and [jump to the next chapter](#loading-the-map-in-tiled).
+
+If you are new to Git, cloning the map means downloading the map to your computer. To do this, you will need Git, or a Git compatible tool. Our advice is to use [GitHub Desktop](https://desktop.github.com/). We recommend you take some time mastering the notion of pull / commit / push as this will make uploading your maps really easier.
+
+As an (easier) alternative, you can simply use the "Export" button to download the code of the map in a big Zip file. When you want to upload your work again, you will simply drag'n'drop your files in the GitHub website.
+
+### Loading the map in Tiled
+
+The sample map is in the file `map.json`. You can load this file in [Tiled](https://www.mapeditor.org/).
+
+Now, it's up to you to edit the map and write your own map.
+
+Some resources regarding Tiled:
+
+*   [Tiled documentation](https://doc.mapeditor.org/en/stable/manual/introduction/)
+*   [Tiled video tutorials](https://www.gamefromscratch.com/post/2015/10/14/Tiled-Map-Editor-Tutorial-Series.aspx)
+
+### Testing your map locally
+
+In order to test your map, you need a webserver to host your map. The "map starter kit" comes with a local webserver that you can use to test your map.
+
+In order to start the webserver, you will need [Node.JS](https://nodejs.org/en/). When it is downloaded, open your command line and from the directory of the map, run this command:
+
+    $ npm install
+
+This will install the local webserver.
+
+    $ npm run start
+
+This command will start the webserver and open the welcome page. You should see a page looking like this:
+
+<figure class="figure my-5">
+    <img src="images/start_kit_start_screen.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
+    <figcaption class="figure-caption">The welcome page of the "map start kit"</figcaption>
+</figure>
+
+From here, you simply need to click the "Test this map" button to test your map in WorkAdventure.
+
+{.alert.alert-warning}
+The local web server can only be used to test your map locally. In particular, the link will only work on your computer. You cannot share it with other people.
+
+### Pushing the map
+
+When your changes are ready, you need to "commit" and "push" (i.e. "upload") the changes back to GitHub. Just wait a few minutes, and your map will be propagated automatically to the GitHub pages web-server.
+
+## Testing your map
+
+To test your map, you need to find its URL. There are 2 kinds of URLs in WorkAdventure:
+
+*   Test URLs are in the form `https://play.workadventu.re/_/[instance]/[server]/[path to map]`
+*   Registered URLs are in the form `https://play.workadventu.re/@/[organization]/[world]/[map]`
+
+Assuming your JSON map is hosted at "`https://myuser.github.io/myrepo/map.json`", then you can browse your map at "`https://play.workadventu.re/_/global/myuser.github.io/myrepo/map.json`". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.
+
+This will connect you to a "public" instance. Anyone can come and connect to a public instance. If you want to manage invitations, or to perform some moderation, you will need to create a "private" instance. Private instances are available in "pro" accounts.
+
+<div class="card">
+    <div class="card-body">
+        <h3 id="need-some-help">Need some help?</h3>
+        <p>WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing.</p>
+        <p>If you are facing any troubles, do not hesitate to open an "issue" in the
+            <a href="https://github.com/thecodingmachine/workadventure/issues" target="_blank">GitHub WorkAdventure account</a>.
+        </p>
+    </div>
+</div>

docs/maps/meeting-rooms.md

@@ -0,0 +1,81 @@
+{.section-title.accent.text-primary}
+# Meeting rooms
+
+https://www.youtube.com/watch?v=cN9VMWHN0eo
+
+## Opening a Jitsi meet when walking on the map
+
+On your map, you can define special zones (meeting rooms) that will trigger the opening of a Jitsi meet. When a player will pass over these zones, a Jitsi meet will open (as an iframe on the right side of the screen)
+
+In order to create Jitsi meet zones:
+
+*   You must create a specific layer.
+*   In layer properties, you MUST add a "`jitsiRoom`" property (of type "`string`"). The value of the property is the name of the room in Jitsi. Note: the name of the room will be "slugified" and prepended with the name of the instance of the map (so that different instances of the map have different rooms)
+
+## Triggering of the "Jitsi meet" action
+
+By default, Jitsi meet will open when a user enters the zone defined on the map.
+
+It is however possible to trigger Jitsi only on user action. You can do this with the `jitsiTrigger` property.
+
+If you set `jitsiTrigger: onaction`, when the user walks on the layer, an alert message will be displayed at the bottom of the screen:
+
+<figure class="figure">
+    <img src="images/click_space_jitsi.png" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">Jitsi meet will only open if the user clicks Space</figcaption>
+</figure>
+
+If you set `jitsiTriggerMessage: your message action` you can edit alert message displayed. If is not defined, the default message displayed is 'Press on SPACE to enter in jitsi meet room'.
+
+## Customizing your "Jitsi meet"
+
+Your Jitsi meet experience can be customized using Jitsi specific config options. The `jitsiConfig` and `jitsiInterfaceConfig` properties can be used on the Jitsi layer to change the way Jitsi looks and behaves. Those 2 properties are accepting a JSON string.
+
+For instance, use `jitsiConfig: { "startWithAudioMuted": true }` to automatically mute the microphone when someone enters a room. Or use `jitsiInterfaceConfig: { "DEFAULT_BACKGROUND": "#77ee77" }` to change the background color of Jitsi.
+
+The `jitsiConfig` property will override the Jitsi [config.js](https://github.com/jitsi/jitsi-meet/blob/master/config.js) file
+
+The `jitsiInterfaceConfig` property will override the Jitsi [interface_config.js](https://github.com/jitsi/jitsi-meet/blob/master/interface_config.js) file
+
+<div class="alert alert-warning">If your customizations are not working:
+<ul>
+<li>First, check that the JSON you are entering is valid. Take a look at the console in your browser. If the JSON string is invalid, you should see a warning.</li>
+<li>Then, check that the JSON you are using is matching the version of Jitsi used.</li>
+</ul>
+</div>
+
+## Granting moderator controls in Jitsi
+
+{.alert.alert-info}
+Moderator controls are linked to member tags. You need a pro account to edit member tags.
+
+You can grant moderator rights to some of your members. Jitsi moderators can:
+
+*   Publish a Jitsi meeting on Youtube Live (you will need a Youtube Live account)
+*   Record a meeting to Dropbox (you will need a Dropbox account)
+*   Mute someone
+*   Mute everybody expect one speaker
+*   Kick users out of the meeting
+
+In order to grant moderator rights to a given user, you can add a `jitsiRoomAdminTag` property to your Jitsi layer. For instance, if you write a property:
+
+    jitsiRoomAdminTag: speaker
+
+then, any of your member with the `speaker` tag will be automatically granted moderator rights over this Jitsi instance.
+
+You can read more about [managing member tags in the admin documentation](/admin-guide/manage-members).
+
+## Using another Jitsi server
+
+WorkAdventure usually comes with a default Jitsi meet installation. If you are using the online version at `workadventu.re`, we are handling a Jitsi meet cluster for you. If you are running the self-hosted version of WorkAdventure, the administrator probably set up a Jitsi meet instance too.
+
+You have the possibility, in your map, to override the Jitsi meet instance that will be used by default. This can be useful for regulatory reasons. Maybe your company wants to keep control on the video streams and therefore, wants to self-host a Jitsi instance? Or maybe you want to use a very special configuration or very special version of Jitsi?
+
+Use the `jitsiUrl` property to in the Jitsi layer to specify the Jitsi instance that should be used. Beware, `jitsiUrl` takes in parameter a **domain name**, without the protocol. So you should use:  
+`jitsiUrl: meet.jit.si`  
+and not  
+`jitsiUrl: https://meet.jit.si`
+
+{.alert.alert-info}
+When you use `jitsiUrl`, the targeted Jitsi instance must be public. You cannot use moderation features or the JWT 
+tokens authentication with maps configured using the `jitsiUrl` property.

docs/maps/opening-a-website.md

@@ -0,0 +1,65 @@
+{.section-title.accent.text-primary}
+# Opening a website when walking on the map
+
+https://www.youtube.com/watch?v=Me8cu5lLN3A
+
+## The openWebsite property
+
+On your map, you can define special zones. When a player will pass over these zones, a website will open (as an iframe 
+on the right side of the screen)
+
+In order to create a zone that opens websites:
+
+*   You must create a specific layer.
+*   In layer properties, you MUST add a "`openWebsite`" property (of type "`string`"). The value of the property is the URL of the website to open (the URL must start with "https://")
+*   You may also use "`openWebsiteWidth`" property (of type "`number`" between 0 and 100) to control the width of the iframe.
+
+{.alert.alert-warning}
+A website can explicitly forbid another website from loading it in an iFrame using 
+the [X-Frame-Options HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options).
+
+## Integrating a Youtube video
+
+A common use case is to use `openWebsite` to open a Youtube video.
+
+The global Youtube page cannot be embedded into an iFrame (it has the `X-Frame-Options` HTTP header).
+
+To embed a Youtube video, be sure to **use the "embed" link**. You can get this link be clicking "Share > Embed" in Youtube.
+
+<figure class="figure">
+    <img src="images/youtube.jpg" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">Find the URL of your video in the "embed Video" HTML snippet on Youtube</figcaption>
+</figure>
+
+<figure class="figure">
+    <img src="images/open_website.jpg" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">Put this URL in the "openWebsite" property</figcaption>
+</figure>
+
+### Triggering of the "open website" action
+
+By default, the iFrame will open when a user enters the zone defined on the map.
+
+It is however possible to trigger the iFrame only on user action. You can do this with the `openWebsiteTrigger` property.
+
+If you set `openWebsiteTrigger: onaction`, when the user walks on the layer, an alert message will be displayed at the bottom of the screen:
+
+<figure class="figure">
+    <img src="images/click_space_open_website.jpg" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">The iFrame will only open if the user clicks Space</figcaption>
+</figure>
+
+If you set `openWebsiteTriggerMessage: your message action` you can edit alert message displayed. If is not defined, the default message displayed is 'Press on SPACE to open the web site'.
+
+### Setting the iFrame "allow" attribute
+
+By default, iFrames have limited rights in browsers. For instance, they cannot put their content in fullscreen, they cannot start your webcam, etc...
+
+If you want to grant additional access rights to your iFrame, you should use the `openWebsitePolicy` property. The value of this property will be directly used for the [`allow` atttribute of your iFrame](https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy#the_iframe_allow_attribute).
+
+For instance, if you want an iFrame to be able to go in fullscreen, you will use the property `openWebsitePolicy: fullscreen`
+
+<figure class="figure">
+    <img src="images/open_website_policy.jpg" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">The generated iFrame will have the allow attribute set to: <code>&lt;iframe allow="fullscreen"&gt;</code></figcaption>
+</figure>

docs/maps/special-zones.md

@@ -0,0 +1,27 @@
+{.section-title.accent.text-primary}
+# Other special zones
+
+## Making a "silent" zone
+
+https://www.youtube.com/watch?v=z7XLo06o-ow
+
+On your map, you can define special silent zones where nobody is allowed to talk. In these zones, users will not speak to each others, even if they are next to each others.
+
+In order to create a silent zone:
+
+*   You must create a specific layer.
+*   In layer properties, you MUST add a boolean "`silent`" property. If the silent property is checked, the users are entering the silent zone when they walk on any tile of the layer.
+
+## Playing sounds or background music
+
+Your map can define special zones where a sound or background music will automatically be played.
+
+In order to create a zone that triggers sounds/music:
+
+*   You must create a specific layer.
+*   In layer properties, you MUST add a "`playAudio`" property. The value of the property is a URL to an MP3 file that will be played. The URL can be relative to the URL of the map.
+*   You may use the boolean property "`audioLoop`" to make the sound loop (thanks captain obvious).
+*   If the "`audioVolume`" property is set, the audio player uses either the value of the property or the last volume set by the user - whichever is smaller. This property is a float from 0 to 1.0
+
+{.alert.alert-info}
+"`playAudioLoop`" is deprecated and should not be used anymore.

docs/maps/using-typescript.md

@@ -0,0 +1,183 @@
+{.section-title.accent.text-primary}
+# Using Typescript with the scripting API
+
+{.alert.alert-info}
+The easiest way to get started with writing scripts in Typescript is to use the 
+[Github map starter kit repository](https://github.com/thecodingmachine/workadventure-map-starter-kit). It comes with 
+Typescript enabled. If you are **not** using the "map starter kit", this page explains how to add Typescript to your 
+own scripts.
+
+## The short story
+
+In this page, we will assume you already know Typescript and know how to set it up with Webpack.
+
+To work with the scripting API in Typescript, you will need the typings of the `WA` object. These typings can be downloaded from the `@workadventure/iframe-api-typings` package.
+
+```console
+$ npm install --save-dev @workadventure/iframe-api-typings
+```
+
+Furthermore, you need to make the global `WA` object available. To do this, edit the entry point of your project (usually, it is a file called `index.ts` in the root directory).
+
+Add this line at the top of the file:
+
+**index.ts**
+```typescript
+/// <reference path="../node_modules/@workadventure/iframe-api-typings/iframe_api.d.ts" />
+```
+
+From there, you should be able to use Typescript in your project.
+
+## The long story
+
+Below is a step by step guide explaining how to set up Typescript + Webpack along your WorkAdventure map.
+
+In your map directory, start by adding a `package.json` file. This file will contain dependencies on Webpack, Typescript and the Workadventure typings:
+
+**package.json**
+```json
+{
+  "devDependencies": {
+    "@workadventure/iframe-api-typings": "^1.2.1",
+    "eslint": "^7.24.0",
+    "html-webpack-plugin": "^5.3.1",
+    "ts-loader": "^8.1.0",
+    "ts-node": "^9.1.1",
+    "typescript": "^4.2.4",
+    "webpack": "^5.31.2",
+    "webpack-cli": "^4.6.0",
+    "webpack-dev-server": "^3.11.2",
+    "webpack-merge": "^5.7.3"
+  },
+  "scripts": {
+    "start": "webpack serve --open",
+    "build": "webpack --config webpack.prod.js",
+  }
+}
+```
+
+You can now install the dependencies:
+
+```console
+$ npm install
+```
+
+We now need to add a Webpack configuration file (for development mode). This Webpack file will:
+
+*   Start a local webserver that will be in charge of serving the map
+*   Compile Typescript into Javascript and serve it automatically
+
+**webpack.config.js**
+```js
+const path = require('path');
+const webpack = require('webpack');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+
+module.exports = {
+    mode: 'development',
+    entry: './src/index.ts',
+    devtool: 'inline-source-map',
+    devServer: {
+        // The test webserver serves static files from the root directory.
+        // It comes with CORS enabled (important for WorkAdventure to be able to load the map)
+        static: {
+            directory: ".",
+            serveIndex: true,
+            watch: true,
+        },
+        host: 'localhost',
+        allowedHosts: "all",
+        headers: {
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+            "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization"
+        }
+    },
+    module: {
+        rules: [
+            {
+                test: /\.tsx?$/,
+                use: 'ts-loader',
+                exclude: /node_modules/,
+            },
+        ],
+    },
+    resolve: {
+        extensions: [ '.tsx', '.ts', '.js' ],
+    },
+    output: {
+        filename: 'script.js',
+        path: path.resolve(__dirname, 'dist'),
+        publicPath: '/'
+    }
+};
+```
+
+We need to configure Typescript, using a `tsconfig.json` file.
+
+**tsconfig.json**
+```json
+{
+  "compilerOptions": {
+    "outDir": "./dist/",
+    "sourceMap": true,
+    "moduleResolution": "node",
+    "module": "CommonJS",
+    "target": "ES2015",
+    "declaration": false,
+    "downlevelIteration": true,
+    "jsx": "react",
+    "allowJs": true,
+    "strict": true
+  }
+}
+```
+
+Create your entry point (the Typescript file at the root of your project).
+
+**src/index.ts**
+```typescript
+/// <reference path="../node_modules/@workadventure/iframe-api-typings/iframe_api.d.ts" />
+
+console.log('Hello world!');
+```
+
+The first comment line is important in order to get `WA` typings.
+
+Now, you can start Webpack in dev mode!
+
+```console
+$ npm run start
+```
+
+This will automatically compile Typescript, and serve it (along the map) on your local webserver (so at `http://localhost:8080/script.js`). Please note that the `script.js` file is never written to the disk. So do not worry if you don't see it appearing, you need to "build" it to actually write it to the disk.
+
+Final step, you must reference the script inside your map, by adding a `script` property at the root of your map:
+
+<figure class="figure">
+    <img src="images/script_property.png" class="figure-img img-fluid rounded" alt="" />
+    <figcaption class="figure-caption">The script property</figcaption>
+</figure>
+
+### Building the final script
+
+We now have a correct development setup. But we still need to be able to build the production script from Typescript files. We are not going to use the development server in production. To do this, we will add an additional `webpack.prod.js` file.
+
+**webpack.prod.js**
+```javascript
+const { merge } = require('webpack-merge');
+const common = require('./webpack.config.js');
+
+module.exports = merge(common, {
+  mode: 'production',
+  devtool: 'source-map'
+});
+```
+
+This file will simply switch the Webpack config file in "production" mode. You can simply run:
+
+```console
+$ npm run build
+```
+
+and the `script.js` file will be generated in the `dist/` folder. Beware, you will need to move it at the root of map for it to be read by the map.