Show Character

Description

'show character <character_id> <sprite_id> [at <position>] [with <animation> [infinite] [end-<animation>] [classes] [properties]]'

The character action allows you to display a character’s sprite. For other kind of images, take a look at the show image action.

Action ID: Show::Character

Reversible: Yes

Requires User Interaction: No

Character Definition

Characters must be defined before they can be shown. Each character has a unique identifier used in scripts:

monogatari.characters({
    'e': {
        name: 'Evelyn',
        color: '#00bfff',
        directory: 'evelyn', // Subdirectory in assets/characters/
        sprites: {
            normal: 'normal.png',
            happy: 'happy.png',
            sad: 'sad.png'
        }
    }
});

Character Properties

Property Description
name Display name shown in the text box
color Color for the character’s name (hex, rgb, or rgba)
directory Subdirectory within assets/characters/ for sprite images
sprites Object mapping sprite identifiers to image filenames
Face Optional side image shown when the character speaks
Side Optional object mapping side image identifiers for dialog expressions

Syntax

Positions

The at <position> clause sets where the character appears on screen. If omitted, defaults to center.

Common positions (CSS classes):

  • left - Left side of the screen
  • center - Center of the screen (default)
  • right - Right side of the screen

Custom positions can be defined via CSS.

Properties

These are special properties/classes that can be used when showing a character:

Name Description
duration Sets animation-duration CSS property. Format: duration <time> (e.g., duration 2s)
transition Sets transition-duration CSS property for the move class. Format: transition <time>
move Enables smooth movement animation when changing positions
end-<animation> Specifies an animation to play when the sprite is changed or removed
infinite Makes the animation loop indefinitely

Examples

Basic Usage

Show a character at the center (default position):

'show character e normal'

Show a character with an animation:

'show character e normal with fadeIn'

Show a character at a specific position with animation:

'show character e normal at center with fadeIn'

Infinite Animations

Make an animation loop continuously:

'show character e normal with pulse infinite'

Duration

Control how long an animation takes to complete:

'show character e normal with fadeIn duration 20s'

Move + Transition

Smoothly move a character from one position to another:

'show character e normal at left',
'show character e normal at right with move transition 6s'

The character will move from left to right over 6 seconds.

Exit Animations

Prepare an animation to play when the sprite changes. This creates smooth crossfade effects:

'show character e normal with end-fadeOut',
'show character e happy with fadeIn'

When changing from normal to happy, the old sprite will fade out while the new one fades in.

Complete Example

monogatari.script({
    'Start': [
        'show character e normal at left with fadeIn',
        'e Hello there!',
        'show character e happy at center with move transition 1s',
        'e I moved to the center!',
        'show character e normal with end-fadeOut',
        'show character e sad with fadeIn duration 2s',
        'e Now I\'m sad...',
        'hide character e with fadeOut'
    ]
});

Experimental: Layered Sprites

WARNING

This feature requires ExperimentalFeatures to be enabled in settings.

When experimental features are enabled, you can define composite sprites made of multiple layers:

monogatari.characters({
    'y': {
        name: 'Yui',
        directory: 'yui',
        sprites: {
            // Object-based sprites define layers
            normal: {
                base: 'base_uniform.png',
                face: 'face_neutral.png'
            },
            happy: {
                base: 'base_uniform.png',
                face: 'face_happy.png'
            }
        }
    }
});

Showing a layered sprite works the same as regular sprites:

'show character y normal'

For individual layer control, see Character Layers.

Sprite Caching

Character sprites that have been preloaded are automatically cached for faster display. When showing a character, the engine checks for cached sprites before loading from disk.

To preload character sprites:

'preload character e normal'

See the Preload action for more details.