A flexible & efficient way to manage and access services in Unity

A powerful, ScriptableObject-based service locator pattern implementation for Unity that provides robust dependency injection with asynchronous support, automatic scene management, and comprehensive debugging tools.

Features

• ScriptableObject-Based: Clean, asset-based architecture that integrates seamlessly with Unity's workflow.
• Multi-Phase Initialization: A robust, automated lifecycle ensures services are registered, injected, and initialized safely.
• Async Service Resolution: Wait for services to become fully ready with cancellation and timeout support.
• UniTask Integration: Automatic performance optimization when UniTask is available - zero allocations and faster async operations.
• Fluent Dependency Injection: Elegant builder pattern for configuring service injection.
• Automatic Scene Management: Services are automatically tracked and cleaned up when scenes unload.
• Comprehensive Debugging: Built-in editor window with search, filtering, and service inspection.
• Type-Safe: Full generic support with compile-time type checking.
• Performance Optimized: Efficient service lookup with minimal overhead, enhanced further with UniTask.
• Thread-Safe: Concurrent access protection for multi-threaded scenarios.

Installation

Via Unity Package Manager

1. Open the Package Manager window (Window > Package Manager)
2. Click the + button and select Add package from git URL
3. Enter: https://github.com/PaulNonatomic/ServiceKit.git

Via Package Manager Manifest

Add this line to your Packages/manifest.json:

{
  "dependencies": {
    "com.nonatomic.servicekit": "https://github.com/PaulNonatomic/ServiceKit.git"
  }
}

Quick Start

1. Create a ServiceKit Locator

Right-click in your project window and create a ServiceKit Locator: Create > ServiceKit > ServiceKitLocator

2. Define Your Services

public interface IPlayerService
{
    void SavePlayer();
    void LoadPlayer();
    int GetPlayerLevel();
}

public class PlayerService : IPlayerService
{
    private int _playerLevel = 1;

    public void SavePlayer() => Debug.Log("Player saved!");
    public void LoadPlayer() => Debug.Log("Player loaded!");
    public int GetPlayerLevel() => _playerLevel;
}

3. Register Services

public class GameBootstrap : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    private void Awake()
    {
        // Register services during game startup
        var playerService = new PlayerService();
        _serviceKit.RegisterService<IPlayerService>(playerService);

        // A service must be marked as "Ready" before it can be injected
        _serviceKit.ReadyService<IPlayerService>();
    }
}

4. Inject Services

public class PlayerUI : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    // Mark fields for injection
    [InjectService] private IPlayerService _playerService;

    private async void Awake()
    {
        // Inject services with fluent configuration
        await _serviceKit.InjectServicesAsync(this)
            .WithTimeout(5f)
            .WithCancellation(destroyCancellationToken)
            .WithErrorHandling()
            .ExecuteAsync();

        // The service is now injected and ready to use
        _playerService.LoadPlayer();
        Debug.Log($"Player Level: {_playerService.GetPlayerLevel()}");
    }
}

UniTask Integration

ServiceKit provides automatic optimization when UniTask is installed in your project. UniTask is a high-performance, zero-allocation async library specifically designed for Unity.

Automatic Detection

ServiceKit automatically detects when UniTask is available and seamlessly switches to use UniTask APIs for enhanced performance:

// Same code, different performance characteristics:
await serviceKit.GetServiceAsync<IPlayerService>();

// With UniTask installed:   → Zero allocations, faster execution
// Without UniTask:          → Standard Task performance

Installation

Install UniTask via Unity Package Manager:

1. Open Package Manager (Window > Package Manager)
2. Click + and select Add package from git URL
3. Enter: https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask

Or add to your Packages/manifest.json:

{
  "dependencies": {
    "com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask"
  }
}

Performance Benefits

When UniTask is available, ServiceKit automatically provides:

• 🚀 2-3x Faster Async Operations: For immediately completing operations
• 📉 50-80% Less Memory Allocation: Reduced GC pressure and frame drops
• ⚡ Zero-Allocation Async: Most async operations produce no garbage
• 🎯 Unity-Optimized: Better main thread synchronization and PlayerLoop integration

Usage Examples

The same ServiceKit code works with both Task and UniTask - no changes needed:

public class PlayerController : ServiceKitBehaviour<IPlayerController>
{
    [InjectService] private IPlayerService _playerService;
    [InjectService] private IInventoryService _inventoryService;

