Frogger-FPS/CONTRIBUTING.md

# Contributing to FrogFPS

## Coding Standards

### C# Conventions

- Use `PascalCase` for class names, `camelCase` for methods/properties
- Godot nodes: use `[Export]` for inspector-exposed fields
- Signals: connect via code using `Connect()` or `[Signal]` attribute
- Prefer composition over inheritance where possible

### Scene Files (.tscn)

- Keep scene hierarchy flat — avoid deep nesting
- Use unique node names (no "Node", "Node2D", etc.)
- Group related nodes under a named parent

### Git Workflow

- Small, focused commits with descriptive messages
- Branch naming: `feat/<name>`, `chore/<name>`, `bugfix/<name>`
- Pull requests should include what/why, not just what changed

#### Conventional Commits

Use this format for all commit messages:

```
<type>: <description>
```

**Types:**

| Type      | When to use                                          |
|-----------|------------------------------------------------------|
| `feat`    | New feature or functionality                         |
| `fix`     | Bug fixes                                            |
| `chore`   | Maintenance, docs, config, dependencies              |
| `refactor`| Code change that neither fixes a bug nor adds a feat |
| `test`    | Adding or updating tests                             |
| `docs`    | Documentation changes only                           |
| `style`   | Formatting, whitespace, semicolons (no code change)  |
| `perf`    | Performance improvements                             |

**Examples:**

```
feat: add player movement with WASD and mouse look
fix: resolve collision detection issue on river logs
chore: update README with setup instructions
docs: add game design questionnaire
refactor: extract enemy AI into separate class
perf: optimize physics process loop
```

**Rules:**

- Lowercase description after the colon
- No period at the end
- Imperative mood: "add" not "added" or "adds"

## AI Development Guidelines

When working with AI assistants on this project:

1. **Context first** — share relevant scene structure and existing code before asking for implementations
2. **Godot patterns** — AI should follow Godot 4 C# conventions (signals, `_Process`, `_PhysicsProcess`, etc.)
3. **Incremental changes** — one feature at a time; verify each works before moving on
4. **Scene integrity** — don't modify `.tscn` files directly unless necessary; prefer code-based node creation
5. **C#优先** — implement as much as possible in C# rather than GDScript or visual scripting

## AI Development Cycle

All feature work follows this cycle:

```
┌─────────────────────────────────────────────────────────────┐
│ 1. PLAN CHANGES                                             │
│    - Describe what will be built, why, and how              │
│    - List files to create/modify                            │
│    - Note any design decisions                              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. REVIEW CHANGES (initial)                                 │
│    - Self-review before implementation                        │
│    - Check against design doc and questionnaire              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. PRESENT CHANGES                                          │
│    - Show what you plan to do                               │
│    - Await feedback/approval                                │
└─────────────────────────────────────────────────────────────┘
                              ↓ (feedback → loop back to Plan)
                              ↓ (approved)
┌─────────────────────────────────────────────────────────────┐
│ 4. IMPLEMENT CHANGES                                        │
│    - Write code, create scenes, update docs                 │
│    - Keep changes focused and atomic                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. REVIEW CHANGES (fresh perspective)                       │
│    - Use a fresh subagent or second pass without bias       │
│    - Check for bugs, style issues, Godot best practices     │
└─────────────────────────────────────────────────────────────┘
                              ↓ (issues → loop back to Implement)
                              ↓ (approved)
┌─────────────────────────────────────────────────────────────┐
│ 6. PRESENT FINAL CHANGES                                    │
│    - Show completed implementation                          │
│    - Summarize what was done                                │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. DOCUMENT DESIGN CHOICES (if applicable)                  │
│    - Update DESIGN.md with key decisions                    │
│    - Note trade-offs, alternatives considered               │
└─────────────────────────────────────────────────────────────┘
```

### Key Rules

- **Never skip review** — even small changes get a second look
- **Fresh eyes matter** — use a different agent/context for the final review when possible
- **Feedback is mandatory** — if feedback requests changes, loop back to Plan
- **Document decisions** — if a design choice was made, record it in `DESIGN.md`

## Quick Reference

| Concept | Pattern |
|---------|---------|
| Node script | `public partial class MyClass : Node3D { ... }` |
| Export variable | `[Export] public int Health { get; set; } = 100;` |
| Signal | `[Signal] public delegate void HealthChangedEventHandler(int newHealth);` |
| Process loop | `public override void _Process(double delta) { ... }` |
| Physics loop | `public override void _PhysicsProcess(double delta) { ... }` |