RpgMap ​

@MapData decorator ​

id ​

• Property: id
• Type: string
• Optional: true
• Usage:

Map identifier. Allows to go to the map (for example with player.changeMap())

file ​

• Property: file
• Type: string
• Optional: false
• Usage:

the path to the .tmx file (Tiled Map Editor)

Remember to use require() function

import { MapData, RpgMap } from '@rpgjs/server'

@MapData({
     id: 'town',
     file: require('./tmx/town.tmx')
})
class TownMap extends RpgMap { }

name ​

• Property: name
• Type: string
• Optional: true
• Usage:

The name of the map.

events ​

• Property: events
• Type: Class of RpgEvent[] | { event: Class RpgEvent, x: number, y: number }
• Optional: true
• Usage:

Map events. This is an array containing RpgEvent classes. You can also give an object that will indicate the positions of the event on the map.

import { MapData, RpgMap, EventData, RpgEvent } from '@rpgjs/server'

@EventData({
     name: 'Ev-1'
})
class NpcEvent extends RpgEvent { }

@MapData({
     id: 'medieval',
     file: require('./tmx/town.tmx'),
     events: [NpcEvent]
})
class TownMap extends RpgMap {}

If the positions are not defined, the event will be placed on a Tiled Map Editor shape (/guide/create-event.html#position-the-event-on-the-map). Otherwise, it will be placed at {x:0, y:0 }

You can give positions:

events: [{ event: NpcEvent, x: 10, y: 30 }]

sounds ​

• Property: sounds
• Type: Array
• Optional: true
• Usage:

The sounds that will be played when the map is open. Sounds must be defined on the client side. Then, put the name of the sound identifier

So, it is possible to play several sounds (in loop or not) on the card. You can put a background music (BGM) and a background noise (BGS) for example

sounds: ['my-bgm', 'my-bgs']

And client side:

import { Sound } from '@rpgjs/client'

@Sound({
     sounds: {
         'my-bgm': require('./assets/bgm.ogg'),
         'my-bgs': require('./assets/bgs.ogg')
     },
     loop: true
})
export class Sounds {}

See [https://docs.rpgjs.dev/classes/sound.html#properties](RpgSound Decorator)

syncSchema ​

• Property: syncSchema
• Type: object
• Optional: true
• Usage:

Specify which properties will be synchronized with the client. On the client side, you can retrieve the values synchronized with the valueChanges property on the scene

You must create the schema:

import { MapData, RpgMap } from '@rpgjs/server'

@MapData({
     id: 'medieval',
     file: require('./tmx/town.tmx'),
     syncSchema: {
         count: Number
     }
})
export class TownMap extends RpgMap {
     count: number = 0

     onLoad() {}

     onJoin() {
         this.count++
     }

     onLeave(player) {
         super.onLeave(player)
         this.count--
     }
}

If you want to change the scheme of players and events, consider overwriting the existing scheme

import { MapData, RpgMap, RpgPlayer } from '@rpgjs/server'


declare module '@rpgjs/server' {
export interface RpgPlayer {
    customProp: string
}
}

@MapData({
    id: 'medieval',
    file: require('./tmx/town.tmx'),
    syncSchema: {
        users: [
            {
                customProp: String,
                ...RpgPlayer.schemas
            }
        ]
    }
})
export class TownMap extends RpgMap {}

The properties are called users and events. Their scheme is identical and defined in RpgPlayer.schemas. To write schematics, refer to the documentation of the simple-room module

lowMemory ​

• Since: 3.1.0
• Property: lowMemory
• Type: boolean
• Optional: true
• Usage:

Decreases the RAM of the map. In this case, some instructions will be different.

map.getTileByIndex() will not return all tiles of an index but only the tile of the highest layer

You can also use the low-memory property in Tiled maps

RpgMap Hooks ​

Full Example:

import { MapData, RpgMap, RpgPlayer } from '@rpgjs/server'

@MapData({
     id: 'medieval',
     file: require('./tmx/town.tmx')
})
class TownMap extends RpgMap {
    // When map is loaded
    onLoad() {}

    // When the player enters the map
    onJoin(player: RpgPlayer) {}
    
    // When the player leaves the map
    onLeave(player: RpgPlayer) {
        super.onLeave(player)
    }
}

RpgMap methods ​

map id ​

• Property: id
• Type: string
• Optional: true
• Read Only
• Usage:

Layers of map ​

• Property: layers
• Type: object[]
• Optional: true
• Read Only
• Usage:

World X Position ​

• Since: 3.0.0-beta.8
• Property: worldX
• Type: number
• Optional: true
• Read Only
• Usage:

Retrieves the X position of the map in the world (0 if no world assigned)

World Y Position ​

• Since: 3.0.0-beta.8
• Property: worldY
• Type: number
• Optional: true
• Read Only
• Usage:

Retrieves the Y position of the map in the world (0 if no world assigned)

Create Shape ​

• Since: 3.0.0-beta.3
• Method: map.createShape(obj)
• Arguments:
  • {object} obj. (Optional: false)
• Return: RpgShape
• Usage:

Create a shape dynamically on the map

Object:

• (number) x: Position X
• (number) y: Position Y
• (number) width: Width
• (number) height: Height
• (object) properties (optionnal):
  • (number) z: Position Z
  • (hexadecimal) color: Color (shared with client)
  • (boolean) collision
  • You can your own properties

Delete Shape ​

• Method: map.removeShape(name)
• Arguments:
  • {string} name. Name of shape (Optional: false)
• Return: void
• Usage:

Delete a shape

Get Shapes ​

• Method: map.getShapes()
• Return: RpgShape[]
• Usage:

Return all shapes on the map

Get Shape by name ​

• Method: map.getShape(name)
• Arguments:
  • {string} name. Name of shape (Optional: false)
• Return: RpgShape[] | undefined
• Usage:

Returns a shape by its name. Returns undefined is nothing is found

Assign the map to a world ​

• Since: 3.0.0-beta.8
• Method: map.setInWorldMaps(name)
• Arguments:
  • { RpgWorldMaps} worldMap. world maps (Optional: false)
• Usage:

Assign the map to a world

Remove this map from the world ​

• Since: 3.0.0-beta.8
• Method: map.removeFromWorldMaps()
• Return: boolean | undefined
• Usage:

Remove this map from the world

Get attached World ​

• Since: 3.0.0-beta.8
• Method: map.getInWorldMaps()
• Usage:

Recover the world attached to this map (undefined if no world attached)

event list ​

• Property: events
• Type: { [eventId: string]: RpgEvent }
• Optional: true
• Usage:

Get Event ​

• Since: 3.0.0-beta.7
• Method: map.getEvent(eventId)
• Arguments:
  • {string} eventId. Event Id (Optional: false)
• Return: RpgEvent | undefined
• Usage:

Get Event in current map

Remove Event ​

• Since: 3.0.0-beta.4
• Method: map.removeEvent(eventId)
• Arguments:
  • {string} eventId. Event Name (Optional: false)
• Return: boolean
• Usage:

Removes an event from the map. Returns false if the event is not found

Deletion of an event forced to be performed at the end of several aynschronous notions

Players list ​

• Property: players
• Type: { [playerId: string]: RpgPlayer }
• Optional: true
• Read Only
• Usage:

Number of players ​

• Property: nbPlayers
• Type: number
• Optional: true
• Read Only
• Usage:

Update map ​

• Since: 4.0.0
• Method: map.update(data)
• Arguments:
  • {object | string} data. (Optional: false)
• Return: Promise
• Usage:

Update the map with new data. Data can be a string (TMX content) or an object (parsed TMX content) New Map data will be sent to all players on the map

Update tileset ​

• Since: 4.0.0
• Method: map.updateTileset(data)
• Arguments:
  • {TiledTileset | string} data. (Optional: false)
• Return:
• Usage:

Update tileset with new data. Data can be a string (TSX content) or an object (TiledTileset) Cache will be removed for this tileset New tileset data will be sent to all players on the map Warning: tileset is not updated for all maps, only for the current map

Remove map ​

• Since: 4.0.0
• Method: map.remove()
• Throws:

there are still players on the map ​

• Return: void
• Usage:

Remove the map from the server. If there are still players on the map, an error will be thrown Not delete the map file, only in memory

Change Tile in map ​

• Since: 3.0.0-beta.4
• Method: map.setTile(x,y,layer,tileInfo)
• Arguments:
  • {number} x. Position X (Optional: false)
  • {number} y. Position Y (Optional: false)
  • {string | ((layer: any) => boolean)} layer. Name of the layer where you want to put a tile. OYou can also put a function that will act as a filter. The first parameter is the layer and you return a boolean to indicate if you modify the tile of this layer or not (Optional: false)
  • {object} tileInfo. Object with the following properties:
• {number} gid: The tile number in tileset (from 1)
• {object} properties Property of the tile. You own object. To set a collision, set the collision:true property (Optional: false)
• Return: void
• Example:

map.setTile(15, 18, 'mylayer', { gid: 2 })

• Usage:

Edit a tile on the map. All players on the map will see the modified tile

Create Dynamic Event ​

• Since: 3.0.0-beta.4
• Method: map.createDynamicEvent(eventObj|eventObj[])
• Arguments:
  • { { x: number, y: number, z?: number, event: eventClass } } eventsList. (Optional: false)
• Return: { [eventId: string]: RpgEvent }
• Usage:

Dynamically create an event in Shared mode

@EventData({
 name: 'EV-1'
})
class MyEvent extends RpgEvent {
 onAction() {
     console.log('ok')
 }
} 

map.createDynamicEvent({
     x: 100,
     y: 100,
     event: MyEvent
})

You can also put an array of objects to create several events at once

Create a temporary and moving hitbox ​

• Since: 3.2.0
• Method: map.createMovingHitbox(hitboxes,options)
• Arguments:
  • {Array<{ width: number, height: number, x: number, y: number }>} hitboxes. Create several hitboxes that will give an effect of movement (Optional: false)
  • {object} options. (Optional: true)
  • {speed} options.speed. speed of movement (in frames) (Optional: true)
• Return: Observable find the methods of position and movement of an event
• Example:

// Two hitboxes that will be done very quickly
map.createMovingHitbox(
  [ 
     { x: 0, y: 0, width: 100, height: 100 },
     { x: 20, y: 0, width: 100, height: 100 } 
  ]
).subscribe({
     next(hitbox) {
         console.log(hitbox.otherPlayersCollision)
     },
     complete() {
         console.log('finish')
     }
})

• Usage:

Allows to create a temporary hitbox on the map that can have a movement For example, you can use it to explode a bomb and find all the affected players, or during a sword strike, you can create a moving hitbox and find the affected players again

Data of map ​

• Property: data
• Type: object
• Optional: true
• Read Only
• Usage:

Width of the map in pixels ​

• Property: widthPx
• Type: number
• Optional: true
• Read Only
• Usage:

Height of the map in pixels ​

• Property: heightPx
• Type: number
• Optional: true
• Read Only
• Usage:

The depth of the map in pixels (this is the height of a tile 😉) ​

• Property: map.zTileHeight
• Type: number
• Optional: false
• Read Only
• Usage:

Get Layer by name ​

• Method: map.getLayerByName(name)
• Arguments:
  • {string} name. layer name (Optional: false)
• Return: LayerInfo | undefined
• Example:

const tiles = map.getLayerByName(0, 0)

• Usage:

Find a layer by name. Returns undefined is the layer is not found

Get index of tile ​

• Method: map.getTileIndex(x,y)
• Arguments:
  • {number} x. Position X (Optional: false)
  • {number} x. Position Y (Optional: false)
• Return: number
• Usage:

Get the tile index on the tileset

Get origin position of tile ​

• Method: map.getTileOriginPosition(x,y)
• Arguments:
  • {number} x. Position X (Optional: false)
  • {number} x. Position Y (Optional: false)
• Return: {x: number, y: number }
• Example:

// If the size of a tile is 32x32px
const position = map.getTileOriginPosition(35, 12)
console.log(position) // { x: 32, y: 0 }

• Usage:

Find the point of origin (top left) of a tile. Of course, its position depends on the size of the tile

Get tile by position ​

• Method: map.getTileByPosition(x,y)
• Arguments:
  • {number} x. Position X (Optional: false)
  • {number} x. Position Y (Optional: false)
• Return: TileInfo
• Example:

const tiles = map.getTileByPosition(0, 0)

• Usage:

Recover tiles according to a position

Get tile by index ​

• Method: map.getTileByIndex(tileIndex)
• Arguments:
  • {number} tileIndex. tile index (Optional: false)
• Return: TileInfo
• Example:

const index = map.getTileIndex(0, 0)
const tiles = map.getTileByIndex(index)

• Usage:

Retrieves tiles according to its index