ghostland-game/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

Core gameplay lives in root-level C++ translation units: ghostland.cpp orchestrates the loop, player.cpp, ghost.cpp, collisions.cpp, shader.cpp, text.cpp, and config.cpp own their respective systems. Runtime assets stay alongside code: GLSL shaders (*shader.glsl), UI textures (PNG in the repo root), and bitmap fonts under fonts/. Level data is serialized in maze.txt, typically regenerated via mazeparser.py from maze.png. Adjustable settings belong in ghostland.json; document experimental JSON entries before relying on them in code to avoid null lookups.

Build, Test, and Development Commands

• make – builds all objects with C++17 + O3 and links the ghostland binary with GLFW, GLAD, stb_image, and Freetype.
• ./ghostland – runs the game from the repo root; pass config overrides via ghostland.json.
• make clean – removes all .o files and the executable; run before release builds to ensure a full relink.
• python3 mazeparser.py – regenerates maze.txt from the source maze image; adjust the image path in the script if you keep art assets elsewhere.

Coding Style & Naming Conventions

Use 4-space indentation, braces on the same line as control statements, and guard new modules with include guards. Keep standard-library/GLM includes before project headers as in ghostland.cpp. Classes use PascalCase (Player), local variables use snake_case, compile-time constants stay uppercase. Prefer STL containers over manual arrays unless performance-critical, and keep shader uniform names centralized near the top of ghostland.cpp.

Testing Guidelines

There is no automated framework yet, so rely on focused manual passes. Before opening a PR, build fresh (make clean && make), run ./ghostland, and verify spawn position, collision bounds, ghost ordering, and text rendering. When touching geometry, regenerate maze.txt and inspect extremes logged at the bottom of the file. Mention any GPU or driver quirks encountered so others can reproduce.

Commit & Pull Request Guidelines

Existing history favors short, descriptive subjects ("Player's position is reset when close to ghosts"). Follow that tone, keep subjects under 72 characters, and add body lines for rationale or performance numbers. Each PR should include: summary of gameplay-visible changes, configs or assets touched, reproduction steps or screenshots when visuals change, and confirmation that make succeeds on a clean tree. Link related issues and call out any follow-up tasks explicitly.