addInDatabase(id: string, data: any, options?: { force?: boolean }): boolean

// Add an item class to the database
map.addInDatabase('Potion', PotionClass);

// Add an item object to the database
map.addInDatabase('custom-item', {
  name: 'Custom Item',
  price: 100
});

// Force overwrite existing data
map.addInDatabase('Potion', UpdatedPotionClass, { force: true });

applySyncToClient()

map.applySyncToClient();

map.broadcast(type, value)

map.broadcast("weather:warning", {
  level: "storm",
});

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

const socket = inject<AbstractWebsocket>(WebSocketToken);

socket.on("weather:warning", (payload) => {
  console.log(payload.level);
});

clear(): void

// In test cleanup
afterEach(() => {
  map.clear();
});

clearLighting(options?: LightingSetOptions): void

clearPhysic()

// Clear all physics when changing maps
map.clearPhysic();

// Then reload physics for the new map
map.loadPhysic();

clearWeather(options?: WeatherSetOptions): void

createDynamicEvent(eventObj: EventPosOption, options?: CreateDynamicEventOptions): Promise<string | undefined>

// Using a class-based event
class MyEvent extends RpgEvent {
  onInit() {
    console.log('Event initialized');
  }
}

map.createDynamicEvent({
  x: 100,
  y: 200,
  event: MyEvent
});

// Using an object-based event
map.createDynamicEvent({
  x: 100,
  y: 200,
  event: {
    onInit() {
      console.log('Event initialized');
    },
    onPlayerTouch(player) {
      console.log('Player touched event');
    }
  }
});

createDynamicWorldMaps(world: { id?: string; maps: WorldMapConfig[] }): WorldMapsManager

const manager = map.createDynamicWorldMaps({
  id: 'my-world',
  maps: [
    { id: 'map1', worldX: 0, worldY: 0, width: 800, height: 600 },
    { id: 'map2', worldX: 800, worldY: 0, width: 800, height: 600 }
  ]
});

createMovingHitbox(hitboxes: Array<{ x: number; y: number; width: number; height: number }>, options?: { speed?: number }): Observable<(T | any)[]>

// Create a sword slash effect that moves through two positions
map.createMovingHitbox([
  { x: 100, y: 100, width: 50, height: 50 },
  { x: 120, y: 100, width: 50, height: 50 }
], { speed: 2 }).subscribe({
  next(hits) {
    // hits contains RpgPlayer or RpgEvent objects that were hit
    console.log('Hit entities:', hits);
  },
  complete() {
    console.log('Movement finished');
  }
});

createShape(obj: {
    x: number;
    y: number;
    width: number;
    height: number;
    name?: string;
    z?: number;
    color?: string;
    collision?: boolean;
    properties?: Record<string, any>;
  }): RpgShape

// Create a simple rectangular shape
const shape = map.createShape({
  x: 100,
  y: 200,
  width: 50,
  height: 50,
  name: "spawn-zone"
});

// Create a shape with visual properties
const triggerZone = map.createShape({
  x: 300,
  y: 400,
  width: 100,
  height: 100,
  name: "treasure-area",
  color: "#FFD700",
  z: 1,
  collision: false,
  properties: {
    type: "treasure",
    value: 100
  }
});

// Player hooks will be triggered automatically
const player: RpgPlayerHooks = {
  onInShape(player: RpgPlayer, shape: RpgShape) {
    console.log('in', player.name, shape.name);
  },
  onOutShape(player: RpgPlayer, shape: RpgShape) {
    console.log('out', player.name, shape.name);
  }
};

damageFormulas: any

database

// Add data to database
map.addInDatabase('Potion', PotionClass);

// Access database
const potion = map.database()['Potion'];

dataIsReady$

// Wait for map data to be ready
map.dataIsReady$.subscribe(() => {
  console.log('Map is ready!');
});

deleteWorldMaps(id: string): boolean

const deleted = map.deleteWorldMaps('my-world');
if (deleted) {
  console.log('World manager removed');
}

events

// Get all events
const allEvents = map.events();

// Get a specific event
const event = map.events()['event-id'];

getBody(id: string): Entity | undefined

