Struct LoadedProject 

pub struct LoadedProject { /* private fields */ }

A fully loaded zero-Rust game project.

Implementations

impl LoadedProject

pub fn load(root: &Path) -> Result<Self>

Load the project rooted at root (the directory containing .dotzuki-editor.json) from disk. Convenience for load_with_files over a DiskFiles.

Errors

Fails on a missing/unparseable manifest or any DSL diagnostic.

Examples found in repository

examples/menu_accept.rs (line 83)

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 79)

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,
            external_saves: false,
            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 53)

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 53)

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 load_with_files(files: Arc<dyn ProjectFiles>) -> Result<Self>

Load the project from a ProjectFiles backend.

The DSL is compiled in memory; any compiler diagnostic (unreadable file, compile failure, route conflict) aborts the load with an error listing every diagnostic — the same bar dotzuki check enforces.

Errors

Fails on a missing/unparseable manifest or any DSL diagnostic.

pub fn recompile_scripts(&mut self) -> Result<()>

Recompile every DSL directory and swap the compiled scenes in place.

On success the script registry, routing table and stem indexes are replaced wholesale — a scene currently mid-activation keeps running the JS it was started with; the next activation picks up the new source. On any compiler diagnostic the old scenes are kept and an error listing every diagnostic is returned (same bar as load).

Errors

Fails when the recompile produces any diagnostic.

pub fn files(&self) -> &Arc<dyn ProjectFiles>

The project’s file backend.

pub fn root(&self) -> &Path

Project root directory (empty for a project without a disk root).

pub fn manifest(&self) -> &Manifest

The parsed .dotzuki-editor.json manifest.

pub fn data_root(&self) -> &Path

Resolved data root (manifest dataRoot against the project root).

pub fn data_root_rel(&self) -> &str

The data root as a project-relative POSIX path (VFS key prefix).

pub fn gfx_root(&self) -> Option<&Path>

Resolved graphics root (manifest gfxRoot), when configured.

pub fn gfx_root_rel(&self) -> String

The graphics root as a project-relative POSIX path (the manifest’s gfxRoot, default "gfx").

pub fn scripts(&self) -> &ScriptLoader

Registry of compiled scene JS, keyed by scene name.

pub fn report(&self) -> &CompileReport

The full DSL compile report.

pub fn routes(&self) -> &[RouteEntry]

Storyline routing table (map, npc/onEnter) → storyline, collected from @trigger declarations across all scenes.

pub fn scene_name_for_stem(&self, stem: &str) -> Option<&str>

Compiled scene name for a .scene file stem (e.g. "main" → "Main").

pub fn stem_for_scene_name(&self, name: &str) -> Option<&str>

.scene file stem for a compiled scene name.

pub fn maps_dir_rel(&self) -> String

The maps directory as a project-relative POSIX path: the map activity’s mapsDir (dataRoot-relative), default maps.

pub fn maps_dir(&self) -> PathBuf

Directory holding the per-map subdirectories (disk form of maps_dir_rel).

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

Sorted ids of all map directories under maps_dir.

pub fn entry_map(&self) -> Result<String>

Map to spawn on: game.entryMap, or the first map directory (sorted) under the maps dir.

Errors

Fails when no entryMap is configured and no map directories exist.

pub fn entry_scene_name(&self) -> Result<&str>

Scene to boot into: game.entryScene (a .scene file stem) resolved to its compiled scene name, or the first compiled scene sorted by source path.

Errors

Fails when entryScene names a stem that compiled to nothing, or when the project has no scenes at all.

pub fn load_map(&self, map_id: &str) -> Result<RuntimeMap>

Load a map by id from this project’s maps dir.

pub fn table_dir(&self, table_id: &str) -> Option<PathBuf>

Directory holding the records of data table table_id (a table id from the data activity’s config.tables[]), resolved against the project root. None when the id names no declared table.

pub fn table_dir_rel(&self, table_id: &str) -> Option<String>

The record directory of data table table_id as a project-relative POSIX path (the VFS form of table_dir). None when the id names no declared table.