# RpgMap

# @MapData decorator

Summary

id
file
name
events
sounds
syncSchema
lowMemory

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

# 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

← RpgSceneMap RpgWorldMaps →