Project Alchemy Roadmap

p

Project Alchemy is the next framework expansion target: a real-time tactical RPG where discovery, experimentation, codex knowledge, and card-based combat all reinforce one another.

Current Vertical Slice

• Main menu entry and scene target.
• Data-driven element, compound, reaction, manifestation, modifier, and card files.
• Data-driven Sprint 1 prototype file for player grid position, world grid, regions, camera, material nodes, targeting defaults, mobile controls, starter cards, and training target setup.
• Reusable alchemyManager for normalized reaction lookup.
• Reusable alchemyGraphManager for reaction graph validation, reachability checks, and dead-end discovery auditing.
• Reusable codexManager for discoveries, failed reactions, and notes.
• Reusable codex history/search rows for filtering discoveries, failures, notes, and recent experiments.
• Reusable combatCardFactory for resolving discovery unlock ids into combat deck entries and composing cards from compound + manifestation + modifier data.
• Reusable deckRotationManager for active slots, used-card rotation, and pinned-card-ready structure.
• Reusable targetingManager for projectile/beam ranges, lob landing areas, homing targets, AOE radii, and action-button range/mode summaries.
• Reusable gridWorldManager for grid bounds, obstacle-cell expansion, blocker lists, and material node pickup state.
• Reusable battlefieldGenerator for procedural tactical-grid field-test layouts.
• Reusable battlefieldGenerator mode options for randomized Arena fields and clean split-side Battle boards.
• Reusable researchLabManager for inventory-consuming reaction attempts, failure losses, and save-friendly inventory deltas.
• Reusable topDownController2D for top-down dictionary state, cardinal grid stepping, bounds, blocked cells, line traces, and obstacle collision.
• Reusable gridCombatManager for tactical-grid enemies, enemy turns/cooldowns, card damage resolution, defeated-enemy rewards, projectile/effect state, floating damage numbers, hit/action logs, combat summaries, and saveable combat dictionaries.
• Data-driven enemy archetypes for slime, ranged apprentice, and tank dummy.
• Prototype scene proving: browse locked/unlocked lab pages, start generated field tests, move through a tactical combat grid with step cooldown, camera bounds, mobile controls, collect material nodes, trigger a spell interaction, attempt reactions, record/search codex entries, unlock cards, create/deconstruct spells from compound/Form/Modifier recipes, select/cancel directional combat cards, preview player and enemy attack traces, survive simple enemy turns, recover energy, retry after defeat, collect material drops, view field results, and return to the lab after reaching the exit.
• Lab tooling now includes inventory-consuming research, Arena/Battle mode selection, graph-health diagnostics, a dedicated Loadout tab for equip editing, a dedicated Spells tab for creation/deconstruction, autosave, and three Project Alchemy save slots.
• Research Lab now lives on its own page, refreshes after inventory changes, hides unknown recipe results, and switches known recipes into craft mode.
• Reusable spellLoadoutManager now owns unlocked/equipped spell ids for Project Alchemy and future card-combat games.
• Reusable adventureManager now loads and validates multi-level Adventure JSON and creates save-friendly objective/level progress dictionaries.
• mosswood_intro.json seeds the first three-level Project Alchemy Adventure definition with handcrafted and procedural level examples.
• Sprint 11 alpha hardening adds reusable guidance panels, readable active spell slot mini-cards, structured required/optional objective rows, reward hints, and clearer exit lock/unlock messaging.
• Sprint 12 playtest response removes dead active-field navigation, routes the header Menu to an explicit field menu, starts a square active-field layout, moves status chatter into overlay/toast messaging, fixes Warden Root exit gating, and adds JSON-driven enemy aggro/wander behavior.

Next Framework Extractions

MVP-safe extractions only:

1. projectileLifecycleManager: keep projectile/lob travel state reusable and save-friendly while Project Alchemy finishes MVP combat readability.
2. Active field HUD/status helpers: promote only the pieces already proven by Project Alchemy playtests, such as field menus, resource bars, and status feeds.
3. researchLabManager and combatCardFactory: harden only the paths needed for inventory-backed research, spell creation, deconstruction, and save/load.

Post-MVP extraction backlog:

• gameSettingsPanel: render game-specific settings from JSON so Alchemy, Pong, and platformers share one settings renderer.
• targetingPreviewManager: layer richer visual previews, cones, warning zones, mine timing, and interaction targeting on top of targetingManager.
• encounterController: spawn enemies, track waves, rewards, and victory conditions.
• biomeManager: load region/biome data, material tables, enemy tables, and environmental rules.
• worldInteractionManager: expand the first spell-interaction hook into chains, puzzles, hazards, and biome-specific environmental rules.
• battlefieldGenerator: expand Arena/Battle templates with encounter tables, wave rules, and reward tuning.
• researchLabManager: add catalysts, derived known-recipe crafting, and richer tutorial-friendly result formatting.
• adventureManager: expand beyond the MVP Adventure into additional authored stories, optional content, scripted events, and long-form progression.

Planned Mode Flow

Project Alchemy should separate the lab loop from active field tests:

• New games and loaded saves should land on the Project Alchemy lab/menu layer.
• The lab/menu layer should expose Game Selection, Codex, Spells, Loadout, Research Lab, and Inventory pages.
• Active field tests should lock those lab pages until the current level or level chain is completed.
• Reaching an exit returns the player to the lab/menu layer with collected resources, discoveries, and unlocked spell/research options intact.

Arena Mode

Arena mode keeps the current generated battlefield direction:

• randomized battlefield layout
• free movement across the whole grid
• obstacles, material nodes, enemies, spell interactions, and exits
• appropriate for exploration, biome tests, environmental interactions, and future wave/encounter chains
• rewards: 1 random Form and 1 random Modifier

Battle Mode

Battle mode should be a clean side-vs-side tactical format:

• board split into left and right halves
• supported half sizes: 3x3, 4x4, and 5x5
• player side is always the left half
• enemy side is always the right half
• neither side can cross the center line
• no rocks, no reserved environment squares, no random obstacle cells, and no material nodes in the first implementation
• attacks are resolved by range and mode across the split, making targeting, equipped spells, and positioning the core decisions
• rewards: 1 random Form or 1 random Modifier

Adventure Mode

Adventure mode should become the primary story/progression mode:

• 3+ connected levels per Adventure
• health persists between levels
• exits lead directly to the next level after objectives are complete
• higher rewards than Arena/Battle, including Forms, Modifiers, and Elements
• each Adventure is one JSON definition, even when it contains multiple levels
• levels may be handcrafted or reference procedural templates
• levels can vary in size and should not be constrained to one map dimension
• Adventure JSON should define level metadata, terrain properties, object placement, objectives, scripted events, rewards, secrets, and story flags

Research Lab Inventory Loop

Research should become inventory-driven:

• The player chooses two elements from current inventory.
• A successful combination consumes both inputs and adds the resulting element or compound to inventory.
• A failed combination randomly destroys one input and returns the other.
• All attempts are recorded in codex history.
• The next implementation should make inventory deltas explicit so the UI, save state, and future tutorials can all use the same result data.
• Previously researched combinations should show their known result and switch from discovery mode to craft mode.
• Unknown combinations should hide their result as Unknown.
• Research Lab lives on a dedicated page and should next receive richer recipe details, catalysts, and clearer result panels.
• Research discoveries are knowledge first: they should not automatically create spell cards. Spells are crafted separately from inventory on the Spells page.

Inventory Categories

Project Alchemy inventory should be categorized for both UI and save state:

• Resources/Elements
• Forms
• Modifiers
• Consumables
• Items

Forms and Modifiers are rewards from Arena/Battle/Adventure and are consumed when creating a spell. New games start without Forms, but the Spells page offers None as a form choice for a one-tile element attack. Creating a spell consumes 3x of the selected compound; deconstructing a spell returns only 1x compound plus any Form and Modifier used.

Current status: the save/UI schema now tracks Resources, Forms, Modifiers, Consumables, and Items separately. Arena/Battle reward quantities are defined in prototype.json; spell creation consumes compound plus Form/Modifier inventory, created/equipped spells can be deconstructed back into partial source parts, and field completion displays a first-pass results popup with awarded Forms, Modifiers, and resources collected during the run.

Platformer/Action Support Shared With Alchemy

• Use topDownController2D for grid/action RPG rooms and combat arenas.
• Keep characterController2D focused on side-view platforming.
• Extend physicsEngine with sensor bodies, projectile queries, and hazard zones.
• Reuse powerupInventoryManager for held catalysts, consumables, and quick-slot tools.
• Reuse levelManager for small tactical grids and later arena maps.

Milestones

