Troubleshooting Guide

Common issues and solutions for LoLEngine.

Table of Contents

1. Installation Issues
2. Service Initialization
3. Save System
4. Audio System
5. Resource Management
6. Performance Issues
7. Build Errors

---

Installation Issues

Compilation Errors After Import

Problem: Console shows compilation errors after importing LoLEngine

Solutions: 1. Wait for Unity to finish importing all assets 2. Check Unity version compatibility (6000.0 or newer required) 3. Install required packages: - Input System: Window → Package Manager → Input System - TextMeshPro (should be included by default) 4. Reimport LoLEngine: Right-click folder → Reimport 5. Restart Unity Editor

Missing Dependencies

Problem: "Type or namespace not found" errors

Solutions: 1. Install Unity Input System package 2. If using Addressables, install Addressables package 3. Check that all LoLEngine folders are present:

Assets/LoLEngine/
├── Runtime/
├── Editor/
└── Documentation~/

---

Service Initialization

Services Not Initializing

Problem: "Service not found" errors or null references

Solutions:

1. Check ServiceConfiguration exists and is assigned:

   // In ImprovedGameInitializer Inspector
   Service Configuration: [Must be assigned]
   

2. Verify services are enabled:

3. Open ServiceConfiguration asset

4. Check required services are enabled:

   • [x] Enable Event Manager
   • [x] Enable Resource Service
   • etc.

5. Check initialization order:

   // Wait for services before using them
   void Start()
   {
       if (ServiceAwaiter.AreServicesReady())
           OnServicesReady();
       else
           ServiceAwaiter.WaitForServices(this, OnServicesReady, OnServicesTimeout);
   }
   

6. Verify ImprovedGameInitializer is in first scene:

7. Check Build Settings → Scene 0 contains GameInitializer

8. Ensure only ONE GameInitializer exists

9. Check console for initialization errors:

10. Look for red errors during startup
11. Check service dependency warnings

Service Timeout Errors

Problem: "Timed out waiting for services" message

Solutions:

1. Check for service initialization errors:
2. Look for errors before timeout message

3. Fix any service-specific errors first

4. Verify service dependencies:

   Required dependencies:
   - SaveSystem → SerializationService
   - MusicPlaylistService → AudioService
   

5. Increase timeout if needed (rare):

   ServiceAwaiter.WaitForServices(this, OnReady, OnTimeout, timeoutSeconds: 10f);
   

6. Check ServiceConfiguration is valid:

7. Not null
8. All referenced configs exist
9. No circular dependencies

---

Save System

Save Files Not Creating

Problem: SaveGame() doesn't create files

Solutions:

1. Check Save System is enabled:
2. ServiceConfiguration → [x] Enable Data Persistence Service

3. ServiceConfiguration → [x] Enable Serialization Service

4. Verify save path has write permissions:

   Debug.Log(Application.persistentDataPath);  // Check this path
   

5. Check for save errors in console

6. Verify SaveConfig is assigned:

   // In ServiceConfiguration
   Save Config: [Must be assigned]
   

7. Test with simple save:

   var saveSystem = ServiceLocator.Instance.Get<ISaveSystem>();
   saveSystem.SaveGame("test_save");
   

Load Fails

Problem: LoadGame() returns false or fails

Solutions:

1. Check if save file exists:

   if (saveSystem.HasSaveFile("save1"))
   {
       saveSystem.LoadGame("save1");
   }
   else
   {
       Debug.LogWarning("Save file doesn't exist");
   }
   

2. Check file extension matches configuration:

3. Default: .sav for unencrypted

4. Encrypted: .esave

5. Verify encryption/compression settings match:

6. Can't load encrypted save without encryption enabled

7. Can't load compressed save without compression enabled

8. Check save version compatibility:

9. Older save files may be incompatible with new code
10. Increment save version when making breaking changes

Encryption Errors

Problem: "Failed to encrypt/decrypt" errors

Solutions:

1. Ensure EncryptionService is enabled:

2. ServiceConfiguration → [x] Enable Encryption Service

3. Check encryption key is set in LoLEngineConfig:

   Encryption Settings:
   ├─ Use Encryption: true
   └─ Encryption Key Seed: [Must be set]
   

4. Never commit encryption keys to source control:

5. Use environment variables for production keys

6. Keep development keys separate

7. Encryption key must be consistent:

8. Same key for save and load
9. Changing key makes old saves unreadable

---

Audio System

Audio Not Playing

Problem: PlaySound() doesn't produce audio

Solutions:

1. Check AudioService is enabled:

2. ServiceConfiguration → [x] Enable Audio Service

