Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,8 @@ possesses a body, and the Director's prompt says so. Possession applies to one
Character Instance. Possessing another releases the first. It is not a State,
so a possessed sprite still falls, perches and can be grabbed, and it stays
possessed when another window takes the keyboard. Users see it explained as
"Manually drive the fidget on your screen". #1655.
"Manually drive the fidget on your screen". Possessing plays the optional
`possessed` Animation, or `react` in a package without it. #1655.

**Possess, Release**:
The verbs that turn Possession on and off, and the Menu row's two labels.
Expand Down
39 changes: 35 additions & 4 deletions crates/core/src/character.rs
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,9 @@ pub enum Primitive {
/// velocity and nothing more. `Falling` carries the arc and the existing
/// landing path ends it, so a jump reuses the Throw's physics.
Jump,
/// The moment possession starts. The Engine plays it itself and no
/// Behavior composes it, so it is not in the manifest's names.
Possessed,
}

const PRIMITIVES: [(&str, Primitive); 10] = [
Expand Down Expand Up @@ -482,12 +485,13 @@ impl Character {

/// Optional Animations, and what draws when a package does not declare them:
/// used when present, and absent silently, never as a missing sprite.
const OPTIONAL_FALLBACKS: [(&str, &str); 3] = [
const OPTIONAL_FALLBACKS: [(&str, &str); 4] = [
("climb", "walk"),
("grab", "fall"),
// The Required Animation Set is closed at nine, so a jump is optional art.
// A Character without it rises and falls in its `fall`.
("jump", "fall"),
("possessed", "react"),
];

/// How many Behaviors of a loop a rejection spells out before it stops.
Expand Down Expand Up @@ -620,7 +624,7 @@ fn personality(package: &PackageBytes, errors: &mut Vec<String>) -> String {
}

#[cfg(test)]
mod tests {
pub(crate) mod tests {
use super::*;

use crate::overlay::SpriteRect;
Expand All @@ -646,7 +650,7 @@ mod tests {
}

/// A Character Manifest declaring exactly `animations`, one frame each.
pub(super) fn declaring(animations: &[&str]) -> String {
pub(crate) fn declaring(animations: &[&str]) -> String {
let mut manifest = String::from("name = \"Blip\"\n");
for animation in animations {
manifest.push_str(&format!(
Expand All @@ -656,7 +660,7 @@ mod tests {
manifest
}

pub(super) fn load_manifest(manifest: &str) -> Result<Character, Vec<String>> {
pub(crate) fn load_manifest(manifest: &str) -> Result<Character, Vec<String>> {
let mut package = art();
package.insert(
CHARACTER_MANIFEST_FILE.to_string(),
Expand Down Expand Up @@ -1459,6 +1463,33 @@ mod tests {
);
}

/// Possessed art is optional and outside the Required Animation Set
/// (ADR-0007). A package without it shows the moment in its `react`.
#[test]
fn possessed_is_optional_and_falls_back_to_react() {
let character = load_manifest(&declaring(&REQUIRED_ANIMATIONS)).expect("loads");
assert_eq!(
character
.draw("possessed", 0, 0, 1.0)
.expect("draws")
.animation,
"react"
);

let manifest = format!(
"{}[animations.possessed]\nframes = [\"idle-0.png\"]\n",
declaring(&REQUIRED_ANIMATIONS)
);
let character = load_manifest(&manifest).expect("loads");
assert_eq!(
character
.draw("possessed", 0, 0, 1.0)
.expect("draws")
.animation,
"possessed"
);
}

/// Art is authored facing right and leftward travel mirrors it, which puts
/// Buddy Bot's cheek LED on the wrong cheek. A left strip is drawn as
/// authored instead.
Expand Down
57 changes: 54 additions & 3 deletions crates/core/src/engine.rs
Original file line number Diff line number Diff line change
Expand Up @@ -764,12 +764,17 @@ impl Engine {

/// Hand the sprite to the keyboard, or give it back. Either way the walk
/// under way ends, chosen or from the keys, or it would stride on with no arrow
/// held. The keys own the feet from the next tick.
/// held. The keys own the feet from the next tick, and possession start
/// plays `possessed`.
pub fn set_possessed(&mut self, possessed: bool) {
let starting = possessed && !self.possessed;
self.possessed = possessed;
if matches!(self.on_screen(), Some(Primitive::Walk | Primitive::Chase)) {
self.stop_playing();
}
if starting {
self.play(&[Primitive::Possessed]);
}
// Walk velocity outlives what set it, a Primitive or a held arrow.
if self.is_walking() || self.steering {
self.velocity.x = 0.0;
Expand Down Expand Up @@ -1831,7 +1836,7 @@ impl Engine {
fn permitted(&self, primitives: &[Primitive]) -> bool {
let on_feet = matches!(self.state, State::Grounded | State::Perched);
primitives.iter().all(|primitive| match primitive {
Primitive::React | Primitive::Talk => true,
Primitive::React | Primitive::Talk | Primitive::Possessed => true,
Primitive::Walk | Primitive::Chase => {
on_feet && self.poke_cooldown_ms == 0 && !self.feet_held
}
Expand Down Expand Up @@ -1881,6 +1886,8 @@ fn animation_of(primitive: Primitive) -> &'static str {
// Optional art: the renderer resolves it to `fall` when a package
// draws none, so the required set stays at nine (ADR-0007).
Primitive::Jump => "jump",
// Optional art too, resolved to `react` when a package draws none.
Primitive::Possessed => "possessed",
}
}

Expand Down Expand Up @@ -9698,7 +9705,11 @@ mod tests {
..world.clone()
});
assert_eq!(frame.behavior, None, "{frame:?}");
assert_eq!(frame.playing_primitive, None, "{frame:?}");
assert_eq!(
frame.playing_primitive,
Some(Primitive::Possessed),
"the start's own moment, not the walk: {frame:?}"
);
assert_eq!(frame.dialogue.as_deref(), Some("hands off the wheel"));
assert_eq!(engine.tick(&world).velocity.x, 0.0, "no walk follows");
}
Expand Down Expand Up @@ -9767,6 +9778,46 @@ mod tests {
}
}

/// Possession start plays `possessed`, which a package without that art
/// draws as its `react`. Only the start plays it, not a repeat or the end.
#[test]
fn possession_start_plays_possessed_art_or_react() {
use crate::character::tests::{declaring, load_manifest};
use crate::character::REQUIRED_ANIMATIONS;

let without = load_manifest(&declaring(&REQUIRED_ANIMATIONS)).expect("loads");
let with = load_manifest(&format!(
"{}[animations.possessed]\nframes = [\"idle-0.png\"]\n",
declaring(&REQUIRED_ANIMATIONS)
))
.expect("loads");

let world = on(one_display());
let mut engine = possessed_at(500.0, &world);
let started = engine.tick(&world);
assert_eq!(started.animation, "possessed", "{started:?}");
let drawn = |character: &crate::character::Character| {
character
.draw(started.animation, started.animation_ms, 0, 1.0)
.expect("draws")
.animation
.to_string()
};
assert_eq!(drawn(&with), "possessed");
assert_eq!(drawn(&without), "react");

for _ in 0..60 {
engine.tick(&world);
}
engine.set_possessed(true);
let again = engine.tick(&world);
assert_ne!(again.animation, "possessed", "already possessed: {again:?}");

engine.set_possessed(false);
let released = engine.tick(&world);
assert_ne!(released.animation, "possessed", "{released:?}");
}

#[test]
fn ending_the_possession_hands_the_sprite_back() {
let world = on(one_display());
Expand Down
3 changes: 2 additions & 1 deletion docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -250,13 +250,14 @@ A Character Manifest is at most 1 MiB. A package is at most 64 MiB, 4096 files,

#### Animations

Every Character supplies these nine: `idle`, `walk`, `fall`, `land`, `sit`, `sleep`, `react`, `talk`, and `hold`. The Engine also asks for three optional ones, and draws a stand-in when a package omits them:
Every Character supplies these nine: `idle`, `walk`, `fall`, `land`, `sit`, `sleep`, `react`, `talk`, and `hold`. The Engine also asks for four optional ones, and draws a stand-in when a package omits them:

| Animation | Plays when | Without it |
|---|---|---|
| `grab` | The user drags the sprite | `fall` |
| `climb` | The sprite climbs | `walk` |
| `jump` | A Behavior plays the `jump` Primitive | `fall` |
| `possessed` | The user possesses the fidget | `react` |

Any other name draws only as a Variant or a Left Strip of one of these.

Expand Down
3 changes: 2 additions & 1 deletion docs/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,8 @@ the offending declaration.
Required Animation Set is exactly nine: `idle`, `walk`, `fall`, `land`, `sit`, `sleep`,
`react`, `talk`, `hold`. A declared optional set is used when present and silently absent
otherwise: `climb` falls back to `walk`, and `grab` — the sprite held by the cursor — and
`jump` both fall back to `fall`.
`jump` both fall back to `fall`. `possessed`, played when Possession starts, falls back
to `react`.

A Personality Prompt influences Director output only. It cannot reference Primitives that
do not exist, cannot enable capabilities, and is never forwarded to the Harness as
Expand Down
Loading