Struct Battle 

pub struct Battle { /* private fields */ }

A live battle: the player’s party (the active member fights) against one enemy, the item inventory, the type chart, and the phase machine. Drive with update + draw; outcome reports the end (the runner then resumes the suspended scene with "win"/"lose" and harvests the party state).

Implementations

impl Battle

pub fn new( player: Combatant, enemy: Combatant, chart: TypeChart, rng: Box<dyn BattleRng>, ) -> Self

A 1v1 battle between two already-built combatants (no RON hooks, no items — the unit-test shape).

pub fn with_hooks( player: Combatant, enemy: Combatant, chart: TypeChart, rng: Box<dyn BattleRng>, hooks: Option<HookState>, ) -> Self

A battle between two already-built combatants, with the RON hook state when the project compiled one.

pub fn full( party: Vec<Combatant>, active: usize, enemy: Combatant, items: Vec<BattleItem>, inventory: HashMap<String, u32>, chart: TypeChart, rng: Box<dyn BattleRng>, hooks: Option<HookState>, ) -> Self

The full constructor: the party + its active member, the enemy, the usable items and the inventory counts.

pub fn set_levels(&mut self, levels: Option<LevelsSetup>)

Arm the levels config (v2-c; BattleSetup::start_with calls this).

pub fn set_lang(&mut self, lang: &str)

Set the narration language ("en"/"zh") for the EXP/level-up lines; the runner passes its --lang here.

pub fn set_currency(&mut self, currency: &str)

Set the currency label for the trainer-money narration (the runner’s shop.currency); default “G”.

pub fn set_enemy_party( &mut self, rest: Vec<Combatant>, trainer: bool, money: u32, )

Arm the enemy party extras (v2-d): the enemies queued behind the active one plus the trainer flag and the win’s money reward (BattleSetup::start_with calls this; the plain constructors leave a single wild enemy).

pub fn set_weather(&mut self, weather: Option<String>)

Arm the battle-local weather (v2-e): a kind: Weather RON record id, None to clear. The runner sets this from a scene’s setWeather / clearWeather before the battle begins; it is never saved and dies with the battle.

pub fn weather(&self) -> Option<&str>

The armed weather record id, if any (tests, introspection).

pub fn begin(&mut self)

Battle-start hook pass (v2-e): narrate the armed weather’s intro, then fire both active combatants’ ability SwitchIn hooks (player first). Any produced lines queue as the battle’s opening narration; with nothing to say the battle opens on the root menu exactly as v1. The runner calls this once per battle, after [set_weather]; the plain constructors leave it to tests. No-op without hooks or once the battle is already decided.

pub fn player(&self) -> &Combatant

The active player combatant.

Examples found in repository

examples/encounter_accept.rs (line 158)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn party(&self) -> &[Combatant]

The whole party (index 0 fights unless switched).

Examples found in repository

