# Drones

A drone is a small scout a robot can launch when a match turns drones on. It
flies on its own short program, finds what it can and reports home. It does
no damage. It is fast and easy to hear, easy to see and easy to shoot down,
so it tells its robot where to look, never where to shoot.

Drones are a practice option: `--drones on` locally, **Drones** in a hosted
practice or challenge match, `drones: "on"` through the practice tool. Rated
matches and tournaments have none.

## Give your robot a drone

1. Add a drone program to the project and name it in `bot.json`:

   ```json
   { "drone": "drones/scout.cadence" }
   ```

   In the workbench, add the file with **New file** and the field in
   `bot.json`; through the assistant tools, `build_robot` creates the file
   and edits `bot.json` in one call. [The kit](#the-kit) below has four
   complete drones to copy. Locally, `npx @clunkyard/cli drone add scout`
   copies a kit drone into `drones/` and sets the field, and `drone list`
   shows the kit; these commands and `match --drones on` need a player kit
   released with drones (CLI 2.2.16 and earlier play without them).
2. Launch it from the robot: the act's `drone` group, `{ "launch": true,
   "heading": 40, "pitch": 0, "brief": [620, 180, 1] }`, or the SDK's launch
   control. The **brief** is up to 8 numbers the drone reads as `brief-1` to
   `brief-8`, fixed for its flight: a suspected position, a waypoint, a mode.
   It is the only thing a robot ever tells its drone. `param` is shorthand
   for `brief-1`.
3. Read its reports in the state's `drone` block.

From the SDK, in every language: `drone.launch(heading, pitch, param)`,
`drone.brief(index, value)` for brief-1 to brief-8 before the launch,
`drone.has`, `drone.ready`, `drone.in_flight`, `drone.launches_left`,
`drone.report` (absent before the first) and `drone.sightings` (each with
its world position). `drone.program(language, source)` hands over a drone
before the first state. Vane, Cadence and Glyph robots read `drone-ready`,
`drone-flying`, `drone-age`, `drone-x`, `drone-y`, `drone-z`, `drone-say`,
`drone-sighting` and `drone-sighting-x`, `-y`, `-z` (the nearest sighting
in the newest report), and act with `launch`, `launch-heading`,
`launch-pitch`, `launch-param` and `launch-brief-1` to `launch-brief-4`
([the arena languages](https://clunkyard.com/sdk/arena-languages)).

For a Vane robot such as the starter, these two rules launch the kit scout
towards the middle once it may fly and turn the scanner to what it reports;
with drones off, `drone-ready` is never true and they do nothing:

```vane
# Drones on: once the scout may fly and nothing is in sight, send it to the
# middle of the arena.
rule drone-out priority 96 when drone-ready and not contact
  launch
  launch-heading atan2(height / 2 - y, width / 2 - x)
end

# A fresh sighting from the scout: point the scanner there.
rule scan-drone priority 15 when drone-sighting and drone-age < 1.5 and not contact
  scan-heading atan2(drone-sighting-y - y, drone-sighting-x - x)
  scan-pitch mode3 * atan2(drone-sighting-z - z, sqrt((drone-sighting-x - x) * (drone-sighting-x - x) + (drone-sighting-y - y) * (drone-sighting-y - y)))
  scan-arc 30
