Card Combat Engine — Turn-Based Card Battle Logic for Godot 4 v1.0.0 Scripts 4.6 Community

Submitted by user Dimcairion; AGPLv3; 2026-06-22

If you're building a Digital TCG or CCG, a deck-building roguelike or any
turn-based card battler in Godot, you've probably noticed the pattern: the
popular card addons give you beautiful hands, drag-and-drop and pile
management — 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 (no
rendering, 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. Card
taxonomy, 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 same
seed replays the same combat bit-for-bit. A command log gives you
replay-from-input; full serialization gives you save/resume mid-combat. Run
thousands of headless simulations for balancing, or put the engine on a server
for 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 editor
tooling — copy `addons/card_combat/` into your project and classes register
via `class_name`.

**Pick your license.** AGPLv3 for open projects, or a one-time commercial
license to ship closed-source and run server-side without copyleft
obligations. 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