Skip to main content

​
Common Commands

Core server-side player commands defined on the main Player class.

​
Members

​
applyDefaultParameters

Apply the built-in default parameter curves to this player. Use this when you want RPGJS to provide the initial parameter setup instead of restoring values from your own database or a saved snapshot. This method only defines the parameter curves and related defaults. It does not restore custom persisted data for you.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

player.applyDefaultParameters()

​
attachShape

Attach a zone shape to this player using the physic zone system This method creates a zone attached to the player’s entity in the physics engine. The zone can be circular or cone-shaped and will detect other entities (players/events) entering or exiting the zone.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

attachShape(idOrOptions: string | AttachShapeOptions, options?: AttachShapeOptions): RpgShape | undefined

​
Parameters

  • idOrOptions: string | AttachShapeOptions
  • options?: AttachShapeOptions

​
Examples

// Create a circular detection zone
player.attachShape("vision", {
  radius: 150,
  angle: 360,
});

// Create a cone-shaped vision zone
player.attachShape("vision", {
  radius: 200,
  angle: 120,
  direction: Direction.Right,
  limitedByWalls: true,
});

// Create a zone with width/height (radius calculated automatically)
player.attachShape({
  width: 100,
  height: 100,
  positioning: "center",
});

​
cameraFollow

Make the camera follow another player or event This method sends an instruction to the client to fix the viewport on another sprite. The camera will follow the specified player or event, with optional smooth animation.

​
Design

The camera follow instruction is sent only to this player’s client connection. This allows each player to have their own camera target, useful for cutscenes, following NPCs, or focusing on specific events.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

cameraFollow(otherPlayer: RpgPlayer | RpgEvent, options?: {
      smoothMove?: boolean | { time?: number; ease?: string };
    }): void

​
Parameters

  • otherPlayer: RpgPlayer | RpgEvent
  • options?: { smoothMove?: boolean | { time?: number; ease?: string }; }

​
Examples

// Follow another player with default smooth animation
player.cameraFollow(otherPlayer, { smoothMove: true });

// Follow an event with custom smooth animation
player.cameraFollow(npcEvent, {
  smoothMove: {
    time: 1000,
    ease: "easeInOutQuad"
  }
});

// Follow without animation (instant)
player.cameraFollow(targetPlayer, { smoothMove: false });

​
changeMap

Change the map for this player
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

changeMap(mapId: string, positions?: { x: number; y: number; z?: number } | string): Promise<any | null | boolean>

​
Parameters

  • mapId: string
  • positions?: { x: number; y: number; z?: number } | string

​
Returns

A promise that resolves when the map change is complete

​
Examples

// Change player to map "town" at position {x: 10, y: 20}
await player.changeMap("town", {x: 10, y: 20});

// Change player to map "dungeon" at a named position
await player.changeMap("dungeon", "entrance");

​
emit

Send a custom event to the current player’s client. Use this to push arbitrary websocket payloads to one client only. On the client side, receive the event by injecting WebSocketToken and subscribing with socket.on(...).
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

player.emit(type, value)

​
Parameters

  • type: string
  • value?: any

​
Examples

player.emit("inventory:updated", {
  slots: player.items().length,
});

import { inject } from "@rpgjs/client";
import { WebSocketToken, type AbstractWebsocket } from "@rpgjs/client";

const socket = inject<AbstractWebsocket>(WebSocketToken);

socket.on("inventory:updated", (payload) => {
  console.log(payload.slots);
});

​
flash

Trigger a flash animation on this player This method sends a flash animation event to the client, creating a visual feedback effect on the player’s sprite. The flash can be configured with various options including type (alpha, tint, or both), duration, cycles, and color.

​
Design

The flash is sent as a broadcast event to all clients viewing this player. This is useful for visual feedback when the player takes damage, receives a buff, or when an important event occurs.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

flash(options?: {
    type?: 'alpha' | 'tint' | 'both';
    duration?: number;
    cycles?: number;
    alpha?: number;
    tint?: number | string;
  }): void

​
Parameters

  • options?: { type?: 'alpha' | 'tint' | 'both'; duration?: number; cycles?: number; alpha?: number; tint?: number | string; }

​
Examples

// Simple flash with default settings (alpha flash)
player.flash();