end
```

**The referee runs the drone.** It compiles the program once, before the
first tick, and runs it itself; the robot never runs it and cannot change it
during the match. The program comes from the robot's build (locally, its
project), unless the robot hands one over in its `ready` reply:

```json
{ "v": 2, "type": "ready", "drone": { "language": "cadence", "path": "scout.cadence", "source": "drone Scout\n..." } }
```

That program replaces the build's for this match, so a remote robot, or one
that picks a drone after reading the `hello`, flies the one it sends. A
WebAssembly robot cannot send one (its host writes the `ready` reply); it
flies the drone its `bot.json` names. One
that does not compile leaves the build's in place, and `state.drone.error`
says why.

A drone program that is missing or does not compile leaves the robot without
a drone; the robot still plays. Locally the CLI says why; a hosted build
fails with the file, line and column, shown in the build log and returned
by `build_robot` as a diagnostic.

## Watch and debug it

- **Replays** draw each drone in its owner's colour with its scan cone, its
  flares and where it was lost, in the tactical and cinematic views. Events
  say when a drone launched, fired a flare, had a run skipped (`budget` or
  `error`, never the text), was lost (`shot`, with the robot that shot it,
  or what it broke on) or ended. A replay names each robot's drone program
  and file, or that it failed, never its source or its errors.
- **The trace** (`/watch?replay=<id>&trace=<robot>`, your own robots only)
  shows, each turn, the drone block your robot last read: whether it has a
  program and the compile error if not, the last fault with its text, the
  launches left, whether it is in flight, and the newest report with its
  sightings. **D** jumps between the drone's moments.
- **The assistant tools**: `matches` with view `events` or `ticks` lists
  the drone events and, for your robots, a `drone` row each time the block
  changed: every report as the robot received it, each fault and error.
- **Stats**: a robot's match stats count `dronesLaunched`, `dronesLost`,
  `flares`, `dronesDowned` (other robots' drones it shot), `droneOverruns`
  and `droneFaults`.

## The rules

All values are in `hello.drones` and the [rules sheet](https://clunkyard.com/sdk/rules).

**Launching.** Each robot launches one drone a match, from 3 s, so when to
send it is a real choice. The drone appears 30 units out along the launch
heading. **Every other robot
hears the launch**: a `launch` cue from where the launching robot stands,
with the usual cue noise.

**Flight.** A drone flies by direct control in every ruleset, with no
momentum and no gravity: up to 140 units/s, turning at up to 240°/s and, in
3D, climbing at up to 180°/s within ±80°. It lasts 30 s. It breaks on a
wall, the ground, a hill or another robot, and passes through its own; a
break hurts nobody.

**Being found.** One shot that passes within 12 units of its centre downs
it; downing a drone scores nothing and does not count as a hit. A robot's
scan finds a drone 1.5 times as far as it finds a robot, and its proximity
sense finds one at any arc; the contact has `kind: "drone"` and an id such as
`drone-3`, never its owner. Each drone hums once a second, heard as a
`drone` cue (fade range 450). A robot's own shots pass its own drone.

**Its sensor.** A fixed 70° cone, reach 260, scanned every 4 ticks. It finds
robots other than its own, and other drones. A sighting's bearing has an
error of σ = 14° and its range 8%. The drone hears no cues and has no
proximity sense.

**Flares.** A drone carries 2 flares, at most one every 2 s. A flare is a
`muzzle` cue from the drone, exactly as a power-1 shot from there would be
heard: same fade, same noise. It fires no shot.

**Reports.** Every 10 ticks (0.5 s) the drone reports, and the robot reads
the report 0.5 s later. A report gives the drone's position and heading when
it was made, its state (`flying`, `lost` or `ended`), flares left, the
program's `say` value and up to two sightings: kind, bearing, elevation and
range from the drone, their errors and the tick each was taken. A drone that
is shot down, breaks or runs out of life sends one last report.

```
state.drone = { has, error?, fault?, launchesLeft, ready, inFlight, report }
report      = { tick, state, x, y, z, heading, pitch, flares, say, sightings }
sighting    = { tick, kind, bearing, elevation, range, bearingError, rangeError }
```

A sighting's world position is the report's position plus `range` along
`(bearing, elevation)`.

## The drone language

A drone program is Vane or Cadence with a drone's own words. It starts with
`drone NAME` in place of `bot NAME`; everything else, Vane's rules, cells and
priorities, Cadence's states, timers and variables, `let`, is the language
you know. See the [Vane](https://clunkyard.com/sdk/vane) and
[Cadence](https://clunkyard.com/sdk/cadence) references.

The program runs every 2 ticks with a budget of **256 operations**, counted
as each language counts them. A run that goes over, or that fails (a
non-finite control, a name with no value), is skipped: the drone keeps the
commands of its last good run, the robot's stats count the overruns, and its
state's `drone.fault` says what failed. Replays record only that a run
failed, never the text, which quotes the program.
Nothing forfeits. A program is at most 4 KiB (the kit drones are about 1), and a word or action outside
the drone set is a compile error.

| Word | Meaning |
| --- | --- |
| `tick`, `time` | ticks and seconds since launch |
| `life` | seconds the drone has left |
| `x`, `y`, `z`, `heading`, `pitch`, `speed` | where it is and how it flies |
| `width`, `height`, `depth`, `mode3` | the arena; `mode3` is true in 3D |
| `brief-1` … `brief-8` | the brief its robot launched it with (0 where none was given); `param` is `brief-1` |
| `home-x`, `home-y`, `home-z` | where its robot stood at launch |
| `flares` | flares left |
| `wall-distance` | how far it can fly along its heading before a wall, the floor or the ceiling |
| `contact`, `range`, `bearing`, `elevation` | the nearest sighting of its last scan |
| `contact-drone` | that sighting is a drone |
| `contacts`, `since-contact` | sightings in the last scan; seconds since the last one |
| `scan-heading`, `scan-pitch` | where its scanner points |

`contact-range(i)`, `contact-bearing(i)` and the other contact functions
read each sighting of the last scan, nearest first; `contact-x(i)` and its
siblings give the sighting's world position.

| Action | Effect |
| --- | --- |
| `drive` | speed, 0 to 1 of 140 units/s |
| `turn`, `pitch-turn` | turning and climbing rate, −1 to 1 |
| `steer-heading`, `steer-pitch` | turn toward a world heading or pitch at full rate (in place of `turn`, `pitch-turn`) |
| `scan-heading`, `scan-pitch` | point the scanner (it turns at 360°/s) |
| `flare` | fire a flare (no expression means true) |
| `say` | a number sent home in each report |
| `status-text` | a label shown in the replay |

A run that leaves a control unwritten holds still for that control: no
drive, no turn, no flare. A run that writes `steer-heading` steers, whatever
`turn` says, so a drone that steers must turn away from walls with
`steer-heading` too, as the kit does (`steer-heading heading + 90`). `say` and `status-text` keep their last value.

```cadence
drone Scout
initial search
state search
  each drive 1
  each if wall-distance < 90 -> turn 1
  each scan-heading heading + wave(30, 35)
  when contact and not contact-drone -> shadow
