Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Andrew Yeet
|
928681a64a |
@@ -1,455 +0,0 @@
|
||||
# Testing Workflow Guide for YeetGeese
|
||||
|
||||
This document provides a structured approach to testing Godot 4.x games, with specific focus on the tower defense mechanics of YeetGeese. It covers what to test, how to structure tests, and debugging failed tests.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Testing Philosophy](#testing-philosophy)
|
||||
2. [Test Organization](#test-organization)
|
||||
3. [Test Categories](#test-categories)
|
||||
4. [Writing Tests](#writing-tests)
|
||||
5. [Debugging Failed Tests](#debugging-failed-tests)
|
||||
6. [CI Integration](#ci-integration)
|
||||
|
||||
---
|
||||
|
||||
## Testing Philosophy
|
||||
|
||||
### Why Test?
|
||||
|
||||
- **Regression prevention:** Catch unintended side effects from changes
|
||||
- **Documentation by example:** Tests serve as usage examples
|
||||
- **Design validation:** Ensure architecture matches intent
|
||||
- **Confidence for refactoring:** Safe to reorganize code when tested
|
||||
|
||||
### What AI Can Help With
|
||||
|
||||
AI can:
|
||||
- Generate boilerplate test scaffolding
|
||||
- Suggest edge cases and boundary conditions
|
||||
- Write mock implementations for complex systems
|
||||
- Explain Godot testing framework capabilities
|
||||
|
||||
### What AI Cannot Handle
|
||||
|
||||
AI should NOT:
|
||||
- Design game mechanics or balance (human domain)
|
||||
- Make subjective quality-of-life judgments
|
||||
- Replace manual playtesting of actual gameplay feel
|
||||
- Generate test data for art assets (no AI-generated art rule applies)
|
||||
|
||||
---
|
||||
|
||||
## Test Organization
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── core/ # Autoloads and global state tests
|
||||
│ ├── wave_progression_test.gd
|
||||
│ └── currency_manager_test.gd
|
||||
├── towers/ # Tower behavior tests
|
||||
│ ├── tower_base_test.gd
|
||||
│ ├── projectile_spawner_test.gd
|
||||
│ └── target_finder_test.gd
|
||||
├── enemies/ # Enemy system tests
|
||||
│ ├── enemy_mob_test.gd
|
||||
│ ├── navigation_system_test.gd
|
||||
│ └── spawner_test.gd
|
||||
├── projectiles/ # Projectile handling tests
|
||||
│ ├── goose_projectile_test.gd
|
||||
│ └── impact_handler_test.gd
|
||||
├── ui/ # HUD and menu tests
|
||||
│ ├── health_bar_test.gd
|
||||
│ └── currency_display_test.gd
|
||||
├── utils/ # Utility functions
|
||||
│ └── math_utils_test.gd
|
||||
└── integration/ # Cross-system tests
|
||||
├── wave_complete_sequence_test.gd
|
||||
└── tower_placement_integration_test.gd
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- Files: `<system>_test.gd` (e.g., `tower_base_test.gd`)
|
||||
- Functions: `func test_<behavior_description>()` (e.g., `func test_fire_rate_scales_with_level()`)
|
||||
- Assertions: Use descriptive names like `assert_equal`, `assert_signal_emitted`, `assert_no_error`
|
||||
|
||||
---
|
||||
|
||||
## Test Categories
|
||||
|
||||
### Unit Tests
|
||||
|
||||
Test individual functions or methods in isolation.
|
||||
|
||||
**Example:** Testing a tower's fire rate calculation
|
||||
|
||||
```gdscript
|
||||
@tool
|
||||
extends Node
|
||||
|
||||
func test_fire_rate_calculation(tower: Node) -> void:
|
||||
assert_equal(tower.fire_rate, 1.0)
|
||||
|
||||
# Modify tower level
|
||||
tower.tower_level = 2
|
||||
|
||||
# Verify fire rate changed appropriately
|
||||
assert_greater(tower.fire_rate, 1.0)
|
||||
assert_less(tower.fire_rate, 2.0)
|
||||
|
||||
func test_damage_scaling_by_tower_level(tower: Node) -> void:
|
||||
tower.tower_level = 3
|
||||
|
||||
var initial_damage = tower.get_damage_at_current_level()
|
||||
tower.tower_level = 5
|
||||
|
||||
# Verify damage increased with level
|
||||
assert_greater(tower.get_damage_at_current_level(), initial_damage)
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Testing pure logic (math, state transitions)
|
||||
- Testing Resource loading and property access
|
||||
- Testing signal emission patterns
|
||||
|
||||
---
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Test interactions between multiple systems.
|
||||
|
||||
**Example:** Testing the full projectile launch sequence
|
||||
|
||||
```gdscript
|
||||
@tool
|
||||
extends Node
|
||||
|
||||
func test_projectile_launch_sequence() -> void:
|
||||
# Arrange: Create mock tower and target
|
||||
var tower := _create_mock_tower()
|
||||
var target := _create_mock_target()
|
||||
|
||||
# Act: Fire at target
|
||||
tower.fire_at(target)
|
||||
|
||||
# Assert: Verify projectile spawned in correct state
|
||||
assert_true(tower.projectile_count == 1)
|
||||
assert_equal(tower.projectiles[0].source_node, tower.$ProjectileSpawner)
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Testing scene hierarchies with multiple nodes
|
||||
- Verifying signal connections between systems
|
||||
- Validating Godot's built-in component behavior (e.g., RigidBody2D movement)
|
||||
|
||||
---
|
||||
|
||||
### Regression Tests
|
||||
|
||||
Tests added when a bug is fixed to ensure it doesn't return.
|
||||
|
||||
**Example:** Preventing physics tunneling after a collision fix
|
||||
|
||||
```gdscript
|
||||
@tool
|
||||
extends Node
|
||||
|
||||
func test_projectile_collision_prevents_tunneling() -> void:
|
||||
# Scenario: Goose projectile moving at high speed
|
||||
var projectile := _create_goose_with_velocity(100.0)
|
||||
var enemy := _create_enemy_with_small_hitbox()
|
||||
|
||||
# Act: Move projectile toward enemy's hitbox
|
||||
projectile.yeet_from(projectile.position, enemy.position)
|
||||
|
||||
# Assert: Projectile detected collision on this frame
|
||||
assert_signal_emitted(projectile, 'collision_detected')
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- After fixing a critical bug
|
||||
- When performance regression occurs
|
||||
- To validate edge case handling
|
||||
|
||||
---
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Test Function Template
|
||||
|
||||
```gdscript
|
||||
@tool
|
||||
extends Node
|
||||
|
||||
func test_<behavior_under_test>() -> void:
|
||||
# Arrange: Setup the scenario
|
||||
var <subject> := _create_mock_<subject>()
|
||||
|
||||
# Act: Execute the action being tested
|
||||
<subject>.<method_or_event>()
|
||||
|
||||
# Assert: Verify expected behavior
|
||||
assert_true(<condition_1>)
|
||||
assert_false(<condition_2>)
|
||||
assert_signal_emitted(<signal_source>, '<signal_name>')
|
||||
```
|
||||
|
||||
### Available Assertions
|
||||
|
||||
| Assertion | Purpose | Example |
|
||||
|-----------|---------|---------|
|
||||
| `assert_equal(a, b)` | Check exact equality | `assert_equal(tower.level, 3)` |
|
||||
| `assert_not_equal(a, b)` | Check inequality | `assert_not_equal(projectile.speed, 0.0)` |
|
||||
| `assert_true(condition)` | Verify boolean is true | `assert_true(tower.is_ready())` |
|
||||
| `assert_false(condition)` | Verify boolean is false | `assert_false(projectile.is_removed())` |
|
||||
| `assert_greater(a, b)` | Check a > b | `assert_greater(damage_dealt, 10)` |
|
||||
| `assert_less(a, b)` | Check a < b | `assert_less(enemy.health, 50.0)` |
|
||||
| `assert_null(obj)` | Verify object is null | `assert_null(projectile.get_target())` |
|
||||
| `assert_not_null(obj)` | Verify object exists | `assert_not_null(projectile)` |
|
||||
| `assert_array_size(arr, size)` | Check array length | `assert_array_size(tower.projectiles, 4)` |
|
||||
|
||||
### Signal Testing Pattern
|
||||
|
||||
```gdscript
|
||||
var _signal_verified = false
|
||||
|
||||
func test_health_changed_signal_emits_correct_values() -> void:
|
||||
var enemy := EnemyMob.new()
|
||||
enemy.health_changed.connect(func(new_health) {
|
||||
assert_true(_signal_verified == false) # Prevent double-firing
|
||||
assert_equal(new_health, 75.0)
|
||||
_signal_verified = true
|
||||
})
|
||||
|
||||
enemy.take_damage(25.0)
|
||||
|
||||
assert_true(_signal_verified)
|
||||
```
|
||||
|
||||
### Mock Object Helpers
|
||||
|
||||
Use these helper functions to create mock objects for tests:
|
||||
|
||||
```gdscript
|
||||
# Create a mock tower with minimal setup
|
||||
func _create_mock_tower() -> Node:
|
||||
var tower := TowerBase.new()
|
||||
tower.tower_level = 1
|
||||
return tower
|
||||
|
||||
# Create a mock enemy for collision testing
|
||||
func _create_mock_enemy() -> EnemyMob:
|
||||
var enemy := EnemyMob.new()
|
||||
enemy.health = 50.0
|
||||
enemy.damage_taken.connect(func() { pass }) # Prevent death on damage
|
||||
return enemy
|
||||
|
||||
# Verify no error occurred during test
|
||||
func _assert_no_error(condition: bool) -> void:
|
||||
assert_true(condition, "Test completed with errors")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Failed Tests
|
||||
|
||||
### Common Failure Patterns
|
||||
|
||||
#### 1. Test Completes Before Signal Fires
|
||||
|
||||
**Problem:** `signal_emitted` verification fails because the test ends too early.
|
||||
|
||||
**Solution:** Add a yield or use Godot's built-in coroutine system:
|
||||
|
||||
```gdscript
|
||||
func test_signal_fires_after_delay() -> void:
|
||||
var subject := _create_subject()
|
||||
subject.event.triggered.connect(_on_event_triggered)
|
||||
|
||||
subject.do_something()
|
||||
|
||||
# Ensure signal fires before test ends
|
||||
get_tree().process_frame.connect(_on_frame_processed)
|
||||
yield(get_tree(), "process_frame") # Wait for signal
|
||||
|
||||
assert_true(_signal_received)
|
||||
|
||||
func _on_frame_processed() -> void:
|
||||
_on_event_triggered.call_deferred()
|
||||
```
|
||||
|
||||
#### 2. Scene Loading in Tests Fails
|
||||
|
||||
**Problem:** Godot scenes loaded via `load("res://...")` may not find their resources.
|
||||
|
||||
**Solution:** Use absolute paths or ensure test assets are in proper location:
|
||||
|
||||
```gdscript
|
||||
# Bad: Relative path that breaks in tests
|
||||
var mob_scene := load("enemy_mob.tscn").instantiate()
|
||||
|
||||
# Good: Absolute resource path
|
||||
var mob_scene := load("res://src/enemies/enemy_mob.tscn").instantiate()
|
||||
```
|
||||
|
||||
#### 3. Random Behavior Causes Flaky Tests
|
||||
|
||||
**Problem:** Tests pass sometimes but fail others due to randomness (e.g., particle emission).
|
||||
|
||||
**Solution:** Disable randomness in test environment:
|
||||
|
||||
```gdscript
|
||||
# At start of test, seed RNG for reproducibility
|
||||
Rand.randi = func() -> int: return 42 # Fixed value for testing
|
||||
|
||||
# Or disable randomness for specific systems
|
||||
var projectile := Projectile.new()
|
||||
projectile.random_variation_enabled = false
|
||||
```
|
||||
|
||||
#### 4. Physics Tunneling in Collision Tests
|
||||
|
||||
**Problem:** Fast-moving projectiles miss collisions when tested with static enemies.
|
||||
|
||||
**Solution:** Use multiple physics frames or smaller time steps:
|
||||
|
||||
```gdscript
|
||||
func test_high_velocity_collision_detection() -> void:
|
||||
var projectile := _create_goose_with_velocity(200.0)
|
||||
|
||||
# Run multiple physics frames for collision detection
|
||||
for _ in range(5):
|
||||
get_tree().physics_ticks_processed = 1
|
||||
get_tree().process_frame()
|
||||
|
||||
assert_true(_collision_detected)
|
||||
```
|
||||
|
||||
#### 5. Signal Connections Leak Between Tests
|
||||
|
||||
**Problem:** Test A's signal handlers remain active when Test B runs.
|
||||
|
||||
**Solution:** Disconnect signals at test end:
|
||||
|
||||
```gdscript
|
||||
func cleanup_test(subject: Node, signal_name: String) -> void:
|
||||
subject.signal_removed.connect(_disconnect_signals)
|
||||
|
||||
# Clear all signals from subject
|
||||
var signals = subject.get_signal_list()
|
||||
for s in signals:
|
||||
if s.is_connected(func):
|
||||
s.disconnect(func)
|
||||
|
||||
# Call cleanup at end of each test function
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI Integration (Optional for Indie Teams)
|
||||
|
||||
### GitHub Actions / GitLab CI Setup
|
||||
|
||||
If using a continuous integration server, add tests to build pipeline.
|
||||
|
||||
**Example workflow:**
|
||||
|
||||
```yaml
|
||||
name: YeetGeese Tests
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Install Godot
|
||||
run: |
|
||||
# Download and install Godot 4.x stable
|
||||
|
||||
- name: Run Tests
|
||||
run: |
|
||||
godot --path . --headless tests/run_all_tests.gd
|
||||
```
|
||||
|
||||
### Local Test Runner Script
|
||||
|
||||
Create a script to run all tests from command line:
|
||||
|
||||
```gdscript
|
||||
# tests/run_all_tests.gd
|
||||
extends Node
|
||||
|
||||
func _ready():
|
||||
var result := 0
|
||||
|
||||
# Run unit tests
|
||||
for file in DirAccess.get_directories() if dir_name == "core" or dir_name == "towers":
|
||||
pass # Implementation depends on test runner framework
|
||||
|
||||
if result == 0:
|
||||
print("All tests passed!")
|
||||
else:
|
||||
error("Some tests failed")
|
||||
|
||||
func _exit_tree():
|
||||
quit(0)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Before Writing Tests for New Feature
|
||||
|
||||
- [ ] Identify the system(s) being tested
|
||||
- [ ] Determine unit vs. integration testing needs
|
||||
- [ ] List expected inputs and outputs
|
||||
- [ ] Identify edge cases (empty arrays, null objects, etc.)
|
||||
|
||||
### Test Coverage Goals
|
||||
|
||||
| System Type | Recommended Test Coverage |
|
||||
|-------------|---------------------------|
|
||||
| Core game loop | 100% (critical path) |
|
||||
| Tower logic | 90%+ |
|
||||
| Enemy AI states | 85%+ |
|
||||
| UI displays | 80%+ |
|
||||
| Utility functions | 95%+ |
|
||||
|
||||
### Review Checklist for AI-Generated Tests
|
||||
|
||||
When asking AI to generate tests, verify:
|
||||
|
||||
- [ ] Uses `@tool` directive for editor-only execution
|
||||
- [ ] Sets up proper mock objects for isolation
|
||||
- [ ] Disconnects signals at test end to prevent leaks
|
||||
- [ ] Uses absolute paths for resource loading
|
||||
- [ ] Handles expected error conditions gracefully
|
||||
- [ ] Includes assertions for all critical behaviors
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**AI can help with:**
|
||||
- Generating boilerplate test scaffolding
|
||||
- Suggesting edge cases and boundary conditions
|
||||
- Writing mock implementations for complex systems
|
||||
- Explaining Godot testing framework capabilities
|
||||
|
||||
**Remember:**
|
||||
- Tests should be runnable in editor (`@tool` functions)
|
||||
- Keep tests focused on one behavior per function
|
||||
- Disconnect signals to prevent cross-test contamination
|
||||
- Use absolute paths for resource loading in tests
|
||||
- Document test intent with clear, descriptive names
|
||||
|
||||
For more details, see `AI_HELP.md` for prompt templates when working with AI assistants on testing tasks.
|
||||
@@ -1,547 +0,0 @@
|
||||
# Skills, Agents, and Commands Reference
|
||||
|
||||
This document provides a reference for AI assistants working with YeetGeese. It describes available capabilities, when to use them, and best practices for interaction.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Available Skills](#available-skills)
|
||||
2. [Agent Types & Use Cases](#agent-types--use-cases)
|
||||
3. [Command Reference](#command-reference)
|
||||
4. [Prompt Templates](#prompt-templates)
|
||||
5. [Best Practices](#best-practices)
|
||||
|
||||
---
|
||||
|
||||
## Available Skills
|
||||
|
||||
### `customize-opencode`
|
||||
|
||||
**Purpose:** Configure and modify the AI assistant's own settings, including:
|
||||
- `opencode.json`, `opencode.jsonc` files
|
||||
- `.opencode/` configuration directory
|
||||
- `~/.config/opencode/` user settings
|
||||
- Agent definitions (subagents, skills, plugins, MCP servers)
|
||||
- Permission rules
|
||||
|
||||
**When to use:** When configuring the AI assistant itself, not for project code.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
"Adjust the maximum context window size for this session."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `make-pr` — Pull Request Creation (Gitea Web UI)
|
||||
|
||||
**Purpose:** On Gitea, pull requests are created directly via the web interface at:
|
||||
`https://gitea.letteka.com/letteka/YeetGeese/pulls/new/move_docs`
|
||||
|
||||
**How to use on Gitea:**
|
||||
1. Push changes to a branch (e.g., `move_docs`)
|
||||
2. Visit the URL above or navigate via Gitea web UI
|
||||
3. Create PR with descriptive title and body
|
||||
4. Include testing strategies and validation status in description
|
||||
|
||||
**When to use:**
|
||||
- When ready to submit a pull request from your current branch
|
||||
- Before pushing code that requires peer review
|
||||
- To ensure all changes are properly documented and validated
|
||||
- When creating PRs for features, fixes, or refactoring
|
||||
|
||||
**Best practices for Gitea PRs:**
|
||||
- Use descriptive titles following conventional commits format
|
||||
- Include file-by-file change summary in PR body
|
||||
- List testing strategies: unit tests, integration tests, manual QA
|
||||
- Mention any validation already performed locally
|
||||
- Flag known issues or limitations clearly
|
||||
|
||||
---
|
||||
|
||||
## Agent Types & Use Cases
|
||||
|
||||
### `code-gen` — Code Generation
|
||||
|
||||
**Purpose:** Write new code, implement features, create boilerplate.
|
||||
|
||||
**Capabilities:**
|
||||
- GDScript 4 implementation
|
||||
- Scene graph construction descriptions
|
||||
- Resource file (`.tres`) schema design
|
||||
- Signal declarations and connections
|
||||
- Method implementations matching project conventions
|
||||
|
||||
**When to use:**
|
||||
- Implementing a new tower or projectile type
|
||||
- Adding a feature to existing systems
|
||||
- Creating boilerplate for common patterns
|
||||
- Writing unit tests
|
||||
|
||||
**Input required:**
|
||||
- Target file path or node description
|
||||
- Desired behavior/goal
|
||||
- Any constraints (e.g., "must use Resource for stats")
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Create a GDScript 4 class `ImpactEffect.gd` that extends Area2D. It should:
|
||||
1. Detect collision with enemies in _body_entered
|
||||
2. Emit signal 'effect_triggered' with damage and target Node2D
|
||||
3. Apply random color variation to its texture
|
||||
4. Set lifespan to 0.8 seconds
|
||||
5. Include comments explaining each step"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `debug-helper` — Debugging Assistance
|
||||
|
||||
**Purpose:** Analyze errors, suggest debugging strategies, interpret profiler output.
|
||||
|
||||
**Capabilities:**
|
||||
- Error message interpretation (Godot/IDE/compiler)
|
||||
- Suggesting debugging tool usage (Scene Debugger, Physics Monitor)
|
||||
- Profiling tips and bottleneck identification
|
||||
- Common pitfall recognition (e.g., physics tunneling, navmesh gaps)
|
||||
|
||||
**When to use:**
|
||||
- When an error occurs during implementation
|
||||
- When code behaves unexpectedly
|
||||
- When performance issues appear in profiler
|
||||
|
||||
**Input required:**
|
||||
- Error message or log output
|
||||
- Relevant file paths and line numbers if available
|
||||
- Brief description of expected vs. actual behavior
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"This tower stops firing after 30 seconds even though fire_rate is set to 1.0.
|
||||
Error: 'get_tree()' returned null at runtime. Debug it."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `refactor-assistant` — Refactoring Support
|
||||
|
||||
**Purpose:** Break up large scripts, improve code organization, add documentation.
|
||||
|
||||
**Capabilities:**
|
||||
- Splitting monolithic scripts into smaller nodes
|
||||
- Extracting methods into separate components
|
||||
- Adding documentation and type hints
|
||||
- Applying project conventions consistently
|
||||
|
||||
**When to use:**
|
||||
- Scripts are growing beyond 150 lines
|
||||
- Multiple unrelated behaviors in one node
|
||||
- Need to improve readability before review
|
||||
|
||||
**Input required:**
|
||||
- File path or code snippet
|
||||
- Refactoring goal (e.g., "split into state machines")
|
||||
- Target organization style
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Refactor this 400-line EnemyMob.gd into smaller components:
|
||||
1. Extract navigation logic to NavigationComponent
|
||||
2. Extract attack behavior to AttackState
|
||||
3. Keep health/currency handling in base class
|
||||
4. Add documentation comments for each section"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `test-generator` — Test Generation
|
||||
|
||||
**Purpose:** Create unit tests for game logic systems.
|
||||
|
||||
**Capabilities:**
|
||||
- Writing Godot test cases using `@tool` functions
|
||||
- Setting up mock scenes and signals
|
||||
- Testing Resource-based stat changes
|
||||
- Validating collision detection and hit calculations
|
||||
|
||||
**When to use:**
|
||||
- After implementing core logic that should be validated
|
||||
- Before refactoring (to preserve behavior)
|
||||
- When adding critical game mechanics
|
||||
|
||||
**Input required:**
|
||||
- System or function being tested
|
||||
- Expected inputs and outputs
|
||||
- Edge cases to cover
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Create tests for TowerBase._can_build_at(). Test:
|
||||
1. Returns true in valid tower placement zones
|
||||
2. Returns false inside enemy navmesh
|
||||
3. Returns false when grid coordinate exceeds bounds
|
||||
4. Returns false if parent node is null"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `design-patterns` — Design Pattern Suggestions
|
||||
|
||||
**Purpose:** Recommend architecture patterns suited to specific problems.
|
||||
|
||||
**Capabilities:**
|
||||
- Suggesting ECS for complex entity management
|
||||
- Recommending FSM for enemy AI states
|
||||
- Proposing event-driven systems for decoupled components
|
||||
- Advising on data-oriented vs. object-oriented design
|
||||
|
||||
**When to use:**
|
||||
- Before implementing a new system
|
||||
- When performance becomes an issue
|
||||
- When refactoring existing code
|
||||
|
||||
**Input required:**
|
||||
- Problem description (e.g., "I need many entities with simple movement")
|
||||
- Performance constraints if any
|
||||
- Preferred Godot nodes or patterns already in use
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"I'm building a system for 50+ projectiles that need to track targets, apply damage, and handle collision.
|
||||
Current approach: individual RigidBody2D for each projectile.
|
||||
What pattern would scale better?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `balance-helper` — Balance Analysis
|
||||
|
||||
**Purpose:** Analyze math relationships and suggest tuning adjustments.
|
||||
|
||||
**Capabilities:**
|
||||
- Calculating damage per second (DPS) from fire rate and projectile stats
|
||||
- Estimating kill time based on enemy HP and total damage sources
|
||||
- Suggesting resource stat ranges that preserve balance space
|
||||
- Identifying scaling relationships between tower levels
|
||||
|
||||
**When to use:**
|
||||
- Before adding new towers/enemies with different power levels
|
||||
- When gameplay feels too easy or difficult
|
||||
- During tuning phase of wave progression
|
||||
|
||||
**Input required:**
|
||||
- Current stats (damage, fire rate, enemy HP)
|
||||
- Desired behavior description (e.g., "kill time should scale with tier")
|
||||
- Resource file structure if applicable
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Current: goose damage=15, fire_rate=1.0/s, chicken HP=80.
|
||||
Tower Level 2 has 4 geese. Calculate total DPS and suggest enemy HP range
|
||||
for level-appropriate difficulty (aim for ~30s wave duration)."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `level-design-helper` — Level Design Assistance
|
||||
|
||||
**Purpose:** Plan layout, progression, and pacing for levels or zones.
|
||||
|
||||
**Capabilities:**
|
||||
- Wave progression suggestions (spawn rates, path complexity)
|
||||
- Tower placement zone recommendations
|
||||
- Pacing analysis for difficulty curves
|
||||
- Zone-based checkpoint design
|
||||
|
||||
**When to use:**
|
||||
- Before creating a new level or wave sequence
|
||||
- When gameplay feels too repetitive or frustrating
|
||||
- During playtesting feedback analysis
|
||||
|
||||
**Input required:**
|
||||
- Level description (size, available zones)
|
||||
- Current wave structure if any
|
||||
- Difficulty curve goals
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"I have 4 tower placement zones along a path with 3 turns.
|
||||
Current waves: linear difficulty increase.
|
||||
Suggest a progression that introduces new mechanics at zone boundaries."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `doc-generator` — Documentation Generation
|
||||
|
||||
**Purpose:** Create documentation from existing code or planning data.
|
||||
|
||||
**Capabilities:**
|
||||
- Generating API docs from GDScript class structures
|
||||
- Writing changelogs from commit history
|
||||
- Creating release notes with feature summaries
|
||||
- Producing onboarding guides from project structure
|
||||
|
||||
**When to use:**
|
||||
- Before releasing a version
|
||||
- After implementing a major feature set
|
||||
- When new team members join the project
|
||||
|
||||
**Input required:**
|
||||
- Source code or commit messages
|
||||
- Feature list for changelog entries
|
||||
- Target audience (developers, players)
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Generate API documentation for the WaveRunner system:
|
||||
1. Describe each public method and its parameters
|
||||
2. List signals emitted with their payloads
|
||||
3. Document the Resource dependencies
|
||||
4. Include usage examples"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `onboarding-guide` — Onboarding Documentation
|
||||
|
||||
**Purpose:** Create setup tutorials and getting-started guides for new developers.
|
||||
|
||||
**Capabilities:**
|
||||
- Environment setup instructions (OS-specific)
|
||||
- Project structure explanation
|
||||
- Editor scene loading order
|
||||
- Common first tasks with examples
|
||||
|
||||
**When to use:**
|
||||
- Before bringing on new team members
|
||||
- When updating project structure significantly
|
||||
- For release candidate documentation
|
||||
|
||||
**Input required:**
|
||||
- Target OS versions supported
|
||||
- Required Godot version and plugins
|
||||
- Team conventions to teach
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Write an onboarding guide for a new developer joining YeetGeese:
|
||||
1. Explain folder structure (src/core, src/towers, etc.)
|
||||
2. Show how to run the game from main.tscn
|
||||
3. Describe the tower placement workflow
|
||||
4. List common commands for debugging"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `api-specs` — API Specification
|
||||
|
||||
**Purpose:** Define external interfaces and save/load contracts.
|
||||
|
||||
**Capabilities:**
|
||||
- Defining save file format schemas
|
||||
- Documenting modding API endpoints
|
||||
- Specifying network message protocols
|
||||
- Creating serialization guides
|
||||
|
||||
**When to use:**
|
||||
- Before implementing persistent storage
|
||||
- When enabling mod support
|
||||
- For multiplayer networking design
|
||||
|
||||
**Input required:**
|
||||
- Interface type (save format, mod API, network protocol)
|
||||
- Required functionality list
|
||||
- Platform constraints
|
||||
|
||||
**Example prompt:**
|
||||
```
|
||||
"Define a save file format for YeetGeese:
|
||||
1. Must store unlocked towers and their levels
|
||||
2. Must include currency progress and wave number
|
||||
3. Use Godot Resource serialization (.tres files)
|
||||
4. Include version field for backward compatibility"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command Reference
|
||||
|
||||
### Code Writing Commands
|
||||
|
||||
| Command | When to use |
|
||||
|---------|-------------|
|
||||
| `create file <path>` | For new classes, scenes, or resource files |
|
||||
| `modify file <path>` | For adding methods or changing existing code |
|
||||
| `describe scene <path>` | To generate scene tree descriptions for AI understanding |
|
||||
|
||||
### Review Commands
|
||||
|
||||
| Command | When to use |
|
||||
|---------|-------------|
|
||||
| `review code <path>` | For checking convention compliance |
|
||||
| `optimize performance <scope>` | For profiling suggestions in specific areas |
|
||||
| `debug error <message>` | For interpreting errors and suggesting fixes |
|
||||
|
||||
### Documentation Commands
|
||||
|
||||
| Command | When to use |
|
||||
|---------|-------------|
|
||||
| `generate docs` | For API documentation from code |
|
||||
| `write changelog` | After implementing features or fixing bugs |
|
||||
| `create onboarding guide` | For new developer setup instructions |
|
||||
|
||||
---
|
||||
|
||||
## Prompt Templates
|
||||
|
||||
### Feature Implementation Template
|
||||
|
||||
```
|
||||
Context: I'm implementing [feature name] in [system/file].
|
||||
Current state: [brief description of existing code/structure]
|
||||
Goal: [what this feature should do]
|
||||
Constraints: [any restrictions like "must use Resource" or "no UI changes"]
|
||||
|
||||
Please provide:
|
||||
1. Complete, runnable GDScript 4 code with comments
|
||||
2. Scene hierarchy description if new scenes are needed
|
||||
3. Any new Resources (.tres) and their structure
|
||||
4. Signal declarations and connection points
|
||||
```
|
||||
|
||||
### Debugging Template
|
||||
|
||||
```
|
||||
Error context: [where the error occurred]
|
||||
Error message: [full error output]
|
||||
Expected behavior: [what should have happened]
|
||||
Actual behavior: [what actually happened]
|
||||
Debug steps tried: [what you've already attempted]
|
||||
|
||||
Please provide:
|
||||
1. Root cause analysis
|
||||
2. Minimal fix with explanation
|
||||
3. Prevention strategy for future occurrences
|
||||
```
|
||||
|
||||
### Refactoring Template
|
||||
|
||||
```
|
||||
Current code: [file path or snippet]
|
||||
Issues to address: [e.g., "too monolithic", "missing docs"]
|
||||
Refactoring goals: [what you want to achieve]
|
||||
Target patterns: [any existing patterns to match]
|
||||
|
||||
Please provide:
|
||||
1. Proposed refactored structure
|
||||
2. New files and their responsibilities
|
||||
3. Migration steps for existing code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Provide Context First
|
||||
|
||||
Before asking for code, share:
|
||||
- The relevant file path or node description
|
||||
- The GDScript version being used (Godot 4.x)
|
||||
- Key related signals and methods already in place
|
||||
|
||||
**Good:**
|
||||
```
|
||||
"Create an ImpactEffect.gd extending Area2D with these existing methods:
|
||||
- _body_entered(var area): called on collision
|
||||
- emit_signal('effect_triggered', damage, target)"
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
"I need a collision effect for projectiles."
|
||||
```
|
||||
|
||||
### 2. Specify Godot 4 Conventions
|
||||
|
||||
When requesting code, remind AI of conventions:
|
||||
- Use typed signals: `signal health_changed(new_health: float)`
|
||||
- Prefer `@onready` over `$` in scripts
|
||||
- Type variables and return values consistently
|
||||
- Keep scenes modular (compose behavior across nodes)
|
||||
|
||||
### 3. Reference Existing Architecture
|
||||
|
||||
When implementing features, reference existing patterns:
|
||||
```
|
||||
"Implement this using the same pattern as TowerBase.fire_at():
|
||||
- Use projectile_res.instantiate() for new goose projectiles
|
||||
- Spawn from $ProjectileSpawner.global_position
|
||||
- Add to parent tree immediately after instantiation"
|
||||
```
|
||||
|
||||
### 4. Specify Resource Dependencies Early
|
||||
|
||||
If your project uses Resources for balance:
|
||||
```
|
||||
"Create a Resource-based stats file for this tower:
|
||||
- Fields: damage (float), fire_rate (float), cooldown_reduction (float)
|
||||
- Make it loadable as a Godot Resource (.tres)
|
||||
- Show how the tower reads its stats on _ready()"
|
||||
```
|
||||
|
||||
### 5. Ask for Complete, Runnable Code
|
||||
|
||||
When requesting implementations:
|
||||
```
|
||||
"Return complete, runnable GDScript 4 code with:"
|
||||
"- Comments explaining each major section"
|
||||
"- Type annotations for all variables and methods"
|
||||
"- Signal declarations at top of class"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Use these skills strategically:**
|
||||
- `code-gen`: For new features and boilerplate
|
||||
- `debug-helper`: When errors occur or behavior is wrong
|
||||
- `refactor-assistant`: Before code grows unmanageable
|
||||
- `test-generator`: After implementing critical logic
|
||||
- `design-patterns`: When architecture becomes unclear
|
||||
|
||||
**Always provide:**
|
||||
- File paths, node names, and Godot version context
|
||||
- Desired behavior in terms of existing patterns
|
||||
- Constraints (Resource usage, signal conventions)
|
||||
|
||||
**When in doubt:** Reference `AI_HELP.md` for project-specific conventions before asking questions.
|
||||
|
||||
---
|
||||
|
||||
## Note About `make-pr` Skill Availability
|
||||
|
||||
The **`make-pr`** skill (`.opencode/skills/make-pr.json`) is available for use! This skill will:
|
||||
- Generate comprehensive, human-readable PR descriptions
|
||||
- List testing strategies for each change area
|
||||
- Validate changes before PR creation
|
||||
- Format PR descriptions with clear sections
|
||||
|
||||
**When to use `make-pr` skill:**
|
||||
- When ready to submit a PR from your current branch (any platform)
|
||||
- Before pushing code that requires peer review
|
||||
- To ensure all changes are properly documented and validated
|
||||
- When creating PRs for features, fixes, or refactoring
|
||||
|
||||
The skill automatically adapts to your hosting platform:
|
||||
- **GitHub:** Creates PR via API with comprehensive descriptions
|
||||
- **Gitea:** Falls back to web UI creation (URL provided above)
|
||||
|
||||
**Prompt example:**
|
||||
```
|
||||
"Create a pull request from move_docs to develop. The changes include moving
|
||||
all AI documentation files into an 'AI Docs' folder with organized structure."
|
||||
```
|
||||
|
||||
+51
-1424
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user