getBodyPosition(id: string, mode?: "center" | "top-left"): { x: number; y: number } | undefined

getEvent(eventId: string): T | undefined

// Get any event
const event = map.getEvent('npc-1');

// Get event with type narrowing
const npc = map.getEvent<MyNPC>('npc-1');
if (npc) {
  npc.speak('Hello!');
}

getEventBy(cb: (event: RpgEvent) => boolean): RpgEvent | undefined

// Find an event by name
const npc = map.getEventBy(event => event.name === 'Merchant');

// Find an event at a specific position
const chest = map.getEventBy(event => 
  event.x === 100 && event.y === 200
);

getEvents(): RpgEvent[]

const events = map.getEvents();
console.log(`There are ${events.length} events on the map`);

events.forEach(event => {
  console.log(`- ${event.name} at (${event.x}, ${event.y})`);
});

getEventsBy(cb: (event: RpgEvent) => boolean): RpgEvent[]

// Find all NPCs
const npcs = map.getEventsBy(event => event.name.startsWith('NPC-'));

// Find all events in a specific area
const nearbyEvents = map.getEventsBy(event => 
  event.x >= 0 && event.x <= 100 &&
  event.y >= 0 && event.y <= 100
);

getInWorldMaps(): RpgWorldMaps | undefined

const world = map.getInWorldMaps();
if (world) {
  console.log(world.getAllMaps());
}

getLighting(): LightingState | null

getPlayer(playerId: string): RpgPlayer | undefined

const player = map.getPlayer('player-123');
if (player) {
  console.log(`Player ${player.name} is on the map`);
}

getPlayers(): RpgPlayer[]

const players = map.getPlayers();
console.log(`There are ${players.length} players on the map`);

players.forEach(player => {
  console.log(`- ${player.name}`);
});

getShape(name: string): RpgShape | undefined

// Create a shape with a specific name
map.createShape({
  x: 100,
  y: 200,
  width: 50,
  height: 50,
  name: "spawn-point"
});

// Retrieve it later
const spawnZone = map.getShape("spawn-point");
if (spawnZone) {
  console.log(`Spawn zone at (${spawnZone.x}, ${spawnZone.y})`);
}

getShapes(): RpgShape[]

// Create multiple shapes
map.createShape({ x: 0, y: 0, width: 50, height: 50, name: "zone1" });
map.createShape({ x: 100, y: 100, width: 50, height: 50, name: "zone2" });

// Get all shapes
const allShapes = map.getShapes();
console.log(allShapes.length); // 2

getTick(): number

getWeather(): WeatherState | null

getWorldMaps(id: string): WorldMapsManager | null

const worldManager = map.getWorldMaps('my-world');
if (worldManager) {
  const mapInfo = worldManager.getMapInfo('map1');
}

getWorldMapsManager(): WorldMapsManager | null

const worldMaps = map.getWorldMapsManager();
if (worldMaps) {
  const adjacentMaps = worldMaps.getAdjacentMaps(currentMap, coordinates);
}

globalConfig: any

guiExit(player: RpgPlayer, { guiId, data })

// This method is called automatically when a player closes a GUI
// The GUI is removed from the player's active GUIs

guiInteraction(player: RpgPlayer, value: { guiId: string, name: string, data: any })

// This method is called automatically when a player interacts with a GUI
// The interaction data is sent from the client

heightPx

const height = map.heightPx;
console.log(`Map height: ${height}px`);

hooks

// Trigger a custom hook
map.hooks.callHooks('custom-event', data).subscribe();

id

const mapId = map.id;
console.log(`Current map: ${mapId}`);

interceptorPacket(player: RpgPlayer, packet: any, conn: Parameters<RoomMethods["$send"]>[0])

// This method is called automatically by the framework
// You typically don't call it directly

isMoving(id: string): boolean

// Check if player is moving
if (map.isMoving('player1')) {
  // Player is in motion
}

maps: (MapOptions | any)[]

nextTick(deltaMs?: number): number

// In tests: manually advance game by one tick
map.nextTick(); // Advances by 16ms (one frame at 60fps)

// With custom delta
map.nextTick(32); // Advances by 32ms (two frames at 60fps)

