zfxaction26_1/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This repository should be organized as a Godot 4 .NET project from the root:

• project.godot project entrypoint
• SideScrollerGame.csproj and optional solution file
• scenes/ playable scenes such as scenes/player/Player.tscn
• scripts/ C# gameplay code paired with scenes
• assets/ sprites, audio, fonts, and tile sets
• tests/SideScrollerGame.Tests/ .NET test project for engine-light logic
• addons/ third-party Godot plugins when needed
• build/ local export output; do not commit generated files unless release workflow requires it

Keep scene and script paths aligned. Example: scenes/enemies/Slime.tscn with scripts/enemies/Slime.cs.

Build, Test, and Development Commands

Run commands from the repository root. On Windows PowerShell, use the repo-local wrapper as .\godot.

• .\godot --editor --path . opens the project in the editor
• .\godot --headless --path . --build-solutions builds generated C# project files through Godot
• dotnet build compiles the game assemblies and catches regular C# build errors
• dotnet test tests/SideScrollerGame.Tests runs automated unit tests
• .\godot --headless --path . --export-release "Windows Desktop" ./build/SideScrollerGame.exe exports a desktop build when presets are configured

Document any custom wrapper scripts in README.md if the team adds them later.

Coding Style & Naming Conventions

Use 4 spaces for indentation, nullable reference types, and one primary public type per file. Keep Godot node scripts thin and move reusable gameplay rules into plain C# classes that do not depend on scene state.

• PascalCase for classes, methods, properties, scene files, and C# scripts: PlayerController, PlayerController.cs
• m_PascalCase for private fields
• s_PascalCase for static fields
• camelCase for locals and parameters
• snake_case for asset filenames: player_idle.png, forest_theme.ogg

Use partial classes only when Godot generation requires them; avoid mixing unrelated responsibilities in one node script. Keep a strict element order inside of types:

• Nested types
• Constructors
• Disposable implementation
• Methods
• Properties
• Static Members
• Events
• Fields

Testing Guidelines

Use a .NET test project under tests/ and mirror gameplay areas, for example tests/SideScrollerGame.Tests/Player/PlayerControllerTests.cs. Prefer xUnit-style or NUnit-style tests for movement math, combat rules, save/load logic, and other engine-light systems.

Add regression tests for every gameplay bug fix when practical. If scene-level automation is added later, keep it separate from fast unit tests.

Working rules

• This is a Windows environment, WSL is not installed (i.e. sed is not available). You're running under PowerShell 7.6.0. Due to platform restrictions, file deletions are not possible. Replacing the entire file content via a context diff is a viable alternative.
• PowerShell doesn't support bash-style heredocs. If complex scripts need to be executed, consider using python. Run Python code using python -c with inline commands instead of python - <<'PY'.
• Before beginning with the edit phase, always present a plan first. Only begin editing after the user approves the plan.
• Don't make assumptions in the plan. If necessary, ask all clarifying questions before presenting the final plan.
• After every iteration, evaluate if the test coverage would fall below 100%, and write tests if necessary.
• After every iteration, run jb cleanupcode --build=False $file1;$file2;... for every file you touched.
• After every iteration, if there's a relevant documentation for the current task, update it according to the change.
  • Update the wording of touched concerns instead of introducing incremental change reports
  • The documentation should always represent the current state in its entirety and not derail into a historical development log.
• After every iteration, do a git commit with a brief summary of the changes as a commit message.
• Keep changes small and commit often. If one iteration encompasses many smaller tasks with more than one commit, create a git branch and do the commits there. Let me review the branch before merging it back to master.
• When multiple commits are necessary, pause after every commit and ask the user to give a command to proceed.
• If you find unexpected changes in the code (deletions, changes, diff results that were not communicated), never revert them and never restore the old state. Assume that those changes happened with intent.
• Never use git restore, git checkout --, reset commands, or equivalent rollback actions to discard local changes unless the user explicitly asks for that exact rollback.