Dimcairion
Card Combat Engine — Turn-Based Card Battle Logic for Godot 4
If you're building a Digital TCG or CCG, a deck-building roguelike or anyturn-based card battler in Godot, you've probably noticed the pattern: thepopular card addons give you beautiful hands, drag-and-drop and pilemanagement — and then you're on your own for turns, mana, combat math and AI.Card Combat Engine is that missing part. It is a **logic-only** engine (norendering, no scenes required) that runs the entire battle:- A turn state machine (`BEGIN → PREPARATION → MAIN → ATTACK → DEFENSE → RESOLVE → END`) you drive from your UI — or auto-resolve headlessly.- Decks with hand / draw pile / board / graveyard, per-side mana pools, and fully generic extra zones (exile, banished, extra deck…).- Creatures, spells (damage / heal / buff / AoE / summon), auras, persistent enchantments, and multi-target or hero-targeted effects.- Attack/defense/block declaration with simultaneous damage resolution.- Multi-side combat out of the box: 1v1, free-for-all, 2v2 with teams.**Domain-agnostic by design.** The engine knows nothing about your GDD. Cardtaxonomy, rarities and ability semantics live in opaque containers(`CardData.metadata`) and 14 `Callable` injection points (`ability_fn`,`damage_fn`, `cost_fn`, `attack_restriction_fn`…). An optional`AbilityLibrary` ships 14 ready-made keywords — CHARGE, IMMUNITY, TAUNT,LIFESTEAL, THORNS, STEALTH, WINDFURY, FREEZE, ARMOR, BATTLECRY, SPELLPOWER,LORD, OVERKILL, SPELLBURST — that you can adopt, fork or ignore.**Deterministic and multiplayer-ready.** Shuffles and AI are seeded: the sameseed replays the same combat bit-for-bit. A command log gives youreplay-from-input; full serialization gives you save/resume mid-combat. Runthousands of headless simulations for balancing, or put the engine on a serverfor authoritative netcode.**Engineered, not improvised.** 418 GUT unit tests, a 4-stage CI pipeline(compile gate, unit tests, leak gate, lint gate), no autoloads, no editortooling — copy `addons/card_combat/` into your project and classes registervia `class_name`.**Pick your license.** AGPLv3 for open projects, or a one-time commerciallicense to ship closed-source and run server-side without copyleftobligations. Both packages contain byte-identical code.Includes a runnable demo, an integration guide and a step-by-step tutorial.- **Complete battle loop** — turn FSM, mana ramp, draw, attack/defense/block, simultaneous damage resolution- **Logic only, zero UI** — pairs with any presentation addon (e.g. chun92's Card Framework) or your own scenes- **Deterministic by seed** — bit-for-bit replays, balancing sims, server-authoritative multiplayer- **14 injection points** — abilities, damage formulas, costs, targeting rules: your game logic, never engine forks- **14 keyword abilities included** — optional AbilityLibrary with TAUNT, LIFESTEAL, BATTLECRY, OVERKILL and more- **1v1, FFA and 2v2** — N-sided combat topology with team support, plus save/resume serialization- **418 unit tests + 4-stage CI** — compile, unit, leak and lint gates on every commit
