pollo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

"Los pollos hermanos" (pollo) is a C++20 game using SDL3 and OpenGL. Cross-platform support for Windows, macOS, and Linux.

Build Commands

Using CMake (recommended for development)

cmake -B build && cmake --build build

Using Makefile (platform-specific)

# Development builds
make macos          # macOS
make linux          # Linux
make windows        # Windows

# Debug builds (with symbols, starts at GAME scene)
make macos_debug
make linux_debug
make windows_debug

# Release builds (creates distributable packages)
make macos_release   # Creates .dmg files for Intel and Apple Silicon
make linux_release   # Creates .tar.gz
make windows_release # Creates .zip

Static Analysis Targets (via CMake)

cmake --build build --target tidy        # Run clang-tidy
cmake --build build --target tidy-fix    # Run clang-tidy with auto-fix
cmake --build build --target format      # Run clang-format
cmake --build build --target format-check # Check formatting

Linting Commands

clang-tidy

tools/linter/run_clang-tidy.sh [--fix] [files...]  # Specific files or all
tools/linter/run_clang-tidy.sh source/game/entities/player.cpp

cppcheck

tools/linter/run_cppcheck.sh -w [--path <path>]  # warning, style, performance (daily use)
tools/linter/run_cppcheck.sh -a [--path <path>]  # all checks (exhaustive)
tools/linter/run_cppcheck.sh -u                   # unused functions
# Results saved to tools/linter/cppcheck-result-*.txt

Architecture

Core Engine (source/core/)

• audio/: Audio system with jail_audio.hpp (external, excluded from linting)
• input/: Input handling (keyboard, mouse, gamepad) via Input, Mouse, GlobalInputs
• rendering/: SDL3/OpenGL rendering system - Screen, Surface hierarchy, Texture, Text, shaders
• resources/: Resource pack system - ResourcePack for asset bundling, ResourceCache, ResourceLoader
• system/: Director (main loop), GlobalEvents, Debug (debug-only builds)

Game Logic (source/game/)

• scenes/: Scene classes (Logo, Title, Game) - each scene manages its own lifecycle
• scene_manager.hpp: Scene flow control with SceneManager namespace
• entities/: Game objects (Player, Enemy, Item)
• gameplay/: Game systems - Room, RoomLoader, CollisionMap, TilemapRenderer, managers
• ui/: UI components (Notifier)
• defaults.hpp: Game constants (excluded from magic-numbers linting)
• options.hpp: Configuration

Scene Flow

Director runs the main loop and delegates to scenes based on SceneManager::current:

• Debug builds start at Scene::GAME
• Release builds start at Scene::LOGO -> Scene::TITLE -> Scene::GAME

Code Style

Naming Conventions (enforced via .clang-tidy)

• Variables: snake_case
• Private/protected members: snake_case_ (trailing underscore)
• Classes/Structs/Enums: CamelCase
• Enum values: UPPER_CASE
• Methods/Functions: camelBack
• Namespaces: CamelCase
• Constants: UPPER_CASE

Headers

• Use #pragma once (not include guards)
• Initialize all struct members with default values
• Prefer std::array over C-style arrays
• Order: public section first, then private

Slash Commands

• /refactor-class - Refactors a C++ class applying style best practices, runs linters, compiles
• /lint-clang-tidy - Runs clang-tidy analysis with intelligent false positive filtering
• /lint-cppcheck - Runs cppcheck analysis with categorized results

Build Prerequisites

• SDL3 (framework included in release/frameworks/ for macOS)
• OpenGL
• C++20 compiler (clang++ on macOS, g++ on Linux/Windows)
• CMake 3.10+