# 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

     onEnter() {
         this.count++
     }

     onLeave() {
         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 (opens new window) 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 the player enters the map
    onEnter(player: RpgPlayer) {}
    
    // When the player leaves the map
    onLeave(player: RpgPlayer) {}
}

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

# 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


# 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


# 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