Skip to content

Card Framework v1.4.0

Latest

Choose a tag to compare

@chun92 chun92 released this 08 May 05:06

What's New in v1.4.0

Bug Fixes

  • Card Return-to-Original Offset After Layout Shift (#38): Cards captured original_destination while 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 via change_scene_to_file from a separate main scene.
    • Card.return_card now asks the owning container for an on-demand target pose via the new CardContainer.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_container schedule 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 calls card.queue_free() directly without a matching remove_card() no longer triggers a runtime error in downstream layout/state loops.

Changed

  • BREAKING — _update_target_positions Split: Card-state assignments (show_front, can_be_interacted_with) moved out of _update_target_positions into a new sibling virtual method _update_card_states(). _update_target_positions is 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_positions to 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 by Card.return_card for layout-race-safe return; opt-in for custom containers (base returns {}, in which case Card.return_card falls 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.tscn exposes three entry paths into example1 (immediate change_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