TSU Engine

Alpha note: TSU Engine is still under active development and is not production-ready yet. This is alpha software — expect bugs and breaking changes between versions.

Real-time RTX corridor with flickering lights, camera breathing, volumetric fog, and post-processing — running in TSU Engine.

📽️ Watch the full demo video (127 MB)

TSU Engine is a custom 3D game engine written in C++17 with a Vulkan 1.3 renderer, a built-in editor, Lua 5.4 scripting, real-time ray tracing, physics, audio, skeletal animation, AI (behavior trees + navmesh pathfinding), a particle system, an undo/redo editor, and a standalone runtime export path.

---

Features

Rendering

• Vulkan 1.3 renderer with explicit GPU resource management
• Forward PBR pipeline with Cook-Torrance BRDF and multi-scatter energy conservation
• Up to 16 real-time lights: Directional, Point, Spot, Area
• Cascaded Shadow Maps (4 cascades) for directional lights
• Point-light cubemap shadows (6-face)
• PBR materials: Albedo, Normal, ORM (packed AO/Roughness/Metallic), Emissive, Heightmap
• Parallax Occlusion Mapping (POM) with alpha cutout support
• Procedural sky with day/night cycle, stars, and clouds
• HDRI skybox with IBL (irradiance + prefiltered + BRDF LUT)
• Water rendering
• Decal rendering
• GPU-instanced grass with wind simulation, shadow casting, and LOD culling
• LOD system with automatic distance-based mesh switching
• Particle system: CPU-simulated emitters and bounded volume particles
• GLTF/GLB and OBJ model import with per-material sub-mesh splitting
• Dithered transparency for semi-transparent objects
• SPIR-V shader compilation via glslc
• Vulkan Memory Allocator (VMA) and volk

Ray Tracing

• Real-time ray-traced shadows
• Ray-traced reflections with configurable bounce count
• Ray-traced ambient occlusion
• Ray-traced global illumination
• Spatial denoiser with adjustable strength
• Half-resolution mode for performance
• BLAS caching per unique mesh, TLAS rebuild only when transforms change

Post-Processing (20+ Effects)

• Bloom — 6-mip compute-based with threshold, intensity, and radius
• GTAO — Ground-Truth Ambient Occlusion (compute)
• SSGI — Screen-Space Global Illumination (compute)
• SSR — Screen-Space Reflections with binary search refinement (compute)
• Hi-Z Depth Pyramid — Hierarchical depth for SSR/SSGI acceleration
• TAA — Temporal Anti-Aliasing with Halton jitter and history rejection
• Motion Blur — Velocity-based compute pass
• Depth of Field — Multi-ring bokeh sampling with highlight weighting
• Volumetric Fog — Compute-based with scene light integration
• Auto Exposure — Luminance histogram compute pass
• God Rays — Temporal-jittered radial blur from sun position
• Contact Shadows — Screen-space 16-step ray march
• Lens Flare — 5-ghost procedural flare with halo ring
• Vignette, Film Grain, Chromatic Aberration, Sharpen (CAS)
• Color Grading — Exposure, Saturation, Contrast, Brightness, Lift/Gamma/Gain (ASC CDL)
• LUT Color Grading — 16-slice 3D LUT texture support
• Tonemapping — AgX, ACES, Reinhard, or none
• Lens Distortion, Sepia, Posterize, Pixelate, Scanlines
• VHS Effect — Retro CRT simulation with chromatic split and noise
• Image Overlay — Additive/screen-blend overlay texture with opacity

Audio

• Streaming audio playback with miniaudio backend
• 3D spatial audio with distance attenuation
• AudioSource component per entity (WAV, MP3, OGG, FLAC)
• Volume, pitch, loop, spatial, min/max distance controls
• Lua API: playAudio, stopAudio, setAudioVolume, setAudioPitch, isAudioPlaying, getAudioGain

Skeletal Animation

