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#

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:

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#

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.

Related Actions#

• Hide Character - Remove a character from the screen
• Character Layers - Control individual sprite layers
• Show Image - Show non-character images