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/

MakeModLib Build Helper

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

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:

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

# 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