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

# Start Speed Tracking & Stop Speed Tracking

> Monitor object movement speed during learner interactions

## Overview

Use **Start Speed Tracking** to monitor how fast a learner is moving an object in the 3D scene. This is useful for procedures that require careful, slow movements. Use **Stop Speed Tracking** to end monitoring.

Speed tracking enables you to enforce safe handling practices — for example, requiring a learner to move a delicate component slowly, or detecting reckless, fast movements.

## Start Speed Tracking

### When to Use

* **Enforce slow, careful movements** — Ensure learners move fragile objects at safe speeds
* **Detect unsafe handling** — Flag movement speeds that violate safety practices
* **Quality control training** — Require precision and care during assembly or handling
* **Hazmat procedures** — Enforce careful movement of hazardous materials
* **Simulation realism** — Model real-world constraints on movement speed

### Parameters

| Parameter | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| Object    | String | Yes      | The identifier of the object to monitor (e.g., "vial", "circuit-board")      |
| Threshold | Number | Yes      | The maximum allowed speed (in units per second)                              |
| Unit      | String | No       | Measurement unit: `"m/s"` (meters/second, default), `"cm/s"`, or `"units/s"` |

### Example 1: Careful Vial Movement

```
Action: Start Speed Tracking
Object: "vial"
Threshold: 0.5
Unit: "m/s"
```

The vial is being tracked. If the learner moves it faster than 0.5 meters per second, the speed threshold is violated.

### Example 2: Circuit Board Assembly

```
Action: Start Speed Tracking
Object: "circuit-board"
Threshold: 0.3
Unit: "m/s"
```

The circuit board must be moved at or below 0.3 m/s — a slow, deliberate pace.

### Example 3: High-Precision Component

```
Action: Start Speed Tracking
Object: "precision-component"
Threshold: 20
Unit: "cm/s"
```

20 cm/s is very slow movement, suitable for extremely fragile components.

## Stop Speed Tracking

### When to Use

* End monitoring after the movement phase is complete
* Disable speed tracking before transitioning to the next step
* Stop tracking all objects after a handling sequence

### Parameters

| Parameter | Type   | Required | Description                                                                             |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| Object    | String | Optional | The identifier of a specific object to stop tracking. Omit to stop tracking all objects |

### Example 1: Stop Tracking One Object

```
Action: Stop Speed Tracking
Object: "vial"
```

Vial speed tracking stops. Other tracked objects (if any) continue to be monitored.

### Example 2: Stop Tracking All Objects

```
Action: Stop Speed Tracking
```

All active speed tracking is disabled.

## Best Practices

<Steps>
  <Step title="Pair with other constraints">
    Combine **Start Speed Tracking** with **Set Interactable Objects** to ensure only the target object can be moved.
  </Step>

  <Step title="Provide feedback on violations">
    Use **Show Red Vignette** or **Show Text** to give immediate visual or text feedback when speed is exceeded.
  </Step>

  <Step title="Test thresholds">
    Verify your speed thresholds are achievable and realistic. Test on different devices — mobile vs. desktop handling feels different.
  </Step>

  <Step title="Stop tracking in onExit">
    Always **Stop Speed Tracking** in the **onExit** actions to clean up before the next state.
  </Step>

  <Step title="Use transitions on violations">
    Connect speed-violation events to penalty states (subtract points, retry, warning, etc.).
  </Step>
</Steps>

## Common Patterns

### Careful Handling Procedure

```
State: HandleVial
  onEntry:
    → Set Interactable Objects (["vial"], true)
    → Start Speed Tracking
        Object: "vial"
        Threshold: 0.5
        Unit: "m/s"
    → Show Panel
        Title: "Handle with Care"
        Display Text: "Move the vial slowly and carefully. Do not exceed 0.5 m/s."
        Billboard: true

  transitions:
    - event: "speed-violation"
      action: Show Red Vignette
      target: "HandleVialSpeedViolation"
    - event: "vial-placed-correctly"
      target: "VialPlacedSuccess"

  onExit:
    → Stop Speed Tracking (Object: "vial")
    → Hide Panel
```

The learner is monitored while moving the vial. Exceeding the speed limit triggers a penalty state.

### Assembly With Speed Requirements

```
State: AssembleComponentSlowly
  onEntry:
    → Set Interactable Objects (["component-a", "component-b"], true)
    → Start Speed Tracking
        Object: "component-a"
        Threshold: 0.3
        Unit: "m/s"
    → Show Text "Assemble carefully. Move slowly to avoid damage."

  transitions:
    - event: "speed-violation"
      action:
        - Show Red Vignette
        - Show Text "Too fast! Slow down."
      target: "AssembleComponentSlowly"
    - event: "assembly-complete"
      action: Record achievement "Completed with proper care"
      target: "AssemblySuccess"

  onExit:
    → Stop Speed Tracking
    → Hide Text
```

If the learner moves too fast, they see a red vignette and try again. Completing the assembly slowly records an achievement.

### Multi-Object Handling

```
State: TransferLiquidSlowly
  onEntry:
    → Start Speed Tracking
        Object: "source-beaker"
        Threshold: 0.4
        Unit: "m/s"
    → Start Speed Tracking
        Object: "target-beaker"
        Threshold: 0.2
        Unit: "m/s"
    → Show Panel
        Title: "Transfer Liquid"
        Display Text: "Pour carefully. Source beaker ≤ 0.4 m/s, target beaker ≤ 0.2 m/s"
        Billboard: true

  transitions:
    - event: "speed-violation"
      action: Show Red Vignette
      target: "TransferLiquidSlowly"
    - event: "transfer-complete"
      target: "TransferSuccess"

  onExit:
    → Stop Speed Tracking
    → Hide Panel
```

Two objects are tracked simultaneously with different thresholds. Both must meet their speed requirements.

## Speed Violation Events

Speed tracking typically fires a `"speed-violation"` event when the threshold is exceeded. Use this event to:

* Transition to a penalty or retry state
* Show corrective feedback
* Apply a score reduction
* Display a warning message
* Trigger visual feedback (red vignette)

## Related Actions

* **Set Interactable Objects** — Restrict interactions to only the object being speed-tracked
* **Show Red Vignette** — Provide visual feedback on speed violations
* **Show Text** — Display speed requirements and warnings
* **Show Panel** — Show detailed instructions about speed constraints