# 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
Summary
- map id
- Layers of map
- World X Position
- World Y Position
- Create Shape
- Delete Shape
- Get Shapes
- Get Shape by name
- Assign the map to a world
- Remove this map from the world
- Get attached World
- event list
- Change Tile in map
- Create Dynamic Event
- Get Event
- Remove Event
- Create a temporary and moving hitbox
- Data of map
- Width of the map in pixels
- Height of the map in pixels
- The depth of the map in pixels (this is the height of a tile 😉))
- Get Layer by name
- Get index of tile
- Get origin position of tile
- Get tile by position
- Get tile by index
# 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