123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
# 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
|
||
|
||
- [x] 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.
|