magic-factorio/tasks/tech-tree-todo.md

Full Technology Progression Tasks (superseded)

Superseded by tasks/tech-tree-todo-v0.2.md. Retained only as a record of the rejected factory-reskin direction.

TT1: Define the progression data contract

Description: Create stable IDs and typed records for technologies, research costs, prerequisites, recipes, buildings, unlocks, and postgame formulas. Import the v0.1 catalog without putting unlock conditions in UI code.

Acceptance criteria:

• Every row in docs/tech-tree-nodes-v0.1.csv maps to one runtime record.
• Display names can change without changing save-compatible IDs.
• Mainline, comfort, optional, and postgame roles are explicit data.

Verification:

• Headless catalog-load test reports 76 records.
• Unknown pack, technology, recipe, or unlock IDs fail with an actionable message.
• Existing simulation smoke tests still pass.

Dependencies: None

Files likely touched:

• src/data/technology_definition.gd
• src/data/technology_catalog.gd
• src/data/technology_catalog.tres
• tests/technology_catalog_smoke.gd

Estimated scope: Medium

TT2: Validate the graph and simulate route costs

Description: Add tooling that validates the dependency DAG and computes a selected route's tablet totals, lab-seconds, earliest unlocks, and final heart-furnace materials.

Acceptance criteria:

• Validator rejects duplicates, missing prerequisites, cycles, and any M node that transitively depends on O.
• Mainline totals equal Q 11,220; A 10,920; R 9,990; V 8,400; G 5,300.
• Simulator can compare mainline, recommended-normal, and custom routes.

Verification:

• Fixture tests cover each invalid-graph class.
• Golden output records per-era cost and theoretical lab bottlenecks.
• CI exits nonzero if catalog validation fails.

Dependencies: TT1

Files likely touched:

• src/data/technology_graph.gd
• tools/progression_calculator.gd
• tests/technology_graph_smoke.gd
• tests/fixtures/technology_graphs.tres

Estimated scope: Medium

TT3: Implement the fixed-tick research runtime

Description: Add research queues, lab input consumption, partial progress, completion events, and unlock commands while preserving the simulation's event-driven scheduling.

Acceptance criteria:

• Labs consume one exact tablet set per completed unit and never duplicate or lose items.
• Loss of an input pauses exact progress and input restoration wakes the lab.
• Completing a technology emits one idempotent unlock event.

Verification:

• Fixed-seed runs produce identical research fingerprints.
• Disconnect/reconnect tests preserve partial unit progress exactly.
• Parallel labs complete the same technology without over-consuming the final unit.

Dependencies: TT1, TT2

Files likely touched:

• src/simulation/research_system.gd
• src/simulation/world_simulation.gd
• tests/research_simulation_smoke.gd
• tests/simulation_smoke.gd

Estimated scope: Medium

TT4: Add research UI and persistence

Description: Let players inspect the graph, understand missing prerequisites and materials, manage the queue, and resume exact progress after save/load.

Acceptance criteria:

• Locked, available, queued, active, and complete states are visually distinct.
• Selecting a node shows prerequisites, exact cost, unlocks, and current bottleneck.
• Save/load preserves completion, queue order, invested tablets, timer, and achievement eligibility.

Verification:

• UI only submits research commands and never grants unlocks directly.
• Save-then-run and uninterrupted-run fingerprints match.
• Keyboard/mouse navigation works at 1280×720 and 1920×1080.

Dependencies: TT3

Files likely touched:

• src/ui/research_screen.gd
• scenes/ui/research_screen.tscn
• src/persistence/world_snapshot.gd
• tests/research_save_smoke.gd

Estimated scope: Medium

TT5: Deliver the T0/T1 vertical slice

Description: Build the campaign opening from repair milestones through automated mining, refinement, bridge arms, and continuous cyan-tablet production.

Acceptance criteria:

• A fresh player can reach C11 using only produced resources and objective guidance.
• Existing demo entities map to progression IDs without changing their deterministic behavior.
• Cyan production at 15/min is achievable with a clearly readable small factory.

Verification:

• Fresh-start headless scenario completes all six milestones and C11.
• Manual walkthrough needs no developer controls or hidden starter stock.
• Regression suite for belts, mana, and bridge endpoints passes.

Dependencies: TT4

Files likely touched:

• src/data/era_t0_t1_content.tres
• src/simulation/objective_system.gd
• src/main.gd
• tests/era_t1_flow_smoke.gd

Estimated scope: Medium

TT6: Deliver the T2 mana-logistics slice

Description: Add second-tier belts and bridge arms, mana stabilization, spirit-sand glasswork, ether-fluid handling, and the crimson-tablet gate.

Acceptance criteria:

• The first fluid recipe requires pumps and storage but has no unrecoverable deadlock.
• Disconnecting mana or fluid produces a precise stop reason and resumes safely.
• The reference build sustains 15 crimson tablets per minute.

