# Magic Factory Demo Tasks

## Task 1: Register tools and third-party assets

**Description:** Add the portable Godot version record, import Kenney Factory Kit 3.0, and preserve provenance so every external file remains auditable and replaceable.

**Acceptance criteria:**
- [x] Godot 4.7.1 can run from a workspace-local tool directory.
- [x] Factory Kit source archive and extracted game-ready models are separated.
- [x] Author, source URL, version, license, and acquisition date are documented.

**Verification:**
- [x] Godot reports version 4.7.1 stable.
- [x] Asset archive contains its original CC0 license.
- [x] No unlicensed third-party file is present.

**Dependencies:** None

**Estimated scope:** Medium

## Task 2: Create a launchable 2.5D world

**Description:** Build the project shell, orthographic camera, lit ground, environment, and a minimal HUD using the imported visual language.

**Acceptance criteria:**
- [x] Project starts directly into a readable isometric-like factory site.
- [x] Camera pans and zooms within bounded limits.
- [x] Resolution changes do not break the HUD.

**Verification:**
- [x] Headless project import completes without script errors.
- [x] Graphical capture confirms camera composition and HUD layout.

**Dependencies:** Task 1

**Estimated scope:** Medium

## Task 3: Add grid construction controls

**Description:** Let the player choose a building type, preview its footprint, place it on the grid, rotate it, and remove it.

**Acceptance criteria:**
- [x] Valid and invalid placement previews are visibly different.
- [x] Occupied cells cannot overlap.
- [x] Rotation and removal update both world data and visuals.

**Verification:**
- [x] Automated grid occupancy and removal checks pass.
- [x] Full player-flow smoke test builds the required routes through the construction API.

**Dependencies:** Task 2

**Estimated scope:** Medium

## Task 4: Run one belt-to-machine production chain

**Description:** Implement a source, straight and corner belts, one processing machine, and a sink so an item visibly becomes another item.

**Acceptance criteria:**
- [x] Items advance on fixed simulation ticks and render smoothly between them.
- [x] Machine consumes the correct input and emits exactly one configured output.
- [x] Backpressure stops the machine without losing or duplicating items.

**Verification:**
- [x] Identical fixed-tick runs produce matching counts and state fingerprints.
- [x] Player-flow test remains correct after build, rejected overlap, removal, and replacement.

**Dependencies:** Task 3

**Estimated scope:** Medium

## Task 5: Add mana supply and pipe connectivity

**Description:** Add mana sources, pipes, and capacity-limited consumers; network topology is recalculated only when construction changes it.

**Acceptance criteria:**
- [x] Connected powered machines run and disconnected machines stop.
- [x] Shared demand above source capacity produces deterministic allocation.
- [x] Reconnecting a pipe wakes affected machines immediately.

**Verification:**
- [x] Connectivity and deterministic allocation tests pass.
- [x] Disconnect/reconnect regression preserves unfinished recipe time exactly.

**Dependencies:** Task 4

**Estimated scope:** Medium

## Task 6: Add configurable bridge arms

**Description:** Bind an overhead arm to a machine and let the player select explicit pickup and drop cells across multiple belt lanes.

**Acceptance criteria:**
- [x] Endpoint preview clearly shows valid and invalid target cells.
- [x] The arm transfers through the owning machine without an independent polling loop.
- [x] Removing an endpoint leaves the machine safely waiting for a valid belt.

**Verification:**
- [x] Transfer count remains deterministic under input and output blockage.
- [x] Full player-flow test binds explicit pickup and drop cells across a broken belt route.

**Dependencies:** Task 4

**Estimated scope:** Medium

## Task 7: Add status inspection and objective guidance

**Description:** Add a selection panel, machine stop reasons, throughput counters, construction hints, and a short objective sequence.

**Acceptance criteria:**
- [x] Selected machines expose recipe, progress, inventory, mana, and stop reason.
- [x] Objectives lead from first belt placement to first processed item.
- [x] UI never becomes authoritative simulation state.

**Verification:**
- [x] Every machine state maps to a readable UI message.
- [x] Fresh-start walkthrough can be completed without debug controls.

**Dependencies:** Tasks 5 and 6

**Estimated scope:** Medium

## Task 8: Add a second recipe and demo completion state

**Description:** Extend the chain to raw crystal, refined crystal, and charged crystal, then detect sustained final output as completion.

**Acceptance criteria:**
- [x] Two machine stages can operate continuously with belt backpressure.
- [x] Increasing a real bottleneck increases measured final throughput.
- [x] Completion is based on sustained production, not one debug-spawned item.

**Verification:**
- [x] End-to-end count conservation test passes.
- [x] Fresh-game manual completion path succeeds.

**Dependencies:** Task 7

**Estimated scope:** Medium

## Task 9: Add demo presentation and snapshot saving

**Description:** Add title/pause screens, coherent materials and mana effects, audio hooks, and one-slot world snapshot persistence.

**Acceptance criteria:**
- [x] New game, continue, pause, restart, and quit flows work.
- [x] Snapshot restores construction, transport, production, and objectives.
- [x] Industrial assets read as magical machinery through a unified material pass.

**Verification:**
- [x] Save-then-run and run-from-save produce matching state hashes.
- [ ] Manual UI flow works at 1080p and a smaller window.

**Dependencies:** Task 8

**Estimated scope:** Medium

## Task 10: Add deterministic stress generation and metrics

**Description:** Add a developer-only scene that generates representative active, blocked, and offscreen factories and reports separate simulation/render costs.

**Acceptance criteria:**
- [ ] Presets create 1k visible, 10k active, and 100k blocked entity workloads.
- [ ] Metrics show tick time, frame time, active/sleeping machines, and transported items.
- [ ] Blocked-machine per-tick cost does not grow linearly with their count.

**Verification:**
- [ ] Fixed presets produce repeatable state hashes and entity counts.
- [ ] A saved benchmark report identifies the first measured bottleneck.

**Dependencies:** Task 8

**Estimated scope:** Medium

## Task 11: Package a Windows demo build

**Description:** Configure export settings, build the playable Windows package, and verify it outside the editor.

**Acceptance criteria:**
- [ ] Export contains required assets and third-party notices.
- [ ] Demo starts without the editor or workspace-local source tree.
- [ ] Release README explains controls and current scope.

**Verification:**
- [ ] Clean-path smoke test reaches the first playable objective.
- [ ] Packaged file list contains no source archives or development-only tools.

**Dependencies:** Tasks 9 and 10

**Estimated scope:** Medium

## Post-demo progression work

The 8/24-hour full technology progression is intentionally tracked separately in `tasks/tech-tree-plan-v0.2.md` and `tasks/tech-tree-todo-v0.2.md`. It does not add hidden completion requirements to the current demo tasks.