# 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.