A modern, production-ready C++20 SDL3 game engine template for 2D games. Built for rapid prototyping and scalable game development, it features robust multi-threading, high-performance AI, 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.
-
Modern C++20 & SDL3 Core
Clean, modular codebase with strict style, memory, and type safety.
-
Adaptive Multi-Threading System
Hardware-adaptive thread pool with intelligent WorkerBudget allocation that scales from 1 to 16+ cores. Dynamic burst capacity (30% buffer reserve), queue pressure adaptation, and performance-based batch tuning that converges to optimal parallelism for your hardware. Priority-based scheduling (5 levels) with cache-line aligned atomics for minimal lock contention.
-
High-Performance AI System
Cache-friendly, lock-free, and batch-processed AI manager. Supports 10K+ entities at 60+ FPS with only 4-6% CPU usage. Includes dynamic behaviors (Wander, Patrol, Guard, Flee, Attack, etc.), message system, 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.
-
Professional 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
83+ test executables with Boost.Test framework covering unit, integration, and performance testing. Includes AI+Collision integration tests, SIMD correctness validation, and comprehensive thread safety verification with documented TSAN suppressions. Static analysis (cppcheck), AddressSanitizer (ASAN), ThreadSanitizer (TSAN), and Valgrind integration for production-ready quality assurance.
-
Cross-Platform Optimizations
Unified codebase with platform-specific enhancements: SIMD acceleration (x86-64: SSE2/AVX2, ARM64: NEON), macOS letterbox mode, Wayland detection, adaptive VSync, and DPI scaling.
-
Extensive Documentation
Full guides, API references, best practices, and troubleshooting for all major systems.
- 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.
- CMake 3.28+, Ninja, C++20 compiler (GCC/Clang/MSVC) - MSVC planned
- Platforms: Windows, macOS (Apple Silicon only), Linux
- SDL3 dependencies (image, ttf, mixer)
- Boost (for tests), cppcheck (static analysis), Valgrind (optional, for profiling and validation)
Platform notes:
See Platform Notes for detailed Windows, Linux, and macOS setup instructions.
git clone https://github.com/yourname/SDL3_HammerEngine_Template.git
cd SDL3_HammerEngine_Template
cmake -B build/ -G Ninja -DCMAKE_BUILD_TYPE=Debug
ninja -C build
./bin/debug/SDL3_Template- Run all tests:
./run_all_tests.sh - See tests/TESTING.md for comprehensive test documentation and options
- Static analysis:
./tests/test_scripts/run_cppcheck_focused.shSee tests/cppcheck/README.md for more. - Memory & thread safety validation: AddressSanitizer (ASAN) and ThreadSanitizer (TSAN) support See docs/core/ThreadSystem.md#threadsanitizer-tsan-support for details
- 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 - See tests/valgrind/README.md for details, usage, and performance metrics
📚 Documentation Hub – Full guides, API references, and best practices.
- AI System: Overview, Optimization, Behaviors, Quick Reference, Pathfinding System
- Collision & Physics: Collision System
- Event System: Overview, Quick Reference, Advanced, Examples, EventFactory
- Threading: ThreadSystem
- Managers: ParticleManager, FontManager, TextureManager, SoundManager, CollisionManager, PathfinderManager, ResourceFactory, ResourceTemplateManager, WorldManager, WorldResourceManager
- UI: UIManager Guide, UIConstants Reference, Auto-Sizing, DPI-Aware Fonts, Minimap Implementation
- Utilities: JsonReader, JSON Resource Loading, Serialization, ResourceHandle System, Performance Notes
- Development: Claude Code Skills
- Engine Plans & Issues: Camera Refactor Plan, SDL3 macOS Cleanup Issue
- 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
Contributions welcome!
- Report issues via GitHub with environment details and steps to reproduce.
- Fork, branch, test, and submit PRs with clear descriptions.
- 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.cppandTextureManager) - For advanced usage, see docs/README.md
- SDL3 is working great, but there are some issues with SDL3 Mixer. Mixer is requiring SDL3 main branch so issues fluctuate a bit. When SDL3 mixer gets a stable release, then things will calm down.
- 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!
- World Tiles : Pipoya
- Slimes patvanmackelberg
- Player Abigail adythewolf
