Struct BattlerState 

pub struct BattlerState<P: BattleProvider + ?Sized> {
    pub species: P::Species,
    pub hp: u16,
    pub max_hp: u16,
    pub level: u8,
    pub stats: EnumMap<P::Stat, u16>,
    pub stat_stages: EnumMap<P::Stat, i8>,
    pub status: Option<P::Status>,
    pub moves: Vec<P::Move>,
    pub resources: ResourcePool,
}

The battle state of a single monster/character.

Tracks HP, stats, stat-stage modifiers, status condition, and known moves. Generic over the BattleProvider that supplies the concrete type identifiers.

Fields

species: P::Species

Species of this monster.

hp: u16

Current hit points.

max_hp: u16

Maximum hit points.

level: u8

The battler’s level. Defaults to 50 in new (set it via with_level or the field directly). The engine never interprets it; a provider’s damage/effect logic reads it as needed (e.g. the level term in a damage formula). Additive — existing callers that ignore it keep the prior fixed-50 behaviour.

stats: EnumMap<P::Stat, u16>

Base stat values, keyed by stat ID.

stat_stages: EnumMap<P::Stat, i8>

Stat-stage modifiers (-6 to +6), keyed by stat ID.

status: Option<P::Status>

Current status condition, if any.

moves: Vec<P::Move>

Known moves.

resources: ResourcePool

Generic, game-defined consumable resources (MP / SP / mana / charge — doc 13 §4). Defaults to EMPTY, so a battler that declares no resource behaves exactly as before. Keyed by an opaque game-assigned u16 id; the engine never interprets a resource’s meaning (it is not “MP” to the engine). See ResourcePool.

Implementations

impl<P: BattleProvider + ?Sized> BattlerState<P>

pub fn new( species: P::Species, hp: u16, max_hp: u16, stats: EnumMap<P::Stat, u16>, moves: Vec<P::Move>, ) -> Self

Create a new battler state.

Examples found in repository

examples/hello_dotzuki.rs (line 256)

    fn create_monster(&self, species: Species, level: u8) -> BattlerState<Self> {
        let (hp, atk, def, spd, moves) = match species {
            Species::Warrior => (100u16, 15u16, 10u16, 8u16, vec![MoveKind::Slash]),
            Species::Mage => (80u16, 20u16, 5u16, 12u16, vec![MoveKind::Fireball]),
        };
        let mut stats = EnumMap::new();
        stats.set(StatId::HP, hp);
        stats.set(StatId::ATK, atk);
        stats.set(StatId::DEF, def);
        stats.set(StatId::SPD, spd + level as u16);
        BattlerState::new(species, hp, hp, stats, moves)
    }

pub fn with_level(self, level: u8) -> Self

Builder: set the battler’s level.

pub fn take_damage(&mut self, amount: u16)

Apply damage, clamping HP to zero (never negative).

Examples found in repository

examples/hello_dotzuki.rs (line 230)

    fn apply_move_effect(
        &self,
        effect: MoveEffect,
        user: &mut BattlerState<Self>,
        target: &mut BattlerState<Self>,
    ) -> EffectResult {
        match effect {
            MoveEffect::Damage => {
                let mv = user.moves.first().cloned().unwrap_or(MoveKind::Slash);
                let result = self.calculate_damage(&mv, user, target, 100, false);
                target.take_damage(result.damage);
                EffectResult::DamageDealt {
                    amount: result.damage,
                }
            }
            MoveEffect::Heal => {
                let amount = target.max_hp / 4;
                target.heal(amount);
                EffectResult::Healed { amount }
            }
            MoveEffect::StatusCondition => EffectResult::StatusInflicted,
            MoveEffect::StatChange => EffectResult::StatModified { stages: 1 },
            _ => EffectResult::NoEffect,
        }
    }

    fn create_monster(&self, species: Species, level: u8) -> BattlerState<Self> {
        let (hp, atk, def, spd, moves) = match species {
            Species::Warrior => (100u16, 15u16, 10u16, 8u16, vec![MoveKind::Slash]),
            Species::Mage => (80u16, 20u16, 5u16, 12u16, vec![MoveKind::Fireball]),
        };
        let mut stats = EnumMap::new();
        stats.set(StatId::HP, hp);
        stats.set(StatId::ATK, atk);
        stats.set(StatId::DEF, def);
        stats.set(StatId::SPD, spd + level as u16);
        BattlerState::new(species, hp, hp, stats, moves)
    }
}

// ── BattleAI ───────────────────────────────────────────────────────

