Struct Animator 

pub struct Animator<M, S: AnimationStates> { /* private fields */ }

The machine a game poses a draw with: the state it is in, what that state plays, and the fade out of the state it left.

Typed by the mesh it poses, so a draw of another mesh does not take it. ctx.animate runs one and Instance::posed draws in the pose it holds; no clip length and no time of the game’s own crosses either call.

Implementations

impl<M, S: AnimationStates> Animator<M, S>

pub fn new() -> Self

A machine in its entry state, at the start of what that state plays reading the default input.

Examples found in repository

examples/animation.rs (line 668)

    fn init(_ctx: &mut InitContext<'_, Scene>) -> Result<Self, Error> {
        Ok(Self {
            elf_pos: ELF_START,
            elf_prev: ELF_START,
            elf_yaw: 0.0,
            elf_height: 0.0,
            elf_height_prev: 0.0,
            jump_speed: 0.0,
            elf_input: ElfInput::default(),
            elf_animator: Animator::new(),
            scrubbed_animator: Animator::new(),
            butterfly_animator: Animator::new(),
            hits: 0,
            in_patch: false,
            holding: false,
            camera_yaw: 0.0,
            camera_pitch: 0.0,
            last_event: "none yet",
        })
    }

    /// Turns the camera by how far the pointer moves sideways and upward,
    /// [`CAMERA_PITCH_RANGE`] holding how far it tilts.
    fn steer_camera(&mut self, ctx: &mut FrameContext<'_, Scene>) {
        self.camera_yaw -= ctx.axis(Axis::CameraYaw);
        self.camera_pitch = (self.camera_pitch + ctx.axis(Axis::CameraPitch))
            .clamp(CAMERA_PITCH_RANGE.start, CAMERA_PITCH_RANGE.end);
    }

    /// Turns `elf_yaw` toward the heading `ctx` reads, relative to the
    /// camera's own turn, and moves `elf_pos` along it; the speed it moves
    /// at, a fraction of [`ELF_SPEED`], held at [`WALK_CAP`] until
    /// `Button::Run` is held.
    fn advance(&mut self, ctx: &mut TickContext<'_, Scene>) -> f32 {
        let control = ctx.axis2(Move::Walk).clamp_length_max(1.0);
        let turn = Quat::from_rotation_y(self.camera_yaw);
        let heading = turn * Vec3::X * control.x + turn * Vec3::NEG_Z * control.y;
        let dt = ctx.dt().as_secs_f32();
        if let Some(direction) = heading.try_normalize() {
            let wanted = direction.x.atan2(direction.z);
            let turn = (wanted - self.elf_yaw + core::f32::consts::PI).rem_euclid(TAU)
                - core::f32::consts::PI;
            self.elf_yaw += turn.clamp(-TURN_RATE * dt, TURN_RATE * dt);
        }
        let cap = if ctx.down(Button::Run) { 1.0 } else { WALK_CAP };
        self.elf_pos += heading * cap * ELF_SPEED * dt;
        heading.length() * cap
    }

    /// Integrates [`Self::elf_height`] under [`GRAVITY`] from
    /// [`Self::jump_speed`], held at the ground; `true` the tick it
    /// returns there from above it.
    fn fall(&mut self, dt: f32) -> bool {
        let off_ground = self.elf_height > 0.0;
        self.jump_speed -= GRAVITY * dt;
        self.elf_height = (self.elf_height + self.jump_speed * dt).max(0.0);
        if self.elf_height == 0.0 {
            self.jump_speed = 0.0;
        }
        off_ground && self.elf_height == 0.0
    }

    /// The hurt patch `elf_pos` stands inside, if any.
    fn patch_underfoot(&self) -> Option<Vec3> {
        HURT_PATCHES
            .into_iter()
            .find(|&patch| self.elf_pos.distance(patch) < HURT_RADIUS)
    }

    /// Reads the controls and moves the elf, filling [`Self::elf_input`]
    /// for [`ElfState`] to read.
    fn tick_elf(&mut self, ctx: &mut TickContext<'_, Scene>) {
        let grounded = matches!(
            self.elf_animator.state(),
            ElfState::Idle | ElfState::Locomotion
        );

        self.elf_input.speed = self.advance(ctx);
        self.elf_input.attack = ctx.pressed(Button::Attack);
        self.elf_input.jump = ctx.pressed(Button::Jump);
        self.elf_input.dance = ctx.pressed(Button::Dance);

        self.elf_input.near_seat = self.elf_pos.distance(SEAT_POSITION) < SEAT_INTERACT_RADIUS;
        self.elf_input.interact = ctx.pressed(Button::Interact);
        if self.elf_input.interact && grounded && self.elf_input.near_seat {
            self.elf_pos = SEAT_SPOT;
            self.elf_yaw = SEAT_FACING;
        }

        let underfoot = self.patch_underfoot();
        let entered_patch = underfoot.is_some() && !self.in_patch;
        self.in_patch = underfoot.is_some();
        self.hits += u32::from(entered_patch);
        self.elf_input.hit = entered_patch && self.hits < FATAL_HITS;
        self.elf_input.dying = entered_patch && self.hits >= FATAL_HITS;
        if entered_patch {
            self.last_event = match self.elf_input.dying {
                true => "elf died",
                false => "elf hit",
            };
        }
    }

    /// Starts a new [`Animator`] over the elf's own state, its position and
    /// hit count reset with it.
    fn restart_elf(&mut self) {
        self.elf_animator = Animator::new();
        self.elf_pos = ELF_START;
        self.elf_prev = ELF_START;
        self.elf_yaw = 0.0;
        self.elf_height = 0.0;
        self.elf_height_prev = 0.0;
        self.jump_speed = 0.0;
        self.elf_input = ElfInput::default();
        self.hits = 0;
        self.in_patch = false;
        self.last_event = "new elf started";
    }

