> ## Documentation Index
> Fetch the complete documentation index at: https://docs-unity.molca.id/llms.txt
> Use this file to discover all available pages before exploring further.

# RuntimeManager

> Application bootstrap, service container, and initialization gate.

**Namespace:** `Molca`\
**File:** `Packages/com.molca.core/Runtime/RuntimeManager.cs`

## When to use

`RuntimeManager` is the single bootstrap entry point for every Molca-based project. You interact with it when:

* **Waiting for initialization** before accessing any service or subsystem (always call `await RuntimeManager.WaitForInitialization()` before resolving services).
* **Registering or resolving services** through the built-in DI container (`GetService<T>`, `RegisterService<T>`).
* **Injecting dependencies** into runtime-created objects that missed the automatic scene injection pass.
* **Creating factory-produced instances** with constructor + field injection via `CreateWithInjection<T>`.

## Bootstrap

After scene load, static initialization loads [Molca Project Settings](/setup/molca-project-settings), instantiates the configured RuntimeManager prefab, calls `DontDestroyOnLoad`, then runs async **`InitializeAsync`**: `GlobalSettings` load, subsystem discovery, service registration, scene-wide dependency injection, then **`IsReady`**.

```mermaid theme={null}
flowchart TD
  A[Scene loaded] --> B[Load MolcaProjectSettings]
  B --> C[Instantiate RuntimeManager prefab]
  C --> D[DontDestroyOnLoad]
  D --> E[InitializeAsync]
  E --> F[GlobalSettings.Initialize / LoadAllSettings]
  F --> G[Discover RuntimeSubsystem children]
  G --> H[Sort by InitializationPriority descending]
  H --> I[Initialize each subsystem]
  I --> J[Register services / DI container]
  J --> K[Inject scene MonoBehaviours]
  K --> L["IsReady = true"]
```

## Using from code

```csharp theme={null}
await RuntimeManager.WaitForInitialization();
```

## Service API

Prefer **`GetService<T>()`** / **`TryGetService<T>()`**. For `RuntimeSubsystem` types, **`GetSubsystem<T>()`** still resolves the same instance but is labeled legacy in source comments.

| Method                   | Signature                                                 | Description                                               |
| ------------------------ | --------------------------------------------------------- | --------------------------------------------------------- |
| `WaitForInitialization`  | `static async Awaitable WaitForInitialization()`          | Blocks until `IsReady` is true                            |
| `GetService<T>`          | `static T GetService<T>() where T : class`                | Resolve a registered service; returns `null` if not found |
| `TryGetService<T>`       | `static bool TryGetService<T>(out T service)`             | Try-pattern resolution; returns `true` if found           |
| `HasService<T>`          | `static bool HasService<T>()`                             | Check if a service type is registered                     |
| `RegisterService<T>`     | `static void RegisterService<T>(T instance)`              | Register a singleton service instance                     |
| `BindService<TI,TImpl>`  | `static void BindService<TI, TImpl>()`                    | Lazy singleton — created on first request                 |
| `RegisterFactory<T>`     | `static void RegisterFactory<T>(Func<T> factory)`         | Transient — factory called each resolution                |
| `GetSubsystem<T>`        | `static T GetSubsystem<T>() where T : RuntimeSubsystem`   | Legacy; delegates to `GetService<T>`                      |
| `InjectDependencies`     | `static void InjectDependencies(object target)`           | Inject `[Inject]` fields/properties on any object         |
| `InjectInto`             | `static void InjectInto(MonoBehaviour target)`            | Inject into a specific runtime-created MonoBehaviour      |
| `CreateWithInjection<T>` | `static T CreateWithInjection<T>() where T : class`       | Construct + inject fields/properties                      |
| `RegisterSubsystem`      | `static async void RegisterSubsystem(RuntimeSubsystem s)` | Register an external subsystem after init                 |
| `DeregisterSubsystem`    | `static void DeregisterSubsystem(RuntimeSubsystem s)`     | Remove a previously registered subsystem                  |
| `RunCoroutine`           | `static Coroutine RunCoroutine(IEnumerator e)`            | Start a coroutine on the RuntimeManager instance          |

## Troubleshooting

* **Services/subsystems are null in `Start` or `Awake`:** call `await RuntimeManager.WaitForInitialization()` before resolving. `[Inject]` fields are `null` until the injection pass completes.
* **`MolcaProjectSettings failed to load`:** ensure a `MolcaProjectSettings` asset exists under `Resources/` and the `RuntimeManager` prefab field is assigned.
* **`Multiple instances of subsystem type` warning:** only one enabled component of each `RuntimeSubsystem` type should exist on the prefab. Duplicates are automatically removed.
* **Dynamically created objects have null `[Inject]` fields:** call `RuntimeManager.InjectInto(component)` after `Instantiate` / `AddComponent` — the automatic scene pass only runs once during init.
* **Circular dependency detected:** two services depend on each other during resolution. Refactor one to use lazy resolution or event-based decoupling.

## Related

* [Runtime subsystem](/core/runtime-subsystem) — child components on the prefab
* [Dependency injection](/core/dependency-injection) — `[Inject]`
* [Molca Project Settings](/setup/molca-project-settings) — configures the RuntimeManager prefab reference
* [EventDispatcher](/core/event-dispatcher) — dispatches `TypedEvents.ApplicationInitialized` after init

## Unity Editor

<Frame caption="RuntimeManager prefab instance (DontDestroyOnLoad) in Hierarchy and Inspector">
  <img src="https://mintcdn.com/ptmolcateknologinusantara/jWDWJqZnZidoWqQK/images/features/core/runtime-manager-prefab.png?fit=max&auto=format&n=jWDWJqZnZidoWqQK&q=85&s=bfe1d439ed35da50a795ec59be6b32e7" alt="Runtime Manager Prefab" width="884" height="379" data-path="images/features/core/runtime-manager-prefab.png" />
</Frame>