    // Automatically uses UniTask when available for better performance
    protected override async UniTask InitializeServiceAsync()
    {
        await _playerService.LoadPlayerDataAsync();
        await _inventoryService.LoadInventoryAsync();
    }
}

Multiple service resolution is also optimized:

// UniTask.WhenAll is more efficient than Task.WhenAll
var (player, inventory, audio) = await UniTask.WhenAll(
    serviceKit.GetServiceAsync<IPlayerService>(),
    serviceKit.GetServiceAsync<IInventoryService>(),
    serviceKit.GetServiceAsync<IAudioService>()
);

Best Practices with UniTask

• Mobile Games: UniTask's zero-allocation benefits are most noticeable on mobile devices
• Complex Scenes: Projects with many services see the biggest improvements
• Frame-Critical Code: Use for smooth 60fps gameplay where every allocation matters
• Memory-Constrained Platforms: VR, WebGL, and older devices benefit significantly

Roslyn Analyzer Support

ServiceKit includes integrated support for Roslyn Analyzers to help you write better code with real-time analysis and suggestions specifically tailored for ServiceKit development.

Features

The ServiceKit Analyzers provide:

• Code analysis for common ServiceKit patterns and best practices
• Real-time suggestions to improve your service implementations
• Compile-time warnings for potential issues with dependency injection
• Code fixes to automatically resolve common problems

Installation

ServiceKit includes a built-in tool to download and manage the Roslyn Analyzers:

1. Open the ServiceKit Settings window: Edit > Project Settings > ServiceKit
2. Navigate to the Developer Tools section
3. Click Download Analyzers to automatically fetch the latest version from GitHub
4. The analyzers will be installed to Assets/Analyzers/ServiceKit/

Manual Installation

You can also manually download the analyzers:

1. Visit the ServiceKit Analyzers releases page
2. Download the latest ServiceKit.Analyzers.dll
3. Place it in Assets/Analyzers/ServiceKit/ in your Unity project
4. Unity will automatically recognize and apply the analyzers

Managing Analyzers

Through the ServiceKit Settings window, you can:

• Update: Download the latest version to get new analysis rules and improvements
• Remove: Uninstall the analyzers if you no longer need them
• View Details: See the installed version, file size, and last modified date

Contributing to Analyzers

The ServiceKit Analyzers are open source! If you'd like to contribute new analysis rules or improvements:

• Visit the ServiceKit Analyzers repository
• Check out the contribution guidelines
• Submit issues for bugs or feature requests
• Create pull requests with your improvements

The analyzer repository includes documentation on:

• How to build custom analyzers for ServiceKit
• Adding new diagnostic rules
• Creating code fix providers
• Testing analyzer implementations

Advanced Usage

Using ServiceKitBehaviour Base Class

For the most robust and seamless experience, inherit from ServiceKitBehaviour<T>. This base class automates a sophisticated multi-phase initialization process within a single Awake() call, ensuring that services are registered, injected, and made ready in a safe, deterministic order.

It handles the following lifecycle automatically:

1. Registration: The service immediately registers itself, making it discoverable.
2. Dependency Injection: It asynchronously waits for all services marked with [InjectService] to become fully ready.
3. Custom Initialization: It provides InitializeServiceAsync() and InitializeService() for you to override with your own setup logic.
4. Readiness: After your initialization, it marks the service as ready, allowing other services that depend on it to complete their own initialization.

public class PlayerController : ServiceKitBehaviour<IPlayerController>, IPlayerController
{
    [InjectService] private IPlayerService _playerService;
    [InjectService] private IInventoryService _inventoryService;

    // This is the new hook for your initialization logic.
    // It's called after dependencies are injected, but before this service is marked as "Ready".
    protected override void InitializeService()
    {
        // Safe to access injected services here
        _playerService.LoadPlayer();
        _inventoryService.LoadInventory();

        Debug.Log("Player controller initialized with all dependencies!");
    }

    // For async setup, you can use the async override:
    // Note: Returns UniTask when available, Task otherwise - same code works for both!
    protected override async UniTask InitializeServiceAsync()
    {
        // Example: load data from a web request or file
        await _inventoryService.LoadFromCloudAsync(destroyCancellationToken);
    }

