f

Last updated: 2026-08-20

This handoff summarizes the current reusable-framework state after the latest optimization/refactor pass. Use it with Release Sprint Plan so the next session does not need to rediscover what has already been stabilized.

Current State

The completed optimization/refactor track is documented in Performance And Engine Refactor Plan.
Active release sprint work is documented in Release Sprint Plan.
Sprint 1 through Sprint 5 are closed for the current pass.
Sprint 6 has rolled out the main optimized framework paths across current games. Remaining optimization work is targeted maintenance rather than broad cache or asset migration.
Sprint 7 browser/mobile hardening is complete for the current release pass, with the repeatable checklist in Mobile And Browser Hardening Checklist and the data-driven low-power preset path wired into the framework.
The current build/profile validation path is green for all configured profiles.
Full Godot headless smoke is green locally, with known Godot shutdown RID/resource warnings after successful test completion.

Completed In The Current Pass

Cached Data Loading

dataCacheManager is now the standard runtime JSON cache for stable catalogs. It tracks entries, hits, and misses through get_cache_stats() so managers can be measured by performanceMonitor.

The following convenience loaders now route through dataCacheManager:

gameSettingsPanel.load_definition(...)
aiController.load_profiles(...)
arcadePowerupManager.load_definitions(...)
cardManager.load_cards(...)
packManager.load_packs(...)
combatCardFactory.load_catalog(...)
combatCardFactory.load_definitions(...)
alchemyManager.load_definitions(...)
alchemyManager.load_reactions(...)
gridCombatManager.load_archetypes(...)
adventureManager.load_adventure(...)
menuManager.load_menu(...)
inputManager.load_actions(...)
levelManager.load_level(...)
paletteManager.load_palettes(...)
tutorialManager.load_steps(...)
unlockManager.load_rules(...)
eventManager.load_events(...)
resourceManager.load(...)
actionEffectManager.load_actions(...)
alchemyGraphManager.load_graph(...)
buildProfileManager.load_profile(...)
statsManager.load_achievements(...)
buildInfo.load_info(...)
performanceMonitor.load_baseline_profiles(...)
audioManager music manifest loads

Scenes can still provide already-loaded dictionaries to manager data APIs when a scene-level cache is preferred.

Cached Visual Loading

Direct runtime image/icon loads have been pushed back into spriteManager.

Current shared visual paths include:

Start Menu screen backgrounds through spriteManager.get_texture_for_path(...).
Splash screen RGF/Godot logos through spriteManager.get_texture_for_path(...).
Theme-defined screen/panel/button background images through layoutManager's shared spriteManager.
Reusable resource HUD icons through spriteManager scaled texture lookups.
Reflecting Pool choice-effect icons through the scene spriteManager scaled texture cache.
Reflecting Pool pool effects through the game sprite map and warmed hud_and_pool profile.

A quick audit currently shows the remaining direct texture loads are inside spriteManager, which is the intended owner.

Delayed Save Writes

Arcade Pong uses saveManager.queue_save_state(...) for normal match updates and flushes on match/menu boundaries.
Project Alchemy now uses the same delayed-save pattern for normal field and lab state writes. _process() advances pending saves, _exit_tree() flushes pending state, and headless smoke verifies that generated field starts queue rather than write immediately.

Reusable UI And Render Paths

Main menu achievement pages use the reusable achievementScreen renderer.
Card Game inventory and fight-picker rows use cardInventoryAdapter plus inventoryList.
Card Game battle picker UI now lazy-builds on first Battle screen entry instead of during scene startup. Latest smoke snapshot reduced Card Game entry from about 702 measured nodes to 627.
Card Game Set/Collection tiles now lazy-build on first Collection screen entry instead of during the initial Shop entry. Latest smoke snapshot reduced Card Game entry further to about 171 measured nodes; single-iteration timing remains noisy, so node count is the better signal for this change.
Standard settings popup creation now waits until Settings is opened in the migrated scenes instead of allocating those shared modal trees during _ready(). Reflecting Pool, Card Game, Arcade Pong, and Project Alchemy have smoke coverage for this on-demand path.
Project Alchemy field viewport math uses gridViewportManager.
Platformer rendering uses levelManager visible tile-record and semantic rect caches.
Platformer exits and enemies use levelManager object/world-rect culling helpers so larger scrolling levels avoid drawing off-camera objects.
Platformer level attempts use runManager active/terminal state for level start, coin counters, completion, failure, and result summaries.
Arcade Pong rocket projectile stepping, target-hit partitioning, and out-of-bounds cleanup use arcadePhysicsManager.step_projectiles(...); the scene keeps only stun, SFX, stats, and save responses.
Arcade Pong multiball stepping and scoring promotion use arcadePhysicsManager.step_ball_group(...) and collect_ball_group_scoring(...).
resultsScreenController.show_popup(...) now bundles result popup creation, viewport fitting, theme/text application, and focus for future level, battle, match, and run result screens.
Layout theme styleboxes, achievement rows, inventory rows, button rows, render nodes, sprite caches, data caches, and audio caches expose diagnostics for smoke tests and performance snapshots.

Lifecycle Cleanup

Targeted cleanup hooks are now available in key reusable helpers:

pauseOverlayController.dispose()
standard_settings_popup.dispose()
audioManager.dispose()
achievementNotifier.dispose()

achievementNotifier.dispose() cancels queued achievement toasts, releases any visible toast node, and is now called by the Reflecting Pool and Card Game scenes during exit. Headless smoke covers this cancellation path so future toast UI changes do not reintroduce scene-lifetime leaks.

Current game scenes also call the reusable cleanup hooks they own on exit: Arcade Pong, Reflecting Pool, Card Game, and Project Alchemy now dispose standard settings/pause helpers where applicable before the scene is released.

Do not add broad root-wide cleanup to headless smoke. A previous attempt was rejected because deferred scene callbacks can fire against already-freed nodes. Prefer targeted disposal and deferred-signal cleanup inside the affected helper or scene.

Validation Status

Last local validation completed successfully:

git diff --check
scripts/ci/build_profiles.py --validate-only --profiles all --platforms all
Godot headless smoke: res://tests/headless_smoke.gd

Known local noise:

Godot prints RID/resource leak warnings at shutdown after the successful smoke run.
These warnings are currently tracked as follow-up lifecycle cleanup work, not active smoke failures.

Recommended Next Work

Start Sprint R1 in release_sprints: Arcade Pong feature/update release.
Use Arcade Pong Release Feedback as the game-specific release checklist.
Use the Arcade Pong section of Mobile And Browser Hardening Checklist for the manual browser/mobile pass.
Move to Emoji Card Collector First Release Plan only after the Arcade Pong update is stable.
Continue targeted lifecycle cleanup only where a helper or scene owns a known deferred callback, popup, signal, or temporary cache. Do not add broad root-wide teardown.
Continue entity/update rollout only when release playtest or profiling shows a specific active-game bottleneck.
Keep comparing post-refactor smoke/performance reports against Sprint 1 baselines before larger rewrites.

The broad engine optimization rework is wrapped for this release cycle. Avoid broad refactors that touch many games at once. The successful pattern has been: migrate one reusable seam, add focused smoke coverage, update docs, then run validation.