examples/levels_accept.rs (line 129)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: levels_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let save_file = Path::new(&dir).join(".dotzuki-save.json");
    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            write_saves: true,
            save_file: Some(save_file.clone()),
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // Auto-A drives everything: dialogue pages, battle narration, and the
    // Fight → first-skill picks. Back-to-back `startBattle` commands swap
    // Battle→Battle INSIDE one update, so a new battle is detected by the
    // log resetting, not just by a not-in-battle gap.
    let mut battle_no = 0usize;
    let mut completed = 0usize;
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle = false;
    let mut snapped_battle = false;

    for frame_no in 0..6000u32 {
        if frame_no % 4 == 0 {
            frame(&mut game, GbButton::A.bit_mask());
        } else {
            idle(&mut game, 1);
        }

        let in_battle = game.battle().is_some();
        if in_battle {
            let log_len = game.battle().unwrap().log().len();
            let new_battle = !was_in_battle || log_len < last_log.len();
            if new_battle {
                if was_in_battle {
                    // Seamless Battle→Battle swap: close the previous one
                    // out (the party state is already harvested).
                    completed += 1;
                    println!("\nbattle {completed} log:");
                    for line in &last_log {
                        println!("  {line}");
                    }
                    print_party(&game, &format!("after battle {completed}"));
                    println!();
                    if completed == 2 {
                        break;
                    }
                }
                battle_no += 1;
                let battle = game.battle().unwrap();
                println!("battle {battle_no} starts:");
                for c in battle.party() {
                    println!(
                        "  {} level {} exp {} hp {}/{} mp {}/{} atk {}",
                        c.name, c.level, c.exp, c.hp, c.max_hp, c.mp, c.max_mp, c.attack
                    );
                }
                if battle_no == 2 && !snapped_battle {
                    snapped_battle = true;
                    snap(&mut game, &shot_dir, "battle2-start");
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        } else if was_in_battle {
            completed += 1;
            println!("\nbattle {completed} log:");
            for line in &last_log {
                println!("  {line}");
            }
            print_party(&game, &format!("after battle {completed}"));
            println!();
            last_log.clear();
            if completed == 2 {
                break;
            }
        }
        was_in_battle = in_battle;
    }
    if completed < 2 {
        eprintln!("harness: only {completed} battle(s) completed within the frame cap");
        std::process::exit(1);
    }

    // Dismiss the post-battle text so the scene finishes (the save is
    // written at that stable point).
    for _ in 0..40 {
        if game.dialogue_text().is_none() {
            break;
        }
        press_a(&mut game);
    }
    assert!(game.flag("SLIMES_BEATEN"), "the scene ran to its end");

    // The Party view: Lv + EXP progress on the member rows.
    frame(&mut game, GbButton::Start.bit_mask());
    idle(&mut game, 1);
    press_a(&mut game); // Party
    println!("party view:");
    for line in game.menu_lines().expect("party view open") {
        println!("  {line}");
    }
    snap(&mut game, &shot_dir, "party-view");
    frame(&mut game, GbButton::B.bit_mask());
    idle(&mut game, 1);
    frame(&mut game, GbButton::B.bit_mask());
    idle(&mut game, 1);

    // Save round trip: a fresh boot resumes level/exp from the save.
    println!("\nsave round trip ({}):", save_file.display());
    let project = LoadedProject::load(Path::new(&dir)).expect("reload project");
    let game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            save_file: Some(save_file),
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot from save");
    print_party(&game, "resumed from the save");
    assert!(
        game.party_state().is_some_and(|p| p[0].level > 1),
        "level must survive the save round trip"
    );
    println!("\nacceptance OK");
}

examples/battle_accept.rs (line 142)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: battle_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // The agenda per battle (index = battles started so far − 1).
    let agendas: &[&[Pick]] = &[&[Pick::Item, Pick::Party, Pick::Fight], &[Pick::Fight]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = Vec::new();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut snapped: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let items = battle.menu_items();
                    let label = if items.first().is_some_and(|i| i == "Fight") {
                        "root"
                    } else if items.iter().any(|i| i.contains('/')) {
                        "party"
                    } else {
                        "sub"
                    };
                    if let Some(dir) = &shot_dir {
                        let tag = format!("battle{}-{label}", battles_done + 1);
                        if !snapped.contains(&tag) {
                            snapped.push(tag.clone());
                            snap(&mut game, &dir.join(format!("{tag}.png")));
                        }
                    }
                    mask = match label {
                        "root" => {
                            let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                            if !agenda.is_empty() {
                                agenda.remove(0);
                            }
                            match pick {
                                Pick::Fight => GbButton::A.bit_mask(),
                                Pick::Party => {
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                                Pick::Item => {
                                    keys.push(GbButton::Down);
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                            }
                        }
                        // Submenus: confirm the entry under the cursor (the
                        // party cursor starts on the first switchable member).
                        _ => GbButton::A.bit_mask(),
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the party it starts with (the carried-over
        // state from battle 2 on) and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!("battle {n} starts:");
            for c in battle.party() {
                let status = c.status.as_deref().unwrap_or("-");
                println!(
                    "  {} {}/{} MP {}/{} status {}",
                    c.name, c.hp, c.max_hp, c.mp, c.max_mp, status
                );
            }
            println!("  inventory: {:?}", battle.inventory());
            agenda = agendas[battles_done].to_vec();
        }
        if in_battle {
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the party state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if let Some(party) = game.party_state() {
                println!("party state after battle {battles_done}:");
                for m in party {
                    println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
                }
            }
            if let Some(inv) = game.inventory() {
                println!("inventory: {inv:?}");
            }
            println!();
            last_log.clear();
            if battles_done == 2 {
                println!("both battles done — stopping");
                break;
            }
        }
        was_in_battle_prev = in_battle;
    }

    if battles_done < 2 {
        eprintln!("harness: only {battles_done} battle(s) completed within the frame cap");
        std::process::exit(1);
    }
}

pub fn active_index(&self) -> usize

The active member’s index in party.

pub fn enemy(&self) -> &Combatant

The enemy combatant.

Examples found in repository

examples/encounter_accept.rs (line 159)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn enemies_remaining(&self) -> usize

How many enemies still wait behind the active one (v2-d encounters).

Examples found in repository

examples/encounter_accept.rs (line 160)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn is_trainer(&self) -> bool

Whether this is a trainer battle (Run is blocked).

Examples found in repository

examples/encounter_accept.rs (line 161)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn trainer_money(&self) -> u32

The money the runner pays the player on a win (0 for wild battles).

Examples found in repository

examples/encounter_accept.rs (line 162)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn outcome(&self) -> Option<BattleOutcome>

The result, once the battle has ended (set when the last narration line is dismissed).

pub fn log(&self) -> &[String]

The full narration history.

Examples found in repository

examples/menu_accept.rs (line 135)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: menu_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    dismiss(&mut game); // StartTown main
    println!("== 1. the shop ==");
    println!("money at boot: {} (manifest shop.startMoney)", game.money());

    // Talk to the Shopkeeper at (13,10): the shop opens on the spot.
    game.debug_place(12, 10, Direction::Right);
    press_a(&mut game);
    let rows = game.shop_lines().expect("shop open");
    println!("shop shelf: {rows:?}");
    snap(&mut game, &shot_dir, "shop");

    // Buy one Potion: 100 → 80 G, inventory 3 → 4.
    let before = game.money();
    press_a(&mut game);
    let rows = game.shop_lines().expect("shop still open");
    println!(
        "bought a Potion: money {before} → {} G; inventory {:?}",
        game.money(),
        game.inventory().expect("inventory materialized")
    );
    println!("shop note: {:?}", rows.last());
    snap(&mut game, &shot_dir, "shop-bought");
    assert_eq!(game.money(), 80, "20 G charged");
    assert_eq!(game.inventory().unwrap().get("potion"), Some(&4));
    press_a(&mut game); // dismiss the note

    // B exits; the scene resumes with its follow-up line.
    press(&mut game, GbButton::B);
    let page = game.dialogue_text().expect("scene resumed after the shop");
    println!("scene resumed with: {page:?}");
    assert!(page.contains("Come again!"), "page: {page:?}");
    dismiss(&mut game);

    println!("\n== 2. the whiteout ==");
    // Talk to the Hermit at (11,10) and lose on purpose (overwhelming Slime).
    game.debug_place(12, 10, Direction::Left);
    press_a(&mut game); // "Something stirs…"
    press_a(&mut game); // → battle
    let mut last_log: Vec<String> = Vec::new();
    for _ in 0..120 {
        let Some(battle) = game.battle() else { break };
        last_log = battle.log().to_vec();
        press_a(&mut game);
    }
    println!("lost battle log:");
    for line in &last_log {
        println!("  {line}");
    }
    assert_eq!(last_log.last().map(String::as_str), Some("You lost the battle…"));

    // The scene's post-lose text still plays…
    let page = game.dialogue_text().expect("post-lose text");
    println!("post-lose text: {page:?}");
    assert!(page.contains("no match"), "page: {page:?}");
    press_a(&mut game); // scene finishes → whiteout

    // …then the whiteout: blackout first, then the collapsed line.
    assert!(game.whiteout_active(), "whiteout armed");
    idle(&mut game, 10);
    snap(&mut game, &shot_dir, "whiteout-blackout");
    idle(&mut game, 25);
    let page = game.dialogue_text().expect("whiteout message");
    println!("whiteout message: {page:?}");
    assert!(page.contains("collapsed"), "page: {page:?}");
    snap(&mut game, &shot_dir, "whiteout-message");

    // Landing it: party healed to full, back at the entry spawn, flags kept.
    press_a(&mut game);
    assert!(!game.whiteout_active());
    println!("after the whiteout:");
    println!("  map: {:?} tile: {:?}", game.current_map_id(), game.player_tile());
    for m in game.party_state().expect("party state") {
        println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
    }
    println!("  __played_main_StartTown flag kept: {}", game.flag("__played_main_StartTown"));
    assert_eq!(game.current_map_id(), Some("StartTown"));
    assert!(game
        .party_state()
        .unwrap()
        .iter()
        .all(|m| m.hp > 0 && m.status.is_none()));
    snap(&mut game, &shot_dir, "whiteout-after");

    println!("\nacceptance OK");
}

examples/levels_accept.rs (line 109)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: levels_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let save_file = Path::new(&dir).join(".dotzuki-save.json");
    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            write_saves: true,
            save_file: Some(save_file.clone()),
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // Auto-A drives everything: dialogue pages, battle narration, and the
    // Fight → first-skill picks. Back-to-back `startBattle` commands swap
    // Battle→Battle INSIDE one update, so a new battle is detected by the
    // log resetting, not just by a not-in-battle gap.
    let mut battle_no = 0usize;
    let mut completed = 0usize;
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle = false;
    let mut snapped_battle = false;

    for frame_no in 0..6000u32 {
        if frame_no % 4 == 0 {
            frame(&mut game, GbButton::A.bit_mask());
        } else {
            idle(&mut game, 1);
        }

        let in_battle = game.battle().is_some();
        if in_battle {
            let log_len = game.battle().unwrap().log().len();
            let new_battle = !was_in_battle || log_len < last_log.len();
            if new_battle {
                if was_in_battle {
                    // Seamless Battle→Battle swap: close the previous one
                    // out (the party state is already harvested).
                    completed += 1;
                    println!("\nbattle {completed} log:");
                    for line in &last_log {
                        println!("  {line}");
                    }
                    print_party(&game, &format!("after battle {completed}"));
                    println!();
                    if completed == 2 {
                        break;
                    }
                }
                battle_no += 1;
                let battle = game.battle().unwrap();
                println!("battle {battle_no} starts:");
                for c in battle.party() {
                    println!(
                        "  {} level {} exp {} hp {}/{} mp {}/{} atk {}",
                        c.name, c.level, c.exp, c.hp, c.max_hp, c.mp, c.max_mp, c.attack
                    );
                }
                if battle_no == 2 && !snapped_battle {
                    snapped_battle = true;
                    snap(&mut game, &shot_dir, "battle2-start");
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        } else if was_in_battle {
            completed += 1;
            println!("\nbattle {completed} log:");
            for line in &last_log {
                println!("  {line}");
            }
            print_party(&game, &format!("after battle {completed}"));
            println!();
            last_log.clear();
            if completed == 2 {
                break;
            }
        }
        was_in_battle = in_battle;
    }
    if completed < 2 {
        eprintln!("harness: only {completed} battle(s) completed within the frame cap");
        std::process::exit(1);
    }

    // Dismiss the post-battle text so the scene finishes (the save is
    // written at that stable point).
    for _ in 0..40 {
        if game.dialogue_text().is_none() {
            break;
        }
        press_a(&mut game);
    }
    assert!(game.flag("SLIMES_BEATEN"), "the scene ran to its end");

    // The Party view: Lv + EXP progress on the member rows.
    frame(&mut game, GbButton::Start.bit_mask());
    idle(&mut game, 1);
    press_a(&mut game); // Party
    println!("party view:");
    for line in game.menu_lines().expect("party view open") {
        println!("  {line}");
    }
    snap(&mut game, &shot_dir, "party-view");
    frame(&mut game, GbButton::B.bit_mask());
    idle(&mut game, 1);
    frame(&mut game, GbButton::B.bit_mask());
    idle(&mut game, 1);

    // Save round trip: a fresh boot resumes level/exp from the save.
    println!("\nsave round trip ({}):", save_file.display());
    let project = LoadedProject::load(Path::new(&dir)).expect("reload project");
    let game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            save_file: Some(save_file),
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot from save");
    print_party(&game, "resumed from the save");
    assert!(
        game.party_state().is_some_and(|p| p[0].level > 1),
        "level must survive the save round trip"
    );
    println!("\nacceptance OK");
}

examples/battle_accept.rs (line 153)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: battle_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // The agenda per battle (index = battles started so far − 1).
    let agendas: &[&[Pick]] = &[&[Pick::Item, Pick::Party, Pick::Fight], &[Pick::Fight]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = Vec::new();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut snapped: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let items = battle.menu_items();
                    let label = if items.first().is_some_and(|i| i == "Fight") {
                        "root"
                    } else if items.iter().any(|i| i.contains('/')) {
                        "party"
                    } else {
                        "sub"
                    };
                    if let Some(dir) = &shot_dir {
                        let tag = format!("battle{}-{label}", battles_done + 1);
                        if !snapped.contains(&tag) {
                            snapped.push(tag.clone());
                            snap(&mut game, &dir.join(format!("{tag}.png")));
                        }
                    }
                    mask = match label {
                        "root" => {
                            let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                            if !agenda.is_empty() {
                                agenda.remove(0);
                            }
                            match pick {
                                Pick::Fight => GbButton::A.bit_mask(),
                                Pick::Party => {
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                                Pick::Item => {
                                    keys.push(GbButton::Down);
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                            }
                        }
                        // Submenus: confirm the entry under the cursor (the
                        // party cursor starts on the first switchable member).
                        _ => GbButton::A.bit_mask(),
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the party it starts with (the carried-over
        // state from battle 2 on) and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!("battle {n} starts:");
            for c in battle.party() {
                let status = c.status.as_deref().unwrap_or("-");
                println!(
                    "  {} {}/{} MP {}/{} status {}",
                    c.name, c.hp, c.max_hp, c.mp, c.max_mp, status
                );
            }
            println!("  inventory: {:?}", battle.inventory());
            agenda = agendas[battles_done].to_vec();
        }
        if in_battle {
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the party state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if let Some(party) = game.party_state() {
                println!("party state after battle {battles_done}:");
                for m in party {
                    println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
                }
            }
            if let Some(inv) = game.inventory() {
                println!("inventory: {inv:?}");
            }
            println!();
            last_log.clear();
            if battles_done == 2 {
                println!("both battles done — stopping");
                break;
            }
        }
        was_in_battle_prev = in_battle;
    }

    if battles_done < 2 {
        eprintln!("harness: only {battles_done} battle(s) completed within the frame cap");
        std::process::exit(1);
    }
}

examples/encounter_accept.rs (line 192)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn hooks(&self) -> Option<&HookState>

The RON hook state, when this battle compiled one (tests, debug).

pub fn inventory(&self) -> &HashMap<String, u32>

The live inventory (record id → count).

Examples found in repository

examples/battle_accept.rs (line 149)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: battle_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // The agenda per battle (index = battles started so far − 1).
    let agendas: &[&[Pick]] = &[&[Pick::Item, Pick::Party, Pick::Fight], &[Pick::Fight]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = Vec::new();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut snapped: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let items = battle.menu_items();
                    let label = if items.first().is_some_and(|i| i == "Fight") {
                        "root"
                    } else if items.iter().any(|i| i.contains('/')) {
                        "party"
                    } else {
                        "sub"
                    };
                    if let Some(dir) = &shot_dir {
                        let tag = format!("battle{}-{label}", battles_done + 1);
                        if !snapped.contains(&tag) {
                            snapped.push(tag.clone());
                            snap(&mut game, &dir.join(format!("{tag}.png")));
                        }
                    }
                    mask = match label {
                        "root" => {
                            let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                            if !agenda.is_empty() {
                                agenda.remove(0);
                            }
                            match pick {
                                Pick::Fight => GbButton::A.bit_mask(),
                                Pick::Party => {
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                                Pick::Item => {
                                    keys.push(GbButton::Down);
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                            }
                        }
                        // Submenus: confirm the entry under the cursor (the
                        // party cursor starts on the first switchable member).
                        _ => GbButton::A.bit_mask(),
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the party it starts with (the carried-over
        // state from battle 2 on) and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!("battle {n} starts:");
            for c in battle.party() {
                let status = c.status.as_deref().unwrap_or("-");
                println!(
                    "  {} {}/{} MP {}/{} status {}",
                    c.name, c.hp, c.max_hp, c.mp, c.max_mp, status
                );
            }
            println!("  inventory: {:?}", battle.inventory());
            agenda = agendas[battles_done].to_vec();
        }
        if in_battle {
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the party state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if let Some(party) = game.party_state() {
                println!("party state after battle {battles_done}:");
                for m in party {
                    println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
                }
            }
            if let Some(inv) = game.inventory() {
                println!("inventory: {inv:?}");
            }
            println!();
            last_log.clear();
            if battles_done == 2 {
                println!("both battles done — stopping");
                break;
            }
        }
        was_in_battle_prev = in_battle;
    }

    if battles_done < 2 {
        eprintln!("harness: only {battles_done} battle(s) completed within the frame cap");
        std::process::exit(1);
    }
}

pub fn party_state(&self) -> Vec<PartyMemberState>

The persistent party state (v2-b) for the runner to keep between battles: every member’s current HP/MP and status — plus level/exp (v2-c).

pub fn in_menu(&self) -> bool

true while a player menu owns input.

Examples found in repository

examples/battle_accept.rs (line 85)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: battle_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // The agenda per battle (index = battles started so far − 1).
    let agendas: &[&[Pick]] = &[&[Pick::Item, Pick::Party, Pick::Fight], &[Pick::Fight]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = Vec::new();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut snapped: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let items = battle.menu_items();
                    let label = if items.first().is_some_and(|i| i == "Fight") {
                        "root"
                    } else if items.iter().any(|i| i.contains('/')) {
                        "party"
                    } else {
                        "sub"
                    };
                    if let Some(dir) = &shot_dir {
                        let tag = format!("battle{}-{label}", battles_done + 1);
                        if !snapped.contains(&tag) {
                            snapped.push(tag.clone());
                            snap(&mut game, &dir.join(format!("{tag}.png")));
                        }
                    }
                    mask = match label {
                        "root" => {
                            let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                            if !agenda.is_empty() {
                                agenda.remove(0);
                            }
                            match pick {
                                Pick::Fight => GbButton::A.bit_mask(),
                                Pick::Party => {
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                                Pick::Item => {
                                    keys.push(GbButton::Down);
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                            }
                        }
                        // Submenus: confirm the entry under the cursor (the
                        // party cursor starts on the first switchable member).
                        _ => GbButton::A.bit_mask(),
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the party it starts with (the carried-over
        // state from battle 2 on) and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!("battle {n} starts:");
            for c in battle.party() {
                let status = c.status.as_deref().unwrap_or("-");
                println!(
                    "  {} {}/{} MP {}/{} status {}",
                    c.name, c.hp, c.max_hp, c.mp, c.max_mp, status
                );
            }
            println!("  inventory: {:?}", battle.inventory());
            agenda = agendas[battles_done].to_vec();
        }
        if in_battle {
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the party state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if let Some(party) = game.party_state() {
                println!("party state after battle {battles_done}:");
                for m in party {
                    println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
                }
            }
            if let Some(inv) = game.inventory() {
                println!("inventory: {inv:?}");
            }
            println!();
            last_log.clear();
            if battles_done == 2 {
                println!("both battles done — stopping");
                break;
            }
        }
        was_in_battle_prev = in_battle;
    }

    if battles_done < 2 {
        eprintln!("harness: only {battles_done} battle(s) completed within the frame cap");
        std::process::exit(1);
    }
}

examples/encounter_accept.rs (line 97)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn current_line(&self) -> Option<&str>

The narration line currently on screen.

Examples found in repository

examples/encounter_accept.rs (line 174)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn menu_items(&self) -> Vec<String>

The current menu’s labels (marked × entries are unselectable).

Examples found in repository

examples/battle_accept.rs (line 86)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args.next().expect("usage: battle_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");

    // The agenda per battle (index = battles started so far − 1).
    let agendas: &[&[Pick]] = &[&[Pick::Item, Pick::Party, Pick::Fight], &[Pick::Fight]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = Vec::new();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut snapped: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let items = battle.menu_items();
                    let label = if items.first().is_some_and(|i| i == "Fight") {
                        "root"
                    } else if items.iter().any(|i| i.contains('/')) {
                        "party"
                    } else {
                        "sub"
                    };
                    if let Some(dir) = &shot_dir {
                        let tag = format!("battle{}-{label}", battles_done + 1);
                        if !snapped.contains(&tag) {
                            snapped.push(tag.clone());
                            snap(&mut game, &dir.join(format!("{tag}.png")));
                        }
                    }
                    mask = match label {
                        "root" => {
                            let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                            if !agenda.is_empty() {
                                agenda.remove(0);
                            }
                            match pick {
                                Pick::Fight => GbButton::A.bit_mask(),
                                Pick::Party => {
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                                Pick::Item => {
                                    keys.push(GbButton::Down);
                                    keys.push(GbButton::A);
                                    GbButton::Down.bit_mask()
                                }
                            }
                        }
                        // Submenus: confirm the entry under the cursor (the
                        // party cursor starts on the first switchable member).
                        _ => GbButton::A.bit_mask(),
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the party it starts with (the carried-over
        // state from battle 2 on) and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!("battle {n} starts:");
            for c in battle.party() {
                let status = c.status.as_deref().unwrap_or("-");
                println!(
                    "  {} {}/{} MP {}/{} status {}",
                    c.name, c.hp, c.max_hp, c.mp, c.max_mp, status
                );
            }
            println!("  inventory: {:?}", battle.inventory());
            agenda = agendas[battles_done].to_vec();
        }
        if in_battle {
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the party state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if let Some(party) = game.party_state() {
                println!("party state after battle {battles_done}:");
                for m in party {
                    println!("  {} hp {} mp {} status {:?}", m.id, m.hp, m.mp, m.status);
                }
            }
            if let Some(inv) = game.inventory() {
                println!("inventory: {inv:?}");
            }
            println!();
            last_log.clear();
            if battles_done == 2 {
                println!("both battles done — stopping");
                break;
            }
        }
        was_in_battle_prev = in_battle;
    }

    if battles_done < 2 {
        eprintln!("harness: only {battles_done} battle(s) completed within the frame cap");
        std::process::exit(1);
    }
}

examples/encounter_accept.rs (line 98)

fn main() {
    let mut args = std::env::args().skip(1);
    let dir = args
        .next()
        .expect("usage: encounter_accept <project-dir> [shot-dir]");
    let shot_dir = args.next().map(PathBuf::from);

    let project = LoadedProject::load(Path::new(&dir)).expect("load project");
    let mut game = RunnerGame::new(
        project,
        RunnerOptions {
            headless: true,
            fresh: true,
            // Deterministic battles: always hit, 89% variance, never crit.
            rng_script: Some(vec![50, 100, 1]),
            ..RunnerOptions::default()
        },
    )
    .expect("boot game");
    println!("money at boot: {}", game.money());

    // The agenda per battle (index = battles started so far − 1): the
    // trainer battle tries Run first (blocked), the wild battle runs.
    // Battle 1's agenda is pre-armed: the entry scene suspends on
    // `startBattle` during boot, so its first menu frame precedes the
    // battle-start edge below (later battles arm on their edge — text plays
    // between them).
    let agendas: &[&[Pick]] = &[&[Pick::Run, Pick::Fight], &[Pick::Run]];
    let mut battles_done = 0usize;
    let mut agenda: Vec<Pick> = agendas[0].to_vec();
    // Queued button presses; one key every other frame (a held key is not a
    // fresh just-press, so keys alternate with idle frames).
    let mut keys: Vec<GbButton> = Vec::new();
    let mut last_log: Vec<String> = Vec::new();
    let mut was_in_battle_prev = false;
    let mut snapped: Vec<String> = Vec::new();
    // Shop agenda: 0 = root (→ Sell), 1 = sell view (→ sell one), 2 = note
    // (→ dismiss), 3 = back to root (→ B), 4 = exit (→ B), 5 = done.
    let mut shop_step = 0usize;
    let mut shop_done = false;

    let mut input = InputState::new();
    for frame in 0..6000u32 {
        let was_in_battle = was_in_battle_prev;

        // Decide this frame's input.
        let mut mask = 0;
        if frame % 2 == 0 {
            if !keys.is_empty() {
                mask = keys.remove(0).bit_mask();
            } else if let Some(battle) = game.battle() {
                if battle.in_menu() {
                    let is_root = battle.menu_items().first().is_some_and(|i| i == "Fight");
                    mask = if is_root {
                        let pick = agenda.first().copied().unwrap_or(Pick::Fight);
                        if !agenda.is_empty() {
                            agenda.remove(0);
                        }
                        match pick {
                            Pick::Fight => GbButton::A.bit_mask(),
                            Pick::Run => {
                                // Fight/Party/Item/Run → Down ×3, confirm.
                                keys.push(GbButton::Down);
                                keys.push(GbButton::Down);
                                keys.push(GbButton::A);
                                GbButton::Down.bit_mask()
                            }
                        }
                    } else {
                        GbButton::A.bit_mask() // skill submenu
                    };
                } else if frame % 4 == 0 {
                    mask = GbButton::A.bit_mask(); // page narration
                }
            } else if game.shop_lines().is_some() && battles_done == 2 && !shop_done {
                match shop_step {
                    0 => {
                        println!("shop root: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::Down); // → Sell
                        keys.push(GbButton::A);
                    }
                    1 => {
                        println!("sell view: {:?}", game.shop_lines().unwrap());
                        keys.push(GbButton::A); // sell one Potion
                    }
                    2 => {
                        let lines = game.shop_lines().unwrap();
                        println!("sell note: {lines:?}");
                        if let Some(dir) = &shot_dir {
                            snap(&mut game, &dir.join("shop-sold.png"));
                        }
                        keys.push(GbButton::A); // dismiss the note
                    }
                    3 => keys.push(GbButton::B), // back to the root
                    _ => keys.push(GbButton::B), // exit the shop
                }
                shop_step += 1;
            } else if frame % 4 == 0 {
                mask = GbButton::A.bit_mask(); // page dialogue
            }
        }
        input.set_from_bitmask(mask);
        game.update(&input);
        input.begin_frame();

        let in_battle = game.battle().is_some();
        // Battle-start edge: print the matchup and load its agenda.
        if in_battle && !was_in_battle {
            let n = battles_done + 1;
            let battle = game.battle().unwrap();
            println!(
                "battle {n} starts: {} vs {} (queued {}, trainer {}, reward {})",
                battle.player().name,
                battle.enemy().name,
                battle.enemies_remaining(),
                battle.is_trainer(),
                battle.trainer_money(),
            );
            if battles_done > 0 {
                agenda = agendas[battles_done].to_vec();
            }
        }
        if in_battle {
            // Screenshot the two v2-d narration lines on their first show.
            // Screenshot the two v2-d narration lines on their first show.
            let line = game
                .battle()
                .unwrap()
                .current_line()
                .map(str::to_string);
            if let (Some(dir), Some(line)) = (&shot_dir, line) {
                let tag = match line.as_str() {
                    l if l.starts_with("Can't escape") => Some("run-blocked"),
                    l if l.starts_with("Got away") => Some("run-safe"),
                    l if l.starts_with("Got ") && l.ends_with("for winning!") => {
                        Some("trainer-money")
                    }
                    _ => None,
                };
                if let Some(tag) = tag {
                    if !snapped.contains(&tag.to_string()) {
                        snapped.push(tag.to_string());
                        snap(&mut game, &dir.join(format!("{tag}.png")));
                    }
                }
            }
            last_log = game.battle().unwrap().log().to_vec();
        }
        // Battle-end edge: the runner has harvested the state.
        if was_in_battle && !in_battle {
            battles_done += 1;
            println!("\nbattle {battles_done} log:");
            for line in &last_log {
                println!("  {line}");
            }
            if battles_done == 1 {
                assert!(
                    last_log
                        .iter()
                        .any(|l| l == "Can't escape from a trainer battle!"),
                    "the trainer Run attempt must be blocked (and the turn not consumed)"
                );
            }
            println!("money after battle {battles_done}: {}", game.money());
            if let Some(party) = game.party_state() {
                for m in party {
                    println!(
                        "  {} hp {} mp {} level {} exp {}",
                        m.id, m.hp, m.mp, m.level, m.exp
                    );
                }
            }
            println!();
            last_log.clear();
        }
        // Shop-exit edge.
        if shop_step >= 5 && game.shop_lines().is_none() && !shop_done {
            shop_done = true;
            println!("shop closed: money {}, inventory {:?}", game.money(), game.inventory());
        }
        // Everything done: both battles + the shop, scene finished.
        if battles_done == 2 && shop_done && game.battle().is_none() {
            println!("acceptance complete");
            break;
        }
        was_in_battle_prev = in_battle;
    }

    // Verify the v2-d contract points and exit non-zero on any miss.
    let money = game.money();
    let potions = game.inventory().and_then(|inv| inv.get("potion").copied());
    println!("final: money {money}, potions {potions:?}");
    assert_eq!(battles_done, 2, "both battles must complete");
    assert!(shop_done, "the shop sell must complete");
    assert_eq!(money, 142, "100 start + 32 trainer + 10 sell (20/2)");
    assert_eq!(potions, Some(2), "3 starting − 1 sold");
}

pub fn update(&mut self, input: &InputState)

Advance the battle one frame: menu cursor / confirm / cancel, or narration paging. Sets outcome when the battle resolves.

pub fn draw(&self, fb: &mut FrameBuffer)

Draw the battle screen: a two-tone field with placeholder combatant blobs, an enemy panel (name, element, HP bar) up top, a player panel (name, HP bar, MP) below, and the current menu or narration line at the bottom.