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

# Attach Tool & Remove Tool

> Equip or unequip tools for the learner's hands during training

## Overview

Use **Attach Tool** to equip a 3D tool object to the learner's hand representation in the scene. This is essential for procedural training where learners need to handle specific tools — screwdrivers, wrenches, safety equipment, or specialized instruments.

Use **Remove Tool** to detach the tool when it's no longer needed.

Attaching tools makes training more realistic and helps learners understand which tools are used at each step.

## Attach Tool

### When to Use

* **Equip at procedure start** — Give learners a screwdriver before the assembly step
* **Tool-specific steps** — Provide the right tool for each procedure phase
* **Safety equipment** — Attach protective tools or equipment (fire extinguisher, first aid kit, etc.)
* **Context authenticity** — Make training visually match the real-world procedure
* **Multiple tools** — Attach different tools at different steps of a multi-phase procedure

### Parameters

| Parameter  | Type                      | Required | Description                                                                                           |
| ---------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| Tool Asset | Asset Reference or String | Yes      | The 3D tool object to attach (e.g., `"screwdriver-phillips"`, `"wrench-10mm"`, `"fire-extinguisher"`) |
| Hand       | String                    | No       | Which hand to attach to: `"left"`, `"right"`, or `"both"` (default: `"right"`)                        |

### Example 1: Attach Screwdriver to Right Hand

```
Action: Attach Tool
Tool Asset: "screwdriver-phillips"
Hand: "right"
```

A Phillips screwdriver appears in the learner's right hand.

### Example 2: Attach Wrench to Left Hand

```
Action: Attach Tool
Tool Asset: "wrench-10mm"
Hand: "left"
```

A 10mm wrench appears in the learner's left hand.

### Example 3: Attach Tool to Both Hands

```
Action: Attach Tool
Tool Asset: "pliers-standard"
Hand: "both"
```

Pliers appear in both hands for two-handed handling.

## Remove Tool

### When to Use

* Remove tool after the step requiring it is complete
* Clean up tools before transitioning to the next phase
* Prepare for a non-tool-based step or inspection phase

### Parameters

| Parameter | Type   | Required | Description                                                                           |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| Hand      | String | Optional | Which hand to remove from: `"left"`, `"right"`, `"both"`, or omit to remove from both |

### Example 1: Remove Tool from Right Hand

```
Action: Remove Tool
Hand: "right"
```

The tool is removed from the learner's right hand.

### Example 2: Remove Tool from Both Hands

```
Action: Remove Tool
Hand: "both"
```

Tools are removed from both hands.

### Example 3: Remove Tool (All Hands)

```
Action: Remove Tool
```

All attached tools are removed.

## Best Practices

<Steps>
  <Step title="Attach before the step">
    Use **Attach Tool** in **onEntry** before the step requiring the tool.
  </Step>

  <Step title="Remove after the step">
    Use **Remove Tool** in **onExit** to clean up before transitioning.
  </Step>

  <Step title="Match hand dominance">
    For realistic training, attach tools to the dominant hand (right for most learners, unless specified).
  </Step>

  <Step title="Show tool attachment">
    Use **Show Text** or **Show Panel** to explain what tool is being provided.
  </Step>

  <Step title="Combine with hand representation">
    Use **Set Hand Representation** to show gloved or specialized hands holding the tool.
  </Step>

  <Step title="Test tool visibility">
    Verify the tool 3D model is visible and properly scaled on different screen sizes.
  </Step>
</Steps>

## Common Patterns

### Single-Tool Procedure

```
State: OpenThePanel
  onEntry:
    → Attach Tool (Tool Asset: "screwdriver-phillips", Hand: "right")
    → Show Panel
        Title: "Remove Panel Screws"
        Display Text: "Using the Phillips screwdriver in your right hand, remove all four panel screws."
        Billboard: true
    → Set Interactable Objects (["screw-1", "screw-2", "screw-3", "screw-4"], true)

  transitions:
    - event: "all-screws-removed"
      target: "PanelRemoved"

  onExit:
    → Hide Panel
    → Remove Tool (Hand: "right")
```

A screwdriver is provided, the learner removes screws, then the screwdriver is removed.

