gamedev-the-steward/README.md

The Steward

The Steward is a Godot 4.7 simulation prototype about readable autonomous village life in a magical Jajce-inspired valley. The project is built as a living systems garden: simulation state is authoritative, while scenes provide presentation, navigation, and interaction geometry.

Quick start

Requirements:

• Godot 4.7.x;
• Python 3;
• the pinned development tools from requirements-dev.txt.

Set up the local tools with uv:

uv venv .venv
uv pip install -r requirements-dev.txt

uv discovers the project-local .venv on both macOS and Windows, so the same setup commands work in a shell or PowerShell.

Open project.godot in Godot 4.7 and run the main scene.

Quality gate

Run the complete local gate before committing.

macOS:

./tools/quality.sh

Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1

For a faster changed-GDScript formatting and lint pass, while still running the Godot checks and scenarios:

./tools/quality.sh --changed

powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\quality.ps1 -Changed

Auto-format all game-owned GDScript with ./tools/fix_format.sh on macOS. On Windows:

powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\fix_format.ps1

The gate enforces Godot 4.7, the pinned formatter and linter, headless project scenarios, and the vendored GUT suite. See docs/local_quality_gate.md for setup and troubleshooting.

Project guide

• docs/DEVELOPER_INDEX.md — current developer onboarding index, feature map, extension workflow, and remaining work;
• AGENTS.md — development loop, architecture rules, validation, documentation, and Git expectations;
• docs/PROJECT_CONTEXT.md — vision, current implementation, and constraints;
• docs/ARCHITECTURE_OVERVIEW.md — runtime ownership and dependency map;
• docs/LEARNING_ROADMAP.md — milestone order and the current next slice;
• docs/README.md — complete documentation map.

Start with the current code and tests when they disagree with a plan, preserve in-progress work, and prefer one complete gameplay proof over a broad abstraction.