    // Optional: Handle injection failures gracefully
    protected override void OnServiceInjectionFailed(Exception exception)
    {
        Debug.LogError($"Failed to initialize player controller: {exception.Message}");

        if (exception is TimeoutException)
        {
            Debug.Log("Services took too long to become available");
        }
        else if (exception is ServiceInjectionException)
        {
            Debug.Log("Required services are not registered or failed to become ready");
            gameObject.SetActive(false); // Disable this component
        }
    }
}

Asynchronous Service Resolution

Wait for services that may not be immediately available (or ready):

public class LateInitializer : MonoBehaviour
{
    [SerializeField] private ServiceKitLocator _serviceKit;

    private async void Start()
    {
        try
        {
            // Wait up to 10 seconds for the service to be registered AND ready
            var audioService = await _serviceKit.GetServiceAsync<IAudioService>(
                new CancellationTokenSource(TimeSpan.FromSeconds(10)).Token);

            audioService.PlaySound("welcome");
        }
        catch (OperationCanceledException)
        {
            Debug.LogError("Audio service was not available or ready within the timeout period");
        }
    }
}

Optional Dependencies

Services can be marked as optional using intelligent 3-state dependency resolution:

public class AnalyticsReporter : MonoBehaviour
{
    [InjectService(Required = false)]
    private IAnalyticsService _analyticsService; // Uses intelligent resolution

    [InjectService]
    private IPlayerService _playerService; // Required - will fail if missing

    // ...
}

When Required = false, ServiceKit uses intelligent 3-state resolution:

• Service is ready → Inject immediately
• Service is registered but not ready → Wait for it (treat as required temporarily)
• Service is not registered → Skip injection (field remains null)

This eliminates guesswork - you don't need to predict whether a service will be available. The system automatically waits for registered services that are "coming soon" while skipping services that will "never come."

When Required = true (default):

• Always wait for the service regardless of registration status
• Timeout and fail if service is not available within the specified timeout period

Exempting Services from Circular Dependency Checks

In advanced scenarios, you might need to bypass the circular dependency check. This is useful for two main reasons:

1. Wrapping Third-Party Code: When you "shim" an external library into ServiceKit, that service has no knowledge of your project's classes. A circular dependency check is unnecessary and can be safely bypassed.
2. Managed Deadlocks: In rare cases, a "manager" service might need a reference to a "subordinate" that also depends back on the manager. If you can guarantee this cycle is not accessed until after full initialization, an exemption can resolve the deadlock.

To handle this, you can register a service with an exemption. This should be used with extreme caution, as it bypasses a critical safety feature.

RegisterServiceWithCircularExemption allows a service to be registered without being considered in the dependency graph analysis.

// Example of a service that needs to be exempted
public class SubordinateService : ServiceKitBehaviour<ISubordinateService>
{
    [InjectService] private IManagerService _manager;

    // Override Awake to change the registration method
    protected override void Awake()
    {
        // Instead of the default registration, we call the exemption method.
        ServiceKitLocator.RegisterServiceWithCircularExemption<ISubordinateService>(this);
        Registered = true; // Manually set the flag since we overrode the default
    }
    //...
}

Using ServiceKit with Addressables

ServiceKit fully supports Unity's Addressables system, allowing you to load ServiceKitLocator assets on-demand. However, there are critical considerations regarding how Unity handles ScriptableObjects in Addressable scenes.

Making a ServiceKitLocator Addressable

To use an addressable ServiceKitLocator:

1. Check the Addressable checkbox on the ServiceKitLocator asset
2. Add the ServiceKitLocator asset to an addressable group
3. Load the locator like any other addressable asset

// Example: Loading an addressable ServiceKitLocator
var handle = Addressables.LoadAssetAsync<ServiceKitLocator>("MyServiceKitLocator");
await handle.Task;
var serviceKitLocator = handle.Result;

Critical: ScriptableObject Instance Behavior

Understanding this behavior is crucial for proper ServiceKit functionality in addressable setups.

When an addressable scene references a ScriptableObject, Unity's behavior differs based on whether the ScriptableObject itself is addressable:

Non-Addressable ServiceKitLocator (referenced by addressable scene):

• Unity creates a new instance of the ServiceKitLocator
• The new instance is embedded in the scene's asset bundle
• Services registered outside the addressable scene will not be present in this new instance
• This may be desirable if you want complete isolation between addressable scenes

Addressable ServiceKitLocator (referenced by addressable scene):

• Unity uses the same instance across all scenes
• No new instance is created
• Services registered outside the addressable scene remain registered
• This maintains a global service registry across all scenes

Recommendations

Use Non-Addressable ServiceKitLocator when:

