> ## Documentation Index
> Fetch the complete documentation index at: https://v5.rpgjs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Dialog Box

> Guide for Dialog Box in RPGJS.

# 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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:

```typescript theme={null}
await player.showText('Message', {
    position: 'bottom'  // 'top', 'middle', or 'bottom'
});
```

### Full Width

Determines if the dialog box takes the full width of the screen:

```typescript theme={null}
await player.showText('Message', {
    fullWidth: true  // true by default
});
```

### Auto Close

If enabled, the dialog automatically closes after a delay:

```typescript theme={null}
await player.showText('Message', {
    autoClose: true  // false by default
});
```

### Typewriter Effect

Controls the typewriter animation effect:

```typescript theme={null}
await player.showText('Message', {
    typewriterEffect: true  // true by default
});
```

### Talk With

Makes an event or player turn toward the player during the dialog:

```typescript theme={null}
// 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:

```typescript theme={null}
await player.showText('Hello!', {
    talkWith: this,
    speaker: 'Mystery Voice'
});
```

### Face Display

Shows a character face with a specific expression:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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

```typescript theme={null}
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](/guide/sounds) for comprehensive information about sound configuration, dynamic sound resolution, and playing sounds from the server.

```typescript theme={null}
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

```typescript theme={null}
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](/guide/sounds) - Comprehensive guide on configuring and using sounds, including dynamic sound resolution
* [Prebuilt GUI Contracts](/gui/prebuilt-contracts) - Data and interaction contract for replacing `rpg-dialog` with your own CanvasEngine or Vue dialog box