impl BattleAI<HelloConfig> for HelloConfig {
    fn select_move(
        &self,
        battler: &BattlerState<HelloConfig>,
        _state: &BattleState<HelloConfig>,
    ) -> MoveKind {
        battler.moves.first().cloned().unwrap_or(MoveKind::Slash)
    }
    fn should_switch(&self, _battler: &BattlerState<HelloConfig>) -> bool {
        false
    }
    fn should_use_item(&self, _battler: &BattlerState<HelloConfig>) -> Option<ItemKind> {
        None
    }
}

// ── EffectHandler ──────────────────────────────────────────────────

impl EffectHandler<HelloConfig> for HelloConfig {
    fn handle_effect(
        &self,
        effect: MoveEffect,
        user: &mut BattlerState<HelloConfig>,
        target: &mut BattlerState<HelloConfig>,
        _provider: &HelloConfig,
    ) -> EffectResult {
        // Delegate to the BattleProvider impl.
        self.apply_move_effect(effect, user, target)
    }
}

// ── ItemProvider ──────────────────────────────────────────────────

impl ItemProvider for HelloConfig {
    type Item = ItemKind;
    type Effect = ItemEffect;
    type Monster = MonsterData;
    type CustomKind = ();

    fn item_name(&self, item: &ItemKind) -> &str {
        match item {
            ItemKind::Potion => "Potion",
            ItemKind::Elixir => "Elixir",
        }
    }
    fn item_description(&self, item: &ItemKind) -> &str {
        match item {
            ItemKind::Potion => "Restores 20 HP.",
            ItemKind::Elixir => "Cures status.",
        }
    }
    fn item_effect(&self, item: &ItemKind) -> ItemEffect {
        match item {
            ItemKind::Potion => ItemEffect::Heal(20),
            ItemKind::Elixir => ItemEffect::CureStatus,
        }
    }
    fn item_price(&self, item: &ItemKind) -> u32 {
        match item {
            ItemKind::Potion => 100,
            ItemKind::Elixir => 300,
        }
    }
    fn can_use_outside_battle(&self, _item: &ItemKind) -> bool {
        true
    }
    fn can_use_in_battle(&self, _item: &ItemKind) -> bool {
        true
    }
    fn use_on_monster(&self, item: &ItemKind, monster: &mut MonsterData) -> ItemResult {
        match self.item_effect(item) {
            ItemEffect::Heal(amount) => {
                if monster.current_hp >= monster.max_hp {
                    return ItemResult::NoEffect;
                }
                monster.current_hp = (monster.current_hp + amount).min(monster.max_hp);
                ItemResult::Used
            }
            ItemEffect::CureStatus => ItemResult::Used,
            ItemEffect::None => ItemResult::NoEffect,
        }
    }
    fn consume(&self, _item: &ItemKind) -> bool {
        true
    }
    fn item_kind(&self, item: &ItemKind) -> dotzuki_engine::items::ItemKind<()> {
        let _ = item;
        dotzuki_engine::items::ItemKind::Consumable
    }
}

// ── ShopProvider ───────────────────────────────────────────────────

impl ShopProvider for HelloConfig {
    type Item = ItemKind;
    type ShopId = ();
    fn shop_inventory(&self, _shop_id: &()) -> Vec<(ItemKind, u32)> {
        vec![(ItemKind::Potion, 100), (ItemKind::Elixir, 300)]
    }
    fn shop_name(&self, _shop_id: &()) -> &str {
        "Town Shop"
    }
}

// ── TextProvider — ASCII charmap ──────────────────────────────────

impl TextProvider for HelloConfig {
    type Char = AsciiChar;

    fn decode_byte(&self, byte: u8) -> Option<AsciiChar> {
        match byte {
            0xFE => Some(AsciiChar::Newline),
            0xFF => Some(AsciiChar::Done),
            0xFD => Some(AsciiChar::WaitInput),
            b @ 0x20..=0x7E => Some(AsciiChar::Char(b as char)),
            _ => None,
        }
    }
    fn render_char(&self, c: &AsciiChar, buffer: &mut TileBuffer) {
        if let AsciiChar::Char(ch) = c {
            let pos = buffer.cursor;
            buffer.set_tile(pos, *ch as u16, 0);
            buffer.cursor.x += 1;
        }
    }
    fn string_width(&self, text: &[AsciiChar]) -> u16 {
        text.iter()
            .filter(|c| matches!(c, AsciiChar::Char(_)))
            .count() as u16
            * 8
    }
    fn is_control_code(&self, c: &AsciiChar) -> bool {
        !matches!(c, AsciiChar::Char(_))
    }
    fn process_control(&self, c: &AsciiChar, _state: &mut DialogState) -> ControlAction {
        match c {
            AsciiChar::Newline => ControlAction::Newline,
            AsciiChar::Done => ControlAction::Done,
            AsciiChar::WaitInput => ControlAction::WaitInput,
            _ => ControlAction::None,
        }
    }
}

