Backlog/docs/overview.md

Backlog Game Engine Overview

The Backlog Game Engine is a modern, modular game engine built with Zig, designed for cross-platform game development. It provides a comprehensive set of tools and systems for creating interactive 3D applications and games.

Prerequisites

• Zig 0.14 or later
• Python 3 for build scripts

Running Examples

The engine comes with several examples to demonstrate its capabilities:

Sample Game

The main example showcasing most engine features including:

• 3D rendering with meshes and textures
• Physics simulation
• ImGui debug interface
• Input handling
• Dynamic module loading

To run the sample game:

cd projects
zig build run-sampleGame

To compile and target linux with cross compiling,

zig build -Dtarget=x86_64-linux-gnu

The linux build is always compiled as a static executable.

Sample Game Controls:

• WASD - Move camera
• Mouse - Look around (toggle menu with T)
• E/Q - Move up/down
• R - Reload shaders
• Escape - Exit

Minimal Example

A basic template demonstrating the minimal setup required for a Backlog application:

cd projects/minimal
zig build
zig build run-minimal

This example shows:

• Basic engine initialization
• ImGui integration
• Simple game loop structure

Creating New Projects

The engine includes a project creation tool to help you get started with new projects quickly.

Using the New Project Tool

1. Navigate to the projects directory:

   cd projects
   

2. Run the project creator:

   zig build run-newProject
   

3. Click "Create Project" to generate your new project structure

Manual Project Creation

Alternatively, you can create projects manually by copying the minimal template:

1. Copy the projects/minimal directory:

   cp -r projects/minimal projects/my-new-project
   

2. Edit projects/my-new-project/build.zig and update:

   • Project name
   • Root source file path
   • Enabled modules as needed

3. Modify src/main.zig to implement your game logic

Project Structure

A typical Backlog project includes:

my-project/
├── build.zig              # Build configuration
├── build.zig.zon          # Dependencies
├── src/
│   └── main.zig          # Main game code
├── content/              # Game assets (optional)
└── Saved/                # Runtime generated files

Engine Modules

When creating projects, you can enable these modules:

• core - Essential engine systems (always enabled)
• platform - Windowing and input (always enabled)
• assets - Asset loading and management (always enabled)
• rend - 3D rendering system (always enabled)
• imgui - Debug UI and developer tools
• audio - Sound and music playback
• physics - Physics simulation (Jolt Physics)
• ui - User interface rendering
• papyrus - Text rendering and UI primitives
• sys - System utilities

Asset Pipeline

Assets are placed in the content/ directory within your project:

all shaders are cooked to the target system's native format. DXIL for dx12, msl for metal and spv for vulkan.

These cooked format shaders are placed under content/_shaders

Building and Development

Building Projects

From your project directory:

zig build                    # Build project
zig build run-[projectname]  # Build and run

Testing

Run tests for the entire engine:

zig build test

Or test individual modules:

cd engine/core
zig build test