Skip to content

Ronin15/SDL3_HammerEngine_Template

BranchesTags

Repository files navigation

SDL3 HammerEngine Template

A modern, production-ready C++20 SDL3 game engine template for 2D games. Built for rapid prototyping and scalable game development, it features Data-Oriented Design with EntityDataManager as the central data authority, robust multi-threading, high-performance AI supporting 10K+ entities, a professional UI system, and comprehensive resource and event management. Designed for cross-platform deployment (Windows, macOS, Linux) with a focus on performance, safety, and extensibility.

Key Features

  • Modern C++20 & SDL3 Core

    Clean, modular codebase with strict style, memory, and type safety.

  • Rendering & Engine Core

    Fixed timestep game loop with smooth interpolation at any display refresh rate. Adaptive VSync, sprite sheet animations, particle effects with camera-aware culling, and pixel-perfect zoomed rendering with smooth sub-pixel scrolling. Optional GPU rendering path (-DUSE_SDL3_GPU=ON) for modern graphics with day/night ambient lighting effects.

  • Adaptive Multi-Threading System

    Hardware-adaptive thread pool with intelligent WorkerBudget batch optimization. Automatically detects logical cores (including SMT/hyperthreading) and reserves one to reduce OS contention. Sequential manager execution gives each system ALL workers during its update window. Throughput-based hill-climbing converges to optimal batch sizes for your hardware. Priority-based scheduling (5 levels) with cache-line aligned atomics for minimal lock contention.

  • High-Performance AI System

    Data-Oriented Design with EntityDataManager as single source of truth. Cache-friendly, lock-free, batch-processed AI using Structure-of-Arrays storage. Supports 10K+ entities at 60+ FPS with only 4-6% CPU usage. Includes dynamic behaviors (Wander, Patrol, Guard, Flee, Attack, etc.), simulation tiers (Active/Background/Hibernated), and distance-based culling.

  • Robust Event & State Management

    Event-driven architecture with batch event processing, state machines for entities and game flow, and thread-safe manager updates.

  • Flexible UI System

    Content-aware auto-sizing, professional theming (light/dark/custom), and rich component library (buttons, labels, input fields, lists, modals, etc.). Responsive layouts with DPI-aware rendering and animation support. Centralized UI constants with resolution-aware scaling (1920×1080 baseline) and event-driven resize handling. Optimized for PC handheld devices (Steam Deck, ROG Ally, OneXPlayer) with automatic baseline resolution scaling down to 1280×720.

  • Automatic Resource Management

    JSON-based resource loading for items, materials, currency, and custom types. Handle-based runtime access for performance and extensibility.

  • Fast, Safe Serialization

    Header-only binary serialization system with smart pointer memory management. Used by SaveGameManager for robust, versioned save/load across platforms.

  • Comprehensive Testing & Analysis

    65+ test executables with Boost.Test framework covering unit, integration, and performance testing. Includes AI+Collision integration tests, GPU rendering tests, SIMD correctness validation, and comprehensive thread safety verification with documented TSAN suppressions. Static analysis (cppcheck, clang-tidy), AddressSanitizer (ASAN), ThreadSanitizer (TSAN), and Valgrind integration for production-ready quality assurance.

  • Debug Profiling Tools

    Built-in frame profiler (F3 toggle) with live timing overlay and automatic hitch detection. Zero overhead in Release builds.

  • Cross-Platform Optimizations

    Unified codebase with platform-specific enhancements: SIMD acceleration (x86-64: SSE2/AVX2, ARM64: NEON), macOS Retina support with borderless fullscreen, Wayland detection, adaptive VSync, and native DPI scaling.

  • GameTime & World Simulation

    Fantasy calendar system with day/night cycles, four seasons, dynamic weather, and temperature simulation. Event-driven controllers for time-based gameplay.

  • Chunk-Based World System

    Efficient tile-based world rendering with chunk culling for off-screen optimization. Supports procedural generation, seamless streaming, and automatic seasonal tile switching.

  • Robust Combat System

    Dedicated CombatController handles all combat logic, including hit detection, damage calculation, and status effects. Integrated with entity state machines and event system for dynamic combat scenarios.

  • Power Efficient (Race-to-Idle)

    Optimized for battery-powered devices. Completes frame work quickly then sleeps until vsync, achieving 80%+ CPU idle residency during active gameplay. See Power Efficiency for detailed benchmarks.

  • Extensive Documentation

    Full guides, API references, best practices, and troubleshooting for all major systems.