// In a test loop
for (let i = 0; i < 60; i++) {
  map.nextTick(); // Simulate 1 second of game time
}

map.off(type)

map.on(type, cb)

map.on("chat:message", (player, data) => {
  console.log(player.id, data.text);
});

onAction(player: RpgPlayer, action: any)

// This method is called automatically when a player presses an action button
// Events near the player will have their onAction hook triggered

onInput(player: RpgPlayer, input: any)

// This method is called automatically when a player moves
// The input is queued and processed by processInput()

onJoin(player: RpgPlayer, conn: Parameters<RoomMethods["$send"]>[0])

// This method is called automatically by the framework
// You can listen to the hook to perform custom logic
server.addHook('server-player-onJoinMap', (player, map) => {
console.log(`Player ${player.id} joined map ${map.id}`);
});

onLeave(player: RpgPlayer, conn: Parameters<RoomMethods["$send"]>[0])

// This method is called automatically by the framework
// You can listen to the hook to perform custom cleanup
server.addHook('server-player-onLeaveMap', (player, map) => {
console.log(`Player ${player.id} left map ${map.id}`);
});

patchLighting(patch: Partial<LightingState>, options?: LightingSetOptions): LightingState | null

patchWeather(patch: Partial<WeatherState>, options?: WeatherSetOptions): WeatherState | null

players

// Get all players
const allPlayers = map.players();

// Get a specific player
const player = map.players()['player-id'];

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

// Play a sound for all players on the map
map.playSound("explosion");

// Play background music for everyone with volume and loop
map.playSound("battle-theme", {
  volume: 0.7,
  loop: true
});

// Play a door opening sound at low volume
map.playSound("door-open", { volume: 0.4 });

processInput(playerId: string, controls?: Controls): Promise<{
    player: RpgPlayer,
    inputs: string[]
  }>

// Process inputs with default anti-cheat settings
const result = await map.processInput('player1');
console.log('Processed inputs:', result.inputs);

// Process inputs with custom anti-cheat configuration
const result = await map.processInput('player1', {
  maxTimeDelta: 100,
  maxFrameDelta: 5,
  minTimeBetweenInputs: 16,
  enableAntiCheat: true
});

queryArea(options: MapAreaQueryOptions<TCustom>): Array<MapAreaHit<TCustom | T | any>>

import { AreaShape } from "@rpgjs/server";

const hits = map.queryArea({
  center: player,
  shape: AreaShape.circle({ radius: 120 }),
  targets: ["players", "events"],
  excludeIds: [player.id],
});

for (const hit of hits) {
  const damage = Math.round(80 * hit.falloff.linear());
  hit.target.hp -= damage;
}

import { AreaShape } from "@rpgjs/server";

function explodeBomb(map, bomb, ownerId?: string) {
  const hits = map.queryArea({
    center: bomb,
    shape: AreaShape.circle({ radius: 96 }),
    targets: ["players", "events"],
    excludeIds: ownerId ? [ownerId] : [],
    filter: (target) => target.id !== bomb.id,
  });

  for (const hit of hits) {
    const damage = Math.round(120 * hit.falloff.linear());
    hit.target.hp = Math.max(0, hit.target.hp - damage);
  }
}

const hits = map.queryArea({
  center: { x: 320, y: 240 },
  shape: AreaShape.custom({
    bounds: ({ center }) => ({
      x: center.x - 160,
      y: center.y - 160,
      width: 320,
      height: 320,
    }),
    contains: (target, { center }) => {
      const distance = Math.hypot(target.x - center.x, target.y - center.y);
      return distance >= 64 && distance <= 160;
    },
    maxDistance: () => 160,
  }),
  targets: "custom",
  customTargets: projectiles,
});

queryHitbox(rect: MapHitboxQueryRect, options?: MapHitboxQueryOptions): Array<T | any>

removeEvent(eventId: string)

// Remove an event
map.removeEvent('npc-1');

// Remove event after interaction
const chest = map.getEvent('chest-1');
if (chest) {
  // ... do something with chest ...
  map.removeEvent('chest-1');
}

removeFromWorldMaps(): boolean | undefined

const removed = map.removeFromWorldMaps();

removeInDatabase(id: string): boolean

