RPG-JS Framework

The Player Dash playground is a minimal RPGJS implementation demonstrating the native player dash input. It showcases how the client predicts a dash through the standard movement channel while the server maintains authoritative validation of the dash action.

### Controls
- **Move**: arrow keys
- **Dash**: `Shift`
- **Action**: `Space`

The Vue GUI demonstration showcases how the detached @rpgjs/vue package integrates with RPGJS v5 to create various UI elements:

UI Component Types

• Fixed Overlays: e.g., vue-hud (Heads-Up Display).
• Server-opened Modals: e.g., vue-inventory (triggered by the server).
• Server-opened Panels: e.g., vue-quest-log (triggered by the server).
• Sprite-attached GUIs: e.g., vue-nameplate (UI elements that follow a specific sprite).

Interaction Events

• Vue-to-server interactions: Handled through the rpgGuiInteraction event.
• Closing GUIs: Vue close events are emitted via rpgGuiClose.

RPGJS uses different component systems depending on whether the visual is client-side, server-controlled, or an interactive interface. Use the following guide to select the correct system:

• Sprite Components: Use when you want to add a visual effect (like shadows or auras) to every matching sprite from the client side.
• Authoritative Sprite Components: Use when the server must decide what appears around a player (like name tags, HP bars, or badges).
• Prebuilt Components: Use when you want to reuse an existing visual effect provided by RPGJS instead of building a custom .ce component.
• GUI: Use for interactive interfaces that open, close, or send actions (menus, HUDs, dialogs).
• Attached GUI: Use when you need an interface that follows a sprite but is controlled like a GUI.

RPGJS is a TypeScript framework designed for building both standalone browser RPGs and networked MMORPGs using a unified architecture. The default technology stack includes:

• TypeScript: For writing game logic.
• Vite: For development and production builds.
• CanvasEngine: For rendering the game world.
• RPGJS server and client packages: For handling gameplay mechanics and networking.

The Mouse Interactions playground demonstrates several key patterns for handling user input via a mouse in RPGJS:

• Hover Popovers: Using DOMContainer to show UI elements on hover.
• Client-only Selection: Managing selection state locally on the client.
• Hit Testing: Implementing hitbox or custom-area hit testing.
• Drag and Drop: Implementing drag/drop previews that only trigger server-side calls upon a successful drop.
• Map Clicks: Handling clicks on the map to trigger server-side actions, such as player.moveTo({ x, y }).

A Shape is an invisible zone defined on the map that acts as a trigger mechanism. When an entity (like a player or an NPC) enters or leaves the boundaries of a shape, it can trigger specific actions.

Shapes can be used in several ways:

• Fixed Zones: Static areas on the map (e.g., a room entrance or a trap zone).
• Moving Zones: Shapes that move across the map.
• Attached Areas: Shapes attached to a player or an event to create systems like vision ranges, interaction radii, or aura effects.

A World is an abstraction that links several maps together using a shared coordinate system (world coordinates). You should use a World when your game requires:

• Map-to-map transitions
• Overworld navigation
• A large, connected game world composed of multiple discrete maps.

RPGJS follows a server-authoritative architecture to ensure multiplayer correctness.

• The Server owns the state: This includes player progression, inventory, combat results, map state, shared events, save data, and the validation of all client actions.
• The Client is a view/input layer: The client is responsible for rendering, predicting movement/actions, gathering user input, and reacting to the synchronized state sent by the server.
• Prediction & Reconciliation: While the client can use prediction to improve feel, it must remain reconcilable with the authoritative results provided by the server. A visual component should never silently become the owner of gameplay state.

Global chat is opt-in. To enable it, you must add 'global' to the channels array and provide a broadcastGlobal(message, player) adapter. This adapter is responsible for delivering the message to all clients across different rooms, processes, or edge locations.

provideChat({
  server: {
    channels: ['map', 'global'],

    async broadcastGlobal(message, player) {
      await applicationChatBus.publish(message, {
        senderId: player.id,
      })
    },
  },
})

When an API request requires a reference to an existing item or database ID (e.g., setting a weaponId for a hero or an itemId for an enemy reward), follow this workflow to ensure the ID exists:

1. Search: Perform a search using GET /api/database/:type?query=<search>.
2. Match: If a matching record is found, use its _id.
3. Create: If no match is found, create the record using POST /api/database/:type.
4. Reuse: Use the _id returned in the creation response for your original request.