# Devices

Devices are Fusion's no-code building pieces. Put one in the world, change
its settings, and it does its job: show a message, count down, react when you walk somewhere,
drop props, keep score, give a quest, or tie things together with a rule.

Every Device is a short **Lua script** (`godot/devices/<type>.lua`) with settings. Nothing a
Device does is out of reach of a Lua addon: press **View as Lua** to see exactly what runs, and
copy it into your own addon to go further.

## Using them

While playing any scenario, press **F5**:

- **Place …** puts a Device where you're looking (the first thing the crosshair hits, or 4 m
  ahead on the ground). A marker with its number and name shows where it is.
- Pick a placed Device to change its **settings** (press Enter after typing), **View as Lua**,
  or **Remove** it. A Device restarts with its new settings at once.
- **Save Devices into the scenario** writes them into the scenario's file, so they're there the
  next time it's played (and in the scenario when it's shared).
- A Device with an area (Trigger Zone, Quest Giver) shows it as a glowing column. In an **Experience** (step 4.9) only those columns show, without numbers or names; its
  Devices start when the player presses Start, and its maker can lock the F5 panel.

In the scenario file they are `[[device]]` entries; only settings that differ from the
defaults are written:

```toml
[[device]]
type = "quest_giver"
at = [10.0, 0.0, 6.0]
settings = { goal = "Break a box", kind = "prop.box", count = 1 }
```

## The Devices

| Device | Does | Settings (defaults) |
|---|---|---|
| **Message** | shows a message when the scenario starts, or when a signal arrives | `text` "Welcome!", `seconds` 5, `delay` 1, `on_signal` "" |
| **Timer** | counts down on the screen; at zero shows a message and sends a signal | `seconds` 60, `label` "Time left", `done_text`, `signal` "timer_done", `start_on` "" |
| **Trigger Zone** | when the player walks into it, shows a message and sends a signal | `radius` 3, `text`, `signal` "zone_entered", `once` true |
| **Spawner** | drops physics props, one every few seconds, up to a count | `shape` "box", `color` "orange", `count` 5, `every` 2, `start_on` "" |
| **Scoreboard** | counts entities that die (any game's, or one kind) | `title` "Score", `kind` "", `points` 1 |
| **Quest Giver** | when the player comes close, gives a quest to defeat some entities; says when it's done and sends a signal | `radius` 3, `goal`, `kind` "", `count` 3, `done_text`, `signal` "quest_done" |
| **Rule** | when something happens (a signal, the player near, an entity dying), do something (a message, a signal, call entities here, put a game to sleep or wake it) | `when` "signal", `when_value` "quest_done", `radius` 3, `action` "message", `action_value` "Well done!", `once` true |

**Signals** tie Devices together: a Trigger Zone's `signal` can start a Timer (`start_on`), a
Quest Giver's `signal` can fire a Rule, and so on. Lua addons can send and hear them too
(`Fusion.signal(name)`, the `Fusion.Signal` hook).

## Making a Device

A Device template is a Lua file in `godot/devices/`. Its first lines describe it:

```lua
--- device: Message
--- about: Shows a message on the screen when the scenario starts.
--- setting: text = "Welcome!"
--- setting: seconds = 5
```

- `--- device:` its name (required, first line);
- `--- about:` one sentence for the panel;
- `--- area: radius` (optional): the number setting that is the radius of the area it works in;
  Fusion draws that area as a glowing column;
- `--- setting: key = value`: a setting and its default. Values are written like TOML: text in
  quotes, numbers, `true`/`false`.

When a Device is placed, Fusion puts one line in front of the template:

```lua
local Device = { id = "device_1", type = "message", pos = Vector(0, 0, 6), settings = { text = "Welcome!", seconds = 5 } }
```

So the script reads `Device.settings.text`, `Device.pos`, and uses `Device.id` as its hook name.
Everything else is the normal Lua API ([`docs/lua-api.md`](https://steonmod.com/docs/lua-api)), with the same sandbox and limits.
Each placed Device runs as an addon of its own: if one breaks, the others keep going, and its
error shows in the addon log.