• You want complete isolation between addressable scenes
• Each scene should have its own independent service registry
• Services should not persist between scene loads

Use Addressable ServiceKitLocator when:

• You want a global service registry across all scenes
• Services should persist when loading/unloading addressable scenes
• You need services registered in the bootstrap scene available in addressable scenes

// Example: Bootstrapping with addressable ServiceKitLocator
public class AddressableBootstrap : MonoBehaviour
{
    private async void Start()
    {
        // Load the addressable ServiceKitLocator
        var locatorHandle = Addressables.LoadAssetAsync<ServiceKitLocator>("GlobalServiceKitLocator");
        await locatorHandle.Task;
        var serviceKitLocator = locatorHandle.Result;

        // Register global services
        var audioService = new AudioService();
        serviceKitLocator.RegisterService<IAudioService>(audioService);
        serviceKitLocator.ReadyService<IAudioService>();

        // Now load addressable scenes - they will reference the same ServiceKitLocator instance
        // and have access to the IAudioService
        await Addressables.LoadSceneAsync("GameplayScene").Task;
    }
}

Service Lifecycle in Addressable Scenes

Important: ServiceKitBehaviours registered in a scene are automatically unregistered and destroyed when that scene is unloaded. This applies to both regular and addressable scenes.

To preserve a ServiceKitBehaviour beyond the lifetime of its scene:

Option 1: Use DontDestroyOnLoad

public class PersistentService : ServiceKitBehaviour<IPersistentService>, IPersistentService
{
    protected override void InitializeService()
    {
        // Prevent this service from being destroyed when the scene unloads
        DontDestroyOnLoad(gameObject);
    }
}

Option 2: Load scenes additively

// Load scenes additively to keep previous scene services active
await Addressables.LoadSceneAsync("AdditiveScene", LoadSceneMode.Additive).Task;

Best Practices:

• Use DontDestroyOnLoad for global services that should persist across scene transitions (e.g., audio, save system, analytics)
• Use additive scene loading when you need services from multiple scenes active simultaneously
• Be mindful of memory usage when keeping services alive - unload scenes explicitly when no longer needed
• For addressable scenes, consider whether the service should be tied to the scene's lifetime or persist globally

ServiceKit Debug Window

Access the powerful debugging interface via Tools > ServiceKit > ServiceKit Window:

Features:

• Real-time Service Monitoring: View all registered services across all ServiceKit locators.
• Readiness Status: See at a glance whether a service is just registered or fully ready.
• Scene-based Grouping: Services organized by the scene that registered them.
• Search & Filtering: Find services quickly with fuzzy search.
• Script Navigation: Click to open service implementation files.
• GameObject Pinging: Click MonoBehaviour services to highlight them in the scene.

API Reference

IServiceKitLocator Interface

// Registration & Readiness
void RegisterService<T>(T service, string registeredBy = null) where T : class;
void RegisterServiceWithCircularExemption<T>(T service, string registeredBy = null) where T : class;
void ReadyService<T>() where T : class;
void UnregisterService<T>() where T : class;

// Synchronous Access
T GetService<T>() where T : class;
bool TryGetService<T>(out T service) where T : class;

// Asynchronous Access (automatically uses UniTask when available)
Task<T> GetServiceAsync<T>(CancellationToken cancellationToken = default) where T : class;
// Returns UniTask<T> when UniTask package is installed

// Dependency Injection
IServiceInjectionBuilder InjectServicesAsync(object target);

// Management
IReadOnlyList<ServiceInfo> GetAllServices();

IServiceInjectionBuilder Interface

IServiceInjectionBuilder WithCancellation(CancellationToken cancellationToken);
IServiceInjectionBuilder WithTimeout(float timeoutSeconds);
IServiceInjectionBuilder WithErrorHandling(Action<Exception> errorHandler);
void Execute(); // Fire-and-forget
Task ExecuteAsync(); // Awaitable (UniTask when available)

Best Practices

Service Design

• Use interfaces for service contracts to maintain loose coupling.
• Keep services stateless when possible for better testability.
• Prefer composition over inheritance for complex service dependencies.

Registration Strategy

• Register early in the application lifecycle. ServiceKitBehaviour automates this in Awake.
• Initialize wisely. Place dependency-related logic in InitializeService or InitializeServiceAsync when using ServiceKitBehaviour.
• Global services should be registered in persistent scenes or DontDestroyOnLoad objects.

