Auto Singleton — Documentation

Namespace

All Auto Singleton classes are in the AutoSingleton namespace. Add this at the top of your scripts to access them:

using AutoSingleton;

Automatically Creating a Singleton

Basic

Add the [Singleton] attribute to any class derived from MonoBehaviour or ScriptableObject:

[Singleton]
public class ExampleMB : MonoBehaviour { ... }

[Singleton]
public class ExampleSO : ScriptableObject { ... }

An instance is created automatically in the project Assets folder, under a Singleton directory organized by type.

Project window showing auto-created singleton folder structure

Auto-created singleton assets in the Project window

You can freely rename, move, and modify the asset. If you delete the singleton component from a prefab, a new one will be recreated on the next refresh.

Advanced

The [Singleton] attribute exposes three optional fields:

[Singleton(
    inherited = true,
    displayName = "Example Display Name",
    folderPath = "Folder/SubFolder"
)]
public class ExampleMB : MonoBehaviour { ... }

inherited - If true, the attribute also applies to any class derived from the decorated type.
displayName - The name the singleton asset will have in the Assets folder. Not inherited by derived classes.
folderPath - Where to create the singleton asset, relative to Assets/. Inherited by derived classes when inherited is true.

Retrieving a Singleton

Single Instance

Access a singleton from any script using the Instance property of Singleton<T>:

ExampleMB instance = Singleton<ExampleMB>.Instance;

Multiple Instances

Use Instances to get all registered singletons assignable to a type. T can be a base class or an interface:

// All singletons derived from ParentMB
IReadOnlyList<ParentMB> allMBs = Singleton<ParentMB>.Instances;

// All singletons implementing IInterface
IReadOnlyList<IInterface> allImpl = Singleton<IInterface>.Instances;

Selecting an Instance

When multiple singletons are assignable to T, accessing Instance directly throws an exception in the editor. Call SelectInstance first to designate which one to use. All scripts that call Instance afterwards get the selected one:

// In one script, pick which instance to use:
Singleton<ParentMB>.SelectInstance((pmb) => pmb.enabled);

// In any other script, use Instance normally:
Singleton<ParentMB>.Instance.DoSomething();

See the Public API for all SelectInstance overloads (predicate, priority function, direct instance, type parameter, and no-arg).

Find Method

Find returns every registered singleton matching a predicate as a new array. Cache the result if you need it more than once.

ExampleMB[] matches = Singleton<ExampleMB>.Find(
    (s) => s.name.StartsWith("a"));

Manually Creating a Singleton

For scenarios where you need full control over singleton lifetime, use the Singleton static class to add and remove instances at runtime. This works with any reference type, not just MonoBehaviour or ScriptableObject. Singletons registered this way are accessed exactly like automatically managed ones.

Adding a MonoBehaviour manually does not reparent it under the Auto Singleton root GameObject, so it will be destroyed on scene load unless you call Object.DontDestroyOnLoad on it yourself.

Add & Remove

// Register one or more instances
Singleton.Add(myInstance);
Singleton.Add(instanceA, instanceB, instanceC);

// Unregister a previously added instance
Singleton.Remove(myInstance);

Add throws if a singleton of the same exact runtime type is already registered.
Remove throws if the instance is not in the list, or if it is managed automatically (not added via Add).

Top Bar Menu

All editor tools are under Tools > Auto Singleton:

Tools > Auto Singleton menu

Options / Automatic Refresh

When enabled, singletons are created and deleted automatically after every successful compilation.

Options / Log Changes

When enabled, every singleton creation and deletion is logged to the console.

Options / Project Icons

When enabled, singleton instances display a custom icon in the Project (Assets) window.

Force Refresh

Manually trigger singleton creation and deletion according to the current [Singleton] attribute usage. Has no effect when there are compilation errors.

Auto Singleton List

Selects the singleton list asset in the inspector. From there you can see all registered singletons and toggle each one on or off to prevent it from being instantiated at runtime.

Singleton List inspector

Documentation

Opens this documentation.

Demo

The package ships with a Tic Tac Toe game built with an MVC pattern. It demonstrates 5 singletons across different types: MonoBehaviour, ScriptableObject, and a plain class. Explore it to see the tool used in varied real-world scenarios.

Delete the Demo folder once you are done to avoid instantiating unnecessary singletons and to remove unused assets from your project.

Troubleshooting

Caching a Singleton Reference from Another One

If you store a singleton reference in a field of another automatically managed MonoBehaviour singleton, do not fetch it in Awake. Use Start instead; at Awake time other singletons may not yet be instantiated.

[Singleton]
class MySingleton : MonoBehaviour
{
    AnotherSingleton anotherSingleton;

    void Start() // Do not do this in Awake.
    {
        anotherSingleton = Singleton<AnotherSingleton>.Instance;
    }
}

Caching is rarely worth the effort: Singleton<T>.Instance is already as optimized as a field read at runtime.

Corrupted Singleton List

If the singleton list asset is modified externally (from Unity or outside of it), it may no longer reference the correct assets. When this happens, Auto Singleton repopulates it with freshly created assets, potentially replacing your existing data.

To recover, open the singleton list asset in the inspector in Debug mode and reassign the asset references manually. Switch to Debug mode by clicking the three-dot menu in the top-right corner of the inspector and selecting Debug.

Switching the inspector to Debug mode

Author & Contact

Created by Juste Tools.

Contact: justetools@gmail.com
Other assets: assetstore.unity.com/publishers/52427

If you enjoy Auto Singleton, please consider leaving a review on the Asset Store. Your feedback helps improve the tool!