LoL Engine Documentation¶

Welcome to the complete documentation for LoL Engine - a comprehensive, modular Unity game engine framework.

Quick Links¶

Getting Started - Setup and first steps
CHEATSHEET - Quick reference for all systems
Troubleshooting - Common issues and solutions
IL2CPP & Code Stripping - Required reading before shipping IL2CPP builds
Architecture Guide - Design patterns and ADRs for extending LoL Engine (ADR-001 – ADR-018)

Documentation Index¶

Getting Started¶

Quickstart (5 minutes) - Install → Setup Wizard → first sound playing
Getting Started Guide - Complete setup walkthrough from installation to every service
Services Checklist - Recommended service toggles per game type (RPG, Roguelite, Puzzle)
CHEATSHEET - How To Use - Quick reference for all LoL Engine components
Troubleshooting - Common problems and solutions

Core Systems¶

Service Management¶

Service Locator - Service registration and dependency injection
Game Initializer - Engine initialization and lifecycle
Service Dependencies - Service dependency graph
Config - Configuration system overview

Events¶

Events - Type-safe event system with pooling
Event creation and triggering
Event listeners
Custom events
Performance optimization

Game Services¶

Audio¶

Audio System - Complete audio playback and management
Audio tracks and mixer integration
2D and 3D spatial audio
Audio pooling
Fade in/out effects
Volume control
Audio Helpers — Optional drop-in components (SimpleAudioPlayer and friends)

Input¶

Input — Unity Input System in game code (no IInputService; engine wrapper removed before 1.0)

Data Persistence¶

Data Persistence — save/load, auto-save, quick-save, compression, obfuscation, encryption

Localization¶

Localization - Multi-language support
Language switching
CSV/JSON translation tables
Dynamic text updates
Pluralization

Resource Management¶

Resource Management — asset loading, Addressables, memory budget, async patterns

Utility Services¶

Object Pool - GameObject pooling system
Time Management - Time control and scheduling
Notifications - In-game notification system
Game State - Game state machine

Helper Utilities¶

Helper Utilities - Complete utilities reference
Audio helper components
ShuffleBag and TypedPoolBag
ServiceAwaiter and cached waits
ModelDb, singleton bases, logger helpers

Advanced Topics¶

Architecture Guide - Design patterns and ADRs for extending LoL Engine (ADR-001 – ADR-018)
RNG Service — see Runtime/Scripts/Core/Rng/IRngService.cs and Samples~/Rng/ (interactive scene).

Reference¶

