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

# Load Scene

> Load a 3D scene into the training viewer

## Overview

The **Load Scene** action loads a 3D scene from your scene library into the training viewer. Scenes are the 3D environments where learners interact with objects, perform tasks, and complete objectives. Every state that displays a 3D environment should load a scene on entry.

## When to Use

* **Initialize a scene**: use in the `onEntry` of any state that shows a 3D environment
* **Change environments**: switch to a different scene when the training moves to a new location or task
* **Reset the scene**: reload the same scene to return it to its default state after an action attempt

## Parameters

| Parameter        | Type    | Required | Description                                                                                                        |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| Scene ID         | string  | Yes      | Select the 3D scene from your scene library. This determines which environment is displayed.                       |
| Display Mode     | enum    | No       | How the scene is rendered: `default` (standard 3D view) or other render modes. Defaults to `default`.              |
| Scale Mode       | enum    | No       | How the scene scales to fit the viewer: `fit` (scale to fit), `stretch`, or `original`. Defaults to `fit`.         |
| Initial Position | X, Y, Z | No       | Offset the scene's starting position (in meters). Leave at 0, 0, 0 for default placement.                          |
| Meeple Disabled  | boolean | No       | Set to `true` to hide the learner's avatar/user representation in the scene. Defaults to `false` (avatar visible). |

## Important Notes

* **Scene replacement**: Loading a new scene replaces any currently loaded scene. The previous scene is unloaded.
* **Scene persistence**: The same scene instance persists if you stay in the same state. Objects you move or visibility changes you make are retained.
* **Asset library required**: Scenes must be created and imported in your Creator App project before they can be referenced.

## Practical Example

**Scenario**: A training where learners progress through three environments: a warehouse, a factory floor, and an equipment room.

<Steps>
  <Step>
    Create three states: `Warehouse`, `FactoryFloor`, and `EquipmentRoom`.
  </Step>

  <Step>
    In the **Warehouse** state's `onEntry`, add a Load Scene action:

    * Scene ID: `warehouse_main`
    * Display Mode: `default`
    * Scale Mode: `fit`
    * Meeple Disabled: `false`

    This displays the warehouse environment with the learner's avatar visible.
  </Step>

  <Step>
    In the **FactoryFloor** state's `onEntry`, add a Load Scene action:

    * Scene ID: `factory_floor_main`
    * Meeple Disabled: `true`

    Hide the avatar since this is a first-person inspection scenario.
  </Step>

  <Step>
    Use transitions to move between states. When transitioning from Warehouse → FactoryFloor, the Load Scene action in FactoryFloor's `onEntry` automatically unloads the warehouse and loads the factory floor.
  </Step>
</Steps>

<Tip>
  Use scene names that describe their purpose (e.g., `warehouse_main`, `assembly_line_v2`, `control_room_inspection`). This makes your state machine easier to understand and maintain.
</Tip>

<Warning>
  If a state displays objects or interactions but does not have a Load Scene action in its `onEntry`, no 3D environment will be visible. Always include Load Scene for states that require a 3D environment.
</Warning>