YeetGeese/AI Docs/01-AI-GUIDE.md

How to Ask for Help on YeetGeese

When prompting an AI about this project, include:

1. Godot version: "Godot 4.x" (use GDScript 4 syntax: typed signals, @onready, match/enums)
2. Node context: e.g., "TowerBase.gd extending Node2D with a child ProjectileSpawner Marker2D"
3. Goal + constraint: "Make fire rate scale with tower level without hardcoding values."

Coding Conventions We Follow

• Prefer Resource-backed stats over exported hardcoded numbers where balance changes are expected.
• Use named signals: signal damage_dealt(amount: int), signal mob_killed(currency_reward: int)
• Keep scenes small; compose behavior across nodes rather than one 1000-line script.
• Always type variables and return values in GDScript 4 style.

Prompt Templates That Work Well

• "Write a GDScript 4 find_target() that picks the enemy furthest along its path from this tower, using _get_enemies_in_range() -> Array[EnemyMob]."
• "Refactor this hardcoded fire rate into a TowerStats.res Resource and show how the tower reads it on spawn."
• "Implement a placement preview cursor that snaps to a grid and turns red where _can_build_at() returns false."

What I Expect From You (AI)

• Return complete, runnable GDScript 4 with comments explaining node setup.
• Flag any Godot 3 vs 4 API differences (e.g., move_and_slide() behavior, signal typing).
• If a request needs multiple scenes, describe the scene hierarchy before showing code.

Handling Ambiguity & Assumptions (Crucial!)

When a request is ambiguous, incomplete, or requires knowledge outside the scope of the provided documents:

1. DO NOT guess. Do not write code based on assumptions you cannot validate.
2. Acknowledge the Gap: Explicitly state what information is missing or unclear (e.g., "The current architecture does not specify how `WaveRunner` handles player death.").
3. Propose Assumptions: If a concrete implementation path must be shown, list all assumptions made clearly before writing code. Use a dedicated section like:

```markdown [ASSUMPTIONS MADE]

1. We assume that the `PlayerStats` Resource is accessible from the global scope.
2. We are assuming the signal for enemy death will be named `mob_killed`. ```

This ensures that the final code provided by AI can be reviewed against project reality before integration.