mundane.engine.state

Game-state dataclasses: the single source of truth for a Mundane game.

Nothing in this module mutates state; mundane.engine.rules.apply_action() is the only thing that does. Cards are referenced by id throughout the state; card objects — built from JSON sets by mundane.engine.cards.build_card() — and the effect closures they carry live only in the per-game pool, never in serialisable state. That separation is what lets a whole GameState round-trip through JSON.

Attributes

Effect	An effect mutates the state when its card resolves, given the resolving StackItem.
PERMANENTS
PHASES

Classes

CardType	The five kinds of card. The first three are permanents (they stay on the board).
Card	A card definition, built from a JSON set by mundane.engine.cards.build_card().
Player	One household. Card collections hold library ids (str), never Card objects.
StackItem	A card waiting to resolve. id is unique within a game (see GameState.next_stack_id).
GameState	The entire game. Fully JSON-serialisable: every field is data, never code.

Functions

_no_effect(→ None)

Do nothing. Permanents resolve onto the board, so they carry this placeholder effect.

Module Contents

class mundane.engine.state.CardType

Bases: enum.StrEnum

The five kinds of card. The first three are permanents (they stay on the board).

PERSON = 'person'

APPLIANCE = 'appliance'

HABIT = 'habit'

TASK = 'task'

INSTANT = 'instant'

type mundane.engine.state.Effect = Callable[[GameState, StackItem], None]

An effect mutates the state when its card resolves, given the resolving StackItem.

mundane.engine.state._no_effect(_state: GameState, _item: StackItem) → None

Do nothing. Permanents resolve onto the board, so they carry this placeholder effect.

class mundane.engine.state.Card

A card definition, built from a JSON set by mundane.engine.cards.build_card().

State refers to a card only by its composed id (set_id:id); the bound effect closure lives in the per-game pool, never in serialisable state.

id: str

name: str

cost: int

type: CardType

effect: Effect

text: str = ''

flavor: str = ''

mundane.engine.state.PERMANENTS

class mundane.engine.state.Player

One household. Card collections hold library ids (str), never Card objects.

name: str

composure: int = 20

time: int = 0

hand: list[str] = []

board: list[str] = []

deck: list[str] = []

discard: list[str] = []

class mundane.engine.state.StackItem

A card waiting to resolve. id is unique within a game (see GameState.next_stack_id).

card_id: str

controller: int

target_id: int | None = None

id: int = 0

mundane.engine.state.PHASES = ['RESET', 'WAKE_UP', 'PLAN', 'DO_STUFF', 'WIND_DOWN']

class mundane.engine.state.GameState

The entire game. Fully JSON-serialisable: every field is data, never code.

players: list[Player]

active_player: int = 0

priority_player: int = 0

phase: str = 'PLAN'

stack: list[StackItem] = []

passes_in_a_row: int = 0

turn: int = 1

winner: int | None = None

next_stack_id: int = 1

next_player(i: int) → int

Return the index of the player after i (wraps around the table).

opponent(i: int) → int

Return the opponent of player i (2-player convenience).