128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# 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/`
|
|
|
|
## 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 |