lucasw89/systemic-game-design-course
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: module 03 death step

Browse Source 
Deferred death: damage and destroy only mark minions; the Death Creation
Step removes them when the outermost Phase ends, and Death Phases resolve
Deathrattles in order of play until no new deaths occur. Deathrattle
summons use the board position the Death Event remembered. Harness adds
destroy(target). Expansion Drop: Twisting Nether as content only.

test_02_mortally_wounded_still_triggers no longer asserts the Acolyte is
still on the board: from Module 3 on it leaves at the end of the Sequence,
and verify-references runs Module 2's tests against the Module 3 reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Lucas WintherandClaude Opus 5.5 committed 2026-10-29 02:42:12 +01:00
1 parent 9c50591d3b
commit 8a4eba1948
41 files changed
+4080 -5
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

course/03-death-step/reference/rust/src/engine/card.rs
+99
View File
@@ -0,0 +1,99 @@
//! Card definitions as the engine sees them. The definitions themselves live in `content`.
use std::collections::HashMap;
use super::queue::{Action, Ctx};
/// A card's behaviour: given where and for whom it runs, the actions to perform.
/// Module 2 writes these as Rust functions in `content`; Module 5 turns them into data.
pub type EffectFn = fn(&Ctx) -> Vec<Action>;
/// What a triggered ability listens for.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TriggerOn {
/// This minion takes damage.
SelfDamaged,
/// A minion with the same owner (this one included) takes damage.
FriendlyMinionDamaged,
/// Any minion takes damage.
AnyMinionDamaged,
/// Either hero takes damage.
HeroDamaged,
/// This minion dies. It resolves after the minion has left play.
Deathrattle,
}
impl TriggerOn {
/// The trigger's family name, as reported in `Triggered` events.
pub fn label(self) -> &'static str {
match self {
TriggerOn::SelfDamaged
| TriggerOn::FriendlyMinionDamaged
| TriggerOn::AnyMinionDamaged
| TriggerOn::HeroDamaged => "damaged",
TriggerOn::Deathrattle => "deathrattle",
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct Trigger {
pub on: TriggerOn,
pub effect: EffectFn,
}
/// What the engine needs to know about a card.
#[derive(Debug, Clone)]
pub struct CardDef {
pub name: String,
pub attack: i32,
pub health: i32,
/// Triggered abilities, in printed order.
pub triggers: Vec<Trigger>,
/// A spell's effect when cast; `None` for minions.
pub on_cast: Option<EffectFn>,
}
impl CardDef {
pub fn minion(name: &str, attack: i32, health: i32) -> CardDef {
CardDef {
name: name.to_string(),
attack,
health,
triggers: Vec::new(),
on_cast: None,
}
}
pub fn spell(name: &str, effect: EffectFn) -> CardDef {
CardDef {
on_cast: Some(effect),
..CardDef::minion(name, 0, 0)
}
}
/// Add a triggered ability: "Whenever <on>, <effect>".
pub fn on(mut self, on: TriggerOn, effect: EffectFn) -> CardDef {
self.triggers.push(Trigger { on, effect });
self
}
}
/// Every card the game can create, looked up by name.
#[derive(Debug, Default)]
pub struct CardLibrary {
cards: HashMap<String, CardDef>,
}
impl CardLibrary {
pub fn new(defs: Vec<CardDef>) -> CardLibrary {
let cards = defs.into_iter().map(|d| (d.name.clone(), d)).collect();
CardLibrary { cards }
}
pub fn get(&self, name: &str) -> &CardDef {
self.cards
.get(name)
.unwrap_or_else(|| panic!("unknown card {name:?}: define it in src/content"))
}
}
course/03-death-step/reference/rust/src/engine/death.rs
+30
View File
@@ -0,0 +1,30 @@
//! The Death Creation Step: the one place minions leave play.
//!
//! Damage and destroy effects only mark a minion (0 or less Health, or pending
//! destroy). It stays in play, and keeps triggering, until the outermost Phase
//! ends. Then this step removes every marked minion at once.
use super::event::Event;
use super::world::World;
/// Remove every mortally wounded or pending-destroy minion from play, simultaneously.
/// Returns their Death Events in order of play; empty if nothing died.
pub fn death_creation_step(world: &mut World) -> Vec<Event> {
// Every position is read before anything moves: removal is simultaneous, and each
// Death Event remembers where its minion stood when the step began.
let mut deaths = Vec::new();
for id in world.minions_in_play() {
if world.is_doomed(id) {
let position = world
.board_index(id)
.expect("a minion in play is on the board");
deaths.push(Event::Destroyed { id, position });
}
}
for death in &deaths {
if let Event::Destroyed { id, position } = *death {
world.kill(id, position);
}
}
deaths
}
course/03-death-step/reference/rust/src/engine/event.rs
+47
View File
@@ -0,0 +1,47 @@
//! What happened, in order. The engine records an event each time it changes the game.
use super::card::TriggerOn;
use super::world::{EntityId, PlayerId};
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Event {
Summoned {
id: EntityId,
},
Damaged {
target: EntityId,
amount: i32,
},
Triggered {
source: EntityId,
on: TriggerOn,
},
Drew {
player: PlayerId,
id: EntityId,
},
Fatigue {
player: PlayerId,
},
ArmorGained {
player: PlayerId,
amount: i32,
},
StatsChanged {
id: EntityId,
attack: i32,
health: i32,
},
SpellCast {
card: String,
},
/// A Death Event: the Death Creation Step moved `id` from play to the graveyard.
/// `position` is the board index it had when the step began; its Deathrattle summons there.
Destroyed {
id: EntityId,
position: usize,
},
DeathPhase {
round: u32,
},
}
course/03-death-step/reference/rust/src/engine/mod.rs
+23
View File
@@ -0,0 +1,23 @@
//! Engine core: generic rules machinery. Never name a specific card here.
//!
//! Module 1: every card in the game is an entity addressed by an id handle.
//! The engine knows which zone each entity is in, who owns it, and when it
//! entered play.
//!
//! Module 2: heroes, Health, Attack and Armor; triggered abilities; and the
//! action queue that resolves a Sequence depth-first, recording an event log.
//!
//! Module 3: deferred death. Damage and destroy effects only mark minions; the
//! Death Creation Step removes them when the outermost Phase ends, and Death
//! Phases resolve their Deathrattles until no new deaths occur.
mod card;
mod death;
mod event;
mod queue;
mod world;
pub use card::{CardDef, CardLibrary, EffectFn, Trigger, TriggerOn};
pub use event::Event;
pub use queue::{run_sequence, Action, Ctx};
pub use world::{EntityId, PlayerId, World, Zone, HERO_HEALTH};
course/03-death-step/reference/rust/src/engine/queue.rs
+217
View File
@@ -0,0 +1,217 @@
//! The action queue: how one player action (a Sequence) resolves.
//!
//! Performing an action changes the world and produces events. Every trigger that
//! responds to those events goes into one Queue, oldest listener first, and the Queue
//! is locked. Each queued trigger then resolves completely, including everything
//! its own actions cause, before the next one starts: depth-first.
//!
//! Module 3: nothing leaves play mid-Sequence. When the outermost Phase ends, the
//! Death Creation Step removes the dead, and a Death Phase resolves their
//! Deathrattles. That repeats until a step finds no new deaths.
use super::card::TriggerOn;
use super::death::death_creation_step;
use super::event::Event;
use super::world::{EntityId, PlayerId, World, Zone};
/// Something the engine can do. Card effects return these instead of changing the world.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Action {
/// Deal `amount` to each target at once: all damage first, then the reactions.
Damage {
targets: Vec<EntityId>,
amount: i32,
},
Draw {
player: PlayerId,
},
GainArmor {
player: PlayerId,
amount: i32,
},
GainAttack {
id: EntityId,
amount: i32,
},
Cast {
card: String,
player: PlayerId,
target: Option<EntityId>,
},
/// Mark each target pending destroy. They leave play in the next Death Creation Step.
Destroy {
targets: Vec<EntityId>,
},
/// Summon `card` for `player` at board index `at`, or at the right end if `at` is `None`.
Summon {
card: String,
player: PlayerId,
at: Option<usize>,
},
}
/// What an effect may look at when it runs.
pub struct Ctx<'a> {
pub world: &'a World,
/// The player the effect works for.
pub owner: PlayerId,
/// The minion whose trigger is resolving; `None` for a spell.
pub source: Option<EntityId>,
/// The chosen target, if any.
pub target: Option<EntityId>,
/// The source's board position. For a Deathrattle, the source has left play,
/// and this is the position its Death Event remembered.
pub position: Option<usize>,
}
impl Ctx<'_> {
/// The minion whose trigger is resolving.
pub fn minion(&self) -> EntityId {
self.source.expect("only a triggered ability has a source")
}
pub fn enemy_hero(&self) -> EntityId {
self.world.hero(1 - self.owner)
}
}
/// Run one Sequence: a player action and everything it causes.
pub fn run_sequence(world: &mut World, action: Action) {
perform(world, action);
// The outermost Phase has ended. Each Death Phase is itself an outermost
// Phase, so the end-of-Phase steps run again after it, until nothing dies.
let mut deaths = end_of_outermost_phase(world);
let mut round = 0;
while !deaths.is_empty() {
round += 1;
world.record(Event::DeathPhase { round });
react(world, &deaths);
deaths = end_of_outermost_phase(world);
}
}
/// The steps that run only when the outermost Phase ends; returns the Death Events.
/// Module 4 adds an Aura Update (Health/Attack) before the Death Creation Step
/// and an Aura Update (Other) after it, here.
fn end_of_outermost_phase(world: &mut World) -> Vec<Event> {
death_creation_step(world)
}
fn perform(world: &mut World, action: Action) {
match action {
Action::Damage {
mut targets,
amount,
} => {
// Area damage: every Damage Event is created, in order of play, before any reaction.
targets.sort_by_key(|&id| world.order_of_play(id));
let mut events = Vec::new();
for target in targets {
world.damage(target, amount);
events.push(Event::Damaged { target, amount });
}
react(world, &events);
}
Action::Draw { player } => world.draw(player),
Action::GainArmor { player, amount } => world.gain_armor(player, amount),
Action::GainAttack { id, amount } => world.gain_attack(id, amount),
Action::Destroy { targets } => {
for target in targets {
world.mark_destroyed(target);
}
}
Action::Summon { card, player, at } => {
world.create_at(&card, player, Zone::Board, at);
}
Action::Cast {
card,
player,
target,
} => {
let effect = world
.card(&card)
.on_cast
.unwrap_or_else(|| panic!("{card:?} is not a spell"));
world.record(Event::SpellCast { card });
let actions = effect(&Ctx {
world,
owner: player,
source: None,
target,
position: None,
});
for action in actions {
perform(world, action);
}
}
}
}
/// A Phase: queue every trigger that responds to `events`, then resolve them one by one.
fn react(world: &mut World, events: &[Event]) {
// Fill the Queue: for each event (already in order of play), each listener in order of play.
let mut queue = Vec::new();
for event in events {
for listener in listeners(world, event) {
for trigger in &world.card(world.card_name(listener)).triggers {
if responds(world, trigger.on, listener, event) {
queue.push((listener, *trigger, event));
}
}
}
}
// The Queue is now locked: nothing that happens below adds to it.
for (source, trigger, event) in queue {
world.record(Event::Triggered {
source,
on: trigger.on,
});
let position = match *event {
Event::Destroyed { id, position } if id == source => Some(position),
_ => world.board_index(source),
};
let ctx = Ctx {
world,
owner: world.owner_of(source),
source: Some(source),
target: None,
position,
};
let actions = (trigger.effect)(&ctx);
// Depth-first: each action, and every reaction it causes, finishes before the next.
for action in actions {
perform(world, action);
}
}
}
/// Who may respond to `event`, in order of play: every minion in play and, for a
/// Death Event, the minion that died. It has left play, but its Deathrattle still answers.
fn listeners(world: &World, event: &Event) -> Vec<EntityId> {
let mut ids = world.minions_in_play();
if let Event::Destroyed { id, .. } = *event {
ids.push(id);
ids.sort_by_key(|&id| world.order_of_play(id));
}
ids
}
/// Does a trigger listening for `on`, belonging to `listener`, respond to `event`?
fn responds(world: &World, on: TriggerOn, listener: EntityId, event: &Event) -> bool {
if let Event::Destroyed { id, .. } = *event {
return on == TriggerOn::Deathrattle && id == listener;
}
let Event::Damaged { target, .. } = *event else {
return false;
};
let is_minion = !world.is_hero(target);
match on {
TriggerOn::SelfDamaged => target == listener,
TriggerOn::FriendlyMinionDamaged => {
is_minion && world.owner_of(target) == world.owner_of(listener)
}
TriggerOn::AnyMinionDamaged => is_minion,
TriggerOn::HeroDamaged => !is_minion,
TriggerOn::Deathrattle => false,
}
}
course/03-death-step/reference/rust/src/engine/world.rs
+296
View File
@@ -0,0 +1,296 @@
//! 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. At 0 or below the entity is mortally wounded: still in play until the
/// Death Creation Step.
health: i32,
/// Hit by a destroy effect: still in play until the Death Creation Step.
pending_destroy: bool,
}
/// 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,
pending_destroy: false,
});
// 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 {
self.create_at(card, owner, zone, None)
}
/// Create an entity of `card` for `owner` in `zone` at index `at` (clamped to the
/// zone's length), or at the end if `at` is `None`.
pub fn create_at(
&mut self,
card: &str,
owner: PlayerId,
zone: Zone,
at: Option<usize>,
) -> 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,
pending_destroy: false,
};
let id = self.entities.len() as EntityId;
self.entities.push(entity);
self.enter(id, zone, at);
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, None);
}
/// 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, at: Option<usize>) {
let owner = self.entity(id).owner;
let list = self.sides[owner as usize].zone_mut(zone);
list.insert(at.map_or(list.len(), |i| i.min(list.len())), 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
}
/// Mortally wounded (0 or less Health) or pending destroy: it leaves play at the next
/// Death Creation Step.
pub fn is_doomed(&self, id: EntityId) -> bool {
let entity = self.entity(id);
entity.health <= 0 || entity.pending_destroy
}
/// Index of a minion on its owner's board, left to right; `None` if it is not on the board.
pub fn board_index(&self, id: EntityId) -> Option<usize> {
self.zone(self.owner_of(id), Zone::Board)
.iter()
.position(|&e| e == id)
}
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 }),
}
}
/// Mark for destruction. Nothing leaves play until the Death Creation Step.
pub fn mark_destroyed(&mut self, id: EntityId) {
self.entity_mut(id).pending_destroy = true;
}
/// Move a minion from play to its owner's graveyard, recording its Death Event.
pub fn kill(&mut self, id: EntityId, position: usize) {
self.entity_mut(id).pending_destroy = false;
self.move_to(id, Zone::Graveyard);
self.record(Event::Destroyed { id, position });
}
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 });
}
}