Dependency Management

• Mark dependencies as optional when they're not critical for functionality.
• Use timeouts for service resolution to avoid indefinite waits.
• Handle injection failures gracefully with proper error handling.
• Avoid circular dependency exemptions unless absolutely necessary and the lifecycle is fully understood.

Performance Optimization

• Install UniTask for automatic performance improvements in async operations.
• Use async initialization in InitializeServiceAsync() for I/O operations to avoid blocking the main thread.
• Batch service resolution when possible using UniTask.WhenAll() or Task.WhenAll().
• Profile on target platforms - UniTask benefits are most noticeable on mobile and lower-end devices.

🚀 Benchmark Performance

ServiceKit has been extensively benchmarked to ensure excellent performance across all operations. The framework delivers production-ready performance with sub-millisecond to low-millisecond execution times that make it suitable for real-time applications.

Performance Rating: Excellent ⭐⭐⭐⭐⭐

Core Performance Metrics

⚡ Lightning Fast Operations (< 0.1ms)

Operation	Average Time	Throughput	Category
TryGetService	0.004ms	245,700 ops/sec	👑 ABSOLUTE CHAMPION
IsServiceRegistered	0.005ms	220,614 ops/sec	🏆 ULTRA CHAMPION
IsServiceReady	0.007ms	147,477 ops/sec	🏆 ULTRA CHAMPION
GetService (Synchronous)	0.010ms	103,000 ops/sec	⚡ Lightning Fast
GetServiceAsync	0.018ms	54,789 ops/sec	⚡ Lightning Fast
GetAllServices	0.021ms	47,491 ops/sec	⚡ Lightning Fast
Service Status Checking	0.023ms	42,610 ops/sec	⚡ Lightning Fast
GetService Multiple Types	0.025ms	40,016 ops/sec	⚡ Lightning Fast
GetServicesWithTag	0.026ms	38,493 ops/sec	⚡ Lightning Fast

⚡ Excellent Operations (0.1ms - 2ms)

Operation	Average Time	Throughput	Category
GetService NonExistent	0.002ms	614,931 ops/sec	🏆 CHAMPION
Clear All Services	0.024ms	42,082 ops/sec	⚡ Lightning Fast
Service Discovery	0.042ms	23,805 ops/sec	⚡ Lightning Fast
Tag System (Complex)	0.154ms	6,491 ops/sec	🏆 TAG CHAMPION
RegisterService Simple	0.594ms	1,686 ops/sec	⚡ Excellent
RegisterService WithTags	0.600ms	1,666 ops/sec	⚡ Excellent
RegisterService WithDependencies	0.654ms	1,529 ops/sec	⚡ Excellent
RegisterService WithCircularExemption	1.158ms	863 ops/sec	⚡ Excellent
RegisterAndReadyService	1.196ms	837 ops/sec	⚡ Excellent
DontDestroyOnLoad Services	1.340ms	746 ops/sec	⚡ Excellent
MonoBehaviour Services	1.418ms	705 ops/sec	⚡ Excellent
Scene Service Management	1.522ms	657 ops/sec	⚡ Excellent
Complete Service Lifecycle	1.722ms	581 ops/sec	⚡ Excellent
ReadyService	1.726ms	579 ops/sec	⚡ Excellent
Service Tag Management	1.791ms	558 ops/sec	⚡ Excellent
UnregisterService	1.880ms	532 ops/sec	⚡ Excellent

✅ Good Performance Operations (2ms - 100ms)

Operation	Average Time	Throughput	Category
High Volume Resolution (1000x)	2.763ms	362 ops/sec	⚡ Excellent
Service Cleanup and Reregistration	3.680ms	272 ops/sec	✅ Good
Multiple Services Lifecycle	5.062ms	198 ops/sec	✅ Good
Inject Services With Timeout	5.431ms	184 ops/sec	✅ Good
ServiceKitTimeoutManager	6.107ms	164 ops/sec	⚠️ Moderate
Inject Services Complex Graph	7.755ms	129 ops/sec	✅ Good
Register 10 Services	17.152ms	58 ops/sec	✅ Good
Register 25 Services	43.955ms	23 ops/sec	✅ Good
Memory Allocation - Service Creation	65.429ms	15 ops/sec	⚠️ Memory Intensive
Register 50 Services	91.096ms	11 ops/sec	✅ Good for Volume

🔥 Stress Test Operations (High Volume/Concurrent)