// Flash with red tint when taking damage
player.flash({ type: 'tint', tint: 0xff0000 });

// Flash with both alpha and tint for dramatic effect
player.flash({ 
  type: 'both', 
  alpha: 0.5, 
  tint: 0xff0000,
  duration: 200,
  cycles: 2
});

// Quick damage flash
player.flash({ 
  type: 'tint', 
  tint: 'red', 
  duration: 150,
  cycles: 1
});

​
getInShapes

Get all shapes where this player is currently located Returns all shapes (from any player/event) where this player is currently inside. This is updated automatically when the player enters or exits shapes.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

getInShapes(): RpgShape[]

​
Returns

Array of RpgShape instances where this player is located

​
Examples

// Another player has a detection zone
otherPlayer.attachShape("detection", { radius: 200 });

// Check if this player is in any shape
const inShapes = player.getInShapes();
if (inShapes.length > 0) {
  console.log("Player is being detected!");
}

​
getShapes

Get all shapes attached to this player Returns all shapes that were created using attachShape() on this player.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

getShapes(): RpgShape[]

​
Returns

Array of RpgShape instances attached to this player

​
Examples

player.attachShape("vision", { radius: 150 });
player.attachShape("detection", { radius: 100 });

const shapes = player.getShapes();
console.log(shapes.length); // 2

​
initializeDefaultStats

Initialize the built-in default player stats. This applies the default parameter curves and then restores HP/SP to their current maximum values so the client receives coherent bars on first load. Call this manually in onConnected() or onStart() when your game relies on the built-in defaults. Do not call it after loading a snapshot or hydrating player data from your own database unless you explicitly want to overwrite those values.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

player.initializeDefaultStats()

​
lastProcessedInputTs

Last processed client input timestamp for reconciliation
  • Source: packages/server/src/Player/Player.ts
  • Kind: property
  • Defined in: RpgPlayer

​
Signature

lastProcessedInputTs: number

​
Listen one-time to data from the client

Listen one time to custom data sent by the current player’s client. After the first matching event is received, the listener is removed automatically.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer
  • Since: 3.0.0-beta.5

​
Signature

player.once(key, cb)

​
Parameters

  • key: string
  • cb: (data: any) => void | Promise<void>

​
Examples

player.once("tutorial:ready", (payload) => {
  console.log("Ready once:", payload.step);
});

​
Listen to data from the client

Listen to custom data sent by the current player’s client. This listens to websocket actions emitted from the client with socket.emit(key, data). It is intended for custom client events that are not already handled by built-in server actions such as move, action, or GUI interactions.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer
  • Since: 3.0.0-beta.5

​
Signature

player.on(key, cb)

​
Parameters

  • key: string
  • cb: (data: any) => void | Promise<void>

​
Examples

player.on("chat:message", ({ text }) => {
  console.log("Client says:", text);
});

import { inject } from "@rpgjs/client";
import { WebSocketToken, type AbstractWebsocket } from "@rpgjs/client";

const socket = inject<AbstractWebsocket>(WebSocketToken);
socket.emit("chat:message", { text: "Hello server" });

​
playSound

Play a sound on the client side for this player only This method emits an event to play a sound only for this specific player. The sound must be defined on the client side (in the client module configuration).

​
Design

The sound is sent only to this player’s client connection, making it ideal for personal feedback sounds like UI interactions, notifications, or personal achievements. For map-wide sounds that all players should hear, use map.playSound() instead.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

playSound(soundId: string, options?: { volume?: number; loop?: boolean }): void

​
Parameters

  • soundId: string
  • options?: { volume?: number; loop?: boolean }

​
Examples

// Play a sound for this player only (default behavior)
player.playSound("item-pickup");

// Play a sound with volume and loop
player.playSound("background-music", {
  volume: 0.5,
  loop: true
});

// Play a notification sound at low volume
player.playSound("notification", { volume: 0.3 });

​
Remove listeners of the client event

Remove all listeners for a custom client event on this player.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer
  • Since: 3.0.0-beta.5

​
Signature

player.off(key)

​
Parameters

  • key: string

​
Examples

player.off("chat:message");

​
Run Sync Changes

Run the change detection cycle. Normally, as soon as a hook is called in a class, the cycle is started. But you can start it manually The method calls the onChanges method on events and synchronizes all map data with the client.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Member of: Player
  • Defined in: RpgPlayer

