merged develop

docs/maps/api-camera.md

@@ -4,7 +4,7 @@
 ### Listen to camera updates
 
 ```
-WA.camera.onCameraUpdate(callback: WasCameraUpdatedEventCallback): void
+WA.camera.onCameraUpdate(): Subscription
 ```
 
 Listens to updates of the camera viewport. It will trigger for every update of the camera's properties (position or scale for instance). An event will be sent.
@@ -19,5 +19,6 @@ The event has the following attributes :
 
 Example :
 ```javascript
-WA.camera.onCameraUpdate((worldView) => console.log(worldView));
-```
+const subscription = WA.camera.onCameraUpdate().subscribe((worldView) => console.log(worldView));
+//later...
+subscription.unsubscribe();

docs/maps/api-player.md

@@ -107,6 +107,27 @@ WA.onInit().then(() => {
 })
 ```
 
+### Get the position of the player
+```
+WA.player.getPosition(): Promise<Position>
+```
+The player's current position is available using the `WA.player.getPosition()` function.
+
+`Position` has the following attributes :
+* **x (number) :** The coordinate x of the current player's position.
+* **y (number) :** The coordinate y of the current player's position.
+
+
+{.alert.alert-info}
+You need to wait for the end of the initialization before calling `WA.player.getPosition()`
+
+```typescript
+WA.onInit().then(async () => {
+    console.log('Position: ', await WA.player.getPosition());
+})
+```
+
+
 ### Listen to player movement
 ```
 WA.player.onPlayerMove(callback: HasPlayerMovedEventCallback): void;
@@ -151,3 +172,25 @@ Example:
 ```javascript
 WA.player.state.toto //will retrieve the variable
 ```
+
+### Set the outline color of the player
+```
+WA.player.setOutlineColor(red: number, green: number, blue: number): Promise<void>;
+WA.player.removeOutlineColor(): Promise<void>;
+```
+
+You can display a thin line around your player's name (the "outline").
+
+Use `setOutlineColor` to set the outline and `removeOutlineColor` to remove it.
+
+Colors are expressed in RGB. Each parameter is an integer between 0 and 255.
+
+```typescript
+// Let's add a red outline to our player
+WA.player.setOutlineColor(255, 0, 0);
+```
+
+When you set the outline on your player, other players will see the outline too (the outline color is shared across
+browsers automatically).
+
+![](images/outlines.png)

docs/maps/api-room.md

@@ -1,8 +1,11 @@
 {.section-title.accent.text-primary}
+
 # API Room functions Reference
 
 ### Working with group layers
-If you use group layers in your map, to reference a layer in a group you will need to use a `/` to join layer names together.
+
+If you use group layers in your map, to reference a layer in a group you will need to use a `/` to join layer names
+together.
 
 Example :
 <div class="row">
@@ -12,6 +15,7 @@ Example :
 </div>
 
 The name of the layers of this map are :
+
 * `entries/start`
 * `bottom/ground/under`
 * `bottom/build/carpet`
@@ -26,29 +30,32 @@ WA.room.onLeaveLayer(name: string): Subscription
 
 Listens to the position of the current user. The event is triggered when the user enters or leaves a given layer.
 
-*   **name**: the name of the layer who as defined in Tiled.
+* **name**: the name of the layer who as defined in Tiled.
 
 Example:
 
 ```javascript
 WA.room.onEnterLayer('myLayer').subscribe(() => {
-    WA.chat.sendChatMessage("Hello!", 'Mr Robot');
+  WA.chat.sendChatMessage("Hello!", 'Mr Robot');
 });
 
 WA.room.onLeaveLayer('myLayer').subscribe(() => {
-    WA.chat.sendChatMessage("Goodbye!", 'Mr Robot');
+  WA.chat.sendChatMessage("Goodbye!", 'Mr Robot');
 });
 ```
 
 ### Show / Hide a layer
+
 ```
 WA.room.showLayer(layerName : string): void
 WA.room.hideLayer(layerName : string) : void
 ```
-These 2 methods can be used to show and hide a layer.
-if `layerName` is the name of a group layer, show/hide all the layer in that group layer.
+
+These 2 methods can be used to show and hide a layer. if `layerName` is the name of a group layer, show/hide all the
+layer in that group layer.
 
 Example :
+
 ```javascript
 WA.room.showLayer('bottom');
 //...
@@ -61,12 +68,14 @@ WA.room.hideLayer('bottom');
 WA.room.setProperty(layerName : string, propertyName : string, propertyValue : string | number | boolean | undefined) : void;
 ```
 
