Factory Core

Deterministic, headless-tested belts, machines and power for your Godot 4 automation game.

Typed GDScript kit for Godot 4.7 (tested on 4.7.2). Version 0.5.0.

Features

• Flow-graph belt simulation with gap-based belt lines (no per-item physics); two-lane belts with side-loading and underground tunnels
• Machines with input/output buffers and recipes, Mk1–Mk3 tiers (speed/power per mille), recipe switching
• Splitters with filter and fair mergers
• Power grid with generators and brownout
• Throughput stats and a heuristic bottleneck finder with colour overlay (idle/working/starved/blocked/no power)
• Deterministic fixed tick – FactorySim.step(n) runs fully headless
• Grid build mode: data-driven hotbar, ghost preview (valid/invalid), rotation, drag-placed belt lines with auto-connect, removal with refund and cost hooks
• Undo/redo (restores items of removed nodes), blueprints: capture, rotate, paste, serialize
• Items, recipes and buildables as Resources or loaded from JSON, with FactoryDB.validate()
• JSON save/load with migrations
• Camera pan/zoom and a 120x80 demo map with iron/copper ore fields (drills need ore)
• JSON build scripts for starter layouts; reskin via skin.json + PNGs
• Demo chain: ore → plates → gears, wire → circuits → motors (8 items, 6 recipes, 15 buildables)

What's included

• Full Godot 4.7 project (addons/ plugin code + examples/ demo scene)
• Headless test suite: 249 checks in 33 sections, strict runner tools/run_tests.sh
• README, AGENTS.md, design notes, CHANGELOG
• CREDITS.md and ASSET_LICENSES.md
• Assets: Original 16x16 pixel art (generated by included script), Kenney CC0 sfx, two CC0 music tracks from OpenGameArt
• Web (HTML5) export preset

Tested

249 automated checks pass headless on Godot 4.7.2 (0 failures, 0 script errors).

Not included (by design)

• 1x1 buildables only; no inserters/arms, fluids, trains, robots or logic network
• One power network per sim; no poles, fuel or accumulators
• Bottleneck finder is a heuristic, not full flow analysis
• Tested headless on Godot 4.7.2 (plus scripted headless-Chrome run of the web build); real browsers/devices not tested

Lite vs Pro

Feature	Lite (free, MIT)	Pro (paid, EULA)
Data-driven items/recipes/buildables (Resources or JSON)	✅	✅
Deterministic headless sim, throughput stats	✅	✅
Two-lane belts with side-loading, backpressure	✅	✅
Source, sink, machines (recipes, buffers)	✅ Mk1	✅ Mk1–Mk3 tiers, recipe switching
Splitter and fair merger	✅	✅ + filter splitter
Underground tunnels	–	✅
Power grid, generators, brownout	–	✅
Bottleneck finder + colour overlay	–	✅
JSON save/load	✅ basic	✅ + versioned migrations
Grid build mode: ghost, drag belts, auto-connect, refund, hotbar	–	✅
Undo/redo, blueprints	–	✅
Playable demo game, camera, ore map, inspector	Minimal debug scene	✅
Pixel art, sfx, music (CC0)	–	✅
Headless tests	Lite subset	✅ 249 checks
Web export preset, build scripts, reskin	–	✅
Licence	MIT	Commercial EULA (per seat)

The Pro price buys the full kit above. See lite-scope.md for details.

Licence

Lite is free under the MIT License. Pro is sold under a commercial per-seat EULA (see EULA-Pro.md): each developer needs a seat. You can use it in unlimited commercial and non-commercial games, including shipped binaries. You may not resell or redistribute the kit's source or assets as a template or asset pack. Bundled third-party art/audio is CC0 and keeps its own licence – see CREDITS.md.

Code and docs written with AI coding agents.