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:

    { "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 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).

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:

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

{ "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

The rules

All values are in hello.drones and the rules sheet.

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

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:

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

drones/decoy.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

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

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

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

Download this page as Markdown