1. Sprint 0/1: scaffold Project Alchemy scene, data, save state, and debug-friendly prototype UI.
2. Sprint 2: add projectile/hit detection, visible combat feedback, simple enemy behaviors, and defeat/retry flow.
3. Sprint 3: expand reaction data toward 20 compounds, add richer discovery card unlocks, material drops, combat readability, and reaction graph validation.
4. Sprint 4: add codex views, reaction history, reaction graph inspection UI, failed-experiment search, first environmental spell interactions, mode selection, and spell equip editing.
5. Sprint 5: finish the first data-driven card composition slice, Spells tab creation/deconstruction, created-card persistence, and Project Alchemy save slots.
6. Sprint 6: expand active slots to 10, add random rotation after use, add Auto Mode, tune enemy damage, and pressure-test deck rotation.
7. Sprint 7: complete the first Forest biome vertical slice seed. The closeout includes a larger Mosswood Edge arena, denser material nodes, JSON-tuned obstacle density, forest enemies, an Old Growth Warden boss archetype, field results when returning to the lab, a data-driven objective panel, Mosswood spell-interaction points, weighted reward tables, and Auto Mode enemy-turn gating.
8. Sprint 8: add Adventure mode JSON definitions and reusable multi-level progression scaffolding. First pass includes adventureManager, the mosswood_intro three-level data file, Adventure as a lab Game Selection mode, selector/detail controls, level-to-field conversion, saveable adventure run state, carried health, connected-level advancement, a first transition popup, during-play objective persistence, per-level rewards, an Adventure save fixture, and fixed Adventure completion rewards.
9. Sprint 9: closed the first Adventure expansion pass. The closeout includes Adventure progress summaries, saved progress display in the selector, optional secret objective data, scripted event placeholders, research/crafting separation, 3x spell creation costs, spell cooldowns, run collection summaries, a non-soft-lock Mosswood bramble objective, and the first JSON-driven sprite assignment layer with a reusable sprite mapper seed.
10. Sprint 10: polish sprite assignment and Adventure presentation. Completed work includes visual spritesheet grid picking, direct PNG browsing, explicit sprite source modes, safer JSON save/restore flows, generated JSON validation, clear/reset mapping support, dedicated Adventure objective and reward cards, smooth grid-step/projectile presentation, cross-game sprite map coverage, and a second authored Adventure for selector/detail tuning. Remaining work is more final Project Alchemy sprite assignment, in-game scripted-event/codex presentation, and reusable inventory category panels.
11. Sprint 11: alpha MVP hardening. Current work improves playtest readability through data-driven lab/field guidance, active spell mini-card controls, structured objective rows, reward hints, and explicit exit lock/unlock state. Next work should be driven by playtest feedback, Mosswood Initiation pacing, final-enough sprite assignment, and first-run tutorial flow.
12. Sprint 12: alpha playtest response and MVP closeout. Implementation now removes prototype-only field chrome, hides inactive lab navigation during active runs, routes header Menu into a field menu with Resume/Retry/Give Up/Settings/Main Menu, starts square field sizing, replaces Focus with energy recovery rules, fixes Adventure exit soft locks, separates unknown research from known crafting, adds gold as a saved currency, and introduces JSON-driven enemy aggro/wander behavior. MVP implementation is wrapped; remaining work is validation and tuning: field camera/fog stability, projectile/lob readability, Mosswood pacing, tutorial copy validation, and final-enough readable sprites. Current MVP save/load shape is covered by fixture migration and scene-level active-field restore smoke tests. Consumable/item actions, achievement filtering, single-game packaging, map editors, and expanded equipment systems are post-MVP backlog.

Historical Next Session Handoff

This handoff is retained for Project Alchemy-specific context. Active repository planning now lives in Release Sprint Plan. Start Project Alchemy follow-up with playtest validation rather than new feature scope:

1. Confirm active field Menu behavior: Resume should close the menu; Retry should restart the field; Give Up should return to the lab without current run pickups/rewards; Main Menu should be an explicit abandon route.
2. Verify the square active field on desktop and mobile browser sizes. The desired end state is a stable square camera with fog/shadow outside the viewable area and no board zooming when enemies die or attacks resolve.
3. Tune enemy aggro values in data/games/project_alchemy/enemies.json after playtest. Enemies should feel alive without beelining across the entire map.
4. Avoid new feature scope unless playtest proves it blocks MVP comprehension. Stable active-run helpers already exist for field menus, resource bars, status feeds, projectile lifecycle, and pooled sprite rendering.
5. Only make Sprint 12 lab polish changes if playtest shows confusion around known-recipe labels, reward clarity, or tutorial copy. Spell creation/deconstruction clarity and current MVP save/load confidence have smoke coverage. Gold/sell actions, consumable/item use, and richer spell-card presentation are post-MVP.