t

This audit captures reusable behavior that emerged while playtesting the current demos. It is a reference for future extraction work, not the active sprint plan; active release sequencing lives in Release Sprint Plan.

Already Extracted

inventoryList: Reusable sortable/filterable inventory table renderer with wrapped cells, wide mobile scrollbars, selection callbacks, and configurable columns.
inventoryManager stack helpers and inventoryCategoryPanel: Shared stack/category inventory state and framed category rendering for resources, crafting materials, forms, modifiers, consumables, items, and similar future game inventories.
onscreenControlManager: Reusable translucent touch overlay with configurable controls, side, sizing, opacity, and persisted-state shape.
arcadePhysicsManager: Shared Pong-style ball, paddle, projectile, split-ball, collision, and scoring helpers.
powerupInventoryManager: Fixed-slot held power-up inventory for players and AI owners. Slots do not shift when consumed, which keeps mobile buttons and hotkeys predictable across Pong, platformers, and future action games.
battleSequenceManager: Shared standard/raid battle sequencing and reward scaling.
layoutManager: Shared shells, bottom navigation, pause overlays, achievement collection UI, save-slot rows, and theme/density helpers.
uiFlowManager: Shared focus-first behavior, recursive focus-mode changes, simple screen/tab visibility, next/previous page id cycling, and local timestamp formatting. Current menus plus Reflecting Pool, Card Collector, Arcade Pong, and Project Alchemy all use this for common UI flow glue.
settingsManager and settings_panel_controller: Shared global settings persistence and common settings panel binding.
researchLabManager: Shared inventory-backed alchemy attempts with explicit consume/gain deltas and failed-experiment loss rules.
spellLoadoutManager: Shared unlocked/equipped spell ids, active-slot limits, auto-equip-on-discovery behavior, and saveable loadout state.
rewardManager: Shared weighted reward-table rolling with fallback ids for loot, forms, modifiers, pickups, and post-run rewards.
guidancePanel: Shared compact onboarding and contextual guidance panels for lab pages, active runs, tutorials, and pause/menu surfaces.
combatCardSlotPanel: Shared active card/spell slot button renderer with cost, damage, range/mode, cooldown, and aiming state.
objectivePanel: Shared required/optional objective checklist renderer with status marks, detail text, reward hints, and active exit/objective state.
fieldMenuController: Shared active-run popup menu builder for Resume, Retry, Give Up/Exit, Settings, and Main Menu action lists.
statusFeedManager: Shared stacked status/toast feed with explicit text wrapping, newest-first ordering, exact-message dedupe, and timed expiry.
resourceBar: Shared outlined value bar renderer with readable shadowed text for health, energy, cooldowns, timers, and bounded resources.
gridCombatManager aggro/wander rules: tactical enemies can now use dictionary/JSON behavior values for aggro range, alerting after being hit, wandering, attack range, and movement distance.

Promote Next

<tt>dataValidationManager</tt>

Current locations: headless smoke tests, alchemy graph validation, sprite mapper validation, and future content/editor import flows.

Seeded at scripts/systems/dataValidationManager/data_validation_manager.gd.

This should become the shared validation layer for JSON files and content bundles. It currently validates parse/load success, required fields, duplicate ids, invalid records, bad references, and multi-file bundle checks.

Suggested migration path:

Add bundle checks for every game data root in headless smoke and CI.
Let Sprite Mapper and future map/sprite/content tools reuse the same issue format for missing paths, invalid ids, and bad references.
Keep specialized graph validators such as alchemyGraphManager, but have them return compatible issue dictionaries where possible.

<tt>unlockManager</tt>

Current locations: Project Alchemy mode/adventure gates, future card/item unlocks, tutorial gates, and achievement progression.

Seeded at scripts/systems/unlockManager/unlock_manager.gd.

This should become the shared progression-gate layer for anything that becomes available after meeting data-driven conditions. It currently loads JSON unlock rules, evaluates them through conditionEvaluator, filters unlock rows, and saves/restores unlocked target ids.

Suggested migration path:

Move Project Alchemy menu mode availability and adventure gates to unlockManager.
Let Card Game packs, singles, cards, and modifiers use unlock rows rather than scene-local checks.
Feed achievement and tutorial unlocks through the same condition grammar so save migrations and editor validation can reason about them consistently.