Operation	Average Time	Throughput	Category
Async Service Resolution (100x)	16.413ms	61 ops/sec	⚠️ Expected for Concurrency
GetServiceAsync With Delay	34.333ms	29 ops/sec	⚠️ Expected for Async Waiting
Concurrent Service Access (50x20)	36.818ms	27 ops/sec	⚠️ Expected for Heavy Load
Rapid Service Lifecycle (100x)	198.721ms	5 ops/sec	⚡ Excellent for Volume
High Volume Registration (1000x)	1867.780ms	1 ops/sec	🔥 High Volume Stress
Memory Pressure (50x100)	9209.677ms	0 ops/sec	🧠 Memory Stress Test

Key Performance Highlights

🏆 Outstanding Core Operations

• Sub-millisecond service resolution: TryGetService (0.004ms), IsServiceRegistered (0.005ms), IsServiceReady (0.007ms)
• Lightning-fast service access: GetService operations consistently under 0.02ms
• Exceptional tag system: Complex tag queries with 5 service types perform at 0.154ms
• Perfect scaling: Linear performance scaling with predictable overhead

⚡ Real-World Performance

• Frame-rate friendly: All core operations are fast enough for 60fps+ applications
• Memory efficient: Excellent memory management under extreme pressure (50MB+ tests)
• Concurrent safe: Handles 1000+ concurrent operations without failure
• Production ready: Consistent performance across all operation categories

🎮 Unity-Optimized

• MonoBehaviour integration: 1.418ms average with GameObject lifecycle
• Scene management: 1.522ms for complex scene service operations
• DontDestroyOnLoad: 1.340ms for persistent service handling
• PlayMode compatibility: Robust performance in Unity's runtime environment

Performance Testing

ServiceKit includes a comprehensive benchmark suite that tests:

• Service Registration Patterns: Simple, tagged, bulk registration
• Service Resolution: Sync/async, with/without tags
• Dependency Injection: Single, multiple, inherited, optional dependencies
• Unity Integration: MonoBehaviour, DontDestroyOnLoad, scene management
• Async Operations: Timeout functionality and cancellation
• Stress Testing: High-volume operations and concurrent access

Test Environment Specifications

The benchmark results above were obtained using the following configuration:

Hardware:

• Platform: Windows 10 (CYGWIN_NT-10.0 3.3.4)
• Architecture: x86_64 (64-bit)
• CPU: Modern multi-core processor (specific details may vary)
• RAM: Sufficient for Unity Editor and test execution
• Storage: SSD recommended for optimal test performance

Software:

• Unity Editor: Latest LTS version (specific version may vary)
• .NET Framework: Unity's integrated .NET runtime
• Test Framework: Unity Test Runner with NUnit
• Build Configuration: Development build in Editor mode

Test Methodology:

• Warm-up Iterations: 2-5 iterations to stabilize performance
• Benchmark Iterations: 10-1000 iterations depending on operation complexity
• Statistical Analysis: Average, median, min/max, standard deviation, and throughput
• Isolation: Each test runs independently with proper cleanup
• Repeatability: Multiple test runs to ensure consistent results

Performance Variables:

• Results may vary based on hardware specifications
• Unity Editor overhead affects absolute timing but not relative performance
• Background processes and system load can influence results
• Release builds typically show improved performance over Editor results

Running Your Own Benchmarks

To validate performance on your specific hardware:

1. Open Unity Test Runner (Window → General → Test Runner)
2. Switch to EditMode tab for core benchmarks
3. Switch to PlayMode tab for Unity integration benchmarks
4. Navigate to ServiceKit/Tests/PerformanceTests and run individual or comprehensive suites
5. Compare your results with the baseline metrics above

Note: Your results may differ based on your hardware configuration, Unity version, and system environment. The relative performance characteristics and operation rankings should remain consistent across different setups.

Performance Best Practices

For Maximum Performance:

// 👑 ABSOLUTE FASTEST: Safe service access (0.004ms - 245,700 ops/sec)
if (serviceKit.TryGetService<IPlayerService>(out var service))
{
    // Use service - this is the fastest pattern
}

// 🏆 ULTRA-FAST: Service status checking (0.005ms - 0.007ms)
bool isRegistered = serviceKit.IsServiceRegistered<IPlayerService>();
bool isReady = serviceKit.IsServiceReady<IPlayerService>();

// ⚡ EXCELLENT: Direct service access (0.010ms)
var playerService = serviceKit.GetService<IPlayerService>();

