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 :

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.

The `zone` property, applied on a layer

• 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:

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 :

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 :

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 :

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 :

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.

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 :

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 metadata

WA.room.saveMetadata(key : string, data : any): void
WA.room.loadMetadata(key : string) : any

These 2 methods can be used to save and load data 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 :

WA.room.saveMetadata('config', {
    'bottomExitUrl': '/@/org/world/castle',
    'topExitUrl': '/@/org/world/tower',
    'enableBirdSound': true
});
//...
let config = WA.room.loadMetadata('config');

{.alert.alert-danger} Important: metadata can only be saved/loaded if an administration server is attached to WorkAdventure. The WA.room.saveMetadata and WA.room.loadMetadata functions will therefore be available on the hosted version of WorkAdventure, but will not be available in the self-hosted version (unless you decide to code an administration server stub to provide storage for those data)