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) { ... }