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,122 @@
+# Implementation Plan: Magic Factory Demo
+
+## Overview
+
+Build a small but presentable 2.5D factory game demo in Godot. The player will place belts, machines, mana pipes, and a configurable bridge arm to complete a two-stage magical production chain. The demo uses a coherent CC0 asset pack from the beginning, while all gameplay state remains independent from scene nodes so large-factory performance work is not blocked by the presentation layer.
+
+## Demo promise
+
+The first public-facing slice starts on a small floating factory site and ends when the player continuously produces charged crystals. It must feel like a game rather than an engineering benchmark: it has a title screen, readable construction controls, visible production, machine status feedback, a short objective sequence, sound-ready hooks, and a clear completion state.
+
+## Architecture decisions
+
+- Godot 4.7.1 stable, standard Windows build, with GDScript for the first playable slice.
+- 3D world with an orthographic camera and fixed grid: 2.5D presentation without 2D simulation assumptions leaking into rendering.
+- Simulation advances on a fixed integer tick and is stored in plain data keyed by integer IDs. Scene nodes mirror state; they are not authoritative gameplay objects.
+- Machines do not poll every rendered frame. They wake for exact state-changing events such as input arrival, output space, recipe completion, and mana-network changes.
+- The first logistics route is belt-to-machine. Bridge arms belong to machines and select explicit belt endpoints; there is no independent inserter entity layer.
+- Kenney Factory Kit 3.0 is the initial visual base. Its source archive, CC0 license, URL, version, and acquisition date stay in the repository.
+- Performance tooling is a developer-only mode inside the demo, not the user-facing premise.
+
+## Dependency graph
+
+```text
+Godot project + licensed asset pack
+             |
+             v
+2.5D world + camera + grid
+             |
+             v
+fixed-tick world data + commands
+             |
+      +------+------+
+      |             |
+      v             v
+belt transport   build controls
+      |             |
+      +------+------+
+             v
+machine production
+             |
+      +------+------+
+      |             |
+      v             v
+mana network    bridge arm
+      |             |
+      +------+------+
+             v
+objective flow + polish
+             |
+             v
+stress scene + release check
+```
+
+## Task list
+
+### Phase 1: Playable foundation
+
+- [x] Task 1: Register tools and third-party assets
+- [x] Task 2: Create a launchable 2.5D world
+- [x] Task 3: Add grid construction controls
+- [x] Task 4: Run one belt-to-machine production chain
+
+### Checkpoint: First playable loop
+
+- [x] Project opens without import errors in Godot 4.7.1
+- [x] Player can place a belt and machine with mouse controls
+- [x] A visible item travels into a machine and becomes a visible output item
+- [x] Simulation outcome is independent from render frame rate
+
+### Phase 2: Distinctive game systems
+
+- [x] Task 5: Add mana supply and pipe connectivity
+- [x] Task 6: Add configurable bridge arms
+- [x] Task 7: Add status inspection and objective guidance
+- [x] Task 8: Add a second recipe and demo completion state
+
+### Checkpoint: Demo identity
+
+- [x] Player can diagnose every stopped machine from the UI
+- [x] Bridge arms can cross several belt lanes without becoming standalone ticking entities
+- [x] Mana shortage visibly stops and later resumes production
+- [x] The first complete production chain can be built from a fresh game
+
+### Phase 3: Presentation and scale guardrails
+
+- [ ] Task 9: Add menu, save snapshot, audio hooks, and visual polish
+- [ ] Task 10: Add deterministic stress generation and metrics
+- [ ] Task 11: Package a Windows demo build
+
+### Checkpoint: Demo ready
+
+- [x] Fresh player can reach continuous charged-crystal production
+- [ ] CC0 assets have traceable license records
+- [ ] Fixed-seed automated runs produce identical state hashes
+- [ ] Stress mode reports simulation and rendering costs separately
+- [ ] Windows build launches on a clean path outside the editor
+
+## Explicitly deferred
+
+- Combat, enemies, character control, story campaign, research tree, procedural world generation, multiplayer, mod loading, pressure-based fluid simulation, final commissioned art, and a native C++ simulation extension.
+- C++ is reconsidered only after the representative stress workload identifies a measured hot path that the data layout and scheduler cannot solve in GDScript.
+
+## Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---:|---|
+| Free assets make the game look generically industrial | High | Use one coherent pack, recolor materials, and add a small original mana/rune visual layer before adding more packs. |
+| Scene-node architecture grows with factory size | High | Keep authoritative simulation in arrays/dictionaries and render only visible state. |
+| Bridge-arm setup is tedious | High | Validate source/destination selection in the first production chain and add strong previews and error feedback. |
+| Mana pipe rules become a second fluid simulator | Medium | Demo supports capacity and connectivity, but no pressure, temperature, or free-form fluid physics. |
+| Early polish hides an unscalable core | High | Ship a stress generator and deterministic counters before expanding the recipe catalog. |
+
+## Open decisions with safe defaults
+
+- Reference hardware: use the current development PC until a minimum target specification is chosen.
+- Art direction: Kenney industrial forms with dark stone, brass, cyan mana, and violet high-tier energy.
+- Input: mouse and keyboard first; controller support deferred.
+- Distribution: Windows desktop first.
+
+## Post-demo progression
+
+The research tree remains outside the Tasks 1–11 demo scope, but its current full-game design is specified in `docs/tech-tree-v0.2.md`. Data and implementation work is dependency-ordered in `tasks/tech-tree-plan-v0.2.md` and `tasks/tech-tree-todo-v0.2.md`; it starts only after the demo-ready checkpoint unless the project scope is explicitly changed.