• GLTF/GLB skeletal mesh loading with bone hierarchy
• Keyframe interpolation (STEP, LINEAR)
• Animation clip playback with crossfade blending
• CPU skinning with bone matrices
• Lua API: animPlay, animStop, animSetSpeed, animCrossfade, animGetClipCount, animGetClipName, animIsPlaying, animGetTime

AI

• Behavior Trees — Selector, Sequence, Inverter, Repeater, Cooldown, Wait, Blackboard conditions/setters, custom actions
• NavMesh Pathfinding — Walkable surface extraction, A* polygon search, agent steering with smooth acceleration
• Lua API for both: btAttach, btSetFloat, btGetStatus, navBuildMesh, navSetTarget, navHasReached, etc.

Editor

• Full ImGui-based editor with docking layout
• Hierarchy panel with tree view and drag-and-drop reparenting
• Inspector panel for all component types (30+ component categories)
• Asset Browser with folder navigation
• Console with command system
• Scene View with Move, Rotate, and Scale gizmos
• Material Editor with PBR texture slots and live preview
• Prefab Editor and Room Editor
• Texture Manager
• Undo/Redo — Godot-style lambda-based action recording (Ctrl+Z / Ctrl+Shift+Z)
• Project creation, loading, save, and game export
• Scene asset panel with scene switching
• Drag-and-drop support for models, textures, and scripts
• Script auto-scan from project assets folder

Physics

• Bullet Physics integration
• Rigid bodies with gravity, friction, restitution
• Box, Sphere, Capsule colliders
• Trigger volumes with enter/exit callbacks
• Spatial hash for broad-phase queries

Gameplay Systems

• Parallel-array ECS scene architecture
• Player controller and mouse look
• Animation State Machine with conditional transitions
• Tween system with 14 easing curves
• Scene transitions with fade effects
• Timer system with Lua callbacks
• Tag system (single tag + multi-tag per entity)
• Input Action binding system
• Debug Draw (lines, boxes, spheres)
• UUID generation, Object Pool, Thread Pool, Event Bus, Spline curves
• Config system (.ini load/save), Logger, Profiler, Console, Screenshot, FileWatcher, Resource GC

Scripting

• Lua 5.4 lifecycle scripting (OnStart, OnUpdate, OnStop, OnTriggerEnter, OnTriggerExit)
• 137 API functions: 130 in scene.* + 7 in gui.*
• --@expose inspector variables with types: number, boolean, string, entity, material
• Drag-and-drop entity/material assignment in inspector
• Runtime GUI system: gui.label(), gui.button(), gui.panel(), gui.progressBar(), gui.image(), gui.checkbox(), gui.slider()
• Frame pacing, grass wind, audio, physics, AI, debug draw — all scriptable

Asset and Scene Pipeline

• OBJ model import with auto-scale
• GLTF/GLB model import with per-material sub-mesh splitting and skeletal mesh support
• Drag-and-drop asset loading (models, textures, scripts)
• Human-readable .tscene scene files
• .tprefab prefab files with preview editor
• Per-entity color overrides and material assignment
• Runtime texture/lightmap registries using Vulkan handles behind opaque IDs

Multiplayer

• UDP host/client architecture (ENet)
• Multiplayer manager/controller components
• Prefab-based player spawning
• Launch args: --mp-mode=host|client, --mp-server=IP, --mp-port=PORT, --mp-nick=NAME

Export

• Standalone GameRuntime.exe (Windows) / GameRuntime (Linux)
• Full asset/shader copy on export
• Scene path relativization for portable builds
• game.mode metadata marker for exported games
• Borderless fullscreen on export, windowed mode with --windowed
• Performance overlay (FPS, average, 1% low)

---

Requirements

• CMake 3.16+
• C++17 compiler (MSVC on Windows, GCC/Clang on Linux)
• Vulkan SDK 1.3+
• Vulkan-capable GPU with current drivers

Linux Dependencies

sudo apt-get install cmake ninja-build libgl1-mesa-dev \
  libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev \
  libxi-dev libxext-dev libwayland-dev libxkbcommon-dev

