MovementTests/agents.md

Project Overview: Godot C# Movement Tests

This project is a high-performance 3D character controller for Godot 4.x using C# 13 and .NET 9. It focuses on modular movement systems (Dash, Mantle, Stairs) and robust combat mechanics (Damage, Health, Knockback) decoupled through interfaces.

Core Architecture

• Modular Systems: The PlayerController.cs acts as a central hub for multiple specialized "Systems" (e.g., DashSystem, MantleSystem, HeadSystem, StairsSystem).
• State Management: Uses GodotStateCharts for complex movement and action states. Look for state transitions and triggers within the system scripts.
• Interface-Driven Design: Located in /interfaces/, these define how objects interact (e.g., IDamageable, IHealthable, IKnockbackable). Always implement these interfaces for new interactable entities.
• Node Composition: Most systems are attached to the PlayerController scene as child nodes and initialized via their respective Init() methods or exported fields.

Key Directories

• /scenes/player_controller/: Contains the main player scene, the central PlayerController.cs, and its sub-systems.
• /scenes/player_controller/components/: Modular logic for specific features like Dash, Mantle, and Weapons.
• /interfaces/: Core C# interfaces and shared records (e.g., DamageRecord, HealthChangedRecord).
• /tests/: Automated unit and integration tests using GdUnit4 and xUnit.

Coding Standards & Idioms

• C# 13 & .NET 9: Use modern C# features (records, primary constructors, collection expressions).
• Godot Partial Classes: All Godot scripts must be partial and use [GlobalClass] where appropriate for editor visibility.
• RustyOptions: The project uses RustyOptions for safer null handling and result types (Option<T>, Result<T, E>).
• Signals: Use [Signal] and the EventHandler pattern for Godot signals.
• Dependency Injection: Systems are typically assigned to fields in PlayerController via the editor or GetNode<T>() in _Ready().

LLM Interaction Tips

1. Partial Classes: When suggesting changes to PlayerController.cs or systems, remember they are partial. Large files like PlayerController.cs (2500+ lines) are often split or contain many regions.
2. Node Hierarchy: Always check PlayerController.tscn or system scenes (head_system.tscn) when dealing with node references (GetNode).
3. GdUnit4: For testing, follow the pattern in tests/PlayerMovementTest.cs. Use ISceneRunner to simulate inputs and await frames/milliseconds.
4. Vector Operations: Use Godot's built-in Vector3 methods for movement logic. The project often uses GlobalPosition and DirectionTo.
5. Boilerplate: When creating new systems, mirror the Init() and _PhysicsProcess patterns found in existing systems like DashSystem.cs or MantleSystem.cs.