Skip to main content

​
Dialog Box

The dialog box system in RPG.js allows you to display text messages and choices to players. It provides a built-in GUI component that handles text display, typewriter effects, and choice selection.

​
Basic Usage

​
Show Text

The showText() method displays a simple text message to the player: 
// Basic text display
await player.showText('Hello World!');

// Text with options
await player.showText('Welcome to our village!', {
    position: 'bottom',
    typewriterEffect: true,
    autoClose: false
});

​
Show Choices

The showChoices() method displays a dialog with multiple choices for the player to select from: 
// Basic choices
const choice = await player.showChoices('What would you like to do?', [
    { text: 'Fight', value: 'fight' },
    { text: 'Run away', value: 'run' },
    { text: 'Talk', value: 'talk' }
]);

if (choice) {
    console.log('Player selected:', choice.value);
}

​
Dialog Options

Both showText() and showChoices() accept an options object with the following properties:

​
Position

Controls where the dialog box appears on screen: 
await player.showText('Message', {
    position: 'bottom'  // 'top', 'middle', or 'bottom'
});

​
Full Width

Determines if the dialog box takes the full width of the screen: 
await player.showText('Message', {
    fullWidth: true  // true by default
});

​
Auto Close

If enabled, the dialog automatically closes after a delay: 
await player.showText('Message', {
    autoClose: true  // false by default
});

​
Typewriter Effect

Controls the typewriter animation effect: 
await player.showText('Message', {
    typewriterEffect: true  // true by default
});

​
Talk With

Makes an event or player turn toward the player during the dialog: 
// In an event
await player.showText('Hello!', {
    talkWith: this  // Makes the event turn toward the player
});

​
Speaker Name

Overrides the speaker label shown in the dialog: 
await player.showText('Hello!', {
    talkWith: this,
    speaker: 'Mystery Voice'
});

​
Face Display

Shows a character face with a specific expression: 
await player.showText('Hello!', {
    face: {
        id: 'facesetId',
        expression: 'happy'
    }
});

​
Faceset Configuration

To use faces in dialogs, you need to configure the faceset spritesheet on the client side. The faceset is a single image containing multiple character expressions arranged in a grid.

​
Client-side Setup

In your client configuration (config.client.ts), add the faceset spritesheet: 
import { Presets } from "@rpgjs/client";

export default {
  providers: [
    provideClientModules([
      {
        spritesheets: [
          Presets.FacesetPreset({
            id: "facesetId",
            image: "faceset.png",
            width: 1024,
            height: 1024,
          }, 3, 4, {
            happy: [0, 0],
            sad: [1, 0],
            angry: [2, 0],
            surprised: [0, 1],
            neutral: [1, 1],
            worried: [2, 1]
          }),
        ],
      },
    ]),
  ],
};

​
Faceset Parameters

  • id: Unique identifier for the faceset
  • image: Path to the faceset image file
  • width/height: Dimensions of the faceset image
  • framesWidth/framesHeight: Number of frames horizontally and vertically in the grid
  • expressions: Object mapping expression names to their grid positions [frameX, frameY]

​
Using Faces in Dialogs

Once configured, you can use the faceset in dialogs: 
// Server-side usage
await player.showText('Hello!', {
    face: {
        id: 'facesetId',      // Must match the spritesheet ID
        expression: 'happy'    // Must match an expression defined in the preset
    }
});

​
Faceset Image Layout

Your faceset image should be organized in a grid. For example, with framesWidth: 3 and framesHeight: 4: 
[0,0] [1,0] [2,0]
[0,1] [1,1] [2,1]
[0,2] [1,2] [2,2]
[0,3] [1,3] [2,3]
Each position [frameX, frameY] corresponds to a specific expression in your faceset.

​
Dialog Box Customization

You can customize the appearance and sounds of the dialog box using provideClientGlobalConfig() in your client configuration.

​
Styling the Dialog Box

import { provideClientGlobalConfig } from "@rpgjs/client";

export default {
  providers: [
    provideClientGlobalConfig({
      box: {
        styles: {
          backgroundColor: "#1a1a2e",    // Background color
          backgroundOpacity: 0.9,        // Background opacity
        }
      }
    }),
  ],
};

​
Customizing Sounds

You can customize the sounds used by the dialog box. The sound IDs in provideClientGlobalConfig() must correspond to the sound IDs defined in provideClientModules().
See also: Sounds Guide for comprehensive information about sound configuration, dynamic sound resolution, and playing sounds from the server. 
import { provideClientGlobalConfig } from "@rpgjs/client";

export default {
  providers: [
    provideClientGlobalConfig({
      box: {
        sounds: {
          typewriter: "typewriterId",    // Sound for typewriter effect
          cursorMove: "cursorId",        // Sound when moving cursor in choices
          cursorSelect: "selectId"       // Sound when selecting a choice
        }
      }
    }),
  ],
};
Important: The sound IDs in the box.sounds configuration must match the sound IDs defined in your provideClientModules() configuration. The sounds themselves are loaded through the sounds array in provideClientModules().

​
Complete Configuration Example

import { provideClientGlobalConfig, provideClientModules } from "@rpgjs/client";

export default {
  providers: [
    provideClientGlobalConfig({
      box: {
        styles: {
          backgroundColor: "#2a2a4e",
          backgroundOpacity: 0.95,
        },
        sounds: {
          typewriter: "typewriterId",
          cursorMove: "cursorId",
          cursorSelect: "selectId"
        }
      }
    }),
    provideClientModules([
      {
        sounds: [
          {
            id: "typewriterId",
            src: "typewriter.wav",
          },
          {
            id: "cursorId",
            src: "cursor.wav",
          },
          {
            id: "selectId",
            src: "select.wav",
          }
        ],
      },
    ]),
  ],
};

​
See Also

  • Sounds Guide - Comprehensive guide on configuring and using sounds, including dynamic sound resolution