Spark Engine — Open-Source C++ Game Engine

Platforms & Compilers:

Quality & Testing:

Sanitizers (CI-enforced) — click to download latest report:

Rendering Backends:

Spark Engine is a free, open-source 3D game engine written in C++23. While originally built for first-person shooters, Spark Engine is evolving into a general-purpose game engine capable of supporting a wide range of genres — from FPS and action games to open-world RPGs, MMOs, battle royales, and more. Multi-backend RHI rendering (DirectX 11/12, Vulkan, OpenGL, headless) with global illumination, GPU-driven rendering, mesh shaders, virtual texturing, and DXR ray tracing. Jolt Physics (vehicles, ragdoll, cloth, destruction), XAudio2 spatial audio, AngelScript hot-reload scripting with visual scripting and Shader Graph editors, an ECS architecture (EnTT, 75 component types), and an ImGui-based editor with 57 specialized panels. Features inspired by HeroEngine's MMO technology include seamless world streaming, area-based server architecture, floating-point origin rebasing for large worlds, and collaborative multi-user editing. Cross-platform (Windows and Linux), modular, and licensed under the Spark Open License.

v1.0.0 Released — SparkEngine's first official release. Production-ready core systems with active feature development. See the changelog for details.

AI Disclosure — This project makes extensive use of AI-assisted development. All AI-generated code is reviewed, tested, and validated to ensure correctness, stability, and functional integrity. If the use of AI in development is a concern for you, this project may not be the right fit — but if you're open to it, contributions of any and all kinds are welcome!

Why Spark Engine?

• Complete game engine — rendering (6 backends), physics, audio, AI, animation, networking, scripting, visual scripting, and a 57-panel editor all in one package
• General-purpose — FPS, RPG, MMO, battle royale, open-world, RTS, racing, platformer — build any genre with 10 built-in game module templates
• Advanced rendering — global illumination (DDGI/APV), GPU-driven rendering, mesh shaders, virtual texturing, DXR ray tracing, Shader Graph, and RenderGraph
• Scalable multiplayer — from single-player to MMO-scale via HeroEngine-inspired area-based server architecture with seamless entity migration
• Large world support — seamless area streaming and floating-point origin rebasing for worlds of any size
• Truly open-source — Spark Open License, no royalties, no fees, anti-plagiarism protected
• Built for learning and modding — clean C++23 codebase with 30+ toggleable CMake modules, mod system, and visual scripting
• Ready-to-download binaries — nightly Windows and Linux builds published on every commit

Editor Preview

SparkEditor default layout — Hierarchy, Scene View, Inspector, Console, and Asset Browser. Additional panels available from the Window menu. Spark Professional dark theme.

More screenshots

Welcome Screen (first launch)

Window Menu (57 panels available)

GameObject Creation

FPS Tools

Downloads

Nightly

Built automatically on every commit to Working. Always the latest code — all CI checks pass before publishing.

Platform	Release	Debug
Windows (VS 2022 · x64)
Linux (GCC · ubuntu-24.04 · x64)

Nightly builds are from the nightly release. Each release includes the exact commit hash and build timestamp.

Stable (Recommended)

Stable releases are published manually and thoroughly tested. Recommended for most users.

Platform	Release	Debug
Windows (VS 2022 · x64)
Linux (GCC · ubuntu-24.04 · x64)

Download the latest stable release (v1.0.0). For bleeding-edge features, use the nightly build above.

CI Artifacts

Per-commit build artifacts from CI on the Working branch via nightly.link (no GitHub login required).

Build binaries, sanitizer reports, and coverage

Build Binaries:

Sanitizer Reports:

Code Coverage:

Key Features

Rendering