### Multi-Tool Procedure

```
State: Step1-Disassemble
  onEntry:
    → Attach Tool (Tool Asset: "wrench-10mm", Hand: "right")
    → Show Text "Step 1: Use the wrench to loosen the bolts."
    → Set Interactable Objects (["bolt-1", "bolt-2", "bolt-3"], true)

  onExit:
    → Remove Tool (Hand: "right")

State: Step2-Replace
  onEntry:
    → Attach Tool (Tool Asset: "screwdriver-flat", Hand: "right")
    → Show Text "Step 2: Use the screwdriver to remove the cover plate."
    → Set Interactable Objects (["cover-plate"], true)

  onExit:
    → Remove Tool (Hand: "right")

State: Step3-Inspect
  onEntry:
    → Show Text "Step 3: Inspect the component with bare hands. No tools needed."
    → Set Interactable Objects (["component"], true)

  onExit:
    → Hide Text
```

Different tools are attached and removed as the procedure progresses.

### Two-Handed Tool Use

```
State: AssembleWithPliers
  onEntry:
    → Attach Tool (Tool Asset: "pliers-slip-joint", Hand: "both")
    → Show Panel
        Title: "Secure the Connection"
        Display Text: "Using both pliers, firmly grip and twist the connector into place."
        Media: "pliers-technique.png"
        Billboard: true
    → Set Interactable Objects (["connector"], true)

  transitions:
    - event: "connector-secured"
      target: "ConnectionComplete"

  onExit:
    → Hide Panel
    → Remove Tool (Hand: "both")
```

A tool is attached to both hands for two-handed handling, then removed after the step.

### Safety Equipment Attachment

```
State: FireSafetyResponse
  onEntry:
    → Attach Tool (Tool Asset: "fire-extinguisher", Hand: "right")
    → Show Panel
        Title: "Fire Emergency Response"
        Display Text: "You are holding a fire extinguisher. Know the PASS technique: Pull, Aim, Squeeze, Sweep."
        Billboard: true

  transitions:
    - event: "fire-extinguished"
      target: "SafetyConfirmed"

  onExit:
    → Hide Panel
    → Remove Tool (Hand: "right")
```

A fire extinguisher is provided for the emergency response scenario.

### Specialized Equipment

```
State: MedicalExamination
  onEntry:
    → Attach Tool (Tool Asset: "stethoscope", Hand: "both")
    → Show Text "Perform the examination using the stethoscope. Listen carefully to the patient's breathing."
    → Set Interactable Objects (["patient-chest", "patient-back"], true)

  transitions:
    - event: "examination-complete"
      target: "DiagnosisStep"

  onExit:
    → Hide Text
    → Remove Tool (Hand: "both")
```

A stethoscope is equipped for a medical examination step.

## Tool Asset Reference

Common tool assets available in Creator Studio:

| Tool                 | Asset Name             | Hand  | Use Case               |
| -------------------- | ---------------------- | ----- | ---------------------- |
| Phillips Screwdriver | `screwdriver-phillips` | Right | Standard assembly      |
| Flat Screwdriver     | `screwdriver-flat`     | Right | Panel/plate removal    |
| Adjustable Wrench    | `wrench-adjustable`    | Right | Nut/bolt work          |
| 10mm Wrench          | `wrench-10mm`          | Right | Specific fastener work |
| Pliers               | `pliers-slip-joint`    | Both  | Gripping/twisting      |
| Hammer               | `hammer-claw`          | Right | Driving/removal        |
| Level                | `spirit-level`         | Both  | Alignment/positioning  |
| Fire Extinguisher    | `fire-extinguisher`    | Right | Safety response        |
| Stethoscope          | `stethoscope`          | Both  | Medical examination    |

(Contact your creator team for a complete list of available assets.)

## Related Actions

* **Set Hand Representation** — Change the hand model that holds the tool
* **Set Hand Animation Color** — Customize the color of the hand holding the tool
* **Show Panel** — Display instructions about the tool or procedure
* **Show Text** — Explain what tool is being provided
* **Set Interactable Objects** — Restrict interactions to work with the provided tool