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
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_robotcreates the file and editsbot.jsonin one call. The kit below has four complete drones to copy. Locally,npx @clunkyard/cli drone add scoutcopies a kit drone intodrones/and sets the field, anddrone listshows the kit; these commands andmatch --drones onneed a player kit released with drones (CLI 2.2.16 and earlier play without them).Launch it from the robot: the act's
dronegroup,{ "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 asbrief-1tobrief-8, fixed for its flight: a suspected position, a waypoint, a mode. It is the only thing a robot ever tells its drone.paramis shorthand forbrief-1.Read its reports in the state's
droneblock.
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
- 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 (
budgetorerror, 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:
matcheswith vieweventsortickslists the drone events and, for your robots, adronerow 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),droneOverrunsanddroneFaults.
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:
- 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
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