169 lines
6.5 KiB
Markdown
169 lines
6.5 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
|
|
|
|
## 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
|
|
``` |