Add two-stage charged-crystal demo and original art set.

2026-08-13 13:18:41 +08:00
commit e9f5f81f46
686 changed files with 25601 additions and 0 deletions
@@ -0,0 +1,114 @@
+# 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
+
+```text
+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.