# Quick Start

```{note}
**Video walkthrough coming soon.** A YouTube walkthrough of the recipes below
goes here. Until then, follow the written steps: each one has its own screenshot.
```

Three recipes, each buildable in a few minutes, that together teach the whole
system. Build them in an empty level and you have a Quick-Start map: one actor per
recipe.

```{tip}
Every field named below (`@Panel`, `Open`, `Door`, ...) is offered by a searchable
**[...] picker** in the IC Control Panel. You rarely type anything by hand, and the
panel validates what you write and flags typos with an amber chip.
```

## Recipe 1: A door you open (60 seconds)

**You'll build:** a StaticMesh that swings open on the first press and closes on the
next.

The fastest way to build this is to **record it**, not type it in by hand:

1. Drop a **StaticMeshActor** with a door mesh. Add a child scene component (or use
   the mesh itself) named **`Panel`**: the part that rotates. Select the actor →
   the **IC Control Panel** opens. Click **+ Add Interactive Component** if it has
   no IC yet.

<!-- shot:quickstart-r1-step1-add-ic -->
```{image} ../_static/screenshots/shot-quickstart-r1-step1-add-ic-mockup.svg
:alt: quickstart r1 step1 add ic (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r1-step1-add-ic.png`
<!-- /shot -->

2. Select `Panel` in the viewport, press **● Rec**, rotate it open with the mouse,
   press **■ Stop**, then **Create**. That's the whole recipe: every field in the
   dialog is already filled in (Forward `Open`, Reverse `Close`, Cycle `Toggle`),
   and the Tag (`!Toggle`) is written onto `Panel` automatically, nothing left to
   name or wire up by hand. See {doc}`../guides/control-panel`.

<!-- shot:quickstart-r1-step2-record -->
```{image} ../_static/screenshots/shot-quickstart-r1-step2-record-mockup.svg
:alt: quickstart r1 step2 record (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r1-step2-record.png`
<!-- /shot -->

3. Give your pawn a **Mova Interact Interactor** component and call
   **`TargetInteraction()`** from an input action (or press **▶ Test** on a group
   to preview without playing).

<!-- shot:quickstart-r1-step3-interactor -->
```{image} ../_static/screenshots/shot-quickstart-r1-step3-interactor-mockup.svg
:alt: quickstart r1 step3 interactor (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r1-step3-interactor.png`
<!-- /shot -->

**What just happened:** the tag `!Toggle` on `Panel` says "run the `Toggle` cycle,
driving whatever Component this tag sits on." No explicit target is needed since
the tag lives directly on the Component that moved. Each press moves the cycle
one step (`Open` then `Close` then back) and the recorded KeyFrames tween the
pose. No Blueprint graph.

```{note}
**Doing it by hand instead:** a Cycle only steps over named Groups in order.
It does not reverse a Group on its own. `Toggle` needs two real Groups, `Open`
(ending at an `Open` State) and `Close` (ending back at `@Zero`), not one Group
listed twice. Add State **`Open`** with the open `Rotation`, build a Group `Open`
with one Action on `@Panel` (KeyFrame `0.0` = `@Zero`, KeyFrame `1.0` = `Open`),
then a Group `Close` reversing it (KeyFrame `0.0` = `@Current`, KeyFrame `1.0` =
`@Zero`), then a Cycle `Toggle` listing `Open, Close`. Recording does all of this
for you in one pass.
```

## Recipe 2: A lamp that lights as you approach (no prompt)

**You'll build:** a lamp that turns on when the player walks near and off when they
leave, no aiming, no button.

1. Drop a light-bearing actor. Add its IC. Name the light component **`Bulb`**.

<!-- shot:quickstart-r2-step1-add-ic -->
```{image} ../_static/screenshots/shot-quickstart-r2-step1-add-ic-mockup.svg
:alt: quickstart r2 step1 add ic (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r2-step1-add-ic.png`
<!-- /shot -->

2. **Add State** `On` → in its **Visuals** group set `LightIntensity` up (and
   `LightColor` if you like). **Add State** `Off` → intensity `0`.

<!-- shot:quickstart-r2-step2-states -->
```{image} ../_static/screenshots/shot-quickstart-r2-step2-states-mockup.svg
:alt: quickstart r2 step2 states (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r2-step2-states.png`
<!-- /shot -->

3. **Add Group** `TurnOn` → Action on `@Bulb` → KeyFrame `0.0` = `@Current`, KeyFrame
   `0.3` = `On`. **Add Group** `TurnOff` similarly ending in `Off`.

<!-- shot:quickstart-r2-step3-groups -->
```{image} ../_static/screenshots/shot-quickstart-r2-step3-groups-mockup.svg
:alt: quickstart r2 step3 groups (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r2-step3-groups.png`
<!-- /shot -->

4. On the IC, set **`Proximity.Shape = Sphere`** and a `SphereRadius` (ex: `300`).

