std::stage

Stability: Stable — characters on the stage, written as const fn helpers over the screen.

std::stage is the character layer studios otherwise build by hand. It adds no components: every helper is ordinary const fn code over std::screen, and is the model for how a studio extends the library with its own helpers and constant data. Slots are studio Point constants; faces are ImageAsset constants.

The prelude re-exports Character and character. hide_all and side_face need a use std::stage::{hide_all, side_face};. Complete examples are in Staging Recipes.

Overview

Struct: Character

pub struct Character {
    pub entity: EntityId,
    pub offset: Offset,
    pub anchor: Anchor,
    pub plane: Plane,
    pub z: i32,
}

How a character is placed: the entity that draws it, an offset added to every slot (a per-character correction for sprites of different sizes), and its layout. A Character is constant data. Wherever a method takes a slot at, the target point is at + offset.

character(entity)

pub const fn character(entity: EntityId) -> Character

• Returns: a character drawn by entity, without offset, anchored TOP_LEFT on the Stage plane at z 0.
• Kind: const fn · Builtin: no.

Builders: offset, anchor, plane, z

pub const fn offset(mut self, offset: Offset) -> Character
pub const fn anchor(mut self, anchor: Anchor) -> Character
pub const fn plane(mut self, plane: Plane) -> Character
pub const fn z(mut self, z: i32) -> Character

The layout is applied when show spawns the entity. Kind: const fn · Builtin: no.

character.show(screen, face, at, tween)

pub const fn show(self, screen: &mut Screen, face: ImageAsset, at: Point, tween: Tween)

Shows the character with face at at, fading in, or moves and crossfades it if it is already on the screen.

• If screen.contains(entity): the image changes to face with fade(tween.duration) and the position moves to the target with tween.
• Else: set_plane, set_z and set_anchor from the character; the position is set to the target with instant(); the image to face with cut().
• Either way, the opacity changes to 1.0 with tween.
• Kind: const fn · Builtin: no.

character.face(screen, face, transition)

pub const fn face(self, screen: &mut Screen, face: ImageAsset, transition: Transition)

Changes the face (the MAIN image) with transition. Kind: const fn · Builtin: no.

character.move_to(screen, at, tween)

pub const fn move_to(self, screen: &mut Screen, at: Point, tween: Tween)

Moves the character to at + offset with tween. Kind: const fn · Builtin: no. The body is plain const fn code on the screen:

pub const fn move_to(self, screen: &mut Screen, at: Point, tween: Tween) {
    let target = point(at.x + self.offset.dx, at.y + self.offset.dy);
    screen.entity(self.entity).position().change(target).apply_animation(tween);
}

character.hide(screen, tween)

pub const fn hide(self, screen: &mut Screen, tween: Tween)

Fades the character out (opacity 0.0 with tween) and despawns it. The fade is still drawn; the next step does not inherit the entity. Kind: const fn · Builtin: no.

character.act(screen, motion)

pub const fn act(self, screen: &mut Screen, motion: Motion)

Plays motion on the character’s entity. See Motion. Kind: const fn · Builtin: no.

Function: hide_all(screen, tween)

pub const fn hide_all(screen: &mut Screen, tween: Tween)

Fades out (opacity 0.0 with tween) and despawns every entity on the Stage plane, in screen.entities(Plane::Stage) order. Kind: const fn · Builtin: no.

Function: side_face(screen, face, transition)

pub const fn side_face(screen: &mut Screen, face: Option<ImageAsset>, transition: Transition)

Shows face as the Hud’s side image (Some(f): hud().side_image().change(f)), or clears it (None: .clear()), with transition. The game view draws the side image next to the text window. It is part of the logical screen, so it stays until a later render changes it. Kind: const fn · Builtin: no.

side_face(&mut screen, Some(HANAKO::NORMAL), fade(ms(300)));
side_face(&mut screen, None, fade(ms(300)));

Characters, faces and slots

Slots are studio Point constants. Faces are ImageAsset constants in a module named after the character, so a misspelled face is a resolve error and a missing file is an asset error.

use std::screen::BOTTOM_CENTER;
use std::stage::side_face;

const HANAKO: Character = character(EntityId(1)).offset(offset(0, 40)).anchor(BOTTOM_CENTER);

mod HANAKO {
    pub const NORMAL: ImageAsset = asset("hanako_normal.png");
    pub const SMILE: ImageAsset = asset("hanako_smile.png");
}

const LEFT: Point = point(320, 720);
const CENTER: Point = point(640, 720);

const fn hanako_enters(mut screen: Screen) -> Screen {
    HANAKO.show(&mut screen, HANAKO::NORMAL, CENTER, tween(ms(300)));
    side_face(&mut screen, Some(HANAKO::NORMAL), fade(ms(300)));
    screen
}

const fn hanako_smiles(mut screen: Screen) -> Screen {
    HANAKO.face(&mut screen, HANAKO::SMILE, fade(ms(300)));
    HANAKO.act(&mut screen, jump(30, ms(400)));
    screen
}

const fn hanako_moves_left(mut screen: Screen) -> Screen {
    HANAKO.move_to(&mut screen, LEFT, tween(ms(1000)).ease(Easing::InOutSine));
    screen
}

Stability: Planned — layered character sprites with auto-blink and voice-driven lip sync are not designed yet. Today a face is one ImageAsset on the MAIN part; further parts can be stacked by hand with Entity::part.