<tt>conditionEvaluator</tt>

Current locations: trigger checks, tutorial checks, menu disabled rules, achievement filters, objective gates, and future scripted content.

Seeded at scripts/systems/conditionEvaluator/condition_evaluator.gd.

This should be the shared condition-language implementation for all JSON-driven rules. interactionTriggerManager and tutorialManager now use it directly.

Suggested migration path:

Replace remaining one-off condition checks in menus, achievements, objectives, and scripted Adventure logic with conditionEvaluator.matches.
Use the same condition grammar in future editor tooling so designers can test trigger/tutorial/objective rules outside active gameplay.

<tt>tutorialManager</tt>

Current locations: Project Alchemy MVP tutorial/status helpers and future first-run flows for the other demos.

Seeded at scripts/systems/tutorialManager/tutorial_manager.gd.

This should own data-driven checklist/tutorial state, completion conditions, next-step prompts, and saved completion state. It is intentionally context based: games pass dictionaries such as discoveries, spell counts, run status, or collection progress, and the manager marks matching steps complete.

Suggested migration path:

Project Alchemy: move first-run research -> spell creation -> loadout -> field deployment checklist into tutorial JSON and tutorialManager.
Arcade Pong: add a tiny first-play checklist for movement, power-up collection, and using held slots.
Future platformer: drive onboarding for movement, jump, dash, checkpoint, and hazard mechanics from the same manager.

<tt>aiController</tt> and <tt>entityDefinitionAdapter</tt>

Current locations: Arcade Pong AI logic, Project Alchemy grid enemy behavior, Project Alchemy battlefield/world JSON loading, and future platformer level loading.

Seeded at:

entityDefinitionAdapter converts game/world/level JSON sections into common entity dictionaries. aiController chooses reusable arcade paddle actions, tactical grid attack/move/wait actions, and simple AI ability-use timing.

Suggested migration path:

Arcade Pong: move opponent paddle targeting and AI power-up timing into aiController profiles.
Project Alchemy: after field actors move to entities, feed enemy entities into aiController.choose_grid_action.
Platformer prototype: convert level JSON spawns/pickups/hazards/checkpoints into entities with entityDefinitionAdapter.

<tt>resultsScreenController</tt> and <tt>interactionTriggerManager</tt>

Current locations: Project Alchemy victory/defeat/adventure transition popups, Card Game battle/raid result text, Reflecting Pool game-over state, and Project Alchemy field/adventure interaction checks. Arcade Pong match-over state now uses the reusable result popup path.

Seeded at:

resultsScreenController consumes runManager summaries and renders counters, collected loot, rewards, objective progress, messages, and action buttons. interactionTriggerManager evaluates data-driven events such as spell hits, exit steps, switch use, enemy-clear gates, traps, tutorial steps, and scripted Adventure events.

Suggested migration path:

Project Alchemy: move field victory/defeat/retry/give-up/adventure transition summaries to runManager + resultsScreenController.
Project Alchemy: move bramble gates, exits, scripted events, and spell interactions to interactionTriggerManager.
Card Game: move win/loss/raid result displays to the result controller.
Reflecting Pool: use result screens for game-over summaries with retry/main-menu actions.

<tt>animationStateManager</tt>, <tt>entityRenderer</tt>, and <tt>gameSettingsPanel</tt>

Current locations: Project Alchemy field rendering/settings, Arcade Pong playfield rendering/settings, Card Game combat panels, and future platformer prototype scenes.

Seeded at:

These complete the first pass of the reusable entity spine: entityManager owns save-friendly state, animationStateManager maps that state to directional sprite ids, entityRenderer draws entities with fallback rects and health bars, and gameSettingsPanel renders game-specific tuning controls from data.

Suggested migration path:

Project Alchemy: replace custom active-field actor/material/projectile node rendering with entity records plus entityRenderer.
Arcade Pong: move ball, paddle, rocket, and power-up display to entities. Game tuning rows now use gameSettingsPanel with data/games/arcade_pong/settings.json; remaining UI work should focus on playtest polish and entity-render migration.
Platformer prototype: use entity renderer for actors/pickups/hazards and the settings panel for movement tuning presets.

<tt>entityManager</tt>