3. Verify AudioConfig is assigned and configured:

   Audio Config:
   ├─ Tracks: [Must have at least one track]
   ├─ Master Volume: > 0
   └─ Default Volume: > 0
   

4. Check audio clip path is correct:

   // For Resources
   audioService.PlaySound("Audio/UIClick");  // Must exist at Resources/Audio/UIClick
   
   // For Addressables
   // Asset must be marked as Addressable with matching address
   

5. Verify AudioListener exists in scene:

6. Usually on Main Camera

7. Only ONE AudioListener should exist

8. Check track volume and mute status:

   var track = audioService.GetTrack("Music");
   Debug.Log($"Track volume: {track.Volume}, Muted: {track.Muted}");
   

9. Test with simple audio:

   this.PlaySound("test_audio_clip");
   

Audio Pops or Clicks

Problem: Audio has pops, clicks, or glitches

Solutions:

1. Enable object pooling for AudioSources:

   Audio Config:
   └─ Use Object Pooling: true
   

2. Increase pool size:

   Pool Settings:
   ├─ Initial Pool Size: 20
   └─ Max Pool Size: 50
   

3. Preload frequently used audio:

   await AudioPreloadManager.Instance.PreloadAudioAsync("audioId");
   

4. Check audio clip import settings:

5. Load Type: Streaming (for music)
6. Load Type: Decompress On Load (for SFX)
7. Compression Format: Vorbis or ADPCM

---

Resource Management

Asset Not Loading

Problem: LoadAsync() returns null

Solutions:

1. For Addressables:
2. Verify asset is marked as Addressable
3. Check address/key matches exactly

4. Build Addressables: Window → Asset Management → Addressables → Build → New Build → Default Build Script

5. For Resources:

6. Asset must be in Resources folder
7. Path relative to Resources folder (no extension)

8. Example: Resources/Audio/Music.mp3 → "Audio/Music"

9. Check ResourceService is enabled:

10. ServiceConfiguration → [x] Enable Resource Service

11. Verify asset type matches:

    // Must match actual asset type
    var clip = await resourceService.LoadAsync<AudioClip>("Audio/Music");
    // Not Texture2D if it's an AudioClip!
    

12. Check console for load errors

---

Performance Issues

Low FPS

Solutions:

1. Check object pooling is enabled:
2. ServiceConfiguration → [x] Enable Object Pool

3. Use pooling for frequently spawned objects

4. Optimize save frequency:

5. Reduce auto-save frequency

6. Enable compression

7. Disable debug logging in builds:

   LoLLogger.LOGEnabled = false;  // In production
   

8. Profile with Unity Profiler:

9. Window → Analysis → Profiler
10. Check for CPU/memory spikes

Memory Leaks

Solutions:

1. Release loaded resources:

   void OnDestroy()
   {
       resourceService.Release("asset_path");
   }
   

2. Unsubscribe from events:

   void OnDisable()
   {
       this.EventStopListening<MyEvent>();
   }
   

3. Return pooled objects:

   this.Despawn(gameObject);  // Don't Destroy() pooled objects
   

---

Build Errors

"Type or Namespace Not Found" in Build

Problem: Builds fail with type errors (editor works fine)

Solutions:

1. Check all required packages are installed

2. Verify no Editor-only code in Runtime scripts:

   #if UNITY_EDITOR
   // Editor-only code here
   #endif
   

3. Check platform-specific code is guarded:

   #if UNITY_ADDRESSABLES
   // Addressables code
   #endif
   

Addressables Build Fails

Solutions:

1. Build Addressables before player build:

2. Window → Asset Management → Addressables → Build → New Build → Default Build Script

3. Clean Addressables cache:

4. Addressables → Build → Clean Build → All

5. Then rebuild

6. Check for invalid references

---

Getting More Help

If your issue isn't covered here:

1. Check console for errors - Most issues log helpful error messages
2. Review relevant documentation - Check specific system docs
3. Check samples - LoLEngine includes working examples

4. Enable verbose logging:

   LoLLogger.LOGLevel = LogLevel.Debug;
   

5. Create minimal reproduction:

6. New scene
7. Minimal setup
8. Test specific feature

---

Quick Diagnostics Checklist

When experiencing issues, check:

• [ ] ServiceConfiguration exists and is assigned to GameInitializer
• [ ] Required services are enabled in ServiceConfiguration
• [ ] Console has no errors
• [ ] GameInitializer is in first scene (Scene 0 in Build Settings)
• [ ] Only one GameInitializer exists
• [ ] Using ServiceAwaiter to wait for services
• [ ] All required Unity packages installed
• [ ] Asset paths are correct
• [ ] No circular service dependencies

---

See Also

• Getting Started - Initial setup guide
• CHEATSHEET - Quick reference
• Service Dependencies - Service requirements