Multi-backend RHI abstraction with DirectX 11 (stable), DirectX 12 (mesh shaders, DXR, VRS), Vulkan 1.4, OpenGL 4.6, and NullRHIDevice (headless). Multiple render paths (forward, deferred, forward+, clustered) with a declarative RenderGraph. PBR metallic/roughness materials, cascaded shadow mapping, SSAO, SSR, volumetric lighting/fog, bloom, HDR tone mapping (Reinhard/ACES/Uncharted 2), TAA, FXAA, MSAA (2x/4x/8x), depth of field, motion blur, chromatic aberration, film grain, lens flares, light shafts, IBL, GPU particle system, decals, water rendering, sky atmosphere, and quality presets (Low/Medium/High/Ultra). Global illumination via DDGI probe grids, Adaptive Probe Volumes (brick-based hierarchical LOD), and a hybrid ray tracing pipeline with SDF fallback. GPU-driven rendering with compute-based frustum culling, hierarchical Z-buffer occlusion, and indirect draw generation. Mesh shader pipeline with meshlet clustering (64-128 tri), amplification/mesh shaders, and software rasterizer fallback. Cluster-based virtual geometry system (DAG hierarchy with screen-space error traversal). Virtual texturing with feedback-driven page streaming and LRU cache. DXR 1.1 ray tracing (reflections, soft shadows, AO, multi-bounce GI) with temporal denoising. FSR upscaling. Node-based Shader Graph (35+ nodes, HLSL generation, live material preview). Full CPU software rendering via OpenGL + Mesa llvmpipe for GPU-less environments.

Physics

Jolt Physics integration with rigid bodies (static/kinematic/dynamic), 15 collision shapes (box, sphere, capsule, cylinder, cone, mesh, convex hull, heightfield, compound), 12 constraint types (hinge, slider, fixed, generic), raycasting (single/multi-hit), sphere and box overlap queries, named physics materials, collision and trigger callbacks, character controller with CCD, vehicle physics, ragdoll system, soft body/cloth simulation, deterministic mode for replay/networking, multi-threaded job dispatch, and debug draw overlay.

Audio

XAudio2 hardware-accelerated 3D spatial audio with distance attenuation, Doppler effects, pitch control, looping, master/SFX/music volume channels, and an object pool for efficient source management. Miniaudio as a cross-platform fallback.

Gameplay

ECS architecture (EnTT) with 75 component types across 17 headers and 25 systems. FPS player controller, weapon system (bullet/rocket/grenade), class system, vehicle mechanics (wheeled/tracked/motorcycle), gravity system, HUD (crosshairs, health bars, kill feed, minimap, compass), interactive objects, inventory system, quest system, achievement system, ability/condition system, event response system (data-driven When/If/Then rules), day/night cycle, weather system, game mode management, heightmap terrain with quadtree LOD and texture splatting, mesh LOD, decal system, destruction/fracture system, branching dialogue system, replay record/playback, tween system with easing functions, coroutine scheduler, and accessibility (5 colorblind modes with daltonization, subtitles, high-contrast UI, reduced motion, one-handed input, screen reader hooks).

AI & Navigation

Behavior tree framework (composite, decorator, and action nodes), NavMesh A* pathfinding (Recast/Detour) with dynamic obstacles and off-mesh links, perception system (vision cones, hearing ranges, memory), steering behaviors (seek, flee, pursue, evade, flocking), tactical point system (EQS-like environmental queries), cover system, formation system, group AI coordination, AI budget limiter for 100+ agents, AI director for scripted events, and collision avoidance.

Animation

Skeletal animation with bone hierarchies, keyframe clips, state machines with cross-fading, multi-layer blending (override/additive/layered with per-bone masks), inverse kinematics (two-bone, look-at, FABRIK), root motion extraction, animation retargeting, ragdoll blending, and soft body/cloth simulation. Cinematic sequencer with timeline tracks (camera, entity, animation, events), Bezier/Catmull-Rom interpolation, and a dedicated editor panel. Supports FBX and glTF via Assimp.

Networking

UDP client/server architecture with entity replication, client-side prediction with server reconciliation, lag compensation (hitbox rewinding with 1-second history), reliable/unreliable/ordered message channels, delta snapshot compression, sub-tick input precision, connection scope filtering, network instability simulation (for testing), and network statistics (ping, jitter, packet loss, bandwidth). Area-based server architecture (inspired by HeroEngine) with WorldServer coordination, per-area AreaServer instances, cross-area entity migration, dynamic load balancing, and player session management across area transitions — enabling MMO-scale multiplayer worlds.

Scripting