Current locations: scripts/project_alchemy.gd, scripts/arcade_pong.gd, scripts/emoji_card_collector.gd, gridCombatManager, gridWorldManager, and future platformer scenes.

Seeded at scripts/systems/entityManager/entity_manager.gd.

This should become the shared state/query layer for actors, enemies, projectiles, pickups, hazards, interactables, board pieces, and temporary field markers. It keeps entity data as dictionaries so renderers, physics, save systems, editors, and combat managers can share the same records without depending on scene nodes.

Suggested migration path:

Project Alchemy: move player, enemies, material nodes, spell interactions, exit markers, and active projectiles into entity records, while gridCombatManager continues to resolve tactical rules.
Arcade Pong: represent paddles, balls, rockets, and field power-ups as entities, while arcadePhysicsManager continues handling motion/collision.
Emoji Card Collector: represent active player/opponent cards as combatant entities for battle panels and result summaries.
Platformer prototype: use entities for player spawn, enemies, hazards, collectibles, checkpoints, and exits loaded from level JSON.

<tt>runManager</tt>

Current locations: scripts/project_alchemy.gd, scripts/arcade_pong.gd, scripts/emoji_card_collector.gd, and scripts/main.gd.

Seeded at scripts/systems/runManager/run_manager.gd.

This should become the common lifecycle layer for arenas, adventures, matches, battles, raids, platformer levels, board-game rounds, and roguelike floors. The first implementation creates save-friendly active run dictionaries, tracks objectives, counters, collected run loot, rewards, terminal status, retry attempts, and compact summaries.

Suggested migration path:

Project Alchemy field tests: replace local active_run, collected resources, retry/give-up/complete, and result-summary glue with run state helpers.
Emoji Card Collector battles/raids: wrap standard fights and raid sequences in run summaries so rewards, losses, and fight history share one result flow.
Arcade Pong matches: record match winner, score, rallies, power-up use, and retry/menu choices as run summaries.
Reflecting Pool runs: record highest round, failed resource, and final event as a run-over summary.

<tt>actionEffectManager</tt>

Current locations: scripts/project_alchemy.gd, scripts/arcade_pong.gd, scripts/emoji_card_collector.gd, and Reflecting Pool event/resource choice effects.

Seeded at scripts/systems/actionEffectManager/action_effect_manager.gd.

This should become the common definition layer for spells, cards, power-ups, consumables, enemy abilities, environmental tools, and future platformer/RPG actions. The first implementation normalizes action dictionaries, checks costs and cooldowns, spends resource-style pools, and resolves effect dictionaries through game-provided callbacks.

Suggested migration path:

Project Alchemy spells: use actions for compound/form/modifier cards, energy costs, cooldowns, targeting metadata, damage, status, and environment effects.
Arcade Pong power-ups: model held power-ups as actions with cooldowns, duration effects, projectile/stun effects, ball modifiers, and AI use rules.
Emoji Card Collector battles: model attack rolls and special card modifiers as action/effect bundles instead of bespoke fight-result branches.
Reflecting Pool events: normalize resource changes as action effects so choice previews, summaries, and future event chains can share formatting.

<tt>cardBattlePanel</tt>

Current location: scripts/emoji_card_collector.gd

The fight screen now builds compact side-by-side card panels with icon, name, rarity/modifiers, and current HP/stat summaries. This should become a reusable renderer because future RPGs, roguelikes, board games, and card battlers will need the same "selected unit versus opponent" presentation.

Suggested API:

create_panel(name, options) -> Dictionary
render(panel_state, entity, battle_state = {})
set_empty(panel_state, label, hint)

Inputs should be plain dictionaries and caller-provided formatters for icon, name, metadata, and stats.

<tt>inventoryRecordAdapter</tt>

Current location: scripts/emoji_card_collector.gd

The scene still owns conversion from card instances to inventoryList records, including base-name sorting, selected styling, stat coloring, and sell-price columns. This should become an adapter layer so future games can define list columns from data instead of scene code.

Suggested API:

make_records(items, schema, callbacks = {})
compare_records(a, b, sort_key, ascending)
filter_records(items, filter_id, context = {})

The schema should support labels, sort keys, wrapped columns, icon callbacks, color rules, and hidden columns by screen.