-Set the value of the `propertyName` property of the layer `layerName` at `propertyValue`. If the property doesn't exist, create the property `propertyName` and set the value of the property at `propertyValue`.
+Set the value of the `propertyName` property of the layer `layerName` at `propertyValue`. If the property doesn't exist,
+create the property `propertyName` and set the value of the property at `propertyValue`.
 
 Note :
 To unset a property from a layer, use `setProperty` with `propertyValue` set to `undefined`.
 
 Example :
+
 ```javascript
 WA.room.setProperty('wikiLayer', 'openWebsite', 'https://www.wikipedia.org/');
 ```
@@ -79,13 +88,12 @@ WA.room.id: string;
 
 The ID of the current room is available from the `WA.room.id` property.
 
-{.alert.alert-info}
-You need to wait for the end of the initialization before accessing `WA.room.id`
+{.alert.alert-info} You need to wait for the end of the initialization before accessing `WA.room.id`
 
 ```typescript
 WA.onInit().then(() => {
-    console.log('Room id: ', WA.room.id);
-    // Will output something like: 'https://play.workadventu.re/@/myorg/myworld/myroom', or 'https://play.workadventu.re/_/global/mymap.org/map.json"
+  console.log('Room id: ', WA.room.id);
+  // Will output something like: 'https://play.workadventu.re/@/myorg/myworld/myroom', or 'https://play.workadventu.re/_/global/mymap.org/map.json"
 })
 ```
 
@@ -97,19 +105,17 @@ WA.room.mapURL: string;
 
 The URL of the map is available from the `WA.room.mapURL` property.
 
-{.alert.alert-info}
-You need to wait for the end of the initialization before accessing `WA.room.mapURL`
+{.alert.alert-info} You need to wait for the end of the initialization before accessing `WA.room.mapURL`
 
 ```typescript
 WA.onInit().then(() => {
-    console.log('Map URL: ', WA.room.mapURL);
-    // Will output something like: 'https://mymap.org/map.json"
+  console.log('Map URL: ', WA.room.mapURL);
+  // Will output something like: 'https://mymap.org/map.json"
 })
 ```
 
-
-
 ### Getting map data
+
 ```
 WA.room.getTiledMap(): Promise<ITiledMap>
 ```
@@ -121,12 +127,16 @@ const map = await WA.room.getTiledMap();
 console.log("Map generated with Tiled version ", map.tiledversion);
 ```
 
-Check the [Tiled documentation to learn more about the format of the JSON map](https://doc.mapeditor.org/en/stable/reference/json-map-format/).
+Check
+the [Tiled documentation to learn more about the format of the JSON map](https://doc.mapeditor.org/en/stable/reference/json-map-format/)
+.
 
 ### Changing tiles
+
 ```
 WA.room.setTiles(tiles: TileDescriptor[]): void
 ```
+
 Replace the tile at the `x` and `y` coordinates in the layer named `layer` by the tile with the id `tile`.
 
 If `tile` is a string, it's not the id of the tile but the value of the property `name`.
@@ -137,43 +147,48 @@ If `tile` is a string, it's not the id of the tile but the value of the property
 </div>
 
 `TileDescriptor` has the following attributes :
+
 * **x (number) :** The coordinate x of the tile that you want to replace.
 * **y (number) :** The coordinate y of the tile that you want to replace.
 * **tile (number | string) :** The id of the tile that will be placed in the map.
 * **layer (string) :** The name of the layer where the tile will be placed.
 
-**Important !** : If you use `tile` as a number, be sure to add the `firstgid` of the tileset of the tile that you want to the id of the tile in Tiled Editor.
+**Important !** : If you use `tile` as a number, be sure to add the `firstgid` of the tileset of the tile that you want
+to the id of the tile in Tiled Editor.
 
 Note: If you want to unset a tile, use `setTiles` with `tile` set to `null`.
 
 Example :
+
 ```javascript
 WA.room.setTiles([
-                {x: 6, y: 4, tile: 'blue', layer: 'setTiles'},
-                {x: 7, y: 4, tile: 109, layer: 'setTiles'},
-                {x: 8, y: 4, tile: 109, layer: 'setTiles'},
-                {x: 9, y: 4, tile: 'blue', layer: 'setTiles'}
-                ]);
+  { x: 6, y: 4, tile: 'blue', layer: 'setTiles' },
+  { x: 7, y: 4, tile: 109, layer: 'setTiles' },
+  { x: 8, y: 4, tile: 109, layer: 'setTiles' },
+  { x: 9, y: 4, tile: 'blue', layer: 'setTiles' }
+]);
 ```
 
 ### Loading a tileset
+
 ```
 WA.room.loadTileset(url: string): Promise<number>
 ```
+
 Load a tileset in JSON format from an url and return the id of the first tile of the loaded tileset.
 
 You can create a tileset file in Tile Editor.
 
 ```javascript
 WA.room.loadTileset("Assets/Tileset.json").then((firstId) => {
-    WA.room.setTiles([{x: 4, y: 4, tile: firstId, layer: 'bottom'}]);
+  WA.room.setTiles([{ x: 4, y: 4, tile: firstId, layer: 'bottom' }]);
 })
 ```
 
-
 ## Embedding websites in a map
 
-You can use the scripting API to embed websites in a map, or to edit websites that are already embedded (using the ["website" objects](website-in-map.md)).
+You can use the scripting API to embed websites in a map, or to edit websites that are already embedded (using
+the ["website" objects](website-in-map.md)).
 
 ### Getting an instance of a website already embedded in the map
 
@@ -181,8 +196,8 @@ You can use the scripting API to embed websites in a map, or to edit websites th
 WA.room.website.get(objectName: string): Promise<EmbeddedWebsite>
 ```
 