AngelScript with Unity-style hot-reload (file watcher with debouncing and state preservation), lifecycle callbacks (Start, Update, OnCollision), full engine API bindings (math, components, input, entities), per-file module isolation, client/server script context separation for multiplayer, and runtime error reporting. Visual scripting system with 60 node types across 8 categories that compiles node graphs to AngelScript (no separate runtime needed). Node-based Shader Graph for visual material authoring (35+ nodes, HLSL output). Lua scripting also supported. Mod system for user-created content.

Editor

ImGui-powered visual editor with 57 specialized dockable panels: scene hierarchy, inspector, asset browser, game viewport, gizmos (ImGuizmo), node graphs (imnodes), animation timeline, material editor with Shader Graph, visual script editor (node-based, compiles to AngelScript), terrain editing, weapon editor, profiler, AI editor/debugger, physics debug, cinematic sequencer, dialogue editor, ability/condition/trigger editors, destruction editor, 2D/sprite/tilemap editors, FPS tools, audio mixer, replay panel, save system panel, dedicated server panel, version control integration, build/deployment pipeline, level streaming, search panel, command palette (Ctrl+P), prefab system, event monitor, coroutine debugger, collaboration panel, project management, scene statistics, accessibility settings, VR configuration, and theming. Collaborative multi-user editing (HeroEngine-inspired node locking, edit broadcasting, peer presence awareness). Full undo/redo support, play-mode editing, and plugin system (built-in + DLL).

Procedural Generation

Noise functions (Perlin, Simplex, Worley, FBM, ridged multifractal, domain warping), heightmap generation with thermal and hydraulic erosion, procedural meshes (plane, box, sphere, cylinder, cone, torus, terrain, rock, tree), rule-based object placement, and Wave Function Collapse room/dungeon layout generation.

Save System

ECS-aware serialization with miniz compression, JSON format, multiple save slots, quicksave/quickload, rotating autosaves, per-component serializer registry, and metadata tracking (scene, player class, playtime).

Tooling

Crash handler with minidump generation, all-thread stack traces, screenshot capture, system info collection, and optional HTTP report upload. Debug console overlay with 200+ commands spanning engine, graphics, physics, audio, input, networking, scripting, and profiling. Performance profiler, memory debugger, frame inspector, and debug draw overlay.

Quick Start

# Clone with submodules
git clone --recurse-submodules https://github.com/Krilliac/SparkEngine.git
cd SparkEngine

# Configure (Windows — Visual Studio 2022)
.\generate.bat -g "Visual Studio 17 2022" release

# Configure (Linux/macOS)
chmod +x generate.sh
./generate.sh release -g Ninja

# Build (Windows)
.\build.ps1 -config Release -editor -angelscript

# Build (Linux/macOS)
./build.sh release

# Run
# Windows:  build/bin/SparkEngine.exe
# Linux:    build/bin/SparkEngine

Requirements

• Compiler: MSVC v143 (Visual Studio 2022 17.6+), GCC 13+, or Clang 17+ with C++23 support
• Build System: CMake 3.25+, Ninja (recommended on Linux)
• Linux packages: build-essential, ninja-build, cmake (e.g. sudo apt install build-essential ninja-build cmake)
• Graphics: DirectX 11 capable GPU (Windows), Vulkan SDK (optional), OpenGL 4.5+ (optional), or NullRHIDevice for headless
• Platform: Windows 10+ (primary), Linux (experimental)

Platform Support Matrix

Platform / Backend	Status	Notes
Windows 10+ (MSVC v143)	Stable	Primary development platform, fully tested in CI
Windows (MSVC v144 / VS 2026)	Experimental	CI job included but skipped until runners ship v144 toolset
Linux (GCC 13+)	Experimental	CI tested on ubuntu-24.04; pre-built binaries available
Linux (Clang 17+)	Experimental	CI tested; some platform-specific features may be missing
macOS (Apple Clang)	Experimental	Builds with C++23 support; no CI or pre-built binaries yet
DirectX 11	Stable	Primary rendering backend
DirectX 12	Experimental	Mesh shaders, DXR, Variable Rate Shading; requires Windows 10+
Vulkan 1.4	Experimental	Via RHI abstraction layer; requires Vulkan SDK
OpenGL 4.6	Experimental	Via RHI abstraction layer; GLSL shaders in Shaders/GLSL/
Metal	Experimental	macOS; API layer designed, implementation in progress
DirectX Raytracing (DXR)	Experimental	Requires D3D12 (Windows); enabled by default with SDFGI software fallback
NullRHIDevice	Stable	Headless mode — no GPU required; automatic fallback
Networking (UDP)	Experimental	Enabled by default (ENABLE_NETWORKING=ON); see Networking

