AGENTS.md for Godot

# AGENTS.md

Instructions for coding agents working in this Godot repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Godot 4 project. Scenes compose nodes, GDScript is statically typed where the file already types it, and gameplay reacts to signals instead of polling.

## Layout

- Scenes (`.tscn`) and their scripts sit together in the feature folder the project already uses.
- Autoloads are rare. Do not add a new autoload for state a scene can own.
- Shared resources (`.tres`) hold data. Do not bury tuning numbers in `_ready`.

## Commands

- Editor: `Open the project in Godot 4`
- Script check: `Use the editor's script error list before you finish`
- Play: `Run the scene you changed (F6) or the main scene (F5)`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Prefer signals instead of polling. Connect them in the editor or once in `_ready`.
- Use `@export` for designer-facing values and `@onready` for node references you need up front.
- Type new variables and function signatures when the surrounding script is typed.
- Call down, signal up. A child does not reach across the scene tree to poke a sibling.
- Use `await` for signals and timers the engine already provides. Do not busy-loop.
- Keep `_process` and `_physics_process` small. Move one-off work to a signal or a method.

## Testing

Add or update tests when behavior changes.

If the project already uses GdUnit4 or another runner, add a test for the pure logic. Otherwise keep the rule in a plain function and say how you ran the scene.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Use `push_error` for a broken setup and return early. Do not `assert` on a situation a missing export can cause in the editor.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not call `get_node` every frame.
- Do not use Godot 3 yields, `export var`, or string-based `connect` in new Godot 4 scripts.
- Do not store node references across a scene change unless the node is an autoload.
- Do not edit `.tscn` files by hand when the editor can make the change.

## Done when

- The requested behavior works.
- The script has no parser errors, and the scene you changed runs without a red error in the debugger.
- The diff stays inside the task.
- You list anything you could not run.