godot-genre-card-game

NEVER Do (Expert Anti-Patterns)

Logic & Architecture

• NEVER hardcode card logic inside UI scripts; strictly encapsulate gameplay effects in Callable objects or Command resources pushed to a LIFO stack.
• NEVER perform board-state calculations (Power/Toughness) in _process(); strictly use Signal-driven triggers or a centralized EffectStack resolver.
• NEVER forget LIFO Stack Resolution; strictly use Array.push_back() and Array.pop_back() to resolve reactions from top-to-bottom.

UX & Animation

• NEVER skip Z-Index management during drag-and-drop; strictly raise the card to the front on click to prevent it sliding under other cards.
• NEVER allow instant card "teleportation" between piles; strictly use create_tween() / tween_property chains (0.2s+) for pile moves.
• NEVER use global_position for cards in hand; strictly position them using a Curve2D layout with sample_baked() for smooth arcs.

Deck & State Management

• NEVER forget to handle Empty Deck scenarios; strictly implement auto-reshuffle of the discard pile to prevent soft-locks.
• NEVER use floating point numbers for discrete card stats; strictly use int for Costs, Attack, and Health to avoid precision drift.
• NEVER use standard Control nodes for mass tokens/battlefields; strictly use _draw() custom drawing to bypass SceneTree overhead when rendering 100+ cards or map icons.
• NEVER rely on SceneTree order for hand logic; strictly manage logical order in an Array and update visuals via queue_redraw().
• NEVER erase array elements during a standard for loop; strictly iterate in reverse or use filter() to avoid indexing errors.
• NEVER forget to provide parameterless constructors in _init(); otherwise, Resources will fail to load in the Inspector.

---

🛠 Expert Components (scripts/)

> MANDATORY reads before implementing the matching system:

> 1. [card_effect_resolution.gd](scripts/card_effect_resolution.gd) — LIFO effect stack (push_back / pop_back)

> 2. [card_tween_manager.gd](scripts/card_tween_manager.gd) — interruptible pile/hand Tweens (no teleports)

> 3. [card_data_resource.gd](scripts/card_data_resource.gd) — Inspector-safe Resource card definitions

Original Expert Patterns

• [card_effect_resolution.gd](scripts/card_effect_resolution.gd) - LIFO stack resolver for nested triggers and counter-play.

Modular Components

• [card_data_resource.gd](scripts/card_data_resource.gd) - Data-driven card definitions allowing Inspector-based design.
• [card_data.gd](scripts/card_data.gd) - Lightweight CardData Resource stub used by validators/tests.
• [deck_shuffle_bag.gd](scripts/deck_shuffle_bag.gd) - Secure randomization patterns for uniform card distribution.
• [turn_state_machine.gd](scripts/turn_state_machine.gd) - Managing rigid phases (Draw, Play, Combat) via state matching.
• [card_drag_drop.gd](scripts/card_drag_drop.gd) - Implementation of native _get_drag_data() for Control nodes.
• [board_query_filter.gd](scripts/board_query_filter.gd) - Functional filter() patterns for querying board metadata.
• [card_tween_manager.gd](scripts/card_tween_manager.gd) - Managing interruptible card juice and board transitions.
• [reactive_card_ui.gd](scripts/reactive_card_ui.gd) - Resource-signal driven UI for automatic visual state updates.
• [board_state_dictionary.gd](scripts/board_state_dictionary.gd) - Grid-based tracking (Vector2i) decoupled from Node order.
• [match_state_resetter.gd](scripts/match_state_resetter.gd) - Clean-up pattern for in-match temporary Resource modifications.
• [deck_builder_validator.gd](scripts/deck_builder_validator.gd) - Backend logic for deck-building constraints and mana curves.

---

Core Loop

1. Draw → 2. Evaluate → 3. Play → 4. Resolve (LIFO stack) → 5. Discard/End

Decision Trees

Effect stack

| Need | Action |

|------|--------|

| Nested reactions / counters | MANDATORY [card_effect_resolution.gd](scripts/card_effect_resolution.gd) — LIFO only (pop_back) |

| FIFO sequential animations only | Rare; keep a separate queue — do not reuse the reaction stack |

Hand & board

| Need | Action |

|------|--------|

| Arc hand layout | Curve2D.sample_baked + [card_tween_manager.gd](scripts/card_tween_manager.gd) |