What does "Experimental" mean? These platforms and backends compile and have basic functionality, but are not yet fully tested, may have missing features, and are not guaranteed to work in all configurations. Bug reports are welcome!

Tools

SparkBuild

SparkBuild is a standalone C++ build tool for SparkEngine. A pre-built binary is included at tools/SparkBuild.exe and updated automatically every week via GitHub Actions. You can also update it manually:

# Windows:  .\tools\update-sparkbuild.ps1
# Linux:    ./tools/update-sparkbuild.sh

SparkShaderCompiler

Standalone offline shader compilation tool using the RHI cross-compilation pipeline. Compiles HLSL/GLSL shaders for D3D11, Vulkan, and OpenGL backends.

# Compile a single shader
SparkShaderCompiler BasicVS.hlsl -stage vertex -backend d3d11 -o BasicVS.cso

# Cross-compile HLSL to SPIR-V
SparkShaderCompiler PBR.hlsl -stage pixel -backend vulkan -o PBR.spv

# Validate without writing output
SparkShaderCompiler Water.glsl -stage vertex -backend opengl -validate

# Print shader reflection data
SparkShaderCompiler Phong.hlsl -stage pixel -backend vulkan -reflect

Options: -stage (vertex/pixel/geometry/hull/domain/compute), -backend (d3d11/vulkan/opengl/auto), -entry (entry point), -D (defines), -I (include paths), -O/-Od (optimization), -Zi (debug info), -v (verbose).

SparkConsole

Standalone debug console application that communicates with SparkEngine via named pipes. Provides real-time engine inspection with 200+ commands covering engine status, graphics, physics, audio, networking, and performance monitoring.

Controls

