# Scene and Actor Setup Guide

This guide explains how to configure scenes and actors for the dialogue system.

## Overview

Scenes provide visual backgrounds and actor images for dialogue. Actors are characters that appear when they speak. The configuration uses YAML format with two separate sections: `scenes` and `actors`.

## Configuration Format

Create a YAML file with the following structure:

```yaml
scenes:
  scene1: https://example.com/background1.jpg
  scene2: https://example.com/background2.jpg
  
actors:
  user: https://example.com/user.png
  Narrator: https://example.com/narrator.png
  npc: https://example.com/npc.png
```

## Scenes

### Simple Scene (Background Only)

The simplest format is just the background image URL:

```yaml
scenes:
  scene1: https://example.com/background1.jpg
```

This creates a scene named `scene1` with the specified background. All global actors will be available in this scene.

### Scene with Custom Actors

You can override global actors per scene:

```yaml
scenes:
  scene1:
    background: https://example.com/background1.jpg
    actors:
      special_npc:
        image: https://example.com/special-npc.png
```

This creates `scene1` with a custom background and includes a scene-specific actor `special_npc` in addition to all global actors.

### Scene Structure

- **scene name** (key): The identifier used in Yarn scripts (e.g., `scene: scene1`)
- **background** (string): URL or path to the background image
- **actors** (object, optional): Scene-specific actors that override or extend global actors

## Actors

### Global Actors

Global actors are available in all scenes:

```yaml
actors:
  user: https://example.com/user.png
  Narrator: https://example.com/narrator.png
  npc: https://example.com/npc.png
```

### Actor Configuration

Actors can be defined in two ways:

**Shorthand** (direct URL):
```yaml
actors:
  user: https://example.com/user.png
```

**Full format** (object):
```yaml
actors:
  user:
    image: https://example.com/user.png
```

Both formats are equivalent. The object format allows for future extension with additional actor properties.

## Using Scenes in Yarn Scripts

Add a `scene:` header to any node to activate that scene:

```yarn
title: Start
scene: scene1
---
Narrator: Welcome to the adventure!
User: Let's begin!
===
```

### Scene Persistence

Once a scene is set, the background persists across nodes until a new scene is specified. If a node doesn't have a `scene:` header, the previous scene continues to be used.

## Actor Display

### When Actors Appear

- Actors appear only when they are speaking
- Actor images are matched by name (case-insensitive)
- The speaking actor's image appears at the top center of the scene
- If no matching actor is found in the scene configuration, only the text is shown
- The portrait transition duration defaults to 350 ms and can be adjusted by passing `actorTransitionDuration` (in milliseconds) to either `<DialogueScene />` or `<DialogueView />`

### Actor Matching

Actor names in the Yarn script are matched against actor names in the scene configuration:

```yarn
Narrator: This is the narrator speaking.
```

This matches an actor named `Narrator`, `narrator`, or any case variation in your scene config.

## Example Configuration

```yaml
scenes:
  intro:
    background: /assets/backgrounds/intro.jpg
  forest:
    background: /assets/backgrounds/forest.jpg
    actors:
      guide:
        image: /assets/actors/guide.png
  
actors:
  user: /assets/actors/user.png
  Narrator: /assets/actors/narrator.png
  merchant: /assets/actors/merchant.png
```

In this example:
- `intro` scene uses the intro background and all global actors (user, Narrator, merchant)
- `forest` scene uses the forest background, includes all global actors, plus a scene-specific `guide` actor

## Yarn Script Example

```yarn
title: Intro
scene: intro
---
Narrator: Welcome to the adventure!
User: I'm ready to begin!
===

title: Forest
scene: forest
---
Narrator: You enter the mysterious forest.
Guide: Let me show you the way.
User: Thank you, guide!
===
```

## Image Requirements

- **Background images**: Should be high resolution (recommended: 1920x1080 or higher) as they fill the entire scene
- **Actor images**: Should be transparent PNGs with the character visible in the frame (recommended: 800x1200 or similar portrait aspect)
- Images can be:
  - Local paths: `/assets/images/character.png`
  - Absolute URLs: `https://example.com/image.jpg`
  - Relative URLs: `../images/background.png`

## CSS Styling

All dialogue elements use CSS classes prefixed with `yd-` for easy customization:

- `.yd-scene` - Scene background container
- `.yd-actor` - Actor image
- `.yd-dialogue-box` - Dialogue box container
- `.yd-text-box` - Text dialogue content
- `.yd-options-box` - Options container

You can override these styles in your own CSS to customize the appearance.

## Tips

1. **Reuse actors**: Define common actors globally so they're available in all scenes
2. **Scene-specific actors**: Use scene-specific actors for characters that only appear in certain scenes
3. **Background persistence**: Scenes persist until changed, so you don't need to repeat `scene:` in every node
4. **Case sensitivity**: Actor names are matched case-insensitively, but scene names are case-sensitive
5. **Image loading**: Use optimized images (WebP or compressed PNG/JPG) for better performance