gamedev-the-steward/AGENTS.md

Agent working guide for The Steward

This repository is a Godot 4.7 simulation prototype. Treat it as a living systems project, not a content dump. The expected working style is:

Default development loop

1. Read the relevant roadmap/docs before changing code.
   • Start with docs/README.md.
   • Use docs/LEARNING_ROADMAP.md for the current next item.
   • Use focused plans such as docs/RESOURCE_NODE_MIGRATION.md only within their stated scope.
2. Inspect the current code and tests before assuming roadmap status is still accurate. The user often changes things in parallel.
3. Implement the smallest useful vertical slice.
   • Prefer functional systems progress over broad polish.
   • Avoid deep rabbit holes unless the current slice needs them.
   • Keep Jajce visual/design work bounded; prioritize simulation behavior, validation, WorldEnvironment ambience, and readable presentation.
4. Validate with the local quality gate.
5. Update the smallest relevant docs after completing a phase or decision.
6. Commit with a conventional commit message.

Validation

Only Godot 4.7 matters for this project.

Use the project quality gate for the current platform:

# macOS / Linux
./tools/quality.sh

# Windows
powershell -ExecutionPolicy Bypass -File .\tools\quality.ps1

For changed-file quick checks:

./tools/quality.sh --changed

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

The quality scripts isolate Godot's user profile under logs/quality/godot_profile so headless Godot 4.7 can run without crashing when platform user-data paths are unavailable. Do not remove that behavior.

Useful extra checks:

git diff --check

If touching main.tscn or runtime wiring, also do a direct Godot 4.7 headless boot when practical.

Architecture direction

Preserve the simulation/presentation boundary.

• Simulation state owns authority: resources, storage, NPC inventory, events, task state, target IDs, positions, RNG streams, and save records.
• World nodes are presentation and interaction geometry. They may register or bind state, but they should not become the only owner of persistent facts.
• NPCs store stable IDs, not NodePaths or node references.
• Target discovery should go through ActiveWorldAdapter and ActionTargetResolver.
• Visual movement belongs to WorldViewManager/NpcVisual; decision and task execution belong to the simulation systems.

When adding a system, first prove the contract with one real gameplay use case. Do not extract generic frameworks before multiple real consumers justify them.

Emergent-world doctrine

The game world is the source of narrative truth. Dialogue, tasks, quests, and visible happenings must arise from ordinary simulation state and events rather than maintaining parallel scripted copies.

• Keep immutable definitions, authored instance placement, mutable state, systems, and presentation as separate layers.
• Persist stable IDs and primitive data only. Saved state must never contain scripts, nodes, NodePaths, callables, or resource paths.
• Mutate authoritative state before recording the fact that describes the mutation. Facts may reference exact causes; they may not stand in for a missing world change.
• Treat dialogue prose as presentation. Semantic intents, selected response IDs, action commands, commitments, and their causal world events are the authoritative contract.
• Treat quests as player-facing projections of real unresolved situations. Never create quest-only enemies, items, damage, relationships, resources, or completion facts.
• Route player and NPC interactions through the same authoritative action and capability contracts. Presentation can suggest or submit a command, but the simulation must revalidate it.
• Loaded visuals must not decide whether travel, work, growth, or distant conflict completes. Presentation interpolates authoritative state and may report local feasibility or obstruction.
• Every generated action, situation, helper, dialogue intent, or consequence must expose a concise reason trace with the definition and causal fact IDs that justified it.
• “Data-only content” means new combinations of existing typed predicates, capabilities, effects, behavior profiles, and presentation cues. A genuinely new mechanic adds one bounded reusable handler and tests; it does not add one script per item, creature, quest, or conversation.
• Prefer typed Godot resources, composition, deterministic registries, and explicit strategy handlers. Do not introduce a universal reflection DSL or rewrite the project as a full ECS.

The intended extension path is therefore definition plus content pack, optional presentation cue, and authored placement or simulation spawn. A berry, bear, caravan, shortage, or conversation topic should reuse the same state, action, event, and presentation contracts that existing content uses.

Resource and target rules

Do not reintroduce abstract food/wood task-zone fallbacks.

Current resource gathering should use finite ResourceNode instances:

• food: berries, animal camps, village stock, future farms/crops;
• wood: trees, wood piles, future forestry contexts.

Entity systems pattern

Build every resource, enemy, and animal as a reusable system with shared root behaviour, not as a one-off object. Add a new type through data/definitions plus a small behaviour or visual hook, reusing the root for movement, presentation, serialization, and lifecycle:

• resources: ResourceNode + ResourceStateRecord (amount, yield, regrowth);
• creatures: CreatureVisual shared movement root (navigate to the authoritative simulation position, report position, death), with per-type visuals built from definitions;
• enemies: EnemyDefinition + SimulationEnemies registry driving combatant spawns and hostile visuals;
• animals: AnimalNode + AnimalStateRecord following the same follow-the-authoritative-position contract.

A new berry, tree, bear, bandit, boar, or goat should be mostly a definition plus a bounded hook — never a new movement/combat/save system.

Resource additions should preserve:

• stable unique IDs;
• food/wood coverage;
• meaningful placement context;
• reachable interaction points;
• safety_risk, comfort_distance, and discovery_priority metadata;
• clear player interaction ranges so nearby storage/activity/resource targets do not overlap accidentally.

Storage uses StorageNode. Rest, study, and patrol use ActivitySite. Do not turn these back into generic marker zones.

Testing expectations

Add or update headless scenarios when a change affects:

• resource conservation;
• target selection or reservations;
• save/load or schema behavior;
• navigation/reachability assumptions;
• player/NPC parity;
• deterministic continuation;
• UI/debug state that represents real simulation facts.

Keep tests deterministic. Prefer fixed seeds and stable IDs.

Documentation expectations

Update docs when the implemented behavior changes the roadmap, architecture, or current contract. Keep updates local:

• docs/LEARNING_ROADMAP.md for next-item sequencing and milestone status;
• docs/RESOURCE_NODE_MIGRATION.md for resource-target migration status;
• docs/SIMULATION_STATE_SCHEMA.md for serialized state changes;
• docs/SIMULATION_DEFINITIONS.md for action/profession/ID contracts;
• docs/BUILD_IN_PUBLIC_PLAN.md for Jajce/demo/readability slices;
• docs/decisions/ only for durable architectural decisions.

Do not duplicate full status tables across many docs. If docs and code differ, trust code/tests first, then update docs.

Git expectations

Preserve user changes. Check git status --short before editing and before committing. Do not use destructive cleanup commands unless explicitly asked.

Use conventional commits, for example:

• feat: validate expanded resource discovery
• fix: stabilize godot 4.7 headless validation
• docs: capture agent workflow

Commit only after validation relevant to the change has passed.

Product taste

The project is aiming for a readable, magical simulation garden that can grow into a larger systemic game. Prefer honest visible cause-and-effect:

• NPCs should walk to real resources, storage, and activity sites.
• UI/debug overlays should explain actual simulation state.
• Beauty work should represent real state rather than fake activity.
• Each slice should leave the project easier to reason about than before.