Why Choose HammerEngine Template?

  • Performance: Engineered for cache efficiency, lock-free concurrency, and minimal CPU overhead—even with thousands of entities.
  • Safety: Smart pointers, RAII, strong typing, and robust error handling throughout.
  • Extensibility: Modular managers, clear APIs, and easy resource and UI customization.
  • Developer Experience: Clean code, strict style, automated testing, and comprehensive docs.
  • Production-Ready Design: Architecture and tooling designed for serious game development, with comprehensive testing infrastructure and performance validation.

Get started building your next 2D game with a foundation that’s fast, safe, and ready for anything.

Quick Start

Prerequisites

  • CMake 3.28+, Ninja, C++20 compiler (GCC/Clang) - MSVC support planned
  • Platforms: Linux, macOS (Apple Silicon optimized, Intel supported), Windows (MinGW)
  • SDL3 dependencies (ttf, mixer)
  • Boost (for tests), cppcheck & clang-tidy (static analysis), Valgrind (optional, Linux only)
  • GPU rendering (optional): glslangValidator, spirv-cross (for -DUSE_SDL3_GPU=ON)

Platform notes:
See Platform Notes for detailed Windows, Linux, and macOS setup instructions.

Build

git clone https://github.com/yourname/SDL3_HammerEngine_Template.git
cd SDL3_HammerEngine_Template

# Debug build (recommended for development)
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Debug && ninja -C build

# Release build (optimized)
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Release && ninja -C build

# GPU rendering path (SDL3 GPU API with SPIR-V/Metal shaders)
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Debug -DUSE_SDL3_GPU=ON && ninja -C build

# Run the engine
./bin/debug/SDL3_Template   # Debug build
./bin/release/SDL3_Template # Release build

Sanitizer builds (for debugging memory/thread issues):

# AddressSanitizer (memory errors, leaks)
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-D_GLIBCXX_DEBUG -fsanitize=address -fno-omit-frame-pointer -g" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address" -DUSE_MOLD_LINKER=OFF && ninja -C build

# ThreadSanitizer (data races, deadlocks)
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-D_GLIBCXX_DEBUG -fsanitize=thread -fno-omit-frame-pointer -g" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread" -DUSE_MOLD_LINKER=OFF && ninja -C build

# TSAN suppressions (for known benign races)
export TSAN_OPTIONS="suppressions=$(pwd)/tests/tsan_suppressions.txt"

Note: ASAN and TSAN are mutually exclusive. To reconfigure without a full rebuild: rm build/CMakeCache.txt before running cmake.

Testing & Static Analysis

Valgrind Analysis Suite

  • Comprehensive memory, cache, and thread analysis with Valgrind
  • Quick memory check: ./tests/valgrind/quick_memory_check.sh
  • Cache performance: ./tests/valgrind/cache_performance_analysis.sh
  • Function profiling: ./tests/valgrind/callgrind_profiling_analysis.sh
  • Thread analysis: ./tests/valgrind/thread_safety_check.sh
  • Full suite: ./tests/valgrind/run_complete_valgrind_suite.sh
  • Runtime analysis with Profile build (Valgrind-compatible optimized): 
    cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Profile && ninja -C build
./tests/valgrind/runtime_cache_analysis.sh --profile 300   # MPKI analysis
./tests/valgrind/runtime_memory_analysis.sh --profile 300  # Memory analysis
  • See tests/valgrind/README.md for details, usage, and performance metrics

Documentation

📚 Documentation Hub – Full guides, API references, and best practices.

Core Design Principles

  • Data-Oriented Design: EntityDataManager as single source of truth, Structure-of-Arrays (SOA) storage.
  • Memory Safety: Smart pointers, RAII, no raw pointers
  • Performance: Cache-friendly, batch processing, optimized threading
  • Type Safety: Strong typing, compile-time and runtime validation
  • Cross-Platform: Unified codebase, platform-specific optimizations

Contributing

Contributions welcome!

  • Report issues via GitHub with environment details and steps to reproduce.
  • Fork, branch, test, and submit PRs with clear descriptions.

Notes

  • Window icon support for all platforms (see res/img/)
  • Player and NPC controls: mouse, keyboard, controller (see InputManager)
  • Template can be adapted for 3D (see GameEngine.cpp and TextureManager)
  • For advanced usage, see docs/README.md
  • This is a work in progress and Art is just a place holder for now. All Art is credited to its authors listed below in the Art section!

Art

All art license follows artists licensing. See thier page below for more details!

License

MIT License

About

SDL3 2D game Engine/Template implementing DOD, multi-threading and SIMD, with a focus on memory safety, efficiency, and speed.

roninxv.itch.io/

Resources

Readme

License

MIT license
Activity

Stars

11 stars

Watchers

1 watching

Forks

1 fork
Report repository

Sponsor this project

  •  
Learn more about GitHub Sponsors

Contributors 2

Languages