pub fn state(&self) -> S

The state it is in, which is the state being faded into while a fade runs.

Examples found in repository

examples/animation.rs (line 732)

    fn tick_elf(&mut self, ctx: &mut TickContext<'_, Scene>) {
        let grounded = matches!(
            self.elf_animator.state(),
            ElfState::Idle | ElfState::Locomotion
        );

        self.elf_input.speed = self.advance(ctx);
        self.elf_input.attack = ctx.pressed(Button::Attack);
        self.elf_input.jump = ctx.pressed(Button::Jump);
        self.elf_input.dance = ctx.pressed(Button::Dance);

        self.elf_input.near_seat = self.elf_pos.distance(SEAT_POSITION) < SEAT_INTERACT_RADIUS;
        self.elf_input.interact = ctx.pressed(Button::Interact);
        if self.elf_input.interact && grounded && self.elf_input.near_seat {
            self.elf_pos = SEAT_SPOT;
            self.elf_yaw = SEAT_FACING;
        }

        let underfoot = self.patch_underfoot();
        let entered_patch = underfoot.is_some() && !self.in_patch;
        self.in_patch = underfoot.is_some();
        self.hits += u32::from(entered_patch);
        self.elf_input.hit = entered_patch && self.hits < FATAL_HITS;
        self.elf_input.dying = entered_patch && self.hits >= FATAL_HITS;
        if entered_patch {
            self.last_event = match self.elf_input.dying {
                true => "elf died",
                false => "elf hit",
            };
        }
    }

    /// Starts a new [`Animator`] over the elf's own state, its position and
    /// hit count reset with it.
    fn restart_elf(&mut self) {
        self.elf_animator = Animator::new();
        self.elf_pos = ELF_START;
        self.elf_prev = ELF_START;
        self.elf_yaw = 0.0;
        self.elf_height = 0.0;
        self.elf_height_prev = 0.0;
        self.jump_speed = 0.0;
        self.elf_input = ElfInput::default();
        self.hits = 0;
        self.in_patch = false;
        self.last_event = "new elf started";
    }

    fn panel(&self, ctx: &mut FrameContext<'_, Scene>) {
        let state = match self.elf_animator.state() {
            ElfState::Idle => "idle",
            ElfState::Locomotion if self.elf_input.speed > WALK_CAP => "running",
            ElfState::Locomotion => "walking",
            ElfState::Attack => "attacking",
            ElfState::Hit => "hit",
            ElfState::Death => "dead",
            ElfState::SitDown => "sitting down",
            ElfState::Sit => "sitting",
            ElfState::StandUp => "standing up",
            ElfState::Jump => "jumping",
            ElfState::Dance => "dancing",
        };
        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(PANEL_BACKDROP))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.heading(panel_text(format!("elf is {state}")));
                    ui.label(panel_text(format!(
                        "hits taken {} of the {} red patches hurt for, {}",
                        self.hits, FATAL_HITS, self.last_event
                    )));
                    ui.label(panel_text(match self.elf_animator.transitioning() {
                        true => "fading between clips",
                        false => "one clip playing",
                    }));
                    ui.add_space(f32::from(PANEL_PADDING));
                    egui::Grid::new("controls").show(ui, |ui| {
                        for (key, does) in CONTROLS {
                            ui.label(panel_text(key));
                            ui.label(panel_text(does));
                            ui.end_row();
                        }
                    });
                });
        });
    }

    /// A prompt over the seat, each hurt patch, and the scrubbed elf,
    /// naming what a player finds there; the seat's own prompt names the
    /// live binding of `Button::Interact` by its own name, not one fixed
    /// in the code, and is absent while the elf sits on it.
    fn draw_prompts(&self, ctx: &mut FrameContext<'_, Scene>, camera: Camera) {
        let sit_key = ctx
            .bindings(Button::Interact)
            .into_iter()
            .next()
            .map_or_else(|| "interact".to_owned(), |binding| binding.to_string());
        let sit = ctx.text_layout(
            &format!("{sit_key} sits"),
            egui::FontId::proportional(PROMPT_SIZE),
        );
        let hurts = ctx.text_layout("hurts", egui::FontId::proportional(PROMPT_SIZE));
        let walk_closer = ctx.text_layout("walk closer", egui::FontId::proportional(PROMPT_SIZE));

        let mut prompts = vec![(
            SCRUBBED_ELF_POSITION + Vec3::Y * (ELF_HEIGHT + PROMPT_LIFT),
            walk_closer,
        )];
        if !self.elf_animator.state().seated() {
            prompts.push((
                SEAT_POSITION + Vec3::Y * (SEAT_HEAD_HEIGHT + PROMPT_LIFT),
                sit,
            ));
        }
        prompts.extend(HURT_PATCHES.map(|patch| (patch + Vec3::Y * PROMPT_LIFT, hurts.clone())));

        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        ctx.ui(|ui| {
            let painter = ui.painter();
            for (point, galley) in prompts {
                let Some(pixel) = camera.pixel_of(point, window_size) else {
                    continue;
                };
                let at = logical(pixel, pixels_per_point);
                let ink = galley.mesh_bounds;
                let pos = egui::pos2(at.x - ink.center().x, at.y - ink.center().y);
                let backdrop = egui::Rect::from_center_size(
                    at,
                    ink.size() + egui::Vec2::splat(PROMPT_PADDING * 2.0),
                );
                painter.rect_filled(
                    backdrop,
                    PROMPT_PADDING,
                    egui::Color32::from_black_alpha(PANEL_BACKDROP),
                );
                painter.galley(pos, galley, PANEL_TEXT_COLOR);
            }
        });
    }