<tt>gameSettingsPanel</tt>

Current location: scripts/arcade_pong.gd

Pong now has per-game settings for curve, spin amount, spin duration, power-ups, onscreen controls, and control side. That panel pattern will recur for arcade, platformer, roguelike, and board-game modifiers.

Suggested API:

create_game_settings_panel(definition, state, changed_callback)
Standard controls: checkbox, slider, option button, segmented/radio option.
Optional binding to save/settings state.

Definitions should live under data/games/<game_id>/settings.json.

<tt>achievementScreenController</tt>

Current location: scripts/start_menu.gd

The main menu now renders achievements as a full-screen page instead of a popup. Filtering and collection rendering are reusable, but screen-level composition and Back behavior are still local.

Suggested API:

show_achievement_screen(parent, stats_manager, filters, callbacks)
Support popup, full-screen menu, and embedded tab modes.
Own filter state and Back/Close action wiring.

<tt>saveSlotSummaryAdapter</tt>

Current location: scripts/start_menu.gd

Card save slots load money, card count, wins/losses, and updated time directly inside the menu scene. Other games with multiple saves will need their own slot metadata.

Suggested API:

load_slot_summaries(game_id, slot_count, formatter)
format_updated_at(unix_time, local = true)
Per-game metadata formatters declared in JSON or callbacks.

<tt>arcadePowerupManager</tt>

Current location: scripts/systems/arcadePowerupManager/arcade_powerup_manager.gd

Pong held slots are reusable through powerupInventoryManager, and field pickup lifecycle is now reusable through arcadePowerupManager: spawn timers, active field pickups, expiry, collision collection, and saveable active state. Power-up definitions, labels, colors, sprites, and effect lists are loaded from game JSON such as data/games/arcade_pong/powerups.json. Breakout, duel arenas, platformers, and roguelikes can reuse this lifecycle.

Current API:

configure(definitions, options)
load_definitions(file_path, options)
update(delta, playfield, collectors, options)
spawn(playfield, powerup_id)
get_definition(id), get_label(id), get_color(id), get_powerup_ids()
normalize_effect(id, effect, context), apply_effects(id, context, handlers)
get_active(), set_active(rows), clear()
get_state(), apply_state(state)

Remaining scene-owned work is effect handler implementation after a held slot is used. Generic effect dispatch now covers timers, speed changes, reversals, and labels; Pong still owns scene-specific handlers such as split ball, rockets, and cleanup on score. More concrete handlers can move into the framework as future arcade games prove which effects repeat.

<tt>arcadeAiController</tt>

Current location: scripts/systems/aiController/ai_controller.gd

Arcade Pong now uses reusable AI profiles loaded from data/games/arcade_pong/ai_profiles.json. Paddle target selection, reaction cadence, prediction lead, tracking error, deadzones, and AI power-up timing are centralized in aiController.

Current API:

load_profiles(path)
get_profile(id, overrides)
choose_pong_paddle_decision(paddle, balls, playfield, profile)
should_use_pong_powerup(actor, ball, playfield, profile)

Future extraction should focus on a dedicated arcadePowerupManager for spawn/collection/effect lifecycles and a data-driven gameSettingsPanel so match presets can be declared entirely through JSON.

<tt>fieldHudOverlay</tt>

Current location: emerging in scripts/project_alchemy.gd

Project Alchemy needs health, energy, quick spell slots, and status messages inside the active field without changing the surrounding layout. Platformers, roguelikes, and action RPGs will need the same pattern.

Suggested API:

create_field_hud(definition, state, callbacks = {})
update_health(current, max)
update_energy(current, max, mode = "segmented")
set_quick_slots(slots, selected_index = -1)
push_toast(message, category = "info", duration = 2.5)

<tt>tacticalFieldShell</tt>

Current location: emerging in scripts/project_alchemy.gd

Project Alchemy's active field needs a stable square play area, spell/quick slots directly below the field, and HUD/toast overlays that do not resize the screen. Tactical RPGs, roguelikes, board games, and puzzle rooms will likely need the same shape.

Suggested API:

create_tactical_field_shell(parent, options) -> Dictionary
set_board_size(shell, viewport_size, constraints)
set_quick_slots(shell, controls)
set_overlay(shell, overlay_state)
set_content_locked(shell, locked)