Input	Action
W / A / S / D	Move
Mouse	Look
Space	Jump
Ctrl	Crouch
Left Click	Fire / Capture Mouse
Esc	Release Mouse / Menu
` (Backtick)	Toggle Debug Console

Architecture

+-------------------+-------------------+-------------------+
|    Rendering      |     Physics       |      Audio        |
|                   |                   |                   |
|  RHI (6 backends) |  Jolt Physics     |  XAudio2 / mini   |
|  RenderGraph      |  Vehicles/Ragdoll |  3D Spatial       |
|  GI / GPU-Driven  |  Cloth / Destruct |  Mixer / Music    |
|  PBR / ShaderGraph|  Deterministic    |  Object Pool      |
+-------------------+-------------------+-------------------+
|    Scripting      |    Input & UI     |    Core & ECS     |
|                   |                   |                   |
|  AngelScript VM   |  InputManager     |  EnTT ECS (75+)   |
|  Visual Scripting |  Gamepad / SDL2   |  SceneManager     |
|  Hot Reload / Lua |  ImGui Editor(57) |  AssetPipeline    |
+-------------------+-------------------+-------------------+
|    Gameplay       |    AI & Nav       |    Networking     |
|                   |                   |                   |
|  Weapons/Vehicles |  BehaviorTree     |  UDP Client/Srv   |
|  Quests/Inventory |  NavMesh (A*)     |  AreaServer       |
|  Abilities/Events |  Perception/EQS   |  WorldServer      |
+-------------------+-------------------+-------------------+
|    Procedural     |    Animation      |  Large Worlds     |
|                   |                   |                   |
|  Noise (Perlin+)  |  Skeletal / IK    |  Origin Rebasing  |
|  Erosion / WFC    |  Sequencer        |  Seamless Areas   |
|  Mesh / Terrain   |  Ragdoll / Cloth  |  Scene Streaming  |
+-------------------+-------------------+-------------------+
|   Collaboration   |  Save / Replay    |    Utilities      |
|                   |                   |                   |
|  Multi-User Edit  |  ECS Serializer   |  CrashHandler     |
|  Node Locking     |  Replay System    |  Console (200+)   |
|  Edit Broadcast   |  Autosave / Slots |  Profiler / Debug |
+-------------------+-------------------+-------------------+
|   Accessibility   |  Dialogue / UI    |  Modding / Loc    |
|                   |                   |                   |
|  Colorblind (5)   |  Dialogue Trees   |  Mod System       |
|  Subtitles / TTS  |  UI Extensions    |  Localization     |
|  Reduced Motion   |  Achievements     |  Tween / Coroutine|
+-------------------+-------------------+-------------------+

Project Structure

SparkEngine/
|-- SparkEngine/
|   |-- Source/
|       |-- Audio/           # XAudio2 3D audio engine
|       |-- Camera/          # First-person camera controller
|       |-- Console/         # Debug console integration
|       |-- Core/            # Entry point, engine framework
|       |-- Engine/
|       |   |-- 2D/          # 2D rendering and sprite systems
|       |   |-- Accessibility/ # Colorblind, subtitles, reduced motion, input remap
|       |   |-- AI/          # Behavior trees, NavMesh, perception, steering, EQS
|       |   |-- Animation/   # Skeletal animation, IK, state machines, retargeting
|       |   |-- Cinematic/   # Sequencer, timeline tracks, playback
|       |   |-- Coroutine/   # Async coroutine scheduler
|       |   |-- Destruction/  # Destructible objects and fracture
|       |   |-- Dialogue/    # Branching dialogue system
|       |   |-- ECS/         # Entity component system (EnTT, 75 component types)
|       |   |-- Events/      # Event bus / event response system
|       |   |-- Gameplay/    # Inventory, quests, achievements, abilities, weapons
|       |   |-- Loading/     # Loading screens and management
|       |   |-- Localization/ # Localization system
|       |   |-- Mobile/      # Mobile platform support (touch, gestures, battery)
|       |   |-- Modding/     # Game modding support
|       |   |-- Networking/  # UDP multiplayer, replication, AreaServer, WorldServer
|       |   |-- Persistence/ # Async database-backed persistence
|       |   |-- Physics/     # Physics-specific engine utilities
|       |   |-- Procedural/  # Noise, erosion, mesh generation, WFC
|       |   |-- Replay/      # Record/playback system
|       |   |-- SaveSystem/  # Serialization, compression, save slots
|       |   |-- Scripting/   # AngelScript VM, hot-reload, visual scripting compiler
|       |   |-- Streaming/   # SeamlessAreaManager, SceneTransitionManager
|       |   |-- Tween/       # Tween system with easing functions
|       |   |-- UI/          # UI system and layout extensions
|       |   |-- VR/          # VR headset/controller/tracking (OpenXR-ready)
|       |   |-- World/       # WorldOriginSystem (floating-point origin rebasing)
|       |-- Enums/           # Shared enumerations
|       |-- Game/            # Player, weapons, vehicles, HUD, terrain, inventory
|       |-- Graphics/        # Multi-backend RHI, PBR, GI, GPU-driven, RenderGraph
|       |-- Input/           # Keyboard, mouse, gamepad input
|       |-- Physics/         # Jolt Physics integration
|       |-- Projectiles/     # Weapon projectile system
|       |-- SceneManager/    # Scene and level management
|       |-- Utils/           # Logging, profiler, crash handler, console, debug tools
|-- SparkEditor/
|   |-- Source/              # ImGui editor (57 panels, collaborative editing)
|-- SparkConsole/
|   |-- src/                 # Standalone debug console application
|-- SparkShaderCompiler/
|   |-- src/                 # Offline shader compilation tool
|-- SparkSDK/                # Public SDK/interface headers
|-- GameModules/             # Game module shared libraries (10 modules)
|   |-- SparkGame/           # Base game module
|   |-- SparkGameFPS/        # FPS game module
|   |-- SparkGameMMO/        # MMO game module
|   |-- SparkGameRPG/        # RPG game module
|   |-- SparkGameARPG/       # Action RPG game module
|   |-- SparkGameRTS/        # RTS game module
|   |-- SparkGameRacing/     # Racing game module
|   |-- SparkGamePlatformer/ # Platformer game module
|   |-- SparkGameOpenWorld/  # Open-world game module
|   |-- SparkGameVisualScript/ # Visual script game module
|-- ThirdParty/              # Git submodules (see Dependencies)
|-- Shaders/
|   |-- HLSL/               # DirectX shaders
|   |-- GLSL/               # OpenGL shaders
|   |-- Compiled/           # Pre-compiled DirectX bytecode (.cso)
|-- Assets/
|   |-- Models/             # 3D model files (.obj)
|   |-- Scenes/             # Level/scene JSON files
|   |-- Scripts/            # AngelScript game scripts
|-- Templates/               # Game module project templates
|-- Tests/                   # 3727 unit tests across 303 files (CTest + 5 sanitizers)
|-- tools/
|   |-- SparkBuild.exe       # Pre-built SparkBuild binary
|   |-- update-sparkbuild.*  # Manual update scripts (ps1/sh)
|-- docs/                    # Doxygen docs, wiki, API reference
|-- wiki/                    # 103 wiki pages covering all subsystems
|-- cmake/                   # CMake utility modules
|-- .github/
|   |-- workflows/          # CI/CD (build + release)
|   |-- prompts/            # AI assistant prompt library
|   |-- dependabot.yml      # Automated dependency updates
|-- CMakeLists.txt           # Cross-platform build configuration
|-- build.ps1 / build.sh    # Build scripts
|-- generate.bat / .sh      # CMake configure scripts

Dependencies

All external dependencies are managed as git submodules under ThirdParty/. Dependabot is configured to propose weekly update PRs.

Library	Submodule Path	Purpose
Dear ImGui	UI/imgui	Immediate-mode GUI (docking branch)
EnTT	ECS/entt	Entity component system
Jolt Physics	Physics/JoltPhysics	Physics engine
AngelScript	Scripting/angelscript-mirror	Scripting language
miniz	Utils/miniz	Compression (zlib-compatible)
tinyobjloader	Utils/tinyobjloader	OBJ file loader

The following libraries are included directly in the source tree:

Library	Purpose
DirectXTK	DirectX 11 toolkit
Assimp	3D model import (FBX, glTF, etc.)
ImGuizmo	3D editor gizmos
imnodes	Node graph editor
GLM	Math library
RapidJSON	JSON parsing
spdlog	Structured logging
stb	Image loading
miniaudio	Cross-platform audio fallback

Tests

3727 unit tests across 303 test files covering all major engine systems, built with a lightweight internal test framework (no external test dependencies). Integrated with CMake's CTest.

# Build and run tests
cmake -B build -DBUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

# Export test results to a file (useful for CI review)
./build/bin/SparkTests --output-file test-results.txt

# Export only failures/errors
./build/bin/SparkTests --output-file errors.txt --errors-only

Running Sanitizers Locally

# ASan + UBSan + LSan (GCC) — detects memory errors, undefined behavior, leaks
cmake -B build-asan -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON \
  -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
  -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined" \
  -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined"
cmake --build build-asan --parallel $(nproc)
LSAN_OPTIONS=suppressions=Tests/lsan_suppressions.txt ./build-asan/bin/SparkTests --output-file asan-results.txt

# TSan (GCC) — detects data races and deadlocks
cmake -B build-tsan -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON \
  -DCMAKE_CXX_FLAGS="-fsanitize=thread -fno-omit-frame-pointer" \
  -DCMAKE_C_FLAGS="-fsanitize=thread -fno-omit-frame-pointer" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread" \
  -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=thread"
cmake --build build-tsan --parallel $(nproc)
TSAN_OPTIONS=suppressions=Tests/tsan_suppressions.txt ./build-tsan/bin/SparkTests --output-file tsan-results.txt

# MSan (Clang + libc++) — detects uninitialized memory reads
cmake -B build-msan -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON \
  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_CXX_FLAGS="-fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer -stdlib=libc++ -fsanitize-ignorelist=$(pwd)/Tests/msan_ignorelist.txt" \
  -DCMAKE_C_FLAGS="-fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer -fsanitize-ignorelist=$(pwd)/Tests/msan_ignorelist.txt" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=memory -stdlib=libc++ -lc++abi" \
  -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=memory -stdlib=libc++"
cmake --build build-msan --parallel $(nproc)
./build-msan/bin/SparkTests --output-file msan-results.txt

Test coverage spans all major subsystems: core utilities (math, string, file, UUID, config, ring buffer, object pool), ECS (world, components, integration), physics (rigid bodies, collision layers, frustum culling, interpolation), AI (behavior trees, NavMesh, steering, EQS, formations, cover, group AI), animation (state machines, IK, retargeting, cloth, blend spaces), networking (NetBuffer, encryption, prediction, reliable channels, replication, dedicated server, integration), gameplay (weapons, inventory, quests, achievements, destruction, dialogue, cooldowns), graphics (fog, SSAO/SSR, post-processing, temporal effects, mesh LOD, lights, upscaling, render graph, water, terrain), scene management (serialization, snapshots, loading), events (EventBus, coroutines, tweens), editor (play mode, debug tools, collaborative editing), and infrastructure (engine context, modules, profiling, RBAC).

Build Options

All options are passed to CMake via -D<OPTION>=ON/OFF.

Option	Default	Description
ENABLE_GRAPHICS	ON	Graphics rendering system
ENABLE_EDITOR	ON	ImGui visual editor
ENABLE_PROFILING	ON	Performance profiling tools
ENABLE_NETWORKING	ON	UDP networking (client/server, area servers, replication)
ENABLE_VULKAN	ON	Vulkan graphics backend (experimental)
ENABLE_OPENGL	ON	OpenGL graphics backend (experimental)
ENABLE_METAL	OFF	Metal graphics backend (macOS, experimental)
ENABLE_DXR	ON	DirectX Raytracing (Windows/D3D12; SDFGI fallback on other platforms)
ENABLE_HYBRID_RT	ON	Hybrid ray tracing (SDFGI software + optional hardware DXR/Vulkan RT)
ENABLE_RECAST	ON	Recast/Detour navmesh generation
ENABLE_NEURAL_RENDERING	ON	Neural rendering features (NTC, radiance cache, neural post-processing)
ENABLE_VR	OFF	VR/AR framework (OpenXR-ready stub)
ENABLE_MOBILE	OFF	Mobile platform support (touch, gestures, battery-aware scaling)
ENABLE_SDL2	OFF	SDL2 cross-platform input (auto-enabled on Linux)
SPARK_HEADLESS_SUPPORT	ON	Headless/dedicated server mode support
BUILD_TESTS	ON	Build test suite (CTest)
BUILD_GAME_MODULES	ON	Build in-tree game modules (SparkGameFPS, SparkGameMMO, etc.)
SPARK_STRICT_DEPS	OFF	FATAL_ERROR on missing critical dependencies (Jolt, ImGui, EnTT)
SPARK_SUPPRESS_THIRDPARTY_WARNINGS	ON	Suppress compiler warnings from third-party libraries
SPARK_DOUBLE_PRECISION_PHYSICS	OFF	Double precision physics (JPH_DOUBLE_PRECISION) for large worlds
ENABLE_CONSOLE_IN_SHIPPING	OFF	Include SparkConsole in Shipping builds
ENABLE_DEVCOMMANDS_IN_SHIPPING	OFF	Include developer commands in Shipping builds
STRIP_DEBUG_SYMBOLS	OFF	Strip debug symbols from the final binary

# Example: minimal build without editor
cmake -B build -DENABLE_EDITOR=OFF

CI/CD

Two GitHub Actions workflows run automatically:

build.yml — runs on every push / PR to main, develop, and feature/**:

• Platforms: Windows (MSVC VS 2022 + experimental VS 2026^1), Linux GCC, Linux Clang
• Configurations: Debug and Release matrix
• Sanitizers: 5 sanitizer jobs with downloadable report artifacts (14-day retention)
• Steps: checkout with submodules, CMake configure, build, test, artifact upload

Sanitizer Job	Compiler	What it detects	Suppression files
ASan + UBSan + LSan	GCC	Buffer overflows, use-after-free, undefined behavior, memory leaks	Tests/lsan_suppressions.txt
TSan	GCC	Data races, deadlocks, thread-safety violations	Tests/tsan_suppressions.txt
MSan	Clang + libc++	Reads of uninitialized memory	Tests/msan_ignorelist.txt (continue-on-error^2)

^2 MSan (MemorySanitizer): MSan requires the entire process — including the C++ standard library — to be compiled with MSan instrumentation. The system libc++ on ubuntu-24.04 is not instrumented, which produces false positives in basic string/IO operations. The job is marked continue-on-error and its report artifact is uploaded for manual review of genuine findings. A fully clean MSan run would require building libc++ from source with -fsanitize=memory.

^1 VS 2026 (v144 toolset): The VS 2026 CI job is included for forward compatibility but will be skipped until GitHub Actions runners ship with the v144 platform toolset. It is marked continue-on-error and does not gate merges.

release.yml — runs on every push to master / main:

• Builds Windows (VS 2022) and Linux (GCC) in Debug + Release
• Packages each configuration into a zip / tar.gz archive
• Creates or updates the rolling latest GitHub Release with all four binaries and the exact commit hash

update-sparkbuild.yml — runs weekly (Monday 06:00 UTC) or on manual dispatch:

• Downloads the latest SparkBuild release binary
• Opens a PR to update tools/SparkBuild.exe when a new version is detected

Documentation

• Troubleshooting Guide — Startup issues, debug commands, common fixes
• Feature Roadmap — Planned features across 3 priority tiers
• Project Status — Current system status and recent changes
• API Documentation — Doxygen-based auto-generated API docs
• AI Prompt Library — Prompts for Copilot, GPT, Claude, and others

Generating API Docs

cd docs
./generate-docs.sh        # One-time generation
./auto-update.sh monitor  # Continuous monitoring

Requires doxygen and graphviz.

Templates & Game Modules

SparkEngine supports game modules — shared libraries (.dll on Windows, .so on Linux) that the engine loads at startup. This lets you build your game independently from the engine using only the installed SDK.

Quick Start (Game Module)

# 1. Install SparkEngine to a local prefix
cmake --install build --prefix ~/SparkEngine-install

# 2. Copy the empty template and build it
cp -r Templates/EmptyProject MyGame && cd MyGame
# Replace {{PROJECT_NAME}} placeholders with your project name
cmake -B build -DCMAKE_PREFIX_PATH=~/SparkEngine-install
cmake --build build --config Release

# 3. Run your module through the engine
# Windows:  SparkEngine.exe -game MyGame.dll
# Linux:    ./SparkEngine -game libMyGame.so

Important: You must use the install prefix (the path passed to --prefix) as CMAKE_PREFIX_PATH, not the build directory. The build tree does not contain the CMake config files that find_package(SparkEngine) needs.

See Templates/README.md for full documentation on prerequisites, project structure, and creating new projects.

For additional templates covering physics, AI, networking, procedural generation, and more, check out SparkTemplates.

Networking Configuration

The networking system is enabled by default (ENABLE_NETWORKING=ON). It uses raw UDP sockets — no external networking dependencies are required.

What you get

Feature	Details
Protocol	UDP client/server
Replication	Entity state sync with dirty property tracking
Prediction	Client-side prediction with server reconciliation
Lag compensation	Hitbox rewinding with 1-second history
Message channels	Unreliable, Reliable, ReliableOrdered
Statistics	Ping, jitter, packet loss, bandwidth
Area servers	Per-area server instances coordinated by a WorldServer
Entity migration	Cross-area entity serialization and transfer
Load balancing	Dynamic area reassignment across machines
Player sessions	Session management across area transitions

Platform support

Platform	Status	Dependencies
Windows	Experimental	ws2_32, wsock32 (linked automatically)
Linux	Experimental	POSIX sockets (no extra packages)
macOS	Untested	Expected to work via POSIX sockets

Troubleshooting

• Connection refused — Ensure the server is running and firewall rules allow UDP traffic on your chosen port.
• High packet loss — Check NetworkStats via the console command net_stats for diagnostics.

Console commands

net_status, net_connect <host> <port>, net_disconnect, net_host <port>, net_stats, net_clients

Source

SparkEngine/Source/Engine/Networking/NetworkManager.h — Full API with message types, replication, and lag compensation.

License

Spark Open License 1.0. See LICENSE for details.