Verification:

• Automated flow covers A01 through A12 from a T1-complete save.
• Fluid and mana conservation tests pass under backpressure.
• Bridge II range and filters match catalog data.

Dependencies: TT5

Files likely touched:

• src/data/era_t2_content.tres
• src/simulation/fluid_network.gd
• src/simulation/world_simulation.gd
• tests/era_t2_flow_smoke.gd

Estimated scope: Medium

TT7: Deliver the T3 alchemy slice

Description: Add elemental separation, alchemical synthesis, thermal mana, precision construction, leyline survey, and violet-tablet production.

Acceptance criteria:

• R13 can be reached without any C or O technology.
• Byproducts back up visibly and can be routed or voided through an explicit recipe.
• The reference build sustains 20 violet tablets per minute for normal pacing.

Verification:

• Automated flow covers the mandatory T3 route from a T2-complete save.
• Conservation and deterministic allocation tests include solid, fluid, and mana networks.
• Optional construction golems do not appear in the mandatory dependency closure.

Dependencies: TT6

Files likely touched:

• src/data/era_t3_content.tres
• src/simulation/recipe_system.gd
• src/simulation/resource_survey.gd
• tests/era_t3_flow_smoke.gd

Estimated scope: Medium

TT8: Deliver the T4 cross-island slice

Description: Add bounded floating-island expansion, bulk shipping, deep leyline mining, phase metallurgy, spirit processors, and emerald-tablet production.

Acceptance criteria:

• A mandatory late resource is obtained from another island and moved by an automated route.
• Required-resource distances stay inside the achievement-safe generation envelope.
• The reference build sustains 20 emerald tablets per minute for normal pacing.

Verification:

• Fixed benchmark seeds expose all critical resources in allowed distance bands.
• Cross-island transport preserves item counts across save/load.
• Automated flow reaches V13 without comfort or warding nodes.

Dependencies: TT7

Files likely touched:

• src/data/era_t4_content.tres
• src/simulation/island_logistics.gd
• src/world/resource_topology.gd
• tests/era_t4_flow_smoke.gd

Estimated scope: Medium

TT9: Deliver T5 and the heart-furnace victory loop

Description: Add source extraction, perpetual mana, warp logistics, heart components, furnace assembly, 300-second ignition, authoritative victory timing, and both limit achievements.

Acceptance criteria:

• G13 unlocks the ignition process but does not itself win the game.
• The furnace consumes exact structure and component totals and pauses safely on mana loss.
• Completion at 8 hours grants both achievements; completion after 8 but by 24 grants only the 24-hour achievement.

Verification:

• Accelerated deterministic test runs the entire final sequence without debug item injection.
• Boundary tests cover 07:59:59, 08:00:00, 23:59:59, and 24:00:00.
• Save/load during component assembly and ignition preserves exact progress and clock state.

Dependencies: TT8

Files likely touched:

• src/data/era_t5_content.tres
• src/simulation/victory_system.gd
• src/simulation/achievement_clock.gd
• tests/victory_flow_smoke.gd

Estimated scope: Medium

TT10: Add optional and postgame branches

Description: Implement comfort automation, modules, construction/logistics golems, warding, sky tablets, and seven repeatable technology lines without altering the mainline closure.

Acceptance criteria:

• Every C technology has a measurable convenience or payback claim.
• Standard campaign can finish with every O technology locked.
• Repeatable costs follow catalog formulas and cannot overflow save or UI values.

Verification:

• Dependency validator still reports no M-to-O path.
• Mainline route totals remain unchanged after optional content loads.
• Repeatable levels 1, 10, and 50 calculate deterministically.

Dependencies: TT9

Files likely touched:

• src/data/optional_technology_content.tres
• src/data/postgame_technology_content.tres
• src/simulation/research_system.gd
• tests/postgame_research_smoke.gd

Estimated scope: Medium

TT11: Prove and tune 8/24-hour pacing

Description: Instrument progression timestamps and bottlenecks, create reference saves/routes, run structured expert and normal playtests, then tune against percentile targets.

Acceptance criteria:

• Telemetry records every metric listed in the design without collecting personal data.
• Expert P50/P90 and normal P50/P75 meet the agreed limits on standard maps.
• Each tuning change names the observed bottleneck and preserves route identity.

Verification:

• Benchmark report compares at least three expert runs and eight first-play runs.
• Automated route simulation agrees with catalog costs and benchmark save inventories.
• Final release checklist contains no unexplained wait above five minutes.

Dependencies: TT9, TT10

Files likely touched:

• src/telemetry/progression_metrics.gd
• tools/progression_report.gd
• tests/progression_benchmark_smoke.gd
• artifacts/progression-benchmark.md

Estimated scope: Medium