primer commit

CLAUDE.md

@@ -0,0 +1,109 @@
+# 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)
+```bash
+cmake -B build && cmake --build build
+```
+
+### Using Makefile (platform-specific)
+```bash
+# 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)
+```bash
+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
+```bash
+tools/linter/run_clang-tidy.sh [--fix] [files...]  # Specific files or all
+tools/linter/run_clang-tidy.sh source/game/entities/player.cpp
+```
+
+### cppcheck
+```bash
+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+