-You can get an instance of an embedded website by using the `WA.room.website.get()` method.
-It returns a promise of an `EmbeddedWebsite` instance.
+You can get an instance of an embedded website by using the `WA.room.website.get()` method. It returns a promise of
+an `EmbeddedWebsite` instance.
 
 ```javascript
 // Get an existing website object where 'my_website' is the name of the object (on any layer object of the map)
@@ -191,7 +206,6 @@ website.url = 'https://example.com';
 website.visible = true;
 ```
 
-
 ### Adding a new website in a map
 
 ```
@@ -201,34 +215,38 @@ interface CreateEmbeddedWebsiteEvent {
     name: string;       // A unique name for this iframe
     url: string;        // The URL the iframe points to.
     position: {
-        x: number,      // In pixels, relative to the map coordinates
-        y: number,      // In pixels, relative to the map coordinates
-        width: number,  // In pixels, sensitive to zoom level
-        height: number, // In pixels, sensitive to zoom level
+        x: number,      // In "game" pixels, relative to the map or player coordinates, depending on origin
+        y: number,      // In "game" pixels, relative to the map or player coordinates, depending on origin
+        width: number,  // In "game" pixels
+        height: number, // In "game" pixels
     },
     visible?: boolean,  // Whether to display the iframe or not
     allowApi?: boolean, // Whether the scripting API should be available to the iframe
     allow?: string,     // The list of feature policies allowed
+    origin: "player" | "map" // The origin used to place the x and y coordinates of the iframe's top-left corner, defaults to "map"
+    scale: number, // A ratio used to resize the iframe
 }
 ```
 
-You can create an instance of an embedded website by using the `WA.room.website.create()` method.
-It returns an `EmbeddedWebsite` instance.
+You can create an instance of an embedded website by using the `WA.room.website.create()` method. It returns
+an `EmbeddedWebsite` instance.
 
 ```javascript
 // Create a new website object
 const website = WA.room.website.create({
-    name: "my_website",
-    url: "https://example.com",
-    position: {
-        x: 64,
-        y: 128,
-        width: 320,
-        height: 240,
-    },
-    visible: true,
-    allowApi: true,
-    allow: "fullscreen",
+  name: "my_website",
+  url: "https://example.com",
+  position: {
+    x: 64,
+    y: 128,
+    width: 320,
+    height: 240,
+  },
+  visible: true,
+  allowApi: true,
+  allow: "fullscreen",
+  origin: "map",
+  scale: 1,
 });
 ```
 
@@ -240,30 +258,28 @@ WA.room.website.delete(name: string): Promise<void>
 
 Use `WA.room.website.delete` to completely remove an embedded website from your map.
 
-
 ### The EmbeddedWebsite class
 
 Instances of the `EmbeddedWebsite` class represent the website displayed on the map.
 
 ```typescript
 class EmbeddedWebsite {
-    readonly name: string;
-    url: string;
-    visible: boolean;
-    allow: string;
-    allowApi: boolean;
-    x: number;         // In pixels, relative to the map coordinates
-    y: number;         // In pixels, relative to the map coordinates
-    width: number;     // In pixels, sensitive to zoom level
-    height: number;    // In pixels, sensitive to zoom level
+  readonly name: string;
+  url: string;
+  visible: boolean;
+  allow: string;
+  allowApi: boolean;
+  x: number;         // In "game" pixels, relative to the map or player coordinates, depending on origin
+  y: number;         // In "game" pixels, relative to the map or player coordinates, depending on origin
+  width: number;     // In "game" pixels
+  height: number;    // In "game" pixels
+  origin: "player" | "map";
+  scale: number;
 }
 ```
 
 When you modify a property of an `EmbeddedWebsite` instance, the iframe is automatically modified in the map.
 