// Remove an item from the database
map.removeInDatabase('Potion');

// Check if removal was successful
const removed = map.removeInDatabase('custom-item');
if (removed) {
  console.log('Item removed successfully');
}

removeShape(name: string): void

// Create and then remove a shape
const shape = map.createShape({
  x: 100,
  y: 200,
  width: 50,
  height: 50,
  name: "temp-zone"
});

// Later, remove it
map.removeShape("temp-zone");

setAutoTick(enabled: boolean): void

// Disable auto tick for testing
map.setAutoTick(false);

// Manually trigger tick processing
await map.processInput('player1');

setBodyPosition(id: string, x: number, y: number, mode?: "center" | "top-left"): Entity | undefined

setDay(options?: LightingSetOptions): LightingState | null

setInWorldMaps(worldMap: RpgWorldMaps): void

const world = new WorldMapsManager();
world.configure([{ id: 'm1', worldX: 0, worldY: 0, width: 1024, height: 1024 }]);
map.setInWorldMaps(world);

setLighting(next: LightingState | null, options?: LightingSetOptions): LightingState | null

setNight(options?: LightingSetOptions): LightingState | null

setSync(schema: Record<string, any>)

// Add synchronized properties to the map
map.setSync({
weather: {
$initial: 'sunny',
$syncWithClient: true,
$permanent: false
},
timeOfDay: {
$initial: 12,
$syncWithClient: true,
$permanent: false
}
});

// Use the properties
map.weather.set('rainy');
const currentWeather = map.weather();

setWeather(next: WeatherState | null, options?: WeatherSetOptions): WeatherState | null

shakeMap(options?: {
    intensity?: number;
    duration?: number;
    frequency?: number;
    direction?: 'x' | 'y' | 'both';
  }): void

// Basic shake with default settings
map.shakeMap();

// Intense earthquake effect
map.shakeMap({
  intensity: 25,
  duration: 1000,
  frequency: 15,
  direction: 'both'
});

// Horizontal shake for side impact
map.shakeMap({
  intensity: 15,
  duration: 400,
  direction: 'x'
});

// Vertical shake for ground impact
map.shakeMap({
  intensity: 20,
  duration: 600,
  direction: 'y'
});

showAnimation(position: { x: number, y: number }, graphic: string, animationName?: string)

// Show explosion at specific coordinates
map.showAnimation({ x: 100, y: 200 }, "explosion");

// Show spell effect at player position
const playerPos = { x: player.x, y: player.y };
map.showAnimation(playerPos, "spell-effects", "lightning");

// Show environmental effect
map.showAnimation({ x: 300, y: 150 }, "nature-effects", "wind-gust");

// Show portal opening animation
map.showAnimation({ x: 500, y: 400 }, "portals", "opening");

showComponentAnimation(id: string, position: { x: number, y: number }, params: any)

// Show explosion at specific coordinates
map.showComponentAnimation("explosion", { x: 300, y: 400 }, {
  intensity: 2.5,
  duration: 1500
});

// Show area damage effect
map.showComponentAnimation("area-damage", { x: player.x, y: player.y }, {
  radius: 100,
  color: "red",
  damage: 50
});

// Show treasure spawn effect
map.showComponentAnimation("treasure-spawn", { x: 150, y: 200 }, {
  sparkle: true,
  sound: "treasure-appear"
});

sounds: string[]

// Set sounds for the map
map.sounds = ['background-music', 'ambient-forest'];

stopSound(soundId: string): void

// Start background music for everyone
map.playSound("battle-theme", { loop: true });

// Later, stop it for everyone
map.stopSound("battle-theme");

Input Events ─────────────────────────────────────────────────────────────►
    │
    ▼ (update velocity only)
┌─────────────────────────────────────────────────────────────────────────┐
│                        Game Loop (tick$)                                │
│  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐       │
│  │ updateMovements │ → │  stepOneTick    │ → │ postTickUpdates │       │
│  │ (apply velocity)│   │ (physics step)  │   │ (zones, sync)   │       │
│  └─────────────────┘   └─────────────────┘   └─────────────────┘       │
└─────────────────────────────────────────────────────────────────────────┘