<!-- shot:quickstart-r2-step4-proximity-shape -->
```{image} ../_static/screenshots/shot-quickstart-r2-step4-proximity-shape-mockup.svg
:alt: quickstart r2 step4 proximity shape (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r2-step4-proximity-shape.png`
<!-- /shot -->

5. In **Proximity → Enter tags** add **`!TurnOn @Bulb`**; in **Leave tags** add
   **`!TurnOff @Bulb`**.

<!-- shot:quickstart-r2-step5-enter-leave-tags -->
```{image} ../_static/screenshots/shot-quickstart-r2-step5-enter-leave-tags-mockup.svg
:alt: quickstart r2 step5 enter leave tags (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r2-step5-enter-leave-tags.png`
<!-- /shot -->

**What just happened:** proximity tags use the same grammar as pressed
tags: overlap fires Enter, exit fires Leave. A presence-driven interaction with
zero UI. See {doc}`../concepts/proximity`.

## Recipe 3: A drawer locked behind a keycard (gates)

**You'll build:** a drawer that only opens when a separate `Lock` reads *unlocked*,
and gives a "locked" clunk otherwise.

1. Build a drawer the same way as Recipe 1: select the drawer front, press
   **● Rec**, slide it out, **■ Stop**, then **Create** with the defaults
   (Forward `Open`, Reverse `Close`, Cycle `Toggle`). The `!Toggle` tag lands on
   the drawer front automatically.

<!-- shot:quickstart-r3-step1-record-drawer -->
```{image} ../_static/screenshots/shot-quickstart-r3-step1-record-drawer-mockup.svg
:alt: quickstart r3 step1 record drawer (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r3-step1-record-drawer.png`
<!-- /shot -->

2. Add a second component **`Lock`** with two states **`Locked`** and **`Unlocked`**
   (a small rotation, or only the visibility of a red/green nub).

<!-- shot:quickstart-r3-step2-lock-component -->
```{image} ../_static/screenshots/shot-quickstart-r3-step2-lock-component-mockup.svg
:alt: quickstart r3 step2 lock component (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r3-step2-lock-component.png`
<!-- /shot -->

3. On the drawer's `Open` group, open **Group settings → `Gates`** and
   add **`@Lock:Unlocked`**: "only run while the `Lock` component is in its
   `Unlocked` state."

<!-- shot:quickstart-r3-step3-gate-on-open-group -->
```{image} ../_static/screenshots/shot-quickstart-r3-step3-gate-on-open-group-mockup.svg
:alt: quickstart r3 step3 gate on open group (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r3-step3-gate-on-open-group.png`
<!-- /shot -->

4. Set up the **fail feedback**: bind `OnActionRejected` (a Blueprint event on the
   IC) and, when `GroupName == "Open"`, run a short "clunk" state (an audio-only
   State with a Trigger sound) directly, there is no automatic fail-action field,
   the rejection is reported to you and you decide what plays.

<!-- shot:quickstart-r3-step4-on-action-rejected -->
```{image} ../_static/screenshots/shot-quickstart-r3-step4-on-action-rejected-mockup.svg
:alt: quickstart r3 step4 on action rejected (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r3-step4-on-action-rejected.png`
<!-- /shot -->

5. Make something toggle the `Lock`: a keycard reader, a proximity tag, or a button
   elsewhere addressing it directly (`@Lock`, or `%DrawerActorTag^@Lock` if the
   drawer has its own actor `=Tag`): flip `Lock` to `Unlocked`.

<!-- shot:quickstart-r3-step5-unlock-trigger -->
```{image} ../_static/screenshots/shot-quickstart-r3-step5-unlock-trigger-mockup.svg
:alt: quickstart r3 step5 unlock trigger (placeholder mockup)
:width: 100%
```

Save the real screenshot as: `shot-quickstart-r3-step5-unlock-trigger.png`
<!-- /shot -->

**What just happened:** a Group's `Gates` list is checked before it is allowed to
start, using the same address grammar as everywhere else: a state on this IC
(`:Open`), an internal component (`@Lock:Unlocked`), or a remote object
(`%Vault@Bolt:Locked`). A pass lets the group start. A fail blocks it and
broadcasts `OnActionRejected` with the reason, which you bind to drive whatever
feedback you want. Keycard doors, multi-lock vaults and sequence puzzles all use
this one mechanism. See {doc}`../concepts/gates`.

```{tip}
**Shortcut:** the same gate can be written inline on the tag itself
(`!Toggle ?@Lock:Unlocked`) when you want it on one interaction instead of
the whole group.
```

## When it doesn't work

Open the console and type **`mova.ix.Debug tags gates`**, then aim at the object:

- a target shown **[UNRESOLVED]** → the tag names a component the actor doesn't
  have (check the `@Name`),
- a gate shown **FAIL** → a gate is holding it (check the group's `Gates` list, or
  the other component's state),
- **no points at all** → the IC has no actions or tags yet.

Full problem table: {doc}`../guides/debugging`.