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

Implementation Plan: Full Technology Progression (superseded)

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

Overview

Turn the design in docs/tech-tree-v0.1.md into a data-driven research and progression system after the current demo loop is stable. The implementation proceeds in playable vertical slices: first load and validate the catalog, then make each era playable from mining through research unlock, and finally add the heart-furnace victory loop and pacing telemetry. This is post-demo scope and does not change the completion bar for Tasks 1–11 in tasks/plan.md.

Architecture decisions

• The CSV is a design interchange file, not runtime authority. Runtime content should use a typed Godot Resource or equivalent structured data generated from the same identifiers.
• Technologies, recipes, buildings, UI labels, save data, and achievements reference stable IDs; display names remain localizable data.
• Research is fixed-tick and event-driven like the current machine simulation. A lab wakes on input, queue, completion, or unlock changes rather than polling independently each frame.
• Unlock evaluation lives in the simulation layer. UI only displays state and submits commands.
• Every era is delivered as a complete loop: resource access → processing → research material → gate technology → visible objective.
• The 8/24-hour targets are verified by route simulation and instrumented playtests, not inferred from green unit tests.

Dependency graph

TT1 catalog contract
        |
        +----> TT2 graph/cost validator
        |
        v
TT3 research runtime ----> TT4 UI + save
        |
        v
TT5 T0/T1 slice -> TT6 T2 slice -> TT7 T3 slice -> TT8 T4 slice -> TT9 T5 + victory
                                                              |              |
                                                              +------>-------+
                                                                     v
                                                          TT10 optional/postgame
                                                                     |
                                                                     v
                                                          TT11 telemetry/tuning

Task list

Phase 1: Data and rules

• TT1: Define stable technology, recipe, building, and unlock IDs
• TT2: Add dependency validation and route-cost simulation
• TT3: Implement fixed-tick research runtime
• TT4: Add research UI, queue commands, and save state

Checkpoint: Research foundation

• The full catalog loads with no duplicate, missing, cyclic, or role-invalid dependency
• A headless test researches a node by consuming exact item counts
• Save/load preserves completed and partial research exactly

Phase 2: Early playable progression

• TT5: Deliver T0/T1 from repair milestones to automated cyan tablets
• TT6: Deliver T2 mana-logistics and ether-fluid introduction

Checkpoint: Early game

• A fresh run reaches crimson-tablet production without debug spawning
• Existing belt, mana-pipe, and bridge-arm behavior remains deterministic
• Every stopped lab or production machine exposes a readable reason

Phase 3: Midgame scale

• TT7: Deliver T3 alchemy, precision construction, and leyline survey
• TT8: Deliver T4 cross-island shipping, phase metallurgy, and emerald tablets

Checkpoint: Midgame

• At least one required resource must arrive from another island
• Violet and emerald recipes exercise the intended multi-stage chains
• A reference factory meets the normal and expert tablet-rate targets

Phase 4: Endgame and continuation

• TT9: Deliver T5 source extraction, heart furnace, timed ignition, and achievements
• TT10: Add comfort, warding, and repeatable postgame branches

Checkpoint: Complete progression

• Mainline can finish without researching any O-role node
• Completing G13 alone cannot trigger victory
• First stable ignition records one authoritative completion time and unlocks postgame research

Phase 5: Pacing proof

• TT11: Add route telemetry, benchmark saves, and 8/24-hour balance gates

Checkpoint: Release candidate

• Expert-route P50 is at most 7:15 and P90 at most 8:00
• Experienced first-play P50 is 18–21 hours and P75 at most 24:00
• No mainline wait exceeds five minutes when the era reference factory meets target throughput

Risks and mitigations

Risk	Impact	Mitigation
Sixty-two technologies create content before the core is fun	High	Implement by era and stop at every checkpoint for a complete playable test
Research logic duplicates recipe/building unlock rules	High	One ID-based unlock service is authoritative for simulation, UI, and saving
Random map distance determines achievement validity	High	Clamp required-resource distance and ship fixed benchmark seeds
Optional automation becomes secretly mandatory for 24 hours	High	Maintain a no-comfort-tech reference route and compare it with the recommended route
Speedrun balance removes normal-player breathing room	High	Tune guidance and convenience separately from mainline material cost
High-tier factories overload scene nodes	High	Preserve data-oriented simulation, sleeping machines, and batched visible rendering

Open decisions with safe defaults

• Hostile enemies: default to environmental hazards and optional warding until combat receives its own approved design.
• Campaign map: use a bounded handcrafted resource topology for balance tests; procedural variants must satisfy the same distance envelope.
• Localization names: treat names in v0.1 as Chinese working names while IDs remain stable.
• Achievement clock: count simulation time only, excluding pause/load/non-interactive cutscenes.
• Existing demo: keep its all-tools-available showcase mode even after campaign unlock rules exist.