feat: module 02 action queue

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

course/02-action-queue/reference/rust/src/engine/world.rs

@@ -0,0 +1,252 @@
+//! Entities, zones, order of play, stats and the event log: the game's state.
+//! The rules for resolving actions live in `queue.rs`.
+
+use super::card::{CardDef, CardLibrary};
+use super::event::Event;
+
+/// A handle to an entity. Ids are never reused and stay valid when the entity changes zone.
+pub type EntityId = u32;
+pub type PlayerId = u8;
+
+/// Starting Health of each hero.
+pub const HERO_HEALTH: i32 = 30;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Zone {
+    Deck,
+    Hand,
+    Board,
+    Graveyard,
+}
+
+#[derive(Debug)]
+struct Entity {
+    card: String,
+    owner: PlayerId,
+    zone: Zone,
+    /// Stamped each time the entity enters the board; `None` until it first does.
+    order_of_play: Option<u32>,
+    attack: i32,
+    /// Current Health. It can drop to 0 or below: Module 2 has no death step.
+    health: i32,
+}
+
+/// One player's zones. Each is an ordered list of ids (the board is left to right).
+#[derive(Debug, Default)]
+struct Side {
+    deck: Vec<EntityId>,
+    hand: Vec<EntityId>,
+    board: Vec<EntityId>,
+    graveyard: Vec<EntityId>,
+    hero: EntityId,
+    armor: i32,
+}
+
+impl Side {
+    fn zone(&self, zone: Zone) -> &Vec<EntityId> {
+        match zone {
+            Zone::Deck => &self.deck,
+            Zone::Hand => &self.hand,
+            Zone::Board => &self.board,
+            Zone::Graveyard => &self.graveyard,
+        }
+    }
+
+    fn zone_mut(&mut self, zone: Zone) -> &mut Vec<EntityId> {
+        match zone {
+            Zone::Deck => &mut self.deck,
+            Zone::Hand => &mut self.hand,
+            Zone::Board => &mut self.board,
+            Zone::Graveyard => &mut self.graveyard,
+        }
+    }
+}
+
+pub struct World {
+    library: CardLibrary,
+    /// Indexed by `EntityId`.
+    entities: Vec<Entity>,
+    sides: [Side; 2],
+    next_order_of_play: u32,
+    log: Vec<Event>,
+}
+
+impl World {
+    /// A new game: both heroes are in play from the start, so they are the oldest entities.
+    pub fn new(library: CardLibrary) -> World {
+        let mut world = World {
+            library,
+            entities: Vec::new(),
+            sides: Default::default(),
+            next_order_of_play: 0,
+            log: Vec::new(),
+        };
+        for owner in 0..2 {
+            let id = world.entities.len() as EntityId;
+            world.next_order_of_play += 1;
+            world.entities.push(Entity {
+                card: "Hero".to_string(),
+                owner,
+                zone: Zone::Board,
+                order_of_play: Some(world.next_order_of_play),
+                attack: 0,
+                health: HERO_HEALTH,
+            });
+            // In play, but not on the board list: the board holds minions only.
+            world.sides[owner as usize].hero = id;
+        }
+        world
+    }
+
+    /// Create an entity of `card` for `owner` at the end of `zone` (the right end for the board).
+    pub fn create(&mut self, card: &str, owner: PlayerId, zone: Zone) -> EntityId {
+        assert!(owner < 2, "no player {owner}");
+        let def = self.library.get(card);
+        let entity = Entity {
+            card: def.name.clone(),
+            owner,
+            zone,
+            order_of_play: None,
+            attack: def.attack,
+            health: def.health,
+        };
+        let id = self.entities.len() as EntityId;
+        self.entities.push(entity);
+        self.enter(id, zone);
+        id
+    }
+
+    /// Move an entity to the end of `zone` on its owner's side, keeping its id.
+    pub fn move_to(&mut self, id: EntityId, zone: Zone) {
+        let (owner, from) = (self.entity(id).owner, self.entity(id).zone);
+        self.sides[owner as usize]
+            .zone_mut(from)
+            .retain(|&e| e != id);
+        self.enter(id, zone);
+    }
+
+    /// The single place an entity arrives in a zone. Entering the board starts a new order of play.
+    fn enter(&mut self, id: EntityId, zone: Zone) {
+        let owner = self.entity(id).owner;
+        self.sides[owner as usize].zone_mut(zone).push(id);
+        let entity = &mut self.entities[id as usize];
+        entity.zone = zone;
+        if zone == Zone::Board {
+            self.next_order_of_play += 1;
+            entity.order_of_play = Some(self.next_order_of_play);
+            self.record(Event::Summoned { id });
+        }
+    }
+
+    fn entity(&self, id: EntityId) -> &Entity {
+        self.entities
+            .get(id as usize)
+            .unwrap_or_else(|| panic!("unknown entity id {id}"))
+    }
+
+    fn entity_mut(&mut self, id: EntityId) -> &mut Entity {
+        self.entities
+            .get_mut(id as usize)
+            .unwrap_or_else(|| panic!("unknown entity id {id}"))
+    }
+
+    // ---- Queries -------------------------------------------------------
+
+    pub fn card(&self, name: &str) -> &CardDef {
+        self.library.get(name)
+    }
+
+    pub fn zone_of(&self, id: EntityId) -> Zone {
+        self.entity(id).zone
+    }
+
+    pub fn card_name(&self, id: EntityId) -> &str {
+        &self.entity(id).card
+    }
+
+    pub fn owner_of(&self, id: EntityId) -> PlayerId {
+        self.entity(id).owner
+    }
+
+    /// When the entity last entered the board (larger is later); `None` if it never has.
+    pub fn order_of_play(&self, id: EntityId) -> Option<u32> {
+        self.entity(id).order_of_play
+    }
+
+    /// The ids in one player's zone, in zone order (left to right for the board).
+    pub fn zone(&self, owner: PlayerId, zone: Zone) -> &[EntityId] {
+        assert!(owner < 2, "no player {owner}");
+        self.sides[owner as usize].zone(zone)
+    }
+
+    pub fn hero(&self, owner: PlayerId) -> EntityId {
+        assert!(owner < 2, "no player {owner}");
+        self.sides[owner as usize].hero
+    }
+
+    pub fn is_hero(&self, id: EntityId) -> bool {
+        self.sides.iter().any(|s| s.hero == id)
+    }
+
+    /// Every minion on either board, oldest first (order of play).
+    pub fn minions_in_play(&self) -> Vec<EntityId> {
+        let mut ids: Vec<EntityId> = self.sides.iter().flat_map(|s| s.board.clone()).collect();
+        ids.sort_by_key(|&id| self.order_of_play(id));
+        ids
+    }
+
+    pub fn attack(&self, id: EntityId) -> i32 {
+        self.entity(id).attack
+    }
+
+    pub fn health(&self, id: EntityId) -> i32 {
+        self.entity(id).health
+    }
+
+    pub fn armor(&self, owner: PlayerId) -> i32 {
+        self.sides[owner as usize].armor
+    }
+
+    pub fn log(&self) -> &[Event] {
+        &self.log
+    }
+
+    // ---- Changes: each one records its event ----------------------------
+
+    pub fn record(&mut self, event: Event) {
+        self.log.push(event);
+    }
+
+    pub fn clear_log(&mut self) {
+        self.log.clear();
+    }
+
+    pub fn damage(&mut self, target: EntityId, amount: i32) {
+        self.entity_mut(target).health -= amount;
+        self.record(Event::Damaged { target, amount });
+    }
+
+    /// Draw the top card of `player`'s deck (the first in the list). An empty deck
+    /// records `Fatigue` and changes nothing else.
+    pub fn draw(&mut self, player: PlayerId) {
+        match self.zone(player, Zone::Deck).first() {
+            Some(&id) => {
+                self.move_to(id, Zone::Hand);
+                self.record(Event::Drew { player, id });
+            }
+            None => self.record(Event::Fatigue { player }),
+        }
+    }
+
+    pub fn gain_armor(&mut self, player: PlayerId, amount: i32) {
+        self.sides[player as usize].armor += amount;
+        self.record(Event::ArmorGained { player, amount });
+    }
+
+    pub fn gain_attack(&mut self, id: EntityId, amount: i32) {
+        let entity = self.entity_mut(id);
+        entity.attack += amount;
+        let (attack, health) = (entity.attack, entity.health);
+        self.record(Event::StatsChanged { id, attack, health });
+    }
+}