impl MenuProvider for HelloConfig {
    type MenuId = MenuScreen;

    fn title(&self, _menu: MenuScreen) -> &str {
        "Hello JRPG"
    }
    fn options(&self, _menu: MenuScreen) -> &[MenuOption] {
        &self.main_menu_options
    }
    fn option_count(&self, _menu: MenuScreen) -> u8 {
        self.main_menu_options.len() as u8
    }
    fn scrollable(&self, _menu: MenuScreen) -> bool {
        false
    }
    fn layout(&self, _menu: MenuScreen) -> MenuLayout {
        MenuLayout::new(5, 5, 10, 8)
    }
}

// ── SaveData — binary format: [1B name_len][0..32B name][1B level] ─

#[derive(Debug, Clone, PartialEq, Eq)]
struct GameSave {
    player_name: String,
    player_level: u8,
}

impl SaveData for GameSave {
    fn serialize(&self) -> Vec<u8> {
        let name = self.player_name.as_bytes();
        let len = name.len().min(32);
        let mut v = Vec::with_capacity(1 + len + 1);
        v.push(len as u8);
        v.extend_from_slice(&name[..len]);
        v.push(self.player_level);
        v
    }
    fn deserialize(data: &[u8]) -> Result<Self, SaveError> {
        if data.len() < 2 {
            return Err(SaveError::InvalidData);
        }
        let name_len = data[0] as usize;
        if data.len() < 1 + name_len + 1 {
            return Err(SaveError::InvalidData);
        }
        let name = String::from_utf8(data[1..1 + name_len].to_vec())
            .map_err(|_| SaveError::InvalidData)?;
        let level = data[1 + name_len];
        Ok(GameSave {
            player_name: name,
            player_level: level,
        })
    }
    fn save_size() -> usize {
        35
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// Overworld collision — simple provider: only tile 0xFF is a wall
// ═══════════════════════════════════════════════════════════════════════════

struct SimpleCollision;

impl CollisionProvider<Tileset> for SimpleCollision {
    fn is_tile_passable(&self, _tileset: Tileset, tile_id: u8) -> bool {
        tile_id != 0xFF
    }
    fn check_tile_pair_collision(&self, _t: Tileset, _a: u8, _b: u8, _w: bool) -> bool {
        false
    }
    fn check_ledge_jump(&self, _t: Tileset, _f: u8, _s: u8, _tg: u8, _i: u8) -> bool {
        false
    }
    fn is_counter_tile(&self, _t: Tileset, _id: u8) -> bool {
        false
    }
    fn get_tile_at_position(&self, _t: Tileset, blk: &[u8], w: u8, x: u16, y: u16) -> u8 {
        blk.get((y as usize * w as usize + x as usize).min(blk.len().saturating_sub(1)))
            .copied()
            .unwrap_or(0)
    }
    fn is_door_tile(&self, _t: Tileset, _id: u8) -> bool {
        false
    }
    fn is_warp_tile(&self, _t: Tileset, _id: u8) -> bool {
        false
    }
    fn is_warp_carpet_tile_in_front(&self, _t: Tileset, _f: u8, _id: u8) -> bool {
        false
    }
    fn uses_warp_tile_in_front_check(&self, _t: Tileset) -> bool {
        false
    }
    fn check_extra_warp_special(&self, _t: Tileset, _id: u8) -> Option<bool> {
        None
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// Map builder — 5×5 town with walls, floor, NPC
// ═══════════════════════════════════════════════════════════════════════════
//  Layout:  # = wall (0xFF), . = floor (0x01), N=NPC, P=player start
//  #####
//  #...#
//  #.N.#
//  #.P.#
//  #####

fn build_town_map() -> MapData<MapId, Tileset, ()> {
    let blocks: Vec<u8> = vec![
        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x01, 0x01, 0x01, 0xFF, 0xFF, 0x01, 0x01, 0x01, 0xFF,
        0xFF, 0x01, 0x01, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
    ];
    let npcs = vec![NpcDefinition::new(
        0,
        2,
        2,
        NpcMovementType::Stationary,
        Direction::Down,
        0,
        0,
    )];
    MapData::new(
        MapId(0),
        5,
        5,
        Tileset(0),
        (),
        blocks,
        vec![],
        npcs,
        vec![],
        MapConnections::default(),
    )
}

/// Build NPC runtime states from the map's NPC definitions.
fn build_npc_states(npcs: &[NpcDefinition]) -> Vec<NpcRuntimeState> {
    npcs.iter()
        .enumerate()
        .map(|(i, def)| {
            let s = NpcRuntimeState {
                npc_index: i as u8,
                sprite_id: def.sprite_id,
                x: def.x as u16,
                y: def.y as u16,
                home_x: def.x as u16,
                home_y: def.y as u16,
                facing: def.facing,
                scripted_frame: None,
                movement_type: def.movement,
                range: def.range,
                walk_counter: 0,
                delay_counter: 0,
                text_id: def.text_id,
                defeated: false,
                visible: true,
                scripted_path: std::collections::VecDeque::new(),
                wander_axis: dotzuki_engine::overworld::NpcWanderAxis::Any,
            };
            s
        })
        .collect()
}

/// Print the map as ASCII with player position.
fn show_map(blocks: &[u8], _w: u8, px: u16, py: u16, npcs: &[NpcRuntimeState]) {
    for y in 0..5u16 {
        print!("  ");
        for x in 0..5u16 {
            let idx = (y * 5 + x) as usize;
            if px == x && py == y {
                print!("P");
            } else if npcs.iter().any(|n| n.x == x && n.y == y) {
                print!("N");
            } else if idx < blocks.len() && blocks[idx] == 0xFF {
                print!("#");
            } else {
                print!(".");
            }
        }
        println!();
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// Demo functions
// ═══════════════════════════════════════════════════════════════════════════

fn demo_overworld() {
    println!("\n╔══ OVERWORLD MOVEMENT ═══════════════════╗");
    let map = build_town_map();
    let mut state = OverworldState::new(MapId(0));
    let collision = SimpleCollision;
    let npcs = build_npc_states(&map.npcs);
    let npc_positions = dotzuki_engine::overworld::get_npc_positions(&npcs);

    // Start at (3, 3) — bottom center
    state.player.x = 3;
    state.player.y = 3;
    println!("║ Initial map:");
    show_map(&map.blocks, 5, state.player.x, state.player.y, &npcs);

    // Move right → blocked by wall at (4, 3)
    let standing = collision.get_tile_at_position(Tileset(0), &map.blocks, 5, 3, 3);
    let target = collision.get_tile_at_position(Tileset(0), &map.blocks, 5, 4, 3);
    let result = try_move(
        &mut state,
        Direction::Right,
        Tileset(0),
        5,
        5,
        standing,
        target,
        &npc_positions,
        0,
        &collision,
    );
    println!("║ Move Right → {:?}", result);

    // Move up to (3, 2) — floor is passable
    let standing = collision.get_tile_at_position(Tileset(0), &map.blocks, 5, 3, 3);
    let target = collision.get_tile_at_position(Tileset(0), &map.blocks, 5, 3, 2);
    let result = try_move(
        &mut state,
        Direction::Up,
        Tileset(0),
        5,
        5,
        standing,
        target,
        &npc_positions,
        0,
        &collision,
    );
    println!("║ Move Up   → {:?}", result);
    println!(
        "║ Player at ({}, {}), facing {:?}",
        state.player.x, state.player.y, state.player.facing
    );

    // Advance the walk step
    dotzuki_engine::overworld::advance_step(&mut state);
    dotzuki_engine::overworld::advance_step(&mut state);
    // ...walking finishes after WALK_COUNTER_INIT (8) frames
    for _ in 0..8 {
        dotzuki_engine::overworld::advance_step(&mut state);
    }
    println!(
        "║ After walk: player at ({}, {})",
        state.player.x, state.player.y
    );

    // NPC interaction: check if NPC is nearby
    let interaction = dotzuki_engine::overworld::try_interact(
        &npcs,
        state.player.x,
        state.player.y,
        state.player.facing,
        Some(&map),
        &collision,
    );
    println!("║ Interact → {:?}", interaction);
    println!("╚══════════════════════════════════════════╝");
}

fn demo_dialog() {
    println!("\n╔══ NPC DIALOG ═══════════════════════════╗");
    let provider = HelloConfig::new();
    let mut engine = DialogEngine::new(provider);
    let mut buffer = TileBuffer::new(20, 18);

    // "Greetings, young hero!" + DONE
    let text: &[u8] = b"Greetings, young hero!";
    let mut full = text.to_vec();
    full.push(0xFF); // DONE

    engine.open_dialog(&full);
    while engine.is_active() {
        engine.update(&mut buffer);
    }

    print!("║ Merlin: \"");
    for i in 0..20usize {
        let t = buffer.tiles[i].tile_id;
        if (0x20..=0x7E).contains(&t) {
            print!("{}", t as u8 as char);
        }
    }
    println!("\"");
    println!("╚══════════════════════════════════════════╝");
}

fn demo_battle() {
    println!("\n╔══ BATTLE ENCOUNTER ═════════════════════╗");
    let provider = HelloConfig::new();
    let warrior = provider.create_monster(Species::Warrior, 5);
    let mage = provider.create_monster(Species::Mage, 5);

    println!(
        "║ {} (HP:{}/{}) vs {} (HP:{}/{})",
        warrior.species.name(),
        warrior.hp,
        warrior.max_hp,
        mage.species.name(),
        mage.hp,
        mage.max_hp
    );

    // Warrior attacks with Slash → super effective (2×) vs Mage
    let result = provider.calculate_damage(&MoveKind::Slash, &warrior, &mage, 100, false);
    println!(
        "║ {} uses Slash! {} damage ({}x effective)",
        warrior.species.name(),
        result.damage,
        result.effectiveness
    );

    let mut enemy = mage.clone();
    enemy.take_damage(result.damage);
    println!("║ {} HP: {} → {}", mage.species.name(), mage.hp, enemy.hp);

    // Mage attacks with Fireball → not very effective (0.5×) vs Warrior
    let result = provider.calculate_damage(&MoveKind::Fireball, &mage, &warrior, 100, false);
    println!(
        "║ {} uses Fireball! {} damage ({}x effective)",
        mage.species.name(),
        result.damage,
        result.effectiveness
    );

    let mut hero = warrior.clone();
    hero.take_damage(result.damage);
    println!(
        "║ {} HP: {} → {}",
        warrior.species.name(),
        warrior.hp,
        hero.hp
    );

    // EffectHandler
    let mut user = warrior.clone();
    let mut target = mage.clone();
    let eff_result = HelloConfig::new().handle_effect(
        MoveEffect::Damage,
        &mut user,
        &mut target,
        &HelloConfig::new(),
    );
    println!("║ EffectHandler(Damage) → {:?}", eff_result);

    // BattleAI
    let state = BattleState::new(vec![warrior.clone()], vec![mage.clone()]);
    let ai_move = BattleAI::select_move(&HelloConfig::default(), &warrior, &state);
    println!("║ BattleAI chose: {}", ai_move.name());
    println!("╚══════════════════════════════════════════╝");
}

pub fn heal(&mut self, amount: u16)

Heal HP, clamping to max_hp.

Examples found in repository

examples/hello_dotzuki.rs (line 237)

    fn apply_move_effect(
        &self,
        effect: MoveEffect,
        user: &mut BattlerState<Self>,
        target: &mut BattlerState<Self>,
    ) -> EffectResult {
        match effect {
            MoveEffect::Damage => {
                let mv = user.moves.first().cloned().unwrap_or(MoveKind::Slash);
                let result = self.calculate_damage(&mv, user, target, 100, false);
                target.take_damage(result.damage);
                EffectResult::DamageDealt {
                    amount: result.damage,
                }
            }
            MoveEffect::Heal => {
                let amount = target.max_hp / 4;
                target.heal(amount);
                EffectResult::Healed { amount }
            }
            MoveEffect::StatusCondition => EffectResult::StatusInflicted,
            MoveEffect::StatChange => EffectResult::StatModified { stages: 1 },
            _ => EffectResult::NoEffect,
        }
    }

pub fn with_resource(self, id: u16, max: u16) -> Self

Builder: declare a generic resource (id, current = max) on this battler. Returns self so it chains after new without changing the constructor’s signature (the additivity invariant).

pub fn can_pay_resource(&self, id: u16, amount: u16) -> bool

Whether this battler can pay amount of resource id (delegates to ResourcePool::can_pay). A 0 cost is always payable; a positive cost on an undeclared resource is not. Pure — consumes no randomness.

pub fn pay_resource(&mut self, id: u16, amount: u16) -> bool

Deduct amount of resource id (saturating). Pure arithmetic — no rng.

Trait Implementations

impl<P: BattleProvider + ?Sized> Clone for BattlerState<P>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<P: BattleProvider + ?Sized> Debug for BattlerState<P>

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

Formats the value using the given formatter.