// ✅ Good: Async when services may not be ready (0.018ms)
var playerService = await serviceKit.GetServiceAsync<IPlayerService>();

// ⚡ EXCEPTIONAL: Tag-based discovery (0.026ms)
var performanceServices = serviceKit.GetServicesWithTag("performance");

Registration Optimization:

// ⚡ FASTEST: Simple registration (0.594ms)
serviceKit.RegisterService<IPlayerService>(playerServiceInstance);
serviceKit.ReadyService<IPlayerService>();

// ⚡ EXCELLENT: Combined operation (1.196ms)
serviceKit.RegisterAndReadyService<IPlayerService>(playerServiceInstance);

// ✅ Good: With tags for organization (0.600ms + ready time)
serviceKit.RegisterService<IPlayerService>(playerService, 
    new[] { new ServiceTag("core"), new ServiceTag("player") });

Memory Optimization:

// ✅ Reuse services rather than frequent creation
serviceKit.RegisterAndReadyService<IPlayerService>(playerServiceInstance);

// ✅ Use ServiceKitBehaviour for optimal lifecycle management
public class PlayerController : ServiceKitBehaviour<IPlayerController>
{
    // Automatic registration (0.594ms), injection (~5ms), and cleanup (1.880ms)
}

Batch Operations:

// ⚡ EXCELLENT: Bulk resolution is very efficient (2.763ms for 1000 operations)
for (int i = 0; i < 1000; i++)
{
    var service = serviceKit.GetService<IPlayerService>(); // ~0.003ms each
}

// ✅ Good: Async batch operations
var (player, inventory, audio) = await UniTask.WhenAll(
    serviceKit.GetServiceAsync<IPlayerService>(),
    serviceKit.GetServiceAsync<IInventoryService>(),
    serviceKit.GetServiceAsync<IAudioService>()
);

UniTask Performance Boost:

• Async operations maintain excellent performance (0.018ms vs 0.010ms sync)
• Minimal async overhead - only 80% slower than synchronous
• Excellent concurrent handling - 1000+ operations without failure
• Zero-allocation async for most operations when UniTask is installed

Real-World Performance

ServiceKit's performance characteristics make it suitable for:

• High-frequency gameplay systems (player controllers, input handlers)
• Frame-critical applications (VR, AR, 60fps+ games)
• Mobile applications (memory-constrained environments)
• Complex dependency graphs (large-scale applications)
• Real-time multiplayer (low-latency service access)

The framework's sub-millisecond core operations ensure that dependency injection never becomes a performance bottleneck in your Unity applications.

Migration Guide

Migrating from v1.x to v2.0

Version 2.0 includes breaking changes to improve code readability and self-documentation. If you have custom services that extend ServiceKitBehaviour<T>, you'll need to update your code:

Field Renames

// Old (v1.x)
if (Registered) { /* ... */ }
if (Ready) { /* ... */ }

// New (v2.0)
if (IsServiceRegistered) { /* ... */ }
if (IsServiceReady) { /* ... */ }

Method Renames

// Old (v1.x)
public class MyService : ServiceKitBehaviour<IMyService>
{
    protected override void RegisterService()
    {
        base.RegisterService();
        // Custom logic
    }
    
    protected override void OnServiceInjectionFailed(Exception ex)
    {
        base.OnServiceInjectionFailed(ex);
        // Custom error handling
    }
}

// New (v2.0)
public class MyService : ServiceKitBehaviour<IMyService>
{
    protected override void RegisterServiceWithLocator()
    {
        base.RegisterServiceWithLocator();
        // Custom logic
    }
    
    protected override void HandleDependencyInjectionFailure(Exception ex)
    {
        base.HandleDependencyInjectionFailure(ex);
        // Custom error handling
    }
}

Complete Method Mapping

v1.x Method	v2.0 Method
RegisterService()	RegisterServiceWithLocator()
UnregisterService()	UnregisterServiceFromLocator()
InjectServicesAsync()	InjectDependenciesAsync()
MarkServiceReady()	MarkServiceAsReady()
OnServiceInjectionFailed()	HandleDependencyInjectionFailure()

Quick Migration Steps

1. Update your package.json to version 2.0.0
2. Search your codebase for any overrides of the old method names
3. Replace with the new method names as shown above
4. Update any direct field access from Registered/Ready to IsServiceRegistered/IsServiceReady
5. Recompile and test your services

