Skip to main content

​
Server Map Hooks

Map hooks are global hooks that apply to all maps. They are defined in the map property of your server module.

​
Usage

import { defineModule, type RpgServer } from "@rpgjs/server";

export default defineModule<RpgServer>({
  map: {
    onBeforeUpdate(mapData, map) {
      return map;
    },
    onPhysicsInit(map, { mapData }) {
      // Build shared physics metadata
    },
    onPhysicsEntityAdd(map, { owner, entity, kind }) {
      // Attach entity-level collision rules
    },
    onPhysicsEntityRemove(map, { owner }) {
      // Cleanup entity-level rules
    },
    onPhysicsReset(map) {
      // Cleanup map-level physics extension state
    },
  },
});

​
Lifecycle Hooks

​
onBeforeUpdate(mapData, map)

Called before a map update is applied. Use this to normalize map data (width, height, custom fields) before loadPhysic().

​
onLoad(map)

Called when a map is loaded and initialized.

​
onJoin(player, map)

Called when a player joins a map.

​
onLeave(player, map)

Called when a player leaves a map.

​
Physics Extension Hooks

​
onPhysicsInit(map, context)

Called when map physics is initialized.
  • context.mapData: map data used by loadPhysic()

​
onPhysicsEntityAdd(map, context)

Called when a dynamic physics body is created.
  • context.owner: player/event owning the body
  • context.entity: physics entity instance
  • context.kind: "hero" | "npc" | "generic"

​
onPhysicsEntityRemove(map, context)

Called before a dynamic physics body is removed. Use this to unregister handlers attached in onPhysicsEntityAdd.

​
onPhysicsReset(map)

Called when map physics is reset before a reload. Use this for map-level cleanup.

​
Shared Logic Pattern

For client prediction parity, put collision rules in shared functions, then call them from:
  • server.map.onPhysics*
  • client.sceneMap.onPhysics*
This guarantees the same movement constraints on both sides.