​
Signature

player.syncChanges()

​
setAnimation

  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

setAnimation(animationName: string, nbTimes?: number)

​
Parameters

  • animationName: string
  • nbTimes?: number

​
setGraphicAnimation

Set the current animation of the player’s sprite This method changes the animation state of the player’s current sprite. It’s used to trigger character animations like attack, skill, or custom movements. When nbTimes is set to a finite number, the animation will play that many times before returning to the previous animation state. If animationFixed is true, this method will not change the animation.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

setGraphicAnimation(animationName: string, nbTimes: number): void

​
Parameters

  • animationName: string
  • nbTimes: number

​
setGraphicAnimation

Set the current animation of the player’s sprite with a temporary graphic change This method changes the animation state of the player’s current sprite and temporarily changes the player’s graphic (sprite sheet) during the animation. The graphic is automatically reset when the animation finishes. When nbTimes is set to a finite number, the animation will play that many times before returning to the previous animation state and graphic. If animationFixed is true, this method will not change the animation.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

setGraphicAnimation(animationName: string, graphic: string | string[], nbTimes: number): void

​
Parameters

  • animationName: string
  • graphic: string | string[]
  • nbTimes: number

​
setHitbox

Set the hitbox of the player for collision detection This method defines the hitbox used for collision detection in the physics engine. The hitbox can be smaller or larger than the visual representation of the player, allowing for precise collision detection.

​
Design

The hitbox is used by the physics engine to detect collisions with other entities, static obstacles, and shapes. Changing the hitbox will immediately update the collision detection without affecting the visual appearance of the player.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

setHitbox(width: number, height: number): void

​
Parameters

  • width: number
  • height: number

​
Examples

// Set a 20x20 hitbox for precise collision detection
player.setHitbox(20, 20);

// Set a larger hitbox for easier collision detection
player.setHitbox(40, 40);

​
setSync

Set the sync schema for the map
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

setSync(schema: any)

​
Parameters

  • schema: any

​
showAnimation

  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

showAnimation(graphic: string, animationName: string, replaceGraphic?: boolean)

​
Parameters

  • graphic: string
  • animationName: string
  • replaceGraphic?: boolean

​
showComponentAnimation

Show a temporary component animation on this player This method broadcasts a component animation to all clients, allowing temporary visual effects like hit indicators, spell effects, or status animations to be displayed on the player.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

showComponentAnimation(id: string, params?: any)

​
Parameters

  • id: string
  • params?: any

​
Examples

// Show a hit animation with damage text
player.showComponentAnimation("hit", {
  text: "150",
  color: "red"
});

// Show a heal animation
player.showComponentAnimation("heal", {
  amount: 50
});

​
stopAllSounds

Stop all currently playing sounds for this player This method stops all sounds that are currently playing for the player. Useful when changing maps to prevent sound overlap.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

stopAllSounds(): void

​
Examples

// Stop all sounds before changing map
player.stopAllSounds();
await player.changeMap("new-map");

​
stopSound

Stop a sound that is currently playing for this player This method stops a sound that was previously started with playSound(). The sound must be defined on the client side.
  • Source: packages/server/src/Player/Player.ts
  • Kind: method
  • Defined in: RpgPlayer

​
Signature

stopSound(soundId: string): void

​
Parameters

  • soundId: string

​
Examples

// Start a looping background music
player.playSound("background-music", { loop: true });

// Later, stop it
player.stopSound("background-music");

​
worldPositionX

Computed signal for world X position Calculates the absolute world X position from the map’s world position plus the player’s local X position. Returns 0 if no map is assigned.
  • Source: packages/server/src/Player/Player.ts
  • Kind: getter
  • Defined in: RpgPlayer

​
Signature

worldPositionX

​
Examples

const worldX = player.worldX();
console.log(`Player is at world X: ${worldX}`);

​
worldPositionY

Computed signal for world Y position Calculates the absolute world Y position from the map’s world position plus the player’s local Y position. Returns 0 if no map is assigned.
  • Source: packages/server/src/Player/Player.ts
  • Kind: getter
  • Defined in: RpgPlayer

​
Signature

worldPositionY

​
Examples

const worldY = player.worldY();
console.log(`Player is at world Y: ${worldY}`);