Spelusion.Engine3D

A general-purpose 2D/3D game engine written in C# (.NET 10) using OpenGL (via OpenTK).

Current Status: ? Phase 6 Complete - Audio System (Core + Mixer)

---

Quick Start

# Clone the repository
git clone https://git.spelusion.com/david/Spelusion.Engine3D
cd Spelusion.Engine3D

# Build and run the demo
dotnet build
dotnet run --project Spelusion.Engine3D.Demo

Running the Demos

Default Demo: Asset Database Demo (Milestone 4.1)

dotnet run --project Spelusion.Engine3D.Demo

Available Demos:

• --lighting - Milestone 5.1: Phong lighting with multiple light types
• --cel - Cel/toon shader demo
• --scene-serialization - Scene save/load demo
• --audio - ? Phase 6 Complete! Audio system with mixer demo

Audio Demo (Milestones 6.1 & 6.2):

dotnet run --project Spelusion.Engine3D.Demo -- --audio

?? Requires OpenAL - See OPENAL_SETUP.md for installation

Controls:

• SPACE - Play 3D sound effect (SFX channel)
• M - Toggle music (Music channel)
• +/- - Master volume control
• 1/2 - Music channel volume
• 3/4 - SFX channel volume
• 5/6 - Toggle channel mute
• A/D - Rotate camera (hear 3D audio changes)

See RUN_DEMO.md for all demo details.

---

Features Implemented

? Phase 1: Foundation (Complete)

• Application lifecycle - OpenTK window, game loop, event handling
• Time system - Delta time, fixed timestep, time scale support
• Logging - Multi-level console logging (Info, Warning, Error, Critical)
• Math library - OpenTK.Mathematics wrappers with engine namespace isolation

? Phase 2: Rendering (Complete)

• Shader system - Vertex/Fragment shaders with hot-reload support
• Mesh system - VAO/VBO/EBO, MeshFactory (triangle, cube, quad)
• Texture system - PNG/JPG loading via StbImageSharp, mipmaps, anisotropic filtering
• Material system - GUID-based asset references, uniform management, render state control
• Renderer - Material binding, texture resolver, draw call tracking

? Phase 4: Asset System (Complete)

• AssetDatabase - GUID-based asset management, metadata system
• Asset hot-reload - FileWatcher for shaders, textures, materials
• Scene serialization - JSON-based scene save/load

? Phase 5: Advanced Rendering (Complete)

• Lighting system - Directional, Point, Spot lights with Phong shading
• Debug tools - Gizmos, debug overlay, FPS counter
• Post-processing - Cel/toon shader example

? Phase 6: Audio System (Complete) ? COMPLETE

• AudioEngine - OpenAL integration, master volume control, distance model
• AudioClip - WAV/OGG loading, asset management, streaming flag
• AudioSource - 2D/3D audio, playback control (play/pause/stop/resume), mixer channels
• AudioListener - Scene listener with Doppler effect support
• AudioMixer - Channel hierarchy (Master, Music, SFX, Voice), mute/solo, volume control
• Mixer Integration - Real-time volume application, hierarchical mixing

?? Phase 7: Physics System (Next)

• Colliders (AABB, Sphere) and raycasting
• Rigidbody physics with collision response
• Layer-based collision filtering

---

Documentation

Quick Links

• OPENAL_SETUP.md - How to install OpenAL for audio system
• RUN_DEMO.md - How to run all demos
• TEXTURE_SETUP.md - How to run the textured cube demo
• TROUBLESHOOTING.md - Fix "nothing shows" issues

Complete Documentation

All project documentation is in Spelusion.Engine3D.Core/Docs/:

• GUIDELINES.md - Documentation standards (start here)
• Design Document - Complete architecture
• POC Plan - Implementation roadmap with progress
• Production Plan - ?? Long-term roadmap (Phase 6 complete!)
• Milestone 6.1 Summary - Core Audio implementation
• Milestone 6.2 Summary - ?? AudioMixer implementation
• Coding Guidelines - Coding conventions

---

Architecture

Key Principles

• Component-based (non-ECS) - Flexible, Unity-like component system
• Engine-first, editor later - Solid core before tooling
• Data-driven design - JSON assets & scene serialization
• GUID-based assets - Stable references across file moves
• Graceful degradation - Missing assets don't crash the engine
• API isolation - Users never need using OpenTK.*

Technology Stack

• Language: C# (.NET 10)
• Graphics: OpenGL 4.6 (via OpenTK 4.9.4)
• Math: OpenTK.Mathematics (wrapped in engine namespace)
• Image Loading: StbImageSharp 2.27.14
• Audio: OpenAL (via OpenTK.Audio.OpenAL 4.9.4) ?
• Audio Codecs: NVorbis 0.10.5 (OGG support) ?
• Serialization: System.Text.Json
• Physics: Custom minimal implementation (Phase 7)