---

Build

git clone https://github.com/tsuyu122/tsu-engine
cd tsuEngine
cmake -S . -B build
cmake --build build --config Release

Outputs:

Platform	Editor	Runtime
Windows	build/Release/TsuEngine.exe	build/Release/_engine/GameRuntime.exe
Linux	build/TsuEngine	build/_engine/GameRuntime

Notes:

• GLFW is vendored in external/glfw
• ImGui, Lua, volk, VMA, cgltf, and tinyobjloader are resolved by CMake FetchContent
• GLSL shaders in engine/shaders/ are compiled to SPIR-V at build time

---

Project Layout

tsuEngine/
  CMakeLists.txt
  README.md
  docs/
    lua/           # Lua API reference and examples
  assets/
    scenes/        # .tscene files
    scripts/       # Lua scripts
    textures/      # PBR texture sets
  engine/
    ai/            # Behavior trees, navmesh pathfinding
    animation/     # Skeletal animation, GLTF loader
    audio/         # miniaudio-based audio system
    components/    # Component type definitions
    core/          # Application, window, input, profiler, timers, etc.
    editor/        # Editor camera, undo system
    input/         # Input manager, input actions
    lua/           # Lua 5.4 scripting bindings
    network/       # ENet multiplayer
    physics/       # Bullet physics, spatial hash
    procedural/    # Maze/room generator
    renderer/      # Vulkan backend, PBR renderer, ray tracing, particles
    scene/         # Scene graph, tweens, animation state machine, tags
    serialization/ # Scene/prefab file I/O
    shaders/       # GLSL shaders (PBR, sky, post, water, grass, etc.)
    ui/            # ImGui panels, runtime GUI
  sandbox/
    main.cpp       # Editor entry point
    game_main.cpp  # Runtime entry point

---

Running

Editor:

# Windows
build/Release/TsuEngine.exe

# Linux
./build/TsuEngine

Runtime:

# Windows
build/Release/_engine/GameRuntime.exe

# Linux
./build/_engine/GameRuntime

Export flow:

1. Open or create a project in the editor
2. Build the scene
3. Use File → Export Game...
4. Ship the exported folder with the runtime executable, assets, and shaders

---

Architecture Notes

• TsuEngine: full editor with ImGui panels and tools
• GameRuntime: lean runtime without editor UI
• VulkanBackend: instance, device, swapchain, frame resources, VMA allocator, RT extensions
• Renderer: scene draw path, shadows, ray tracing, compute passes, editor overlays
• Scene: parallel-array ECS keyed by entity index

Coordinate system: +X forward, +Y up, +Z right

Rotation storage: X = Pitch, Y = Yaw, Z = Roll (degrees)

---

Changelog

v1.4.0 — Systems Overhaul

Audio System

• Full audio playback with miniaudio: WAV, MP3, OGG, FLAC
• 3D spatial audio with distance attenuation
• AudioSource component with volume, pitch, loop, spatial controls
• 6 Lua audio bindings

Skeletal Animation

• GLTF/GLB skeletal mesh loading with bone hierarchy
• Keyframe animation with crossfade blending
• CPU skinning
• 9 Lua animation bindings

AI Systems

• Behavior Tree system: Selector, Sequence, Inverter, Repeater, Cooldown, Wait, Blackboard, custom actions
• NavMesh pathfinding: walkable surface extraction, A* search, agent steering
• 16 Lua AI bindings (btAttach, btSet*, navBuildMesh, navSetTarget, etc.)

Editor Improvements

• Undo/Redo system (Godot-style lambda recording, Ctrl+Z / Ctrl+Shift+Z)
• LOD system with distance-based mesh switching
• Script auto-scan and drag-and-drop from asset browser
• --@expose entity and --@expose material variable types with inspector drag-and-drop
• New Scene creates default Camera + Directional Light + Sky

Post-Processing

