Repository navigation
What's New in v1.4.0
Bug Fixes
- Card Return-to-Original Offset After Layout Shift (#38): Cards captured
original_destinationwhile the parent Container's deferred sort had not yet positioned the Pile/Hand, leaving the cache pinned to a transient (pre-sort) coordinate. After the sort, dragging a card and dropping it on an invalid zone returned the card to that stale location with a visible offset, most reproducibly when entering the card scene viachange_scene_to_filefrom a separate main scene.Card.return_cardnow asks the owning container for an on-demand target pose via the newCardContainer.get_target_pose_for()hook, so a returning card always lands at its current slot regardless of any layout shift since the card was last placed._assign_card_to_container/_insert_card_to_containerschedule a deferred layout-only reapply so cards added before the parent Container's sort settles get repositioned against the final layout.DraggableObject.move()now refreshes the cached "original" on its early-return branch so offset-zero cards (Pile bottom) don't get stuck with stale coordinates.
- Crash on Freed Card in
_held_cards: Defensive_prune_freed_cards()now drops invalid entries before each layout pass and the deferred reapply, so game code that callscard.queue_free()directly without a matchingremove_card()no longer triggers a runtime error in downstream layout/state loops.
Changed
- BREAKING —
_update_target_positionsSplit: Card-state assignments (show_front,can_be_interacted_with) moved out of_update_target_positionsinto a new sibling virtual method_update_card_states()._update_target_positionsis now layout-only (positions, drop-zone geometry) and is the method called by the deferred reapply path. In-tree subclasses (Pile, Hand, Tableau, Foundation, Freecell) are migrated, so projects that only consume the framework via these need no code changes. Custom subclasses that overrode_update_target_positionsto also assign card state must move that state code into a_update_card_states()override — see the Migration Guide in the CHANGELOG. - Coalesced Deferred Reapply: Bulk
add_card()flows (e.g. dealing 52 cards from a factory in_ready) now collapse to a single deferred layout pass per frame instead of N enqueued copies, dropping post-sort work from O(n²) to O(n) move() calls.
Added
CardContainer.get_target_pose_for(card)Hook: Subclasses (Pile, Hand) implement this to compute the slot pose a held card SHOULD be at given the container's current state. Used byCard.return_cardfor layout-race-safe return; opt-in for custom containers (base returns{}, in which caseCard.return_cardfalls back to the cached coordinate).CardContainer._update_card_states()Virtual Method: Per-card display + interaction defaults. Override in containers that own these fields container-side; leave to the empty default if game code manages them externally.- Issue #38 Repro Harness:
example1/repro_main.tscnexposes three entry paths into example1 (immediatechange_scene_to_file, after one process frame, and a forced layout-shift variant) for reproducing the bug and verifying regressions after future fixes.
Migration Guide
Most projects need no code changes — bump the version and you're done. The breaking change only affects custom CardContainer subclasses whose _update_target_positions override also sets show_front or can_be_interacted_with. See the Migration Guide (1.3.x → 1.4.0) section of the CHANGELOG for a before/after example and an optional opt-in path for get_target_pose_for in custom containers.
Contributors
Thanks to @HollowTraces for the detailed report on #38 that made this release possible.
Downloads
- For Asset Library users: "Source code (zip)" — Addon only (
addons/card-framework/) - For learning/development:
card-framework-v1.4.0-full.zip— Includes examples and documentation
Installation
From Asset Library: Search "Card Framework" in Godot's AssetLib tab
Manual: Extract and copy addons/card-framework/ to your project
Full Changelog
See CHANGELOG.md