XmobiTea Singleton

Scene-authored singleton utilities for Unity MonoBehaviour managers.

This package gives you:

• Singleton<T> for one cached scene instance per manager type
• DontDestroy for optional cross-scene persistence on the same host GameObject
• OnInit() for one-time setup on the surviving instance

It does not auto-create missing objects, and instance can return null.

AI Entry Points

Open the smallest file for the task:

| Need | Use | | --- | --- | | Generate common runtime code | AI_USAGE.md | | Scene setup and lifecycle requirements | AI_SETUP.md | | Exact signatures and package metadata | AI_API_REFERENCE.md | | Lookup, cache, duplicate, and persistence timing | AI_BEHAVIOR.md | | Agent guardrails and maintenance checklist | AGENTS.md | | Missing or conflicting docs | Runtime/Singleton.cs, Runtime/DontDestroy.cs |

Runtime Contract

• Singleton<T> only works with components that already exist on loaded scene GameObjects.
• instance returns the cached instance when available.
• If the cache is empty, instance uses the default FindObjectOfType<T>() lookup, which does not include inactive GameObjects.
• If no matching component is found, instance returns null.
• isExists only checks whether the private static cache currently evaluates as assigned.
• Duplicate singleton hosts destroy their own GameObject in Awake().
• DontDestroy calls GameObject.DontDestroyOnLoad(gameObject) in Start().

Setup

1. Create a component that derives from Singleton<T>.
2. Attach it to an active GameObject in a loaded scene.
3. Access instance only after the host is expected to exist.
4. Add DontDestroy only when the same host must survive scene loads.
5. Avoid multiple active hosts of the same singleton type across loaded scenes.

See AI_SETUP.md for detailed setup and lifecycle notes.

Usage

using UnityEngine;
using XmobiTea.MiniSingleton;

public sealed class GameManager : Singleton<GameManager>
{
    protected override void OnInit()
    {
        Application.targetFrameRate = 60;
    }

    public void RestartLevel()
    {
        Debug.Log("Restart level");
    }
}

Safe access when scene setup is uncertain:

var manager = GameManager.instance;
if (manager == null)
{
    Debug.LogError("Missing GameManager in loaded scene.");
    return;
}

manager.RestartLevel();

Cache-only check when you explicitly do not want a scene lookup:

if (GameManager.isExists)
{
    GameManager.instance.RestartLevel();
}

Lifecycle Notes

• The surviving instance runs OnInit() once per component instance.
• instance may initialize a found object before that object's own Awake() runs if another component accesses it earlier.
• OnInit() is the right place for setup that other code may need before Start().
• Avoid putting required singleton setup in a derived Awake() method; the package-owned Awake() handles cache assignment, duplicate destruction, and the OnInit() call.
• DontDestroy does not enforce uniqueness; it only makes the host persistent after Start().

Do And Do Not

• Do null-check instance when scene setup is not guaranteed.
• Do use OnInit() for one-time singleton setup.
• Do keep unrelated critical components off possible duplicate hosts.
• Do not assume isExists means a matching object exists somewhere in the scene.
• Do not assume this package creates missing managers.
• Do not use a derived Awake() method for setup that must run after singleton cache assignment.
• Do not add DontDestroy when the manager should remain scene-local.

Common Mistakes

• Using isExists as a scene existence check.
• Accessing instance from code that can run before the host scene object exists.
• Placing two active hosts of the same singleton type in concurrently loaded scenes.
• Expecting an inactive host to be found by instance before Unity activates it and runs Awake().
• Expecting DontDestroy to apply before Start().

Runtime Files

Runtime/Singleton.cs
Runtime/DontDestroy.cs

Package Metadata

• Package: com.xmobitea.changx.mini-singleton
• Runtime assembly: com.xmobitea.changx.mini-singleton.runtime
• Namespace: XmobiTea.MiniSingleton
• Minimum Unity version declared: 2022.3
• Declared dependency: com.xmobitea.changx.app 1.5.2
• License: Apache-2.0