| Drag targeting | [card_drag_drop.gd](scripts/card_drag_drop.gd) |

| Dense boards (100+ icons) | _draw() / [board_state_dictionary.gd](scripts/board_state_dictionary.gd) — not Control-per-token |

Data

| Need | Action |

|------|--------|

| Card definitions | MANDATORY [card_data_resource.gd](scripts/card_data_resource.gd) (parameterless _init) |

| Deck RNG | [deck_shuffle_bag.gd](scripts/deck_shuffle_bag.gd) |

| Turn phases | [turn_state_machine.gd](scripts/turn_state_machine.gd) |

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Data | resources, custom-resources | Card properties (Cost, Type, Effect) |

| 2. UI | control-nodes, layout-containers | Hand layout, tooltips |

| 3. Input | drag-and-drop, state-machines | Targeting, hovering |

| 4. Logic | command-pattern, signals | LIFO stack, turn phases |

| 5. Polish | godot-tweening, shaders | Draw juice, foils |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| FIFO pop_front on reaction stack | Use LIFO pop_back in [card_effect_resolution.gd](scripts/card_effect_resolution.gd) |

| Instant pile snaps | Tween via [card_tween_manager.gd](scripts/card_tween_manager.gd) |

| Float ATK/HP | Use int stats on Resources |

Elite notes (optional polish)

• Holographic foil: UV scroll shader on card Control — not required for stack correctness.
• Card history: signal bus logger for replay/debug; keep off the hot resolve path.

Expert knowledge (on demand)

> LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• [expert-card-patterns.md](references/expert-card-patterns.md) — restored baseline pedagogy (architecture, WHY, implementation depth)
• [card_history_logger.gd](scripts/card_history_logger.gd)
• [hand_manager.gd](scripts/hand_manager.gd)

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — CardData as .tres Resources so designers edit cost/stats without touching UI scripts.
• GDScript exports — @export / @export_group patterns that drive Inspector-authored card definitions.
• Control — _get_drag_data / _can_drop_data / _drop_data and set_drag_preview for native card drag-and-drop.
• Custom GUI controls — building interactive card faces with _gui_input, mouse_filter, and _draw for dense boards.
• Size and anchors — anchoring hand/board zones so layouts survive resolution changes.
• Using Containers — when HBox/Grid help deck-builder grids vs manual hand arcing.
• Tween — interruptible create_tween() / tween_property juice for draw, play, and discard moves.
• Beziers, curves and paths — math behind arcing hand layouts instead of circular fudge factors.
• Curve2D — sample_baked() for smooth non-circular fan positions and rotations.
• Random number generation — seeded RNG and shuffle-bag fairness for draw piles.
• Using signals — Resource changed and effect-stack signals that keep UI reactive without _process polling.
• Your first 2D shader — canvas_item foil/rarity shaders on card faces.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, Autoloads, and import basics before wiring DeckManager and card scenes.
• godot-resource-data-patterns — .tres ownership, duplication, and emit_changed so match buffs never leak into authored card files.
• godot-gdscript-mastery — typed Arrays, Callables/Commands, and match phases used by effect stacks and turn machines.
• godot-ui-containers — Control layout, anchors, and mouse_filter habits required for hand/board hit-testing.

Complements

• godot-tweening — kill/parallel Tween patterns so rapid plays do not teleport or stack dead tweens.
• godot-signal-architecture — bus/signal graphs for draw, play, resolve, and discard without UI owning game rules.
• godot-input-handling — pointer vs action maps when cards share the viewport with keyboard shortcuts and accessibility drag.
• godot-turn-system — Draw/Main/Combat/End phase ownership that this skill's turn state machine plugs into.
• godot-shaders-basics — canvas_item rarity foils and highlight materials beyond the skill's starter hologram snippet.

Downstream / consumers

• godot-monte-carlo-balancer — simulate mulligans, mana curves, and win-rate vs cost/power so card stats stay fair under RNG.
• godot-genre-roguelike — run-based deckbuilders that consume CardData, shops, and per-act draft pools.
• godot-inventory-system — collection/deck-builder UIs that persist owned cards separately from the in-match piles.
• godot-ability-system — keyword/status effects (Poison, Taunt, Shield) resolved as reusable ability resources on the stack.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.