workadventure/docs/maps/api-room.md

{.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.

Example :
<div class="row">
    <div class="col">
        <img src="https://workadventu.re/img/docs/groupLayer.png" class="figure-img img-fluid rounded" alt="" />
    </div>
</div>

The name of the layers of this map are :
* `entries/start`
* `bottom/ground/under`
* `bottom/build/carpet`
* `wall`

### Detecting when the user enters/leaves a zone

```
WA.room.onEnterZone(name: string, callback: () => void): void
WA.room.onLeaveZone(name: string, callback: () => void): void
```

Listens to the position of the current user. The event is triggered when the user enters or leaves a given zone. The name of the zone is stored in the map, on a dedicated layer with the `zone` property.

<div>
    <figure class="figure">
        <img src="https://workadventu.re/img/docs/trigger_event.png" class="figure-img img-fluid rounded" alt="" />
        <figcaption class="figure-caption">The `zone` property, applied on a layer</figcaption>
    </figure>
</div>

*   **name**: the name of the zone, as defined in the `zone` property.
*   **callback**: the function that will be called when a user enters or leaves the zone.

Example:

```javascript
WA.room.onEnterZone('myZone', () => {
    WA.chat.sendChatMessage("Hello!", 'Mr Robot');
})

WA.room.onLeaveZone('myZone', () => {
    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.

Example :
```javascript
WA.room.showLayer('bottom');
//...
WA.room.hideLayer('bottom');
```

### Set/Create properties in a layer

```
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`.

Example :
```javascript
WA.room.setProperty('wikiLayer', 'openWebsite', 'https://www.wikipedia.org/');
```

### Getting information on the current room
```
WA.room.getCurrentRoom(): Promise<Room>
```
Return a promise that resolves to a `Room` object with the following attributes :
* **id (string) :** ID of the current room
* **map (ITiledMap) :** contains the JSON map file with the properties that were set by the script if `setProperty` was called.
* **mapUrl (string) :** Url of the JSON map file
* **startLayer (string | null) :** Name of the layer where the current user started, only if different from `start` layer

Example :
```javascript
WA.room.getCurrentRoom((room) => {
    if (room.id === '42') {
        console.log(room.map);
        window.open(room.mapUrl, '_blank');
    }
})
```

### Getting information on the current user
```
WA.player.getCurrentUser(): Promise<User>
```
Return a promise that resolves to a `User` object with the following attributes :
* **id (string) :** ID of the current user
* **nickName (string) :** name displayed above the current user
* **tags (string[]) :** list of all the tags of the current user

Example :
```javascript
WA.room.getCurrentUser().then((user) => {
    if (user.nickName === 'ABC') {
        console.log(user.tags);
    }
})
```

### 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`.
<div class="row">
    <div class="col">
        <img src="https://workadventu.re/img/docs/nameIndexProperty.png" class="figure-img img-fluid rounded" alt="" />
    </div>
</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.


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'}
                ]);
```

### Saving / loading state

```
WA.room.saveVariable(key : string, data : unknown): void
WA.room.loadVariable(key : string) : unknown
WA.room.onVariableChange(key : string).subscribe((data: unknown) => {}) : Subscription
```

These 3 methods can be used to save, load and track changes in variables related to the current room.

`data` can be any value that is serializable in JSON.

Please refrain from storing large amounts of data in a room. Those functions are typically useful for saving or restoring
configuration / metadatas.

Example :
```javascript
WA.room.saveVariable('config', {
    'bottomExitUrl': '/@/org/world/castle',
    'topExitUrl': '/@/org/world/tower',
    'enableBirdSound': true
});
//...
let config = WA.room.loadVariable('config');
```

If you are using Typescript, please note that the return type of `loadVariable` is `unknown`. This is
for security purpose, as we don't know the type of the variable. In order to use the returned value,
you will need to cast it to the correct type (or better, use a [Type guard](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) to actually check at runtime
that you get the expected type).

{.alert.alert-warning}
For security reasons, you cannot load or save **any** variable (otherwise, anyone on your map could set any data).
Variables storage is subject to an authorization process. Read below to learn more.

#### Declaring allowed keys

In order to declare allowed keys related to a room, you need to add a **objects** in an "object layer" of the map.

Each object will represent a variable.

<div class="row">
    <div class="col">
        <img src="https://workadventu.re/img/docs/object_variable.png" class="figure-img img-fluid rounded" alt="" />
    </div>
</div>

TODO: move the image in https://workadventu.re/img/docs


The name of the variable is the name of the object.
The object **type** MUST be **variable**.

You can set a default value for the object in the `default` property.

Use the `persist` property to save the state of the variable in database. If `persist` is false, the variable will stay
in the memory of the WorkAdventure servers but will be wiped out of the memory as soon as the room is empty (or if the
server restarts).

{.alert.alert-info}
Do not use `persist` for highly dynamic values that have a short life spawn.

With `readableBy` and `writableBy`, you control who can read of write in this variable. The property accepts a string
representing a "tag". Anyone having this "tag" can read/write in the variable.

{.alert.alert-warning}
`readableBy` and `writableBy` are specific to the public version of WorkAdventure because the notion of tags
is not available unless you have an "admin" server (that is not part of the self-hosted version of WorkAdventure).

Finally, the `jsonSchema` property can contain [a complete JSON schema](https://json-schema.org/) to validate the content of the variable.
Trying to set a variable to a value that is not compatible with the schema will fail.




TODO: document tracking, unsubscriber, etc...