pub fn entered(&self, state: S) -> bool

Whether a transition into state started the last time animate ran it.

Examples found in repository

examples/animation.rs (line 900)

    fn tick(&mut self, ctx: &mut TickContext<'_, Scene>) {
        self.elf_prev = self.elf_pos;
        self.elf_height_prev = self.elf_height;

        if ctx.pressed(Button::Restart) {
            self.restart_elf();
        }
        if ctx.pressed(Button::Hold) {
            self.holding = true;
        }
        if ctx.pressed(Button::Release) {
            self.holding = false;
        }

        self.elf_input.landed = self.fall(ctx.dt().as_secs_f32());
        self.tick_elf(ctx);
        ctx.animate(Elf, &mut self.elf_animator, &self.elf_input);

        if self.elf_animator.entered(ElfState::Jump) {
            self.jump_speed = JUMP_LAUNCH_SPEED;
        }
        if self.elf_animator.left(ElfState::StandUp) {
            self.last_event = "elf stood up";
        }
        if self.elf_animator.entered(ElfState::Sit) {
            self.last_event = "elf sat down";
        }
        if self.elf_animator.entered(ElfState::Death) {
            self.last_event = "elf died";
        }

        let scrubbed_input = ScrubbedInput {
            settled: settled_at(self.elf_pos.distance(SCRUBBED_ELF_POSITION)),
        };
        ctx.animate(Elf, &mut self.scrubbed_animator, &scrubbed_input);
        ctx.animate(Butterfly, &mut self.butterfly_animator, &());
    }