end
state shadow
  each steer-heading bearing + 90
  each drive 0.6
  each scan-heading bearing
  each say range
  when since-contact > 1.5 -> search
end
```

## The kit

The kit drones are in the engine's `drones/` folder, and in full below:

- **Scout** (Cadence) flies out along its launch heading, sweeping, and
  circles at the edge of its reach once it finds a robot.
- **Decoy** (Cadence) swings round to a robot's side, fires both flares from
  there and runs.
- **Picket** (Vane) circles its robot's launch point 150 units out, scanning
  outward.
- **Spotter** (Vane) climbs above its robot in 3D, searches in a spiral and
  holds a long stand-off, saying how long it has held its target.

Copy one, change a number, and watch the replay: drones, their scan cones,
flares and losses are all drawn.

### drones/decoy.cadence

```cadence
drone Decoy
# Flies out along its launch heading. On finding a robot it swings round to
# that robot's side and fires both flares from there, so the robot hears
# what sounds like a shot from a direction its own robot is not in. Then
# it runs. In 3D it holds its robot's height.

initial go

state go
  enter status-text "GO"
  each drive 1
  each if wall-distance < 90 -> turn 1
  each scan-heading heading + wave(24, 30)
  each scan-pitch pitch
  each steer-pitch clamp((home-z - z) / 3, -25, 25)
  when contact and not contact-drone -> lure
end

state lure
  enter status-text "LURE"
  each steer-heading bearing + 100
  each drive 0.8
  each if wall-distance < 90 -> steer-heading heading + 90
  each scan-heading bearing
  each scan-pitch elevation
  each flare range < 250
  each say flares
  when flares == 0 -> run
  when since-contact > 2 -> go
end

state run
  enter status-text "RUN"
  each drive 1
  each turn 0.4
  each if wall-distance < 90 -> turn 1
  each steer-pitch clamp((home-z - z) / 3, -25, 25)
end
```

### drones/picket.vane

```vane
drone Picket
# Circles the point its robot launched it from, 150 units out, with its
# scanner facing outward: an early warning for a robot that holds its
# ground. It says the range of anything it sees, and 0 otherwise.

let to-home = atan2(home-y - y, home-x - x)
let off = sqrt((home-x - x) * (home-x - x) + (home-y - y) * (home-y - y)) - 150

rule wall priority 30 when wall-distance < 50
  # steer-heading, as the rules below steer: it would override a turn.
  steer-heading heading + 90
  drive 0.5
end

rule spotted priority 20 when contact and not contact-drone
  say range
  scan-heading bearing
  scan-pitch elevation
end

rule orbit priority 10 when true
  steer-heading to-home + 90 - clamp(off * 0.6, -70, 70)
  drive 0.7
  scan-heading heading + 90
  steer-pitch clamp((home-z - z) / 3, -25, 25)
  say 0
end
```

### drones/scout.cadence

```cadence
drone Scout
# Flies out along its launch heading with its scanner sweeping, turning off
# the walls. Once it finds a robot it circles at the edge of its reach, so
# its robot keeps getting reports, and says the range in each report.
# In 3D it holds its robot's height.

initial search

state search
  enter status-text "SEARCH"
  each drive 1
  each if wall-distance < 90 -> turn 1
  each scan-heading heading + wave(30, 35)
  each scan-pitch pitch
  each steer-pitch clamp((home-z - z) / 3, -25, 25)
  each say 0
  when contact and not contact-drone -> shadow
end

state shadow
  enter status-text "SHADOW"
  each steer-heading bearing + 90
  each if range < 170 -> steer-heading bearing + 140
  each drive 0.6
  each if wall-distance < 90 -> steer-heading heading + 90
  each scan-heading bearing
  each scan-pitch elevation
  each steer-pitch clamp((home-z - z) / 3, -25, 25)
  each say range
  when since-contact > 1.5 -> search
end
```

### drones/spotter.vane

```vane
drone Spotter
# Climbs above its robot (in 3D) and searches in a slow spiral. Once it
# finds a robot it holds a long stand-off, near the edge of its reach, and
# says how many seconds it has held it, so its robot knows the reports are
# fresh and steady.

memory held 0

rule wall priority 30 when wall-distance < 60
  # steer-heading, as the rules below steer: it would override a turn.
  steer-heading heading + 90
  drive 0.5
end

# Its search circles back past where it was launched: keep clear of its
# robot, which a drone breaks on as on any other.
let from-home = sqrt((x - home-x) * (x - home-x) + (y - home-y) * (y - home-y))
rule clear priority 28 when not mode3 and from-home < 70
  steer-heading atan2(y - home-y, x - home-x)
  drive 0.8
end

rule close priority 25 when contact and not contact-drone and range < 200
  steer-heading bearing + 180
  drive 0.6
  scan-heading bearing
  scan-pitch elevation
  set held held + 1
  say held / 10
end

rule hold priority 20 when contact and not contact-drone
  steer-heading bearing + 90
  drive 0.3
  scan-heading bearing
  scan-pitch elevation
  set held held + 1
  say held / 10
end

rule search priority 10 when true
  drive 0.8
  turn 0.3
  scan-heading heading + wave(40, 40)
  scan-pitch -20
  set held 0
  say 0
end

rule level priority 5 when true
  steer-pitch clamp((home-z + 120 - z) / 3, -30, 30)
end
```