-
-{.alert.alert-warning}
-The websites you add/edit/delete via the scripting API are only shown locally. If you want them
-to be displayed for every player, you can use [variables](api-start.md) to share a common state
-between all users.
+{.alert.alert-warning} The websites you add/edit/delete via the scripting API are only shown locally. If you want them
+to be displayed for every player, you can use [variables](api-start.md) to share a common state between all users.
 

docs/maps/camera.md

@@ -29,22 +29,28 @@ It is possible to define special regions on the map that can make the camera zoo
         <img class="document-img" src="images/camera/3_define_new_zone.png" alt="" />
     </div>
 
-4. Edit this new object and click on **Add Property**, like this:
+4. Make sure your object is of type "zone"!
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/4_click_add_property.png" alt="" />
+        <img class="document-img" src="images/camera/4_add_zone_type.png" alt="" />
     </div>
 
-5. Add a **bool** property of name *focusable*:
+5. Edit this new object and click on **Add Property**, like this:
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/5_add_focusable_prop.png" alt="" />
+        <img class="document-img" src="images/camera/5_click_add_property.png" alt="" />
     </div>
 
-6. Make sure it's checked! :)
+6. Add a **bool** property of name *focusable*:
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/6_make_sure_checked.png" alt="" />
+        <img class="document-img" src="images/camera/6_add_focusable_prop.png" alt="" />
+    </div>
+
+7. Make sure it's checked! :)
+
+    <div class="px-5 card rounded d-inline-block">
+        <img class="document-img" src="images/camera/7_make_sure_checked.png" alt="" />
     </div>
 
 All should be set up now and your new **Focusable Zone** should be working fine!
@@ -56,19 +62,19 @@ If you want, you can add an additional property to control how much should the c
 1. Like before, click on **Add Property**
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/4_click_add_property.png" alt="" />
+        <img class="document-img" src="images/camera/5_click_add_property.png" alt="" />
     </div>
 
 2. Add a **float** property of name *zoom_margin*:
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/7_add_zoom_margin.png" alt="" />
+        <img class="document-img" src="images/camera/8_add_zoom_margin.png" alt="" />
     </div>
 
 2. Define how much (in percentage value) should the zoom be decreased:
 
     <div class="px-5 card rounded d-inline-block">
-        <img class="document-img" src="images/camera/8_optional_zoom_margin_defined.png" alt="" />
+        <img class="document-img" src="images/camera/9_optional_zoom_margin_defined.png" alt="" />
     </div>
 
     For example, if you define your zone as a 300x200 rectangle, setting this property to 0.5 *(50%)* means the camera will try to fit within the viewport the entire zone + margin of 50% of its dimensions, so 450x300.

docs/maps/scripting.md

@@ -60,7 +60,7 @@ WA.chat.sendChatMessage('Hello world', 'Mr Robot');
 
 The `WA` objects contains a number of useful methods enabling you to interact with the WorkAdventure game. For instance, `WA.chat.sendChatMessage` opens the chat and adds a message in it.
 
-In your browser console, when you open the map, the chat message should be displayed right away.
+The message should be displayed in the chat history as soon as you enter the room.
 
 ## Adding a script in an iFrame
 

docs/maps/wa-maps.md

@@ -98,13 +98,14 @@ The exception is the "collides" property that can only be set on tiles, but not
 By setting properties on the map itself, you can help visitors know more about the creators of the map.
 
 The following *map* properties are supported:
-* `mapName` (string)
-* `mapDescription` (string)
-* `mapCopyright` (string)
+* `mapName` (string): The name of your map
+* `mapLink` (string): A link to your map, for example a repository
+* `mapDescription` (string): A short description of your map
+* `mapCopyright` (string): Copyright notice
 
-And *each tileset* can also have a property called `tilesetCopyright` (string). 
+Each *tileset* can also have a property called `tilesetCopyright` (string). 
+If you are using audio files in your map, you can declare a layer property `audioCopyright` (string).
 
 Resulting in a "credit" page in the menu looking like this:
 
 ![](images/mapProperties.png){.document-img}
-