Untitled Colony Builder

A low-poly, orthographic 3D colony builder set on a moon orbiting a gas giant. You accept a construction contract, land a colony centre, build an extraction and processing chain, survive the moon's threat cycles, meet the contract goals and then leave — the colony stays behind.

Inspired by Against the Storm's run-based structure, with logistics closer to The Settlers 2 than to belt automation.

Status

Early. The map and control systems are being built up; there is no game to play yet.

Working today:

• Seeded terrain generation — a GridMap with heights quantised into integer terraces, four presets (plains, island, crater, canyon), generated at runtime with no art assets
• A* pathfinding across terrain, where walkability is a property of the edge rather than the tile, so a cliff has no connection across it while both its tiles remain walkable
• Building placement with footprints, entrances, placement rules and a build panel
• Pawns — a record, a registry, and a mover that walks a path and rides the terraces
• A game clock, a task tree, and a task manager
• Orthographic camera rig with yaw, pitch and zoom

Not started: resources and deposits, the work loop that connects pawns to tasks, environmental threats, contracts, and both meta loops.

The design in three loops

1. Run loop — accept a contract, land, scout, build extraction → processing chains, survive the threat cycles, meet the goals, launch. Scored on build goals, extraction goals, and the sustainability of what you leave behind, since colonies persist after the crew departs.
2. Meta loop — spend cash and XP on your home ship, itself a mini colony builder with adjacency bonuses. This is the tech tree; there is no in-run research.
3. Meta-meta loop — accumulate resources across runs toward a megastructure win condition.

Constraints that shape the code

These are design decisions with teeth — they constrain the data model, not just the content:

• Threats are deterministic cycles, not a random director. Eclipses, radiation belts, tidal quakes and the rest derive from orbital mechanics on nested periods, so they must be computable ahead of time and displayed as a forecast. They are a schedulable timeline queried by lead time, not roll-per-tick events.
• Forecast lead time is a purchased resource. Sensor tier sets how far ahead you can see.
• No building's upkeep is denominated in its own output. An electronics plant repairs on metal and labour, never electronics. This kills death spirals by construction, and is enforced in the data schema rather than by convention.
• A subsistence floor never depends on the advanced chain, and one "Emergency Protocols" toggle reprioritises all labour and power to life support.
• Difficulty has two independent axes — Pressure (threat frequency and scarcity) and Complexity (how many systems interact, how deep the chains go).
• Failure is recoverable. A colonist's death is a workforce and specialisation loss, not a cascading morale collapse.

Rationale for all of the above is in docs/colony-builder-ideas.md.

Running it

Godot 4.7 (currently 4.7.2), GL Compatibility renderer, Jolt for 3D physics, GDScript throughout. Godot is expected on PATH.

GODOT=Godot_v4.7.2-stable_win64_console.exe

"$GODOT" --path . --headless --quit   # import assets / validate
"$GODOT" --path .                     # run the game
"$GODOT" --path . --editor            # open the editor

Use the _console.exe variant from a terminal. The plain .exe is a Windows GUI app and detaches, so print() output and stack traces are lost.

Two things that bite:

• Adding a class_name needs an editor scan, not just an import pass: --headless --editor --quit. Without it, every use of the new type fails to parse.
• Headless renders nothing under GL Compatibility. Anything visual has to be checked with a real window.

Tests

GUT 9.7.1, vendored in addons/gut/. Configuration lives in .gutconfig.json.

"$GODOT" --path . --headless -s addons/gut/gut_cmdln.gd            # everything
"$GODOT" --path . --headless -s addons/gut/gut_cmdln.gd -gselect=pawn   # one script

Tests live in test/unit/, one script per subject. They cover logic, not rendering — a green suite says nothing about how anything looks, because headless draws nothing. Visual checks are manual and screenshot-based; tools/ holds throwaway probe scripts that build a scene, render it headed and save a PNG for exactly that purpose.

Layout

common/      the game scene and its setup
entities/    terrain, buildings, pawns, tasks, camera
globals/     autoloads (GameState, GameClock)
ui/          menus, build panel, debug layer, tooltips
test/unit/   GUT tests
tools/       throwaway probe and screenshot scripts
docs/        design drafts
addons/gut/  vendored test framework

Design docs

Written in Obsidian, so they carry frontmatter and [[wikilinks]]; some link targets live in a personal vault rather than this repo.

Document	Covers
colony-gameplay-loop.md	The three nested loops, and what completing a contract looks like
colony-builder-ideas.md	Rationale for the design constraints above
colony-game-resource-types.md	The three resource tiers
colony-game-facilities.md	Extraction and processing facilities
colony-game-environmental-threats.md	The orbital threat cycles
colony-game-contract-types.md	Contract varieties and goals
resource-prospecting.md	Finding deposits on a fresh map

Tracker

Issues, bugs and tasks live in the forgejo issue tracker. Larger bodies of work are milestones, with issues as the units of work beneath them. Issues and pull requests share one number sequence.

Branch from a freshly fetched origin/main, named <issue>-<short-slug>. The repo uses merge commits rather than squashes, so branch commits become real ancestors of main and individual commit messages survive — worth writing properly.

CLAUDE.md holds the working notes for this repo: engine gotchas, conventions inherited from the proof-of-concept, and the constraints that were found by failing at them.