The shell should keep the playfield square when requested, expose safe mobile padding, and prevent status messages from changing the board's layout.

<tt>tacticalAggroController</tt>

Current location: scripts/systems/gridCombatManager/grid_combat_manager.gd

Grid enemies now support first-pass aggro behavior directly inside gridCombatManager: enemies can wander until alerted, become alerted when hit, or start pursuing when the player enters a configured aggro range. If this grows to patrol paths, factions, hearing/noise, stealth, or scripted alerts, the behavior rules should be promoted behind a dedicated controller.

Suggested API:

evaluate_alert(enemy_state, player_cell, context) -> Dictionary
choose_idle_action(enemy_state, world_state, config) -> Dictionary
choose_alert_action(enemy_state, world_state, config) -> Dictionary
Behavior data: aggro_range, wander, patrol_path, return_to_post, alert_on_hit, shared_alert_radius, and target_priority.

<tt>buildProfileManager</tt>

Current location: scripts/systems/buildProfileManager/build_profile_manager.gd

The framework now hosts multiple demos. Build profiles are seeded under data/build_profiles/ so future CI can build a selected game from that game's home screen and avoid packaging unrelated data/assets where practical.

Current API/data:

data/build_profiles/<game_id>.json
buildProfileManager.load_profiles(...)
buildProfileManager.validate_profile(...)
buildProfileManager.get_export_plan(...)
start scene or menu route
included game data roots
included shared framework roots
excluded game roots
platform export presets
CI artifact naming

Suggested migration path:

Keep the combined export as all_demos while also building individual profile artifacts.
Split the current profile loop into a GitLab matrix if pipeline duration gets too long.
Keep hardening generated export include/exclude filters from include_roots and exclude_roots.
Add a runtime start override only if direct per-game start_scene exports need to bypass the shared splash/main menu.

<tt>mapEditor</tt>

Current location: planned tooling

Project Alchemy Adventures are JSON-driven enough to justify a small editor. The editor should later support other games that use tile maps, tactical grids, or platformer rooms.

Suggested capabilities:

load/save a game's level/adventure JSON files
paint floor, wall, terrain, and metadata tiles
place player starts, enemies, resources, exits, traps, switches, and secrets
edit objectives, triggers, rewards, and script hooks
validate missing exits, invalid spawns, and unreachable required objectives

Keep Game-Specific For Now

Reflecting Pool custom drawing: it is a useful theme-aware pattern, but the scene is specific enough that only palette hooks should remain shared.
Emoji card data and balancing: card names, modifiers, pack weights, and sell values belong under data/games/emoji_card_collector/.
Pong scoring presentation: the rules can stay in matchManager; the current label copy is game-specific.

Release-Aware Extraction Order

Arcade Pong release support: keep improvements narrow and focused on audioManager, arcadePhysicsManager, inputManager, resultsScreenController, achievementScreen, and related smoke coverage.
Emoji Card Collector release support: promote repeated inventory, battle, result, save-slot, and achievement behavior only when it removes duplicated release work.
Build/docs/publishing support: harden buildProfileManager, profile validation, Doxygen navigation, and CI helpers while release profiles are still hosted in one repo.
Level editor and platformer prep: continue extracting levelEditorManager, levelManager, editor plugin, schema validation, and object palette logic.
Post-release engine work: revisit broader entity/render/action extraction only after profiling or release playtest identifies a concrete bottleneck.

Test Coverage To Add

Instantiate cardBattlePanel with a selected card, opponent card, and empty card, then assert visible name/stat labels exist.
Build inventoryRecordAdapter records from sample card instances and assert base-name sorting groups modified cards with their base card.
Build gameSettingsPanel from a JSON definition and assert changed callbacks emit stable keys/values.
Render achievement screen in full-screen mode and assert a Back action exists.
Step powerupInventoryManager through fixed-slot add/use/save/restore.
Step arcadePowerupManager through spawn, collect, expire, held-slot use, and clear-on-score.
Open a reusable field menu and assert Resume does not abandon a run while Retry/Give Up/Main Menu dispatch explicit callbacks.
Feed sample enemy states through aggro/wander rules and assert enemies wander before alert, chase after being hit, and attack only inside configured range.