API Reference — XML doc comments on interfaces under Runtime/Scripts/Core/*/Interfaces/; open in IDE or generate with your preferred DocFX / dotnet tooling.

Sample Projects¶

LoL Engine includes comprehensive sample projects demonstrating each system:

Core Samples¶

Audio Sample - Audio playback, tracks, mixing, pooling
Event Sample - Event creation, listening, triggering
Object Pooling Sample - Pooling GameObjects and components
Resource Management Sample - Asset loading with Addressables/Resources

Game System Samples¶

Data Persistence Sample - Save/load, auto-save, quick save
Game State Sample - MainMenu / Gameplay / Paused state machine
Localization Sample - Multi-language, CSV table setup, LocString
Notifications Sample - In-game notifications with priorities
Deterministic RNG Sample - Named streams, weighted rolls, pity counter, seed replay
Music / Now Playing code samples - 10_MusicPlaylistSample.cs, 11_NowPlayingSample.cs under Samples~/Scripts/

Import Samples: Package Manager → LoL Engine → Samples tab → Import (adds assets/scripts; optional)

Bundled demo scenes: Seven .unity files ship under Samples~/…/Scenes/ — open directly after Setup Wizard.

Regenerate scenes (optional): Tools → LoL Engine → Create Sample Scenes

System Requirements¶

Required¶

Unity 6000.0 or newer
Unity Addressables 2.5.0+ (com.unity.addressables)
Newtonsoft JSON 3.2.1+ (com.unity.nuget.newtonsoft-json)

Optional¶

Unity Input System Package (game code only — see Input.md)
Unity Audio Mixer (for advanced audio bus routing)
TextMeshPro (for sample UI labels)

Platform Support¶

Platform	Status
Windows / macOS / Linux (Mono & IL2CPP)	Supported
iOS / Android (IL2CPP)	Supported — read IL2CPP & Code Stripping first
WebGL	Not supported in 1.0

WebGL has no managed threads. The async save/load paths (SaveSystem), async obfuscation, and the background file log sink rely on Task.Run, which cannot execute on WebGL. WebGL support is under consideration for a future release.

Architecture Overview¶

LoL Engine is built on solid architectural principles:

Service Locator Pattern¶

Decoupled service architecture
Easy testing with mock services
Explicit dependencies
Thread-safe service access

ScriptableObject Configuration¶

Designer-friendly
Version control friendly
Runtime/Editor separation
Data-driven design

Component-Based Design¶

Composition over inheritance
Reusable components
Flexible architecture

Event-Driven Architecture¶

Loosely coupled systems
Type-safe events
Event pooling for performance
Easy to extend

Key Features¶

Core Services¶

Event Manager — Type-safe, pooled event bus Audio Service — Tracks, pooling, fades, spatial audio Music Playlist Service — Gapless crossfade, shuffle, per-track gain Save System — Async persistence with encryption, compression, migration & quarantine Resource Service — Addressables-first asset loading with Resources fallback Object Pool Service — GameObject pooling with prewarming Time Service — Channels, time-scale, scheduler, timers Localization Service — CSV tables, LocString, dynamic variables, CI validator Notification Service — In-game notifications with priorities and categories Game State Manager — Extensible state machine Auto Save / Quick Save — Configurable intervals and rotating slots Serialization / Compression / Encryption — Pluggable JSON + GZip + AES pipeline RNG Service — Deterministic named streams (SplitMix64) with snapshot save/load

Helper Utilities¶

Audio helper components (playback and preloading) ShuffleBag and TypedPoolBag ServiceAwaiter and cached coroutine waits ModelDb for canonical model lookup Singleton bases, Counter, LRUCache, logger helpers, and color extensions

Quick Start Example¶

using LoLEngine.Core.ServiceManagement.Service;
using LoLEngine.Core.Audio.Interfaces;
using LoLEngine.Core.DataPersistence.Interfaces;
using LoLEngine.Runtime;
using UnityEngine;

public class MyGame : MonoBehaviour
{
    private IAudioService _audioService;
    private ISaveSystem _saveSystem;
    private bool _initialized = false;

    void Start()
    {
        // Wait for LoL Engine services to initialize
        if (ServiceAwaiter.AreServicesReady())
            OnServicesReady();
        else
            ServiceAwaiter.WaitForServices(this, OnServicesReady, OnTimeout);
    }

    private void OnServicesReady()
    {
        // Get service references
        _audioService = ServiceLocator.Instance.Get<IAudioService>();
        _saveSystem = ServiceLocator.Instance.Get<ISaveSystem>();

        _initialized = true;

        // Use services
        _audioService.PlaySound("Audio/MainTheme");

        // Load saved game if exists
        if (_saveSystem.HasSaveFile("autosave"))
        {
            _saveSystem.LoadGame("autosave");
        }
    }

    private void OnTimeout()
    {
        Debug.LogError("Services failed to initialize!");
    }
}

Best Practices¶

1. Always Wait for Services¶

// Good
ServiceAwaiter.WaitForServices(this, OnReady, OnTimeout);

// Bad
var service = ServiceLocator.Instance.Get<IMyService>();  // May not be ready!

2. Use Appropriate Data Structures¶

Lists - Dynamic collections
Arrays - Fixed-size, fast access
ShuffleBag - Weighted random without repeats
TypedPoolBag - Bucketed no-replacement draws
ModelDb - Canonical model lookup by ModelId

3. Enable Object Pooling¶

// Good - Use pooling for frequently spawned objects
GameObject enemy = this.Spawn(enemyPrefab, position, rotation);

// Clean up
this.Despawn(enemy);

4. Subscribe/Unsubscribe Events Properly¶

void OnEnable() => this.EventStartListening<MyEvent>();
void OnDisable() => this.EventStopListening<MyEvent>();

5. Use Configuration Assets¶

// Good - ScriptableObject configuration
[SerializeField] private AudioConfig audioConfig;

// Avoid - Hardcoded values
private float volume = 0.8f;

Performance Tips¶

Enable Object Pooling for frequently spawned objects
Use Addressables for large assets
Cache Service References instead of repeated Get() calls
Enable Compression for save files
Disable Debug Logging in production builds
Preload Audio for instant playback
Use Events instead of Update checks where possible

Version History¶

See CHANGELOG.md for detailed version history.

Current package version: see ../package.json.

Support and Resources¶

Documentation¶

Full documentation in Documentation~ folder
Sample projects in Samples~ folder
API reference throughout docs

Getting Help¶

Check Troubleshooting Guide
Review CHEATSHEET
Examine relevant sample project
Check console for error messages

Contributing¶

When extending LoL Engine:

Follow Existing Patterns - Use Service Locator, ScriptableObject configs
Add Documentation - Document your custom systems
Include Samples - Provide usage examples
Write Tests - Add unit tests for core functionality
Update CHEATSHEET - Add quick reference for new features

License¶

See the package license.

Credits¶

LoL Engine Framework - A comprehensive Unity game development framework

Next Steps¶

Ready to start? Head over to the Getting Started Guide to set up your first LoL Engine project!