The core functionality remains unchanged - only the naming has been improved for better clarity and maintainability.

Unit Testing

ServiceKit provides first-class support for unit testing through the UseLocator() method, which allows you to inject mock or test instances of IServiceKitLocator without requiring Unity's serialized field assignment.

Important: When using AddComponent<T>() to create a ServiceKitBehaviour, Unity calls Awake() immediately—before you can assign a locator. UseLocator() handles this automatically by triggering registration if it was skipped during Awake().

Testing with Mocks

Use NSubstitute or any mocking framework to create isolated unit tests:

[TestFixture]
public class MyServiceTests
{
    private IServiceKitLocator _mockLocator;
    private IServiceInjectionBuilder _mockBuilder;

    [SetUp]
    public void Setup()
    {
        _mockLocator = Substitute.For<IServiceKitLocator>();
        _mockBuilder = Substitute.For<IServiceInjectionBuilder>();

        // Setup fluent API chain
        _mockBuilder.WithCancellation(Arg.Any<CancellationToken>()).Returns(_mockBuilder);
        _mockBuilder.WithTimeout(Arg.Any<float>()).Returns(_mockBuilder);
        _mockBuilder.WithTimeout().Returns(_mockBuilder);
        _mockBuilder.WithErrorHandling(Arg.Any<Action<Exception>>()).Returns(_mockBuilder);
        _mockBuilder.ExecuteAsync().Returns(Task.CompletedTask);
        _mockLocator.InjectServicesAsync(Arg.Any<object>()).Returns(_mockBuilder);
    }

    [Test]
    public async Task MyBehaviour_RegistersService_OnAwake()
    {
        // Arrange
        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceBehaviour>();
        behaviour.UseLocator(_mockLocator);

        // Act
        await behaviour.TestAwake(CancellationToken.None);

        // Assert
        _mockLocator.Received(1).RegisterService(Arg.Any<IMyService>(), Arg.Any<string>());
    }
}

Testing with Real ServiceKitLocator

For integration tests, use a real ServiceKitLocator instance:

[TestFixture]
public class MyServiceIntegrationTests
{
    private ServiceKitLocator _locator;

    [SetUp]
    public void Setup()
    {
        _locator = ScriptableObject.CreateInstance<ServiceKitLocator>();
    }

    [TearDown]
    public void TearDown()
    {
        _locator?.ClearServices();
        if (_locator != null) Object.DestroyImmediate(_locator);
    }

    [Test]
    public void MyBehaviour_RegistersAutomatically_WhenUseLocatorCalled()
    {
        // Arrange - AddComponent triggers Awake, but registration is skipped (no locator yet)
        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceBehaviour>();

        // Act - UseLocator triggers registration automatically
        behaviour.UseLocator(_locator);

        // Assert - Service is now registered
        Assert.IsTrue(_locator.IsServiceRegistered<IMyService>());
    }

    [Test]
    public async Task MyBehaviour_InjectsDependencies_WhenServicesReady()
    {
        // Arrange
        var playerService = new PlayerService();
        _locator.RegisterAndReadyService<IPlayerService>(playerService);

        var go = new GameObject();
        var behaviour = go.AddComponent<MyServiceBehaviour>();
        behaviour.UseLocator(_locator);

        // Act - Complete injection manually
        await _locator.InjectServicesAsync(behaviour)
            .WithCancellation(CancellationToken.None)
            .WithTimeout()
            .ExecuteAsync();

        _locator.ReadyService<IMyService>();

        // Assert
        Assert.IsNotNull(behaviour.PlayerService);
        Assert.AreSame(playerService, behaviour.PlayerService);
    }
}

Creating Testable ServiceKitBehaviours

Expose a TestAwake method to manually trigger the initialization sequence in tests:

public class MyServiceBehaviour : ServiceKitBehaviour<IMyService>, IMyService
{
    [InjectService] private IPlayerService _playerService;

    public IPlayerService PlayerService => _playerService;

    public async Task TestAwake(CancellationToken cancellationToken)
    {
        RegisterServiceWithLocator();

        await Locator.InjectServicesAsync(this)
            .WithCancellation(cancellationToken)
            .WithTimeout()
            .WithErrorHandling(HandleDependencyInjectionFailure)
            .ExecuteAsync();

        await InitializeServiceAsync();
        InitializeService();

        MarkServiceAsReady();
    }
}

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ for the Unity community