pub fn left(&self, state: S) -> bool

Whether a transition out of state started the last time animate ran it.

Examples found in repository

examples/animation.rs (line 903)

    fn tick(&mut self, ctx: &mut TickContext<'_, Scene>) {
        self.elf_prev = self.elf_pos;
        self.elf_height_prev = self.elf_height;

        if ctx.pressed(Button::Restart) {
            self.restart_elf();
        }
        if ctx.pressed(Button::Hold) {
            self.holding = true;
        }
        if ctx.pressed(Button::Release) {
            self.holding = false;
        }

        self.elf_input.landed = self.fall(ctx.dt().as_secs_f32());
        self.tick_elf(ctx);
        ctx.animate(Elf, &mut self.elf_animator, &self.elf_input);

        if self.elf_animator.entered(ElfState::Jump) {
            self.jump_speed = JUMP_LAUNCH_SPEED;
        }
        if self.elf_animator.left(ElfState::StandUp) {
            self.last_event = "elf stood up";
        }
        if self.elf_animator.entered(ElfState::Sit) {
            self.last_event = "elf sat down";
        }
        if self.elf_animator.entered(ElfState::Death) {
            self.last_event = "elf died";
        }

        let scrubbed_input = ScrubbedInput {
            settled: settled_at(self.elf_pos.distance(SCRUBBED_ELF_POSITION)),
        };
        ctx.animate(Elf, &mut self.scrubbed_animator, &scrubbed_input);
        ctx.animate(Butterfly, &mut self.butterfly_animator, &());
    }

pub fn transitioning(&self) -> bool

Whether a fade out of the state it left was still running the last time animate ran it.

Examples found in repository

examples/animation.rs (line 803)

    fn panel(&self, ctx: &mut FrameContext<'_, Scene>) {
        let state = match self.elf_animator.state() {
            ElfState::Idle => "idle",
            ElfState::Locomotion if self.elf_input.speed > WALK_CAP => "running",
            ElfState::Locomotion => "walking",
            ElfState::Attack => "attacking",
            ElfState::Hit => "hit",
            ElfState::Death => "dead",
            ElfState::SitDown => "sitting down",
            ElfState::Sit => "sitting",
            ElfState::StandUp => "standing up",
            ElfState::Jump => "jumping",
            ElfState::Dance => "dancing",
        };
        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(PANEL_BACKDROP))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.heading(panel_text(format!("elf is {state}")));
                    ui.label(panel_text(format!(
                        "hits taken {} of the {} red patches hurt for, {}",
                        self.hits, FATAL_HITS, self.last_event
                    )));
                    ui.label(panel_text(match self.elf_animator.transitioning() {
                        true => "fading between clips",
                        false => "one clip playing",
                    }));
                    ui.add_space(f32::from(PANEL_PADDING));
                    egui::Grid::new("controls").show(ui, |ui| {
                        for (key, does) in CONTROLS {
                            ui.label(panel_text(key));
                            ui.label(panel_text(does));
                            ui.end_row();
                        }
                    });
                });
        });
    }

pub fn hold(&mut self)

Holds what it plays where it is, until resume.

Required if you want a paused game to leave every mesh in the pose it is drawn in: the span between this call and the resume counts for nothing, so each motion runs on from where it was held.

pub fn resume(&mut self)

Plays on from where hold left it.

Trait Implementations

impl<M, S: AnimationStates> Clone for Animator<M, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M, S: AnimationStates> Debug for Animator<M, S>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

The state it is in and whether it is still fading out of the one it left.

impl<M, S: AnimationStates> Default for Animator<M, S>

fn default() -> Self

A machine in its entry state; see Animator::new.