Backlog/CLAUDE.md

# CLAUDE.md

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

## Project Overview

Backlog is a game engine written in Zig (version 0.14) with a modular architecture. The engine supports cross-platform development with Windows, macOS, and Linux targets, and includes support for both static and dynamic module loading.

## Build System

The project uses Zig's build system with a custom `BuildSystem` wrapper:

### Key Build Commands

- `zig build` - Build the engine and default projects
- `zig build -Dcookshaders` - Build with shader compilation enabled
- `zig build -Dstatic_build` - Force static linking (required for Linux)
- `zig build tools` - Install development tools (gltf2ozz, spirv-reflect)
- `zig build gltf2ozz -- [args]` - Run GLTF animation converter
- `zig build spv-reflect -- [args]` - Run SPIRV reflection tool
- `python tools/scripts/cookShaders.py` - Compile shaders from HLSL to SPIR-V, MSL, and DXIL formats, must be run after editing shader files

### Project-Specific Commands

From the `projects/` directory:
- `zig build` - Build sample game and tools
- `zig build run-sampleGame` - Run the sample game
- `zig build run-newProject` - Run the project creation tool

### Testing

- `zig build test` - Run all tests (individual modules have their own test files in `tests/` subdirectories)

### Setup Commands

- `python tools/scripts/first-time-setup.py` - Initial setup script

## Architecture

### Engine Modules

The engine is organized into these core modules:

- **core** - Foundation systems (ECS, logging, memory tracking, jobs, scripting)
- **platform** - Cross-platform windowing and input handling
- **assets** - Asset loading and management system
- **rend** - 3D rendering system with mesh, camera, and material support
- **audio** - Sound engine integration
- **ui** - User interface rendering system
- **papyrus** - Text rendering and UI primitives
- **imgui** - Debug UI integration
- **physics** - Physics engine integration (Jolt)
- **sys** - System utilities and subprocess management

### Key Directories

- `engine/` - Core engine modules, each with their own `build.zig`
- `projects/` - Sample projects and games
- `lib/` - Third-party dependencies and wrappers
- `tools/` - Development utilities and scripts
- `content/` - Game assets and resources (located at `projects/content/`)
- `extras/` - Optional engine extensions

### Engine Initialization

The engine uses a spec-based initialization system where modules are conditionally enabled:

```zig
// Programs define which modules to enable
sampleGame.setModuleEnabled("imgui", true);
sampleGame.setModuleEnabled("physics", true);
```

### Dynamic Modules

The engine supports dynamic module loading for game-specific code:

```zig
const externGame = sampleGame.addDynamicModule("externGame", b.path("sampleGame/externGame/externGame.zig"));
```

### Shader Pipeline

Shaders are written in HLSL and compiled to multiple targets:
- SPIR-V for Vulkan
- MSL for Metal (macOS)
- DXIL for DirectX

The shader compilation system automatically discovers `.hlsl` files in `engine/*/shaders/` directories.

## Development Notes

- All memory allocations go through a centralized `MemoryTracker` for leak detection
- The engine uses Tracy for profiling when enabled
- Lua scripting is integrated for game logic
- The build system generates API wrappers automatically for enabled modules
- Content directory location is determined by `content.txt` file pointing to `projects/content/`

### MakeModLib Build Helper

The project uses a custom `MakeModLib` helper function (defined in `lib/bh/build.zig`) to create library modules with consistent patterns:

```zig
const mylib = bh.MakeModLib(b, .{
    .name = "mylib",
    .target = target,
    .optimize = optimize,
    .static_build = static_build,
    .root = b.path("src/mylib.zig"),
});
```

**What MakeModLib creates:**
- A Zig module (`.mod`) for compile-time imports
- A library artifact (`.lib`) for linking (static or dynamic based on `static_build` flag)
- The library uses an empty stub source file and is intended to carry C dependencies

**Usage pattern:**
All libraries using `MakeModLib` follow this pattern in their test executables:
```zig
tests.root_module.addImport("mylib", mylib.mod);  // Import the module
tests.root_module.linkLibrary(mylib.lib);         // Link the library
```

**Libraries using MakeModLib:**
- `bh`, `cimgui`, `enet`, `lua`, `miniaudio`, `nfd`, `objLoader`, `p2`, `packer`, `spng`, `tracy`, `watcher`, `zgltf`, `zmath`

This pattern separates Zig code (in the module) from C/C++ dependencies (in the library), allowing for flexible static/dynamic linking while maintaining consistent module interfaces.

## Common Development Tasks

- Adding new engine modules: Create in `engine/` with `build.zig` and add to `engineDepList`
- Creating new projects: Use the project template in `projects/minimal/`
- Shader development: Add HLSL files to module `shaders/` directories, run `cookShaders.py`
- Asset pipeline: Assets go in `projects/content/` and use `.cook` extensions for processed assets

## Issue Tracking with git-bug

This project uses git-bug for distributed issue tracking. Bug data is stored directly in the git repository. While named "git-bug", it can track all types of development work including bugs, features, tasks, and documentation.

### Common Commands

- `git bug bug` - List all issues
- `git bug bug new -t "title" -m "message"` - Create a new issue with title and message
- `git bug bug show <id>` - Display issue details
- `git bug bug comment <id>` - Add a comment to an issue
- `git bug bug status <id>` - Display issue status
- `git bug bug label new <id> <label>` - Add a label to an issue
- `git bug bug label rm <id> <label>` - Remove a label from an issue
- `git bug bug label <id>` - Display labels for an issue
- `git bug bug status:open` - List only open issues
- `git bug pull` - Pull issue updates from remote
- `git bug push` - Push issue updates to remote

### Workflow

- Issues are stored in the repository and sync with `git bug pull`/`git bug push`
- Issue IDs can be abbreviated to the first few characters
- Use labels to categorize issues by both type and component
- Use `--non-interactive` flag for scripting
- Keep issue descriptions factual and clear

### Standard Labels

Use these standard labels to categorize issues:

- **Component labels**: `core`, `rendering`, `physics`, `build-system`, `platform`, `assets`, `audio`, `ui`, `documentation`
- **Issue type labels**:
  - `bug` - Defects, errors, or incorrect behavior
  - `feature` - New functionality to implement
  - `enhancement` - Improvements to existing features
  - `task` - General development work items
  - `documentation` - Documentation improvements or additions
  - `question` - Design decisions or technical discussions
  - `refactoring` - Code cleanup and restructuring
- **Problem type labels** (for bugs):
  - `memory` - Memory allocation, leaks, or performance issues
  - `threading` - Job system, parallelization, race conditions, or deadlocks
  - `crash` - Application crashes or critical failures
  - `build` - Build system or compilation issues

### Examples

```bash
# Create a feature request
git bug bug new -t "Add procedural terrain generation" -m "Implement heightmap-based terrain system"
git bug bug label new <id> feature rendering

# Create a task
git bug bug new -t "Update to Zig 0.15" -m "Migrate codebase to latest Zig version"
git bug bug label new <id> task build-system

# Create a documentation issue
git bug bug new -t "Document shader pipeline" -m "Add comprehensive guide for shader development workflow"
git bug bug label new <id> documentation rendering

# Create a bug report
git bug bug new -t "Memory leak in asset loader" -m "Assets not freed when unloading scenes"
git bug bug label new <id> bug assets memory
```