• GTAO (Ground-Truth Ambient Occlusion, compute)
• SSGI (Screen-Space Global Illumination, compute)
• Hi-Z depth pyramid for SSR/SSGI acceleration
• TAA (Temporal Anti-Aliasing)
• Motion Blur (compute)
• Volumetric Fog (compute)
• Auto Exposure (histogram compute)
• God Rays with temporal jitter
• Contact Shadows (screen-space ray march)
• Lens Flare (5-ghost procedural)
• Lift/Gamma/Gain (ASC CDL color grading)
• CAS Sharpening (replaced unsharp mask)
• VHS post effect
• Image overlay post effect
• Multi-scatter energy conservation (PBR)
• Dithered transparency
• Procedural stars and clouds in sky

Rendering

• Water rendering
• Decal rendering
• Particle system (CPU emitters + bounded volumes)
• TLAS rebuild optimization (only mesh renderer transforms trigger rebuild)
• Aspect ratio fix between editor viewport and exported game

Gameplay Systems

• 20 new core systems: Timer, Config, Profiler, Console, DebugDraw, Screenshot, Logger, ResourceGC, FileWatcher, InputAction, AnimStateMachine, Tween (14 easing curves), SceneTransition, TagSystem, SpatialHash, UUID, EventBus, ObjectPool, ThreadPool, Spline
• Runtime GUI for Lua: gui.label(), gui.button(), gui.panel(), gui.progressBar(), gui.image(), gui.checkbox(), gui.slider()

Scripting

• 114 total Lua API functions (107 scene + 7 gui)
• Exposed variable types: number, boolean, string, entity, material
• Full audio, animation, AI, physics, debug draw control from Lua

Export

• Project folder assets copy with path relativization
• Compiled SPIR-V shaders bundled with export
• All per-frame systems now run in GameRuntime
• Scene loading via Lua (scene.loadScene()) works in exported games

Bug Fixes

• Fixed POM rendering artifacts
• Fixed emissive material rendering
• Fixed RT AO and specular occlusion
• Fixed UV mapping issues
• Fixed entity rotation gizmo
• Fixed child entity reparenting
• Fixed Film Grain flickering
• Fixed VHS screen shake
• Fixed SIGSEGV crash from null vertex normal buffer
• Fixed serialization for entity colors and exposed variable types
• Fixed FPS drops in exported game (missing per-frame system updates)
• Fixed FOV mismatch between editor preview and exported game

Known Issues

• Running the exported game while the editor is open may cause significant FPS degradation in the game — cause still under investigation
• Baked lighting is incomplete — full support planned for a future release

v1.3.2 — Rendering Overhaul

Vulkan Stabilization

• Finished the main Vulkan build path for editor and runtime
• Migrated ImGui integration to imgui_impl_vulkan
• Restored editor previews and debug overlays
• Restored Vulkan shadow passes for directional/spot and point lights
• Reconnected the fullscreen Vulkan post-processing path
• Editor/play frame pacing with Unlimited, VSync, and manual FPS cap profiles

New Rendering Features

• Real-time ray tracing: shadows, reflections, ambient occlusion, global illumination
• GPU-instanced grass system with wind simulation and LOD
• Depth of Field (DOF) post-processing
• Screen Space Reflections (SSR)
• Procedural sky with day/night cycle
• HDRI skybox support with night-time dimming
• GLTF model import with multi-material sub-mesh splitting

New Lua API Bindings

• Frame pacing: setVSync, getVSync, setFPSLimit, getFPSLimit
• Grass control: setGrassWind, getGrassWind, setGrassWindFrequency, setGrassWindTurbulence, setGrassEnabled, setGrassDensity

v1.3.1 — Multiplayer

• Basic authoritative multiplayer over UDP
• Host/client flow
• Prefab-based player spawning

---

Roadmap

• Complete the baked lighting pipeline
• Terrain system
• Visual scripting
• Hot reload for Lua scripts
• Better asset bundling for export
• GPU-driven rendering

---

Contributing

See CONTRIBUTING.md.

---

License

Released under the MIT License. ,