> ## 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.

# VR SDK architecture

> VR training layers on Molca Core, scenario terminology, app flow, and session integration.

**Product:** [Molca VR SDK](/overview/platforms) (`Assets/_MolcaSDK/_VR/`) on [Molca Core](/core/runtime-manager). For **cross-product** Core placement, see [Architecture](/overview/architecture). For **content structure** (modules → scenario → simulation vs tour), see [VR content hierarchy](/vr/sdk-content-hierarchy).

## Layers (VR training on Molca Core)

```mermaid theme={null}
flowchart TB
  subgraph L1["Your VR content"]
    A["Scenes · Step hierarchies · ScenarioData assets"]
  end
  subgraph L2["Molca SDK VR"]
    B["ScenarioManager · Session · Tour · Home UI · VR steps · interactions"]
  end
  subgraph L3["Molca Core"]
    C["RuntimeManager · DI · EventDispatcher · References · Sequences · HTTP · Settings"]
  end
  subgraph L4["Unity / XR"]
    D["XR Interaction Toolkit · player rig"]
  end
  L1 --> L2 --> L3 --> L4
```

Dependency direction: **your VR training content** calls into the VR SDK; the VR SDK sits on **Molca Core**; both run on **Unity + XR**.

## Glossary (VR training)

| Term               | Where it lives                                                                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scenario**       | `BaseScenarioData` → `SimulationScenarioData` / `TourScenarioData` in `Scenario/Data/`                                                        |
| **Simulation**     | Activities + steps; optional time limit on `SimulationScenarioData`                                                                           |
| **Tour**           | Areas (often additive scenes), spots (`TourSpotController`), informational **materials** (not Unity materials)                                |
| **Activity**       | `ScenarioActivity` — `SequenceController` + root `Step` list; ties to scoring/session                                                         |
| **Step**           | `Molca.Sequence.Step` — may nest children (`ParallelStep`, etc.); completes when self + children complete                                     |
| **Step auxiliary** | `StepAuxiliary` list on `Step` (e.g. **`StepInfo`** titles for [Scenario UI](/vr/scenario-ui) task lists, scoring, haptics, controller hints) |
| **Mode driver**    | `IScenarioModeDriver` — `SimulationScenarioModeDriver` vs `TourScenarioModeDriver`                                                            |

## Scenario state (`ScenarioManager`)

`ScenarioState`: `Inactive`, `Active`, `Paused`, `Completed`, `Terminated`, `TimedOut`.

`FailScenario()` sets **`Terminated`**. API comments note that **success** and **failure** can both end as a finished session from the backend’s perspective; **pass/fail may depend on posted scores**. Inspect `CompleteScenario`, `FailScenario`, and `TimeoutScenario` in `Scenario/ScenarioManager.cs` when customizing outcomes.

## Typical VR app flow (molca-sdk-vr)

```mermaid theme={null}
flowchart LR
  P["Preload VR"] --> Auth["Auth VR"]
  Auth --> Home["Home VR"]
  Home --> Scn["Scenario scene"]
  Scn --> Out["Complete / timeout / fail"]
  Out --> Home
```

1. **Preload** — `VRPreloadCheck` runs child components implementing `IPreloadCheck` (`_MolcaSDK/Code/.../Preload/`).
2. **Auth** — `ScenarioSessionManager.VisitorLoginAsync` (6-digit OTP) or `MemberLoginAsync(email, password)`. Avoid obsolete `MemberLoginAsyncUsingClerk`.
3. **Home** — `HomeUIManager` + `ScenarioDataConfig` (and fetched org content when connected).
4. **Scenario** — `ScenarioManager` + mode driver; simulation uses activities/sequences; tour uses `TourSubsystem`.
5. **End** — completion / timeout / fail UI + session status and scores via `ScenarioNetworkConfig`.

## Scenario lifecycle states

`ScenarioState` on [ScenarioManager](/vr/scenario-manager) (simplified — see source for guards):

```mermaid theme={null}
stateDiagram-v2
  direction LR
  [*] --> Inactive
  Inactive --> Active: StartScenario
  Active --> Completed: CompleteScenario
  Active --> TimedOut: TimeoutScenario
  Active --> Terminated: FailScenario
  Completed --> [*]
  TimedOut --> [*]
  Terminated --> [*]
```

**Pause UI:** `PauseScenario()` / `ResumeScenario()` only show or hide the pause modal. **`CurrentState` stays `Active`**; sequences and timers keep running (see API comments in `ScenarioManager.cs`). The enum includes `Paused`, but that path is not used by the pause modal flow.

## Connected session (high level)

```mermaid theme={null}
sequenceDiagram
  participant UI as Auth / Home UI
  participant SM as ScenarioSessionManager
  participant API as Backend VR API
  UI->>SM: VisitorLogin / MemberLogin
  SM->>API: token / login
  API-->>SM: bearer token
  SM->>API: GetContent
  API-->>SM: scenarios
  Note over UI,API: User picks scenario
  UI->>SM: CreateSession / Start / Load scene
  SM->>API: session + scores + status
```

## VR entry-point cheat sheet

| Concern                | Type                                                           |
| ---------------------- | -------------------------------------------------------------- |
| Bootstrap              | `RuntimeManager` (`_Core/Runtime/RuntimeManager.cs`)           |
| Project config asset   | `MolcaProjectSettings`                                         |
| Module bag             | `GlobalSettings` + `SettingModule` (e.g. `ScenarioDataConfig`) |
| Scenario orchestration | `ScenarioManager`, `ScenarioActivity`                          |
| Backend VR HTTP        | `ScenarioSessionManager`, `ScenarioNetworkConfig`              |

## Related

* [VR overview](/vr/sdk-overview) — doc hub for this SDK
* [VR content hierarchy](/vr/sdk-content-hierarchy) — simulation vs tour trees
* [VR assets and scenes](/vr/sdk-assets-and-scenes) — ScriptableObjects vs Unity scenes
* [Runtime and settings](/overview/runtime-and-settings) — shared bootstrap