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:

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

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/

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

Bug Tracking with git-bug

This project uses git-bug for distributed bug tracking. Bug data is stored directly in the git repository.

Common Commands

• git bug bug - List all bugs
• git bug bug new -t "title" -m "message" - Create a new bug with title and message
• git bug bug show <id> - Display bug details
• git bug bug comment <id> - Add a comment to a bug
• git bug bug status <id> - Display bug status
• git bug bug label <id> <label> - Add a label to a bug
• git bug bug status:open - List only open bugs
• git bug pull - Pull bug updates from remote
• git bug push - Push bug updates to remote

Workflow

• Bugs are stored in the repository and sync with git bug pull/git bug push
• Bug IDs can be abbreviated to the first few characters
• Use labels to categorize bugs by component (e.g., core, rendering, physics, build-system)
• Use --non-interactive flag for scripting
• Keep bug descriptions factual - describe what happens, not speculation about why