---

Project Structure

Spelusion.Engine3D/
?? Spelusion.Engine3D.Core/          # Core engine library
?   ?? Core/                          # Application, Time, Log
?   ?? Math/                          # Math types (OpenTK wrappers)
?   ?? Rendering/                     # Renderer, Shaders, Materials, Textures
?   ?? Docs/                          # All project documentation
?
?? Spelusion.Engine3D.Demo/          # Demo application
?   ?? Assets/
?   ?   ?? Shaders/                   # GLSL shader files
?   ?   ?? Textures/                  # Texture files
?   ?? Examples/                      # Usage examples
?   ?? SimpleCubeDemo.cs             # Basic rendering demo
?   ?? TexturedCubeDemo.cs           # Material system demo
?
?? Spelusion.Engine3D.Tests/         # Unit tests (future)

---

Milestone Progress

Phase	Status	Milestones
Phase 1: Foundation	? Complete	1.1 Core Systems, 1.2 Math Library
Phase 2: Rendering	? Complete	2.1 Shaders, 2.2 Meshes, 2.3 Textures & Materials
Phase 3: Scene System	? Complete	3.1 GameObject, 3.2 Camera, 3.3 MeshRenderer
Phase 4: Asset Management	? Complete	4.1 Asset Database, 4.2 Hot Reload, 4.3 Serialization
Phase 5: Advanced Rendering	? Complete	5.1 Lighting, Debug Tools
Phase 6: Audio System	? Complete	6.1 Core Audio, 6.2 Mixer
Phase 7: Physics	? Next	Colliders, Raycasting, Rigidbody

See PRODUCTION-PLAN.md for detailed roadmap.

---

Usage Example

using Spelusion.Engine3D.Rendering;
using Spelusion.Engine3D.Math;  // Engine namespace - no OpenTK!

// 1. Load texture
var textureId = Guid.NewGuid();
var texture = Texture.LoadFromFile(textureId, "Stone", "Assets/Textures/stone.jpg");

// 2. Load shader
var shaderId = Guid.NewGuid();
var shader = Shader.LoadFromFiles(shaderId, "Standard", "standard.vert", "standard.frag");

// 3. Create material
var material = new Material(Guid.NewGuid(), "StoneMaterial")
{
    ShaderGuid = shaderId,
    Shader = shader
};
material.SetTexture("uTexture", textureId);
material.SetColor("uColor", new Vector4(1, 1, 1, 1));

// 4. Render
var renderer = new Renderer();
renderer.SetTextureResolver(guid => textureDatabase[guid]);
var mesh = MeshFactory.CreateCube();
renderer.Submit(mesh, material, Matrix4.Identity);

See TextureMaterialExample.cs for more examples.

---

Testing

Run the Demo

dotnet run --project Spelusion.Engine3D.Demo

Expected Output

[INFO] Starting Simple Cube Demo (Diagnostic)
[INFO] Application initialized
[INFO] Shader 'Unlit' compiled successfully
[INFO] Cube mesh created successfully
[INFO] Simple cube demo ready!
[INFO] You should see an orange spinning cube
[INFO] FPS: 60.0

What You Should See

• SimpleCubeDemo: Orange spinning cube
• TexturedCubeDemo (no texture): Magenta spinning cube (fallback)
• TexturedCubeDemo (with demotex.jpg): Stone-textured spinning cube with lighting

If nothing shows, see TROUBLESHOOTING.md.

---

Contributing

Coding Conventions

Follow the guidelines in .github/copilot-instructions.md:

• Naming: PascalCase for classes/methods, camelCase with _ for private fields
• Asset References: Always use GUIDs, never file paths
• Error Handling: Graceful degradation, no crashes on missing assets
• API Isolation: Hide OpenTK from engine users
• Documentation: All docs in Core/Docs/ (see GUIDELINES.md)

Before Submitting

1. ? Build succeeds: dotnet build
2. ? Code follows conventions
3. ? Documentation updated in Core/Docs/
4. ? Usage examples added if appropriate

---

Support

Having issues?

1. Check TROUBLESHOOTING.md - Common issues and fixes
2. Review console output - Look for [ERROR] or [WARNING] messages
3. Run SimpleCubeDemo first - Verify basic functionality works
4. Read the docs - See Core/Docs/

---

License

(License information to be added)

---

Links

• Repository: https://git.spelusion.com/david/Spelusion.Engine3D
• OpenTK Documentation: https://opentk.net/learn/
• OpenTK API Reference: https://opentk.net/api/

---

Current Milestone: ? Phase 6 Complete - Audio System (Core + Mixer)
Next Milestone: ? Phase 7 - Physics System
Project Status: On Track ?