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

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

Task 1: Register tools and third-party assets
Task 2: Create a launchable 2.5D world
Task 3: Add grid construction controls
Task 4: Run one belt-to-machine production chain

Checkpoint: First playable loop

Project opens without import errors in Godot 4.7.1
Player can place a belt and machine with mouse controls
A visible item travels into a machine and becomes a visible output item
Simulation outcome is independent from render frame rate

Phase 2: Distinctive game systems

Task 5: Add mana supply and pipe connectivity
Task 6: Add configurable bridge arms
Task 7: Add status inspection and objective guidance
Task 8: Add a second recipe and demo completion state

Checkpoint: Demo identity

Player can diagnose every stopped machine from the UI
Bridge arms can cross several belt lanes without becoming standalone ticking entities
Mana shortage visibly stops and later resumes production
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

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.

6.0 KiB Raw Permalink Blame History Unescape Escape