104 lines
4.4 KiB
Markdown
104 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Coffee Crisis Arcade Edition is a 2-player cooperative arcade shooter built with C++20 and SDL3. Players defend coffee against giant balloons. The game targets Windows, Linux, macOS (Intel/Apple Silicon), Raspberry Pi, and Anbernic handhelds.
|
|
|
|
## Build Commands
|
|
|
|
The project uses both CMake and a top-level Makefile. The Makefile is the primary build interface.
|
|
|
|
### CMake (generates compile_commands.json for IDE/linter support)
|
|
```bash
|
|
cmake -B build -DCMAKE_BUILD_TYPE=Debug # configure
|
|
cmake --build build # build
|
|
```
|
|
|
|
### Makefile (direct compilation, platform-specific targets)
|
|
```bash
|
|
make linux # build for Linux
|
|
make linux_debug # debug build with -DDEBUG -DVERBOSE
|
|
make linux_release # release tar.gz with resources.pack
|
|
make windows # build for Windows (cross-compile or native)
|
|
make windows_debug # Windows debug build
|
|
make macos # build for macOS (arm64)
|
|
make raspi # build for Raspberry Pi
|
|
make anbernic # build for Anbernic (no shaders, arcade mode)
|
|
make no_audio # build without audio system
|
|
```
|
|
|
|
### Tools & Resources
|
|
```bash
|
|
make pack_tool # compile resource packer
|
|
make resources.pack # pack data/ into resources.pack (required for release builds)
|
|
make spirv # compile GLSL shaders to SPIR-V headers
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
make format # run clang-format on all sources (or: cmake --build build --target format)
|
|
make format-check # check formatting without modifying
|
|
make tidy # run clang-tidy static analysis (cmake --build build --target tidy)
|
|
make tidy-fix # run clang-tidy with auto-fix
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Singletons (core systems)
|
|
- **Director** (`source/director.hpp`) — Application state machine, orchestrates scene transitions (Logo → Intro → Title → Game → Credits/HiScore → Title)
|
|
- **Screen** (`source/screen.hpp`) — Window management, SDL3 GPU rendering pipeline, post-processing effects
|
|
- **Resource** (`source/resource.hpp`) — Asset loading/caching with PRELOAD and LAZY_LOAD modes, reads from `resources.pack`
|
|
- **Audio** (`source/audio.hpp`) — Music and SFX management
|
|
- **Input** (`source/input.hpp`) — Keyboard and gamepad input handling
|
|
|
|
### Scenes (source/sections/)
|
|
Each scene is a self-contained class with update/render lifecycle. Scene flow is managed by Director.
|
|
|
|
### Entity Managers
|
|
- `BalloonManager` / `BulletManager` — Object pool-based entity management
|
|
- `Player` — Two-player support (player 1: keyboard, player 2: gamepad)
|
|
|
|
### Rendering Pipeline
|
|
- SDL3 GPU API (Vulkan/Metal/D3D12 backends)
|
|
- SPIR-V shaders compiled offline from GLSL (`data/shaders/`) via `glslc`
|
|
- Compiled shader headers embedded in `source/rendering/sdl3gpu/postfx_*_spv.h`
|
|
- macOS uses Metal (no SPIR-V compilation needed)
|
|
|
|
### Configuration
|
|
- Game parameters: `config/param_320x240.txt`, `config/param_320x256.txt`
|
|
- Asset manifest: `config/assets.txt`
|
|
- Balloon formations: `config/formations.txt`
|
|
- Level definitions: `config/stages.txt`
|
|
- Gamepad mappings: `config/gamecontrollerdb.txt`
|
|
|
|
### External Libraries (header-only/vendored in source/external/)
|
|
- nlohmann/json, fkyaml (YAML), stb_image, stb_vorbis, jail_audio
|
|
|
|
## Code Style
|
|
|
|
Enforced via `.clang-format` (Google-based) and `.clang-tidy`:
|
|
|
|
- **Naming conventions**: Classes/structs `CamelCase`, methods/functions `camelBack`, variables/params `snake_case`, private/protected members `snake_case_` (trailing underscore), constants/constexpr `UPPER_CASE`, namespaces `CamelCase`, enum values `UPPER_CASE`
|
|
- 4-space indentation, no column limit, braces attach to statement
|
|
- clang-tidy treats all warnings as errors
|
|
|
|
## Conditional Compilation Defines
|
|
|
|
| Define | Purpose |
|
|
|--------|---------|
|
|
| `WINDOWS_BUILD` / `LINUX_BUILD` / `MACOS_BUILD` | Platform selection |
|
|
| `DEBUG` / `VERBOSE` | Debug output |
|
|
| `RELEASE_BUILD` | Release-specific code paths |
|
|
| `RECORDING` | Demo recording mode |
|
|
| `NO_SHADERS` | Disable shader pipeline (Anbernic) |
|
|
| `NO_AUDIO` | Build without audio |
|
|
| `ARCADE` | Arcade-specific mode |
|
|
| `MACOS_BUNDLE` | macOS .app bundle paths |
|
|
| `ANBERNIC` | Anbernic handheld build |
|
|
|
|
## Language
|
|
|
|
Code comments are in Spanish/Catalan. Game UI supports multiple languages via JSON files in `data/lang/`.
|