Imported from KwangSon/trade (AGENTS.md). Install upstream with npx skills add KwangSon/trade. Copyright stays with the author.

AGENTS.md

Project

This is an AI-driven Godot project.

• src/ contains the Godot project source.
• doc/ contains confirmed design and implementation notes.
• Use singular directory names (for example, doc/, not docs/).
• Target mobile portrait at a 720 x 1280 reference viewport.

Source Rules

• Write all game logic, UI construction, and runtime node composition in GDScript (.gd).
• Do not create .tscn files for ordinary game content or UI.
• Scene files are reserved for Godot entry points such as main.tscn and manual test fixtures under test/manual/. These must be scenes when Godot requires a scene entry point.
• Prefer small, explicit scripts that are easy for an AI agent to inspect, modify, and test.

Architecture

State

• The central state is the source of truth for all runtime data and game progress.
• Runtime data that must survive a screen change must live in state, not only in a screen node.
• Persist the complete state to data.json and restore the game from that file.
• State changes drive screen transitions.

Main

• main owns the active screen and is the only place that creates, replaces, or removes screens.
• main observes the central state and displays the screen that corresponds to the current state.
• Keep exactly one active screen at a time.

Screens

• Screens live under src/screen/.
• A screen is one full-screen step in the game flow, for example splash -> ... -> ending.
• Keep screen scripts thin and self-contained. A screen should handle only the presentation and input needed for its step, while shared or domain logic belongs in separate .gd systems.
• A screen must never instantiate, free, or directly switch to another screen.
• When a screen finishes or needs to move elsewhere, it updates the central state and then stops. main detects that change and performs the screen replacement.
• Do not pass canonical runtime data directly from one screen node to another; write it to state before the transition.

Workflow

• Inspect the relevant source, tests, and doc/ files before editing.
• Prefer the smallest correct change.
• Add or update automated tests for behavior changes.
• Use a manual test scene only when the behavior cannot be verified reasonably with a .gd test.
• Keep manual test scenes and their supporting scripts under test/manual/.
• After adding a .gd file, refresh Godot imports, verify that its sibling .gd.uid was generated, and include both files in the same commit.
• Update the relevant doc/ file when confirmed behavior or architecture changes.

Commands

# Python tooling
source .venv/bin/activate

# Lint changed GDScript files
gdlint path/to/changed_file.gd

# Full lint
find . -name "*.gd" -not -path "./addons/*" | xargs gdlint

# Refresh Godot imports after asset/resource changes
./godot --headless --editor --path "$PWD" --quit

# Run all unit tests
./godot --headless -d -s --path "$PWD" addons/gut/gut_cmdln.gd -gdir=res://test/unit

# Run one test file
./godot --headless -d -s --path "$PWD" addons/gut/gut_cmdln.gd -gtest=res://test/unit/test_screen_routing.gd

Verification

• Lint every changed .gd file.
• Run the most relevant GUT tests after behavior changes.
• Verify runtime behavior with automated GUT unit tests.
• Use still images only when visual inspection is necessary. Do not record video for verification; images do not replace behavioral tests.
• After a Godot run, check the output for SCRIPT ERROR, Parser Error, Could not preload resource script, and [Failed].
• Report pre-existing failures separately from failures introduced by the current change.