coffee_crisis_arcade_edition/CLAUDE.md

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)

cmake -B build -DCMAKE_BUILD_TYPE=Debug   # configure
cmake --build build                        # build

Makefile (delegates to CMake)

make                      # build Release via cmake
make debug                # build Debug via cmake
make release              # create release package (auto-detects OS)
make linux_release        # release tar.gz with resources.pack
make windows_release      # release zip for Windows
make macos_release        # release dmg for macOS (Intel + Apple Silicon)
make raspi_release        # release tar.gz for Raspberry Pi

Tools & Resources

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

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/.