RISC-V assembly
Develop locally · Develop hosted · Read a trace
Write your robot in real RISC-V assembly: the RV32IMFD instruction set,
with the standard ilp32d calling convention, the code a RISC-V chip runs.
Your .s file is the robot. LLVM assembles and links it, and it runs on a
small RISC-V machine that Clunkyard built for robots, inside the same
sandbox as every WebAssembly robot and metered the same way. Because we
built the machine, it can tell you exactly what went wrong: a bad load or
jump stops the robot with the instruction, its source line and the
registers that led there.
This guide assumes you have never written assembly. It explains registers, memory, calls and the stack as they work in this machine, then builds a robot one step at a time, ending at the starter. Every example here is assembled and run by the arena's tests, so what you read is what the machine does. RISC-V in ten minutes is the one-page summary, and the reference at the end lists every call.
Your first robot
# Drive in a circle and sweep the scanner around.
.include "clunkyard.inc" # the names for every robot call
.text # code goes in the .text section
.globl clunkyard_turn # make the label visible to the machine
clunkyard_turn: # the machine calls this once a turn
li t0, 1 # t0 = 1
fcvt.d.w fa0, t0 # fa0 = 1.0, a double
cy_drive_throttle # full speed: the call reads fa0
li t0, 2
fcvt.d.w fa0, t0
fdiv.d fa0, fa0, fa0 # 2.0 / 2.0 = 1.0
cy_drive_turn # turn hard left
li a0, 0 # status 0: play on
ret # back to the machine
Each line is one instruction, a directive (starting with .), or a label
(ending in :). # starts a comment. The machine calls clunkyard_turn
once a turn, like a function: it starts at the label and runs until ret
returns to the machine. Putting 0 in a0 before returning means "play on";
anything else ends the robot. A program may also have clunkyard_start,
which the machine calls once, before the first turn.
The cy_ lines are calls to the robot: each one is a macro from
clunkyard.inc that puts a call number in register a7 and runs ecall,
the instruction that asks the machine for something. The arguments are
already in registers: cy_drive_throttle takes its one number from fa0.
Registers
A RISC-V processor computes in registers: 32 integer registers, each
holding one 32-bit word, and, with the F and D extensions, 32
floating-point registers, each holding one 64-bit double. Instructions take
their inputs from registers and put their result in one; only loads and
stores touch memory. Every register has a number (x0 to x31, f0 to
f31) and a name that says what the calling convention uses it for.
Write the names: the assembler accepts both.
| Name | Register | What it is for | Kept across a call? |
|---|---|---|---|
zero |
x0 | always 0; writes to it vanish | |
ra |
x1 | the return address | no |
sp |
x2 | the stack pointer | yes |
gp, tp |
x3, x4 | reserved; leave them alone | |
t0 to t6 |
x5–x7, x28–x31 | temporaries | no |
s0 to s11 |
x8, x9, x18–x27 | saved registers | yes |
a0 to a7 |
x10–x17 | arguments and results | no |
ft0 to ft11 |
f0–f7, f28–f31 | floating-point temporaries | no |
fs0 to fs11 |
f8, f9, f18–f27 | floating-point saved registers | yes |
fa0 to fa7 |
f10–f17 | floating-point arguments and results | no |
The calling convention is the agreement that lets functions call each other. The few rules that matter here:
- Arguments go in
a0,a1, ... for integers and addresses, and infa0,fa1, ... for doubles, each list in order. A result comes back ina0orfa0. - A function may change any temporary (
t,ft) and argument (a,fa) register. If you need a value after you call one, keep it in a saved register (s,fs), and if your own function uses a saved register, put its old value back before you return. call labeljumps to a function and puts the return address inra;retjumps back tora. A function that calls another must save its ownrafirst, or it can never return.sppoints at the top of the stack, which grows down; keep it a multiple of 16.
The robot calls are kinder than functions: an ecall changes only a0
(the status) and a7 (the call number), so every other register keeps its
value across cy_ calls.
The instructions a robot needs
RISC-V instructions name their destination first: add t0, t1, t2 means
t0 = t1 + t2. Instructions ending in i take a 12-bit immediate, a number
from -2048 to 2047 written in the instruction. A few common instructions
are pseudo-instructions the assembler turns into real ones: li (load
any 32-bit number), la (load a label's address), mv, j, call,
ret, beqz, bnez, fmv.d, fneg.d and fabs.d.
li t0, 1000 # t0 = 1000
addi t1, t0, -1 # t1 = t0 - 1
add t2, t0, t1 # t2 = t0 + t1
sub t2, t2, t1 # t2 = t2 - t1
slli t3, t0, 2 # t3 = t0 * 4, a shift left by 2
mul t3, t3, t0 # t3 = t3 * t0
li t4, 7
div t5, t3, t4 # t5 = t3 / 7, rounded towards zero
rem t6, t3, t4 # t6 = the remainder
mv a1, t6 # copy a register
seqz a2, t6 # a2 = 1 if t6 is 0, else 0
slt a3, t1, t0 # a3 = 1 if t1 < t0 (signed), else 0
Division never traps: dividing by zero gives -1 (all ones) and the remainder is the dividend.
Branches compare two registers and jump to a label when the test holds:
beq, bne, blt, bge (signed), bltu, bgeu (unsigned), and the
one-register forms beqz, bnez, bltz and bgez. A number followed by
a colon, such as 1:, is a local label; 1b jumps to the nearest
1: backward and 1f to the nearest forward, so short loops need no
names.
# Add 1 + 2 + ... + 10 into t1.
li t0, 10 # the counter
li t1, 0 # the sum
1: add t1, t1, t0
addi t0, t0, -1
bnez t0, 1b # go round again until the counter is 0
# if t1 >= 50 then t2 = 1 else t2 = 2
li t3, 50
blt t1, t3, 2f
li t2, 1
j 3f
2: li t2, 2
3:
Doubles
Every number the robot API gives or takes is a double: headings and
pitches in degrees, ranges in arena units, battery charge. The D extension
computes with them in the f registers.
li t0, 3
fcvt.d.w ft0, t0 # integer to double: ft0 = 3.0
li t0, 4
fcvt.d.w ft1, t0 # ft1 = 4.0
fmul.d ft2, ft0, ft0 # 9.0
fmadd.d ft2, ft1, ft1, ft2 # ft1 * ft1 + ft2 = 25.0, rounded once
fsqrt.d ft3, ft2 # 5.0
fdiv.d ft4, ft3, ft1 # 1.25
fsub.d ft4, ft4, ft0 # -1.75
fabs.d ft5, ft4 # 1.75
fneg.d ft6, ft5 # -1.75
fmin.d ft7, ft5, ft6 # -1.75, the smaller
flt.d t1, ft6, ft5 # t1 = 1 if ft6 < ft5: comparisons give 0 or 1
feq.d t2, ft4, ft6 # t2 = 1, they are equal
fcvt.w.d t3, ft3, rtz # double to integer, rounded towards zero: 5
There are no floating-point immediates: a constant such as 0.7 lives in
memory, and you load it (the next section shows how). Small whole numbers
are often quicker with li and fcvt.d.w, as above. Converting a double
to an integer takes a rounding mode: rtz truncates like C, rne rounds
to nearest. .d instructions work on doubles; the .s forms work on
singles, which the robot API never uses.
Memory
Your program, its data and its stack share one megabyte of memory, from
address 0x00000000 to 0x000fffff. Each 4 KiB page is either code, read
only, read and write, or not there at all:
| Addresses | What is there |
|---|---|
0x00000000 to 0x0000ffff |
nothing: reading or writing here faults, which catches null pointers |
0x00010000 on |
your program: .text (code, which can run but not be written), then .rodata (constants, read only), then .data and .bss (read and write) |
up to 0x000d0000 |
the most your program may take |
0x000e0000 to 0x000fffff |
the stack, 128 KiB; sp starts at the top, 0x00100000 |
Sections are where you put things: .text for code, .rodata for
constants, .data for variables with a starting value and .bss for
variables that start at zero. Memory keeps its contents between turns,
so .data and .bss are how a robot remembers. Registers do not: each
turn starts with every register zero but sp and ra.
A load copies from memory into a register and a store from a register into
memory, at an address written as an offset from a register:
lw t1, 8(t0) loads the 4-byte word at t0 + 8. lw and sw move words,
lb and sb bytes, and fld and fsd doubles. An access must be
aligned: a word's address a multiple of 4 and a double's a multiple of
8. .balign 8 before a label puts it on an 8-byte boundary.
# Count the turns in memory, and keep constants in .rodata.
.include "clunkyard.inc"
.section .rodata
.balign 8
SEVEN_TENTHS: .double 0.7 # a constant double
.section .data
.balign 4
turns: .word 0 # a word that starts at 0
.text
.globl clunkyard_turn
clunkyard_turn:
la t0, turns # t0 = the address of turns
lw t1, 0(t0) # load the count
addi t1, t1, 1
sw t1, 0(t0) # store it back: it is there next turn
la t0, SEVEN_TENTHS
fld fa0, 0(t0) # fa0 = 0.7
cy_drive_throttle
li a0, 0
ret
The stack
The stack is memory a function borrows while it runs: it moves sp down
to make room, stores what it must keep, and moves sp back before it
returns. A function that calls another function keeps ra there:
.include "clunkyard.inc"
.text
# twice(fa0) -> fa0 * 2, a leaf: it calls nothing, so it needs no stack.
twice:
fadd.d fa0, fa0, fa0
ret
# four_times(fa0) -> fa0 * 4: it calls twice, so it saves ra.
four_times:
addi sp, sp, -16 # room for 16 bytes, keeping sp a multiple of 16
sw ra, 12(sp) # save the return address
call twice # ra now points here, inside four_times
call twice
lw ra, 12(sp) # put the return address back
addi sp, sp, 16
ret
.globl clunkyard_turn
clunkyard_turn:
addi sp, sp, -16
sw ra, 12(sp)
li t0, 1
fcvt.d.w fa0, t0
call four_times # fa0 = 4.0
lw ra, 12(sp)
addi sp, sp, 16
li a0, 0
ret
clunkyard_turn is a function too: the machine called it, and ra holds
the way back, so it saves ra before it calls anything with call.
Calling the robot
Every call to the robot is a cy_ macro from clunkyard.inc. Before the
macro, put the call's arguments in registers: integers and addresses in
a0, a1, ... in order, and doubles in fa0, fa1, ... in order. The
reference below gives each call's registers, and so does the comment above
its macro in clunkyard.inc. The call's status comes back in a0: 0
(CY_OK) when it answered, 1 (CY_NONE) when there is nothing to answer
with, such as no robot in sight, and a negative number for an error.
A call that answers with a value writes it to memory, at an address you
pass. cy_me_heading takes one argument, the address of 8 bytes for the
heading:
.include "clunkyard.inc"
.section .bss
.balign 8
HEADING: .zero 8 # 8 bytes for one double
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, HEADING # where to write the heading
cy_me_heading # writes it; a0 = the status
la t0, HEADING
fld fa0, 0(t0) # fa0 = this robot's heading, in degrees
cy_scanner_heading # point the scanner the same way
li a0, 0
ret
A call that answers CY_NONE leaves your memory as it was, so check the
status, or clear the memory first.
Reading a record
Some answers are records: several fields laid out in memory one after
another. A contact, a robot the sensors detect, has a slot number, a range,
a bearing, an elevation and more. clunkyard.inc gives each record's size
and each field's offset from the record's start: CY_CONTACT_SIZE is 72
bytes, and CY_CONTACT_RANGE is 8, so the range is the double at the
record's address plus 8.
.include "clunkyard.inc"
.section .bss
.balign 8 # records hold doubles: align them to 8
TARGET: .zero CY_CONTACT_SIZE # room for one contact
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, TARGET
cy_sensors_nearest # the nearest precise contact, if any
bnez a0, 1f # CY_OK is 0: anything else means none
la t0, TARGET
fld fa0, CY_CONTACT_BEARING(t0) # the field at TARGET + its offset
cy_gun_aim_heading # turn the turret towards it
lw t1, CY_CONTACT_SLOT(t0) # an integer field: a word
1: li a0, 0
ret
fld fa0, CY_CONTACT_BEARING(t0) is the whole idea: the base address in a
register and the field's offset written in the instruction. A record
inside a record, such as a zone's centre, has an offset of its own
(CY_ZONE_CENTER), and so does each of its fields (CY_ZONE_CENTER_X). A
call that takes a record, such as cy_angles_bearing_to, takes its
address: la a1, ZONE + CY_ZONE_CENTER passes the centre inside ZONE.
A robot, step by step
Each step adds one idea and plays a match as it is.
1. Search: drive, turn and sweep the scanner
The scanner sees robots in an arc. Sweeping it around finds them; the
scanner remembers where it last pointed, and cy_scanner_last reads that
back.
.include "clunkyard.inc"
.macro fload freg, label # a double constant from .rodata
la t6, \label
fld \freg, 0(t6)
.endm
.section .rodata
.balign 8
CRUISE: .double 0.5
LEFT: .double 0.33
ARC: .double 40.0
STEP: .double 36.0
.section .bss
.balign 8
SCAN: .zero CY_SCAN_SIZE
.text
.globl clunkyard_turn
clunkyard_turn:
fload fa0, CRUISE
cy_drive_throttle
fload fa0, LEFT
cy_drive_turn
la a0, SCAN
cy_scanner_last # where the scanner pointed last turn
la t0, SCAN
fld fa0, CY_SCAN_HEADING(t0)
fload ft0, STEP
fadd.d fa0, fa0, ft0 # 36 degrees on
cy_scanner_heading
fload fa0, ARC
cy_scanner_arc # a 40-degree beam
li a0, 0
ret
fload is a macro of our own: .macro names a few lines and \freg
and \label are its arguments, so fload fa0, CRUISE becomes the la and
fld beneath it. The starter uses the same one.
2. Find a robot and aim at it
When a robot is in the beam, cy_sensors_nearest writes its contact.
Point the turret at its bearing and elevation; otherwise keep searching.
.include "clunkyard.inc"
.macro fload freg, label
la t6, \label
fld \freg, 0(t6)
.endm
.section .rodata
.balign 8
CRUISE: .double 0.5
LEFT: .double 0.33
ARC: .double 40.0
STEP: .double 36.0
.section .bss
.balign 8
SCAN: .zero CY_SCAN_SIZE
TARGET: .zero CY_CONTACT_SIZE
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, TARGET
cy_sensors_nearest
bnez a0, search
la t0, TARGET
fld fa0, CY_CONTACT_BEARING(t0)
cy_gun_aim_heading
fld fa0, CY_CONTACT_ELEVATION(t0) # t0 survives the call: ecall keeps it
cy_gun_aim_pitch
fld fa0, CY_CONTACT_BEARING(t0)
cy_scanner_heading # keep the beam on it
j done
search:
fload fa0, CRUISE
cy_drive_throttle
fload fa0, LEFT
cy_drive_turn
la a0, SCAN
cy_scanner_last
la t0, SCAN
fld fa0, CY_SCAN_HEADING(t0)
fload ft0, STEP
fadd.d fa0, fa0, ft0
cy_scanner_heading
fload fa0, ARC
cy_scanner_arc
done:
li a0, 0
ret
3. Fire when the turret is on target
The turret turns at a limited rate, so fire only once it points within a
few degrees of the target, and only when the gun can fire with battery to
spare: cy_gun_aim_now writes where it points now, and
cy_gun_can_fire writes 1 when a shot of that power would leave the
battery the spare you name. This step keeps the turn in saved registers
(s1, fs0), which it saves and restores, because it calls a function.
.include "clunkyard.inc"
.macro fload freg, label
la t6, \label
fld \freg, 0(t6)
.endm
.section .rodata
.balign 8
POWER: .double 2.0
SPARE: .double 10.0
ON_TARGET: .double 3.0
.section .bss
.balign 8
NUMBER: .zero 8
WHOLE: .zero 8
TARGET: .zero CY_CONTACT_SIZE
NOW: .zero CY_DIRECTION_SIZE
.text
# angle_diff(fa0 target, fa1 current) -> fa0, from -180 to 180.
angle_diff:
la a0, NUMBER
cy_angles_angle_diff
la t0, NUMBER
fld fa0, 0(t0)
ret
.globl clunkyard_turn
clunkyard_turn:
addi sp, sp, -16
sw ra, 12(sp)
sw s1, 8(sp)
fsd fs0, 0(sp)
la a0, TARGET
cy_sensors_nearest
bnez a0, done
la s1, TARGET # s1 survives the call below
fld fs0, CY_CONTACT_BEARING(s1)
fmv.d fa0, fs0
cy_gun_aim_heading
fld fa0, CY_CONTACT_ELEVATION(s1)
cy_gun_aim_pitch
fmv.d fa0, fs0
cy_scanner_heading
la a0, NOW
cy_gun_aim_now # where the turret points now
fmv.d fa0, fs0
la t0, NOW
fld fa1, CY_DIRECTION_HEADING(t0)
call angle_diff # how far it has to go
fabs.d fa0, fa0
fload ft0, ON_TARGET
flt.d t1, fa0, ft0
beqz t1, done # still turning: hold fire
fload fa0, POWER
fload fa1, SPARE
la a0, WHOLE
cy_gun_can_fire
la t0, WHOLE
lw t1, 0(t0)
beqz t1, done # not loaded, or not enough battery
cy_gun_fire
fload fa0, POWER
cy_gun_power
done:
fld fs0, 0(sp)
lw s1, 8(sp)
lw ra, 12(sp)
addi sp, sp, 16
li a0, 0
ret
4. Earn the bearing
A contact's bearing is only as good as the beam that saw it: its error,
CY_CONTACT_BEARING_ERROR, is a fixed share of the arc. A wide beam finds a
robot; a narrow one aims at it. So once a robot is in the beam, halve the
arc each turn down to a few degrees, and fire only when the error across
the line of sight, range × error in radians, is small. Add this to step 3
after the contact is read, and fire only when t1 is 1:
# A contact 300 units out with a bearing error of 0.5 degrees: in a
# robot, these come from the contact's own fields.
li t1, 300
fcvt.d.w ft0, t1 # range
li t1, 1
fcvt.d.w ft1, t1
li t1, 2
fcvt.d.w ft2, t1
fdiv.d ft1, ft1, ft2 # bearing error, 0.5 degrees
fmul.d ft3, ft0, ft1 # range × error
li t1, 573
fcvt.d.w ft4, t1
li t1, 10
fcvt.d.w ft5, t1
fdiv.d ft4, ft4, ft5 # 57.3 degrees a radian
fdiv.d ft3, ft3, ft4 # units across the line of sight: 2.6
li t1, 12
fcvt.d.w ft5, t1
flt.d t1, ft3, ft5 # t1 = 1: precise enough to fire
The starter does this with the arc it scanned with (cy_scanner_last) and
a beam held 60 units across at the target's range.
5. The starter
The starter in a new project puts these together and adds what keeps a
robot alive: it leads a target that holds its course
(cy_gun_lead), picks a shot's power from the range
(cy_gun_power_for_flight_time), looks again where it last saw a robot
(cy_tracker_last_seen, cy_tracker_position), follows a passive cue
(cy_tracker_cue), swerves for half a second when it hears a shot
(cy_sensors_cues), drives gently when the battery is low, steps out of
the storm (cy_nav_storm) and heads back into the safe zone in sudden
death (cy_nav_zone). Its comments explain each part; read it next.
Common mistakes, and what the fault says
When the machine cannot go on, the robot stops with RISCV_FAULT and a
message that says what happened, the label and offset of the instruction,
its line in your source, and the registers that led there. The match
result, npx @clunkyard/cli match's output and the replay all show it.
A null pointer. A record address that was never set is 0, and the first 64 KiB are not mapped:
# expect: RISCV_FAULT
.include "clunkyard.inc"
.text
.globl clunkyard_turn
clunkyard_turn:
li t0, 0 # meant to be la t0, TARGET
fld fa0, CY_CONTACT_RANGE(t0)
li a0, 0
ret
8-byte load from 0x00000008, near 0: a null pointer? at clunkyard_turn+0x4 (bot.s:7: fld fa0, CY_CONTACT_RANGE(t0)); t0=0x00000000 sp=0x00100000 ra=0xfffffff0
Read it from the left: what (an 8-byte load), the address, the machine's
guess, where (clunkyard_turn+0x4 is 4 bytes, one instruction, into the
label, at line 7), and the register the address came from.
A double that is not aligned. A record after a 4-byte word, without
.balign 8, starts on a 4-byte boundary:
# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .bss
COUNT: .zero 4
TARGET: .zero CY_CONTACT_SIZE # needs .balign 8 before it
.text
.globl clunkyard_turn
clunkyard_turn:
la t0, TARGET
fld fa0, CY_CONTACT_RANGE(t0)
li a0, 0
ret
8-byte load from 0x0001100c, which is not a multiple of 8 at clunkyard_turn+0x8 (bot.s:10: fld fa0, CY_CONTACT_RANGE(t0)); t0=0x00011004 sp=0x00100000 ra=0xfffffff0
A missing ret. Without it, the processor runs on into whatever comes
next, here the end of the code:
# expect: RISCV_FAULT
.include "clunkyard.inc"
.text
.globl clunkyard_turn
clunkyard_turn:
li a0, 0
ran past the end of the code (a missing ret?) at clunkyard_turn (bot.s:6: li a0, 0); sp=0x00100000 ra=0xfffffff0
A lost return address. A function that calls another without saving
ra returns to itself, forever, until the turn's fuel runs out
(WASM_TURN_FUEL). If a turn never ends, look for a call in a function
that does not save ra.
Writing a constant. .rodata is read only:
# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .rodata
.balign 4
LIMIT: .word 10
.text
.globl clunkyard_turn
clunkyard_turn:
la t0, LIMIT
sw zero, 0(t0) # constants cannot change
li a0, 0
ret
4-byte store to 0x00011000, which is read-only (code or constants) at clunkyard_turn+0x8 (bot.s:10: sw zero, 0(t0)); t0=0x00011000 sp=0x00100000 ra=0xfffffff0
A temporary after a call. t and ft registers may change in any
function you call (though not in a cy_ call): keep values you need
afterwards in s and fs registers. This one does not fault; it just
computes with the wrong number.
Forgetting .globl. The build says so: clunkyard_turn must be global: add .globl clunkyard_turn.
A bad pointer to a call. A call that writes a record needs room for all of it in writable memory:
# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .bss
.balign 8
TARGET: .zero CY_CONTACT_SIZE
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, TARGET # the contact to lead
li a1, 0 # meant to be la a1, AIM
cy_gun_lead
li a0, 0
ret
ecall gun_lead_v1: a1 = 0x00000000 must point to 24 writable bytes, near 0: a null pointer? at clunkyard_turn+0x10 (bot.s:11: cy_gun_lead); sp=0x00100000 ra=0xfffffff0
Seeing what your robot does
ebreak is a trace point: it adds a line to the turn's debug log with
where it is and the values in a0 and fa0, and the robot carries on. Put
the value you want to see in a0 (a whole number) or fa0 (a double)
first:
.include "clunkyard.inc"
.section .bss
.balign 8
HEADING: .zero 8
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, HEADING
cy_me_heading
la t0, HEADING
fld fa0, 0(t0)
li a0, 1 # a marker: the first trace point
ebreak # logs "ebreak bot.s:13 a0=1 fa0=..."
li a0, 0
ret
The trace keeps the first four log lines of each turn. A local match saves
them in the replay, and npx @clunkyard/cli replay opens it in the viewer,
whose trace panel shows each turn's lines beside what the robot sensed.
Hosted, the same lines are in your robot's trace on the match page. An
ebreak costs about 1,700 fuel; take them out when you are done.
Fuel: what a turn costs
Every instruction costs fuel, and so does every call; a turn has a budget, the same on every computer. The costs are fixed by kind:
| Instruction | Fuel |
|---|---|
addi, add, mul and most integer instructions |
about 40 |
div, rem, loads and stores |
53 to 58 |
fadd.d, fsub.d, fsqrt.d |
85 to 105 |
fmul.d, fdiv.d, fcvt.w.d |
95 to 156 |
fmin.d, fmax.d |
about 190 |
fmadd.d and the other fused instructions |
about 460 |
a cy_ call |
about 220, its 32-fuel call fee included |
In Season 3 a RISC-V robot plays Standard at fuel tier 6: 1.79 billion fuel
a turn, about 45 million instructions. The starter spends about 22,000 a
turn. npx @clunkyard/cli match prints what yours spent.
Develop locally
Run the RISC-V player kit on Linux x86-64 with Node 24 or later, LLVM 17
or later with the RISC-V target, and ld.lld. Install clang and lld
through your Linux distribution. Set CLUNKYARD_CLANG and
CLUNKYARD_LD_LLD to their paths if they are outside PATH.
On macOS, Windows or ARM hosts, you can develop hosted in the Clunkyard workbench.
Then:
npx @clunkyard/cli new riscv my-robot
cd my-robot
npx @clunkyard/cli doctor # finds clang with riscv32, and ld.lld
npx @clunkyard/cli build
npx @clunkyard/cli match 42 2d classic
npx @clunkyard/cli replay # the replay, with your trace
The build assembles every .s file in the project, so you can split a
robot into several. Put .include "clunkyard.inc" at the top of each; the
build finds it in the SDK, so do not copy it into the project. An error
names the file, line and column, as bot.s:4:5: error: unrecognized instruction mnemonic, did you mean: add, addi?. The linked program is kept as .clunkyard/build/bot.elf:
llvm-objdump -d --no-show-raw-insn .clunkyard/build/bot.elf shows the
instructions the assembler made, pseudo-instructions expanded, and their
addresses, which is how to read clunkyard_turn+0x18 in a fault.
A robot is assembly source: the project may hold only text files, and the
build refuses .incbin.
Develop hosted
Create a RISC-V robot on the site: the workbench opens bot.s with
highlighting for the instructions, registers, labels and cy_ calls.
Build shows the assembler's errors by file, line and column, and a
practice match plays the robot against a house robot. With the MCP tools,
build_robot returns the same diagnostics, and practice_match plays a
match and matches shows its trace. npx @clunkyard/cli open ROBOT_ID
clones a hosted robot to work on locally.
Starting from C
The machine runs any RV32IMFD code that follows ilp32d, so a compiler's
assembly works too, and reading it is a good way to learn. Compile with the
same target as the build, and keep the .s:
clang --target=riscv32-unknown-elf -march=rv32imfd -mabi=ilp32d -mno-relax -O2 -S steer.c -o steer.s
Things to keep in mind:
- There is no C library. Write freestanding code; a compiler may still call
memcpyormemsetfor a large copy, which you then write in assembly. - The robot calls are macros, not functions, but a call's registers are exactly a C function's, so a two-line wrapper makes one callable from C:
.include "clunkyard.inc"
.text
# int angle_diff(double target, double current, double *out) for C
.globl angle_diff
angle_diff:
cy_angles_angle_diff
ret
.globl clunkyard_turn
clunkyard_turn:
li a0, 0
ret
- Declare it in C as
int angle_diff(double target, double current, double *out);and call it as any function. - Rust's prebuilt riscv32 targets use soft-float or single-precision conventions, not ilp32d, so their code does not link with a RISC-V robot; use C.
What this machine is
- RV32I, M, F and D, with
fflags,frmandfcsr: nothing else. There are no compressed instructions (C), atomics (A), counters, privileged modes or interrupts. An instruction outside the set faults. - Code cannot be written and data cannot run. Loads and stores must be aligned.
- Floating point is IEEE 754 as the RISC-V specification defines it, the same on every computer: all five rounding modes, the exception flags, canonical NaNs and NaN-boxed singles.
- At each entry every register is zero but
sp(0x00100000) andra(0xfffffff0, the machine's return address), andfcsris zero, so rounding is to nearest even.
The official RISC-V test suites for RV32I, M, F and D pass on it, all but two RV32I tests that need what the machine leaves out by design: code that rewrites itself, and misaligned loads and stores. docs/design/riscv-assembly.md is the machine's design.
Reference
Every entry of the robot API 2.1.0 as a RISC-V robot calls it, with the macros clunkyard.inc defines. Each line gives the canonical signature (a property is read like a field; a call takes the arguments shown; "or none" may be absent), the macro and its registers, and what it gives. &name is an address you pass: of a record the call reads, or of room for what it writes. Each call returns its status in a0: CY_OK, CY_NONE when an "or none" result is absent (the memory is left as it was), CY_SHORT when a list or text does not fit (the count or length says how much is needed), or a negative error. Text is an address and a length in bytes, not NUL-terminated; a list is an address, a capacity in records and the address of a count.
match
match.mode → mode·cy_match_mode(a0 = &out) — The match is 2D or 3D.match.ruleset → ruleset·cy_match_ruleset(a0 = &out) — The ruleset in play.match.control → control·cy_match_control(a0 = &out) — Whether the drive sets speeds (direct) or forces.match.robots → int·cy_match_robots(a0 = &out) — Robots in the match, you included; slots run 1 to this.match.is_3d → bool·cy_match_is_3d(a0 = &out) — The match is 3D.match.tick_rate → int·cy_match_tick_rate(a0 = &out) — Ticks per second.match.max_ticks → int·cy_match_max_ticks(a0 = &out) — The last tick the match can reach.match.robot_id(slot: int) → text·cy_robot_id(a0 = slot, a1 = &buf, a2 = capacity, a3 = &length) — The id the protocol gives the robot in a slot.
clock
clock.tick → int·cy_clock_tick(a0 = &out) — This tick, from 0.clock.seconds → number·cy_clock_seconds(a0 = &out) — The match time in seconds.clock.remaining_ticks → int·cy_clock_remaining_ticks(a0 = &out) — Ticks left: match.max_ticks less this tick.
arena
arena.size → vec3·cy_arena_size(a0 = &out) — The arena runs from 0 to this on each axis.arena.gravity → vec3·cy_arena_gravity(a0 = &out) — The acceleration of gravity, units/s².arena.terrain_kind → terrain_kind·cy_arena_terrain_kind(a0 = &out) — The kind of ground: none, flat or hills.arena.ground_height(x: number, y: number) → number·cy_arena_ground_height(fa0 = x, fa1 = y, a0 = &out) — The height of the ground at a point, interpolated as the arena does.
me
me.health → number·cy_me_health(a0 = &out) — Health left.me.position → vec3·cy_me_position(a0 = &out) — Your centre.me.velocity → vec3·cy_me_velocity(a0 = &out) — Your velocity, units/s.me.heading → number·cy_me_heading(a0 = &out) — Your chassis heading.me.pitch → number·cy_me_pitch(a0 = &out) — Your chassis pitch; 0 in 2D.me.roll → number·cy_me_roll(a0 = &out) — Your chassis roll; 0 in 2D and classic.me.angular_velocity → rotation·cy_me_angular_velocity(a0 = &out) — Your rotation rates, degrees/s.me.attitude → attitude·cy_me_attitude(a0 = &out) — Your chassis axes in world axes.me.grounded → bool·cy_me_grounded(a0 = &out) — You rest on the ground, under gravity.me.altitude → number·cy_me_altitude(a0 = &out) — In 3D, the height of your underside above the ground.me.wall_contact → vec3·cy_me_wall_contact(a0 = &out) — The walls that stopped or bounced your move in the tick just simulated, reported by the arena (self.wall); zero when none did. Under gravity the ground is not a wall (me.grounded), so z is at most the ceiling's -1 there.me.hurt → hurt·cy_me_hurt(a0 = &out) — The health you lost in the tick just simulated, by cause: shots that hit you, shots that burst near you, collisions with robots and the boundary (the zone, the stall ring or the storm), as the arena reports it (self.hurt); all 0 when you lost none. It never names the robot behind a loss or where it came from.me.applied → applied·cy_me_applied(a0 = &out) — What the previous tick applied to you.me.hull_mounts → bool·cy_me_hull_mounts(a0 = &out) — Your turret and scanner are mounted on the hull: gun.aim, scanner.set, gun.aim_now and scanner.last are in your chassis frame, not world axes.me.to_mount(heading: number, pitch: number) → direction·cy_me_to_mount(fa0 = heading, fa1 = pitch, a0 = &out) — A world direction in the frame your mounts take: in your chassis frame (angles.to_chassis with me.attitude) when me.hull_mounts, unchanged otherwise.me.from_mount(heading: number, pitch: number) → direction·cy_me_from_mount(fa0 = heading, fa1 = pitch, a0 = &out) — A direction in your mounts' frame, such as gun.aim_now, in world axes: angles.from_chassis with me.attitude when me.hull_mounts, unchanged otherwise.me.mount_toward(point: vec3) → direction·cy_me_mount_toward(a0 = &point, a1 = &out) — The direction from you to a point, in the frame your mounts take: me.to_mount of its bearing and elevation from you.
battery
battery.charge → number·cy_battery_charge(a0 = &out) — Charge now, before this tick's regeneration and driving.battery.capacity → number·cy_battery_capacity(a0 = &out) — Charge when full.battery.regen → number·cy_battery_regen(a0 = &out) — Charge regained each second.battery.sustainable_drive → number·cy_battery_sustainable_drive(a0 = &out) — The drive fraction regeneration pays for forever.battery.compute → compute or none·cy_battery_compute(a0 = &out) — How compute is charged, when the match charges it.battery.drive_cost(fraction: number) → number·cy_battery_drive_cost(fa0 = fraction, a0 = &out) — What holding a drive fraction costs each second, by hello.formulas.driveCost.
drive
drive.hover_lift → number·cy_drive_hover_lift(a0 = &out) — The forces.lift that cancels gravity for a level robot; 0 without gravity.drive.set(throttle: number -1..1, turn: number -1..1, pitch_turn: number -1..1)·cy_drive_throttle(fa0 = value),cy_drive_turn(fa0 = value),cy_drive_pitch_turn(fa0 = value) — Ask for direct controls this tick; the arena decides what they do in the ruleset.drive.forces(thrust: number -1..1, strafe: number -1..1, lift: number -1..1, yaw_torque: number -1..1, pitch_torque: number -1..1, roll_torque: number -1..1, brake: number 0..1)·cy_drive_thrust(fa0 = value),cy_drive_strafe(fa0 = value),cy_drive_lift(fa0 = value),cy_drive_yaw_torque(fa0 = value),cy_drive_pitch_torque(fa0 = value),cy_drive_roll_torque(fa0 = value),cy_drive_brake(fa0 = value) — Ask for forces and torques this tick, in the force rulesets.drive.get() → {throttle, turn, pitch_turn, thrust, strafe, lift, yaw_torque, pitch_torque, roll_torque, brake}·cy_drive_get_throttle(a0 = &out),cy_drive_get_turn(a0 = &out),cy_drive_get_pitch_turn(a0 = &out),cy_drive_get_thrust(a0 = &out),cy_drive_get_strafe(a0 = &out),cy_drive_get_lift(a0 = &out),cy_drive_get_yaw_torque(a0 = &out),cy_drive_get_pitch_torque(a0 = &out),cy_drive_get_roll_torque(a0 = &out),cy_drive_get_brake(a0 = &out) — What this tick's act holds for a drive field so far, as set.
gun
gun.aim_now → direction·cy_gun_aim_now(a0 = &out) — Where the turret points now, in your mounts' frame (me.from_mount gives world axes); a shot leaves along it.gun.cooldown_ticks → int·cy_gun_cooldown_ticks(a0 = &out) — Ticks until the gun can fire; 0 means it can fire this tick.gun.spread → number·cy_gun_spread(a0 = &out) — The aim spread a shot would have at your speed now.gun.max_power → number·cy_gun_max_power(a0 = &out) — The heaviest shot the battery pays for now; 0 when it cannot pay for the lightest.gun.damage_scale → number·cy_gun_damage_scale(a0 = &out) — The escalation multiplier on hit damage this tick.gun.can_fire(power: number, reserve: number) → bool·cy_gun_can_fire(fa0 = power, fa1 = reserve, a0 = &out) — The cooldown is 0 and the battery pays for a shot at this power and still holds the reserve.gun.shot_speed(power: number) → number·cy_gun_shot_speed(fa0 = power, a0 = &out) — How fast a shot at this power flies, units/s, by hello.formulas.shotSpeed.gun.shot_cost(power: number) → number·cy_gun_shot_cost(fa0 = power, a0 = &out) — What a shot at this power costs the battery, by hello.formulas.shotCost.gun.reload_ticks(power: number) → number·cy_gun_reload_ticks(fa0 = power, a0 = &out) — The reload after a shot at this power, ticks, by hello.formulas.reloadTicks.gun.shot_damage(power: number) → number·cy_gun_shot_damage(fa0 = power, a0 = &out) — The damage of a hit at this power before escalation, by hello.formulas.shotDamage.gun.power_for_speed(speed: number) → number·cy_gun_power_for_speed(fa0 = speed, a0 = &out) — The power whose shot flies at this speed, within the legal powers, by hello.formulas.powerForSpeed.gun.power_for_flight_time(range: number, seconds: number) → number·cy_gun_power_for_flight_time(fa0 = range, fa1 = seconds, a0 = &out) — The power whose shot covers this range in this time, within the legal powers.gun.lead(contact: contact, power: number) → solution or none·cy_gun_lead(a0 = &contact, fa0 = power, a1 = &out) — The intercept if the contact holds its tracked velocity (tracker.velocity, smoothed as tracker.configure sets; zero for a passive contact or an untracked robot): the aim at which a shot fired now meets it then; absent when no shot reaches it. It is a starting point, and a target that turns, reverses or weaves beats it; for your own prediction, use lead_point.gun.lead_point(position: vec3, velocity: vec3, power: number) → solution or none·cy_gun_lead_point(a0 = &position, a1 = &velocity, fa0 = power, a2 = &out) — The intercept geometry for your own prediction: the aim at which a shot fired now meets a point that starts at this position and moves at this velocity; absent when no shot reaches it.gun.aim(heading: number, pitch: number)·cy_gun_aim_heading(fa0 = value),cy_gun_aim_pitch(fa0 = value) — Ask the turret to turn toward a direction; it slews at gun.turnRate.gun.fire(fire, power: number)·cy_gun_fire,cy_gun_power(fa0 = value) — Ask to fire this tick; the arena decides whether the gun and battery allow it.gun.get() → {aim_heading, aim_pitch, fire, power}·cy_gun_get_aim_heading(a0 = &out),cy_gun_get_aim_pitch(a0 = &out),cy_gun_get_fire(a0 = &out),cy_gun_get_power(a0 = &out) — What this tick's act holds for a gun field so far, as set.
scanner
scanner.last → scan·cy_scanner_last(a0 = &out) — The scan that produced this tick's contacts: where the scanner points now, in your mounts' frame.scanner.proximity_range → number·cy_scanner_proximity_range(a0 = &out) — Robots this close are detected in any direction.scanner.reach(arc: number) → number·cy_scanner_reach(fa0 = arc, a0 = &out) — How far a scan of this arc reaches, by hello.formulas.reach.scanner.arc_for_reach(range: number) → number·cy_scanner_arc_for_reach(fa0 = range, a0 = &out) — The widest arc that still reaches this far, by hello.formulas.arcForReach.scanner.set(heading: number, arc: number, pitch: number)·cy_scanner_heading(fa0 = value),cy_scanner_arc(fa0 = value),cy_scanner_pitch(fa0 = value) — Ask the scanner to turn toward a direction for the next state; it slews at scanner.turnRate, and the arc changes at once.scanner.is_on → bool·cy_scanner_is_on(a0 = &out) — The scanner was on for the tick this state's contacts come from.scanner.power(on: number)·cy_scanner_on(fa0 = value) — Switch the scanner on (1) or off (0) for this tick; it is on unless an act switches it off. Off, it still slews and re-arcs but sees no scan or faint contacts and shows no beam.scanner.get() → {heading, arc, pitch, on}·cy_scanner_get_heading(a0 = &out),cy_scanner_get_arc(a0 = &out),cy_scanner_get_pitch(a0 = &out),cy_scanner_get_on(a0 = &out) — What this tick's act holds for a scanner field so far, as set.
sensors
sensors.contacts → list of contact·cy_sensors_contacts(a0 = &out, a1 = capacity, a2 = &count) — Every contact this tick: scan and proximity first, nearest first, then passive ones.sensors.nearest → contact or none·cy_sensors_nearest(a0 = &out) — The nearest precise contact this tick. Passive contacts are never returned.sensors.cues → list of contact·cy_sensors_cues(a0 = &out, a1 = capacity, a2 = &count) — This tick's passive contacts, most accurate (smallest bearing error) first.sensors.contact(slot: int) → contact or none·cy_sensors_contact(a0 = slot, a1 = &out) — The precise contact for a robot this tick, if it was detected.sensors.position_of(contact: contact) → vec3·cy_sensors_position_of(a0 = &contact, a1 = &out) — Where a contact places its robot: your position plus its range along its bearing and elevation.
tracker
tracker.cue → cue or none·cy_tracker_cue(a0 = &out) — The most accurate passive contact heard in the last cue_ticks (60 by default), or absent.tracker.nearest_bearing_rate → number·cy_tracker_nearest_bearing_rate(a0 = &out) — How fast the nearest contact's bearing turns, from two sightings.tracker.velocity(slot: int) → vec3·cy_tracker_velocity(a0 = slot, a1 = &out) — The robot's tracked velocity, the one gun.lead uses: the difference of its first two sightings, then smoothing × the old velocity + (1 − smoothing) × each newer difference; zero when it has no track.tracker.position(slot: int) → vec3 or none·cy_tracker_position(a0 = slot, a1 = &out) — Where the robot was last seen, if it was.tracker.history(slot: int) → list of sighting·cy_tracker_history(a0 = slot, a1 = &out, a2 = capacity, a3 = &count) — The robot's last 32 precise sightings, oldest first, as measured: positions as the sensors placed them, with the errors they reported; empty when it has none. A gap in the ticks is a gap in the sightings, and a track restart does not clear them.tracker.last_seen(slot: int) → int or none·cy_tracker_last_seen(a0 = slot, a1 = &out) — The tick the robot was last seen, if it was.tracker.configure(smoothing: number, forget_ticks: int, cue_ticks: int)·cy_tracker_configure(fa0 = smoothing, a0 = forget_ticks, a1 = cue_ticks) — Sets the Tracker's parameters, in the robot's start only; after the first state it refuses with E_PHASE.
nav
nav.zone → zone or none·cy_nav_zone(a0 = &out) — The sudden-death safe zone, once sudden death starts.nav.zone.margin(point: vec3) → number or none·cy_nav_zone_margin(a0 = &point, a1 = &out) — How far inside the zone a point is, by its shape's distance; absent while there is none.nav.zone.contains(point: vec3, margin: number) → bool or none·cy_nav_zone_contains(a0 = &point, fa0 = margin, a1 = &out) — The point is inside the zone by at least the margin; absent while there is none.nav.zone.distance_from(point: vec3) → number or none·cy_nav_zone_distance_from(a0 = &point, a1 = &out) — How far a point is from the zone's edge, 0 inside; absent while there is none.nav.storm → storm or none·cy_nav_storm(a0 = &out) — The storm, once it enters.nav.storm.margin(point: vec3) → number or none·cy_nav_storm_margin(a0 = &point, a1 = &out) — How far inside the storm a point is, by its shape's distance; absent while there is none.nav.storm.contains(point: vec3, margin: number) → bool or none·cy_nav_storm_contains(a0 = &point, fa0 = margin, a1 = &out) — The point is inside the storm by at least the margin; absent while there is none.nav.storm.distance_from(point: vec3) → number or none·cy_nav_storm_distance_from(a0 = &point, a1 = &out) — How far a point is from the storm's edge, 0 inside; absent while there is none.nav.hill → hill or none·cy_nav_hill(a0 = &out) — The hill, once it appears.nav.hill.margin(point: vec3) → number or none·cy_nav_hill_margin(a0 = &point, a1 = &out) — How far inside the hill a point is, by its shape's distance; absent while there is none.nav.hill.contains(point: vec3, margin: number) → bool or none·cy_nav_hill_contains(a0 = &point, fa0 = margin, a1 = &out) — The point is inside the hill by at least the margin; absent while there is none.nav.hill.distance_from(point: vec3) → number or none·cy_nav_hill_distance_from(a0 = &point, a1 = &out) — How far a point is from the hill's edge, 0 inside; absent while there is none.nav.wall_margin() → wall_margin·cy_nav_wall_margin(a0 = &out) — How far the edge of your robot is from the walls: from your position, your radius (hello.robot.radius) and the arena size, nothing the arena reports.nav.pickups → list of pickup·cy_nav_pickups(a0 = &out, a1 = capacity, a2 = &count) — Every pickup on the field.nav.nearest_pickup(kind: pickup_kind) → pickup or none·cy_nav_nearest_pickup(a0 = kind, a1 = &out) — The pickup of this kind nearest you by field distance, if there is one.nav.field_distance(a: vec3, b: vec3) → number·cy_nav_field_distance(a0 = &a, a1 = &b, a2 = &out) — The distance between two points as the field measures it: in the plane under gravity, in space otherwise.
score
score.me → number or none·cy_score_me(a0 = &out) — Your score; absent when the match does not score.score.best → number or none·cy_score_best(a0 = &out) — The best other robot's score; absent when the match does not score.score.armour → number or none·cy_score_armour(a0 = &out) — Your armour; absent when the match has no objectives.
drone
drone.has → bool·cy_drone_has(a0 = &out) — You have a drone program to launch (state.drone.has).drone.ready → bool·cy_drone_ready(a0 = &out) — A launch this tick would be accepted (state.drone.ready).drone.in_flight → bool·cy_drone_in_flight(a0 = &out) — Your drone is in the air (state.drone.inFlight).drone.launches_left → int·cy_drone_launches_left(a0 = &out) — The launches you have left (state.drone.launchesLeft).drone.report → report or none·cy_drone_report(a0 = &out) — Your drone's newest report, kept after the drone ends; absent before the first.drone.sightings → list of drone_sighting·cy_drone_sightings(a0 = &out, a1 = capacity, a2 = &count) — What the newest report saw, nearest first, each projected to a world point from the report's position; empty with no report.drone.launch(launch, heading: number, pitch: number, param: number -1000..1000)·cy_drone_launch,cy_drone_launch_heading(fa0 = value),cy_drone_launch_pitch(fa0 = value),cy_drone_launch_param(fa0 = value) — Ask to launch your drone this tick; the arena decides whether drone.ready allows it.drone.brief(index: int, value: number)·cy_drone_brief(a0 = index, fa0 = value) — Sets one number of this tick's launch brief, which the drone program reads as brief-1 to brief-8; unset numbers before the highest set one go as 0, but brief-1 goes as the launch param when that is set. It goes only with drone.launch, and a later call replaces the number.drone.get() → {launch, launch_heading, launch_pitch, launch_param}·cy_drone_get_launch(a0 = &out),cy_drone_get_launch_heading(a0 = &out),cy_drone_get_launch_pitch(a0 = &out),cy_drone_get_launch_param(a0 = &out) — What this tick's act holds for a drone field so far, as set.
angles
angles.normalize(degrees: number) → number·cy_angles_normalize(fa0 = degrees, a0 = &out) — An angle brought into 0 to 360, exactly: degrees % 360, plus 360 when that is negative.angles.angle_diff(target: number, current: number) → number·cy_angles_angle_diff(fa0 = target, fa1 = current, a0 = &out) — The signed turn from current to target: normalize(target - current + 540) - 180.angles.bearing_to(from: vec3, to: vec3) → number·cy_angles_bearing_to(a0 = &from, a1 = &to, a2 = &out) — The heading from one point to another.angles.elevation_to(from: vec3, to: vec3) → number·cy_angles_elevation_to(a0 = &from, a1 = &to, a2 = &out) — The elevation from one point to another.angles.direction(heading: number, pitch: number) → vec3·cy_angles_direction(fa0 = heading, fa1 = pitch, a0 = &out) — The unit vector along a heading and pitch.angles.distance(a: vec3, b: vec3) → number·cy_angles_distance(a0 = &a, a1 = &b, a2 = &out) — The straight-line distance between two points.angles.to_chassis(heading: number, pitch: number, attitude: attitude) → direction·cy_angles_to_chassis(fa0 = heading, fa1 = pitch, a0 = &attitude, a1 = &out) — A world direction as a heading and pitch in a chassis frame: with d = direction(heading, pitch), the heading of (d·forward, d·right) and the pitch atan2(d·up, √((d·forward)² + (d·right)²)).angles.from_chassis(heading: number, pitch: number, attitude: attitude) → direction·cy_angles_from_chassis(fa0 = heading, fa1 = pitch, a0 = &attitude, a1 = &out) — A chassis-frame heading h and pitch p in world axes: the direction of cos p cos h × forward + cos p sin h × right + sin p × up.angles.clamp(value: number, low: number, high: number) → number·cy_angles_clamp(fa0 = value, fa1 = low, fa2 = high, a0 = &out) — A value held within low and high.
status
status.set(text: text, value: number)·cy_status_text(a0 = &text, a1 = text_length),cy_status_value(fa0 = value) — Set the status line; leaving it out keeps the last one.status.get() → {text, value}·cy_status_get_text(a0 = &buf, a1 = capacity, a2 = &length),cy_status_get_value(a0 = &out) — What this tick's act holds for the status line so far, as set.
debug
debug.log(line: text)·cy_debug_log(a0 = &line, a1 = line_length) — Adds a line to this tick's act for your trace; the first four of a turn are kept and later ones dropped. Unlike session.log, the arena keeps it.
raw
raw.number(path: text) → number or none·cy_raw_number(a0 = &path, a1 = path_length, a2 = &out) — The number at a path, if there is one.raw.text(path: text) → text or none·cy_raw_text(a0 = &path, a1 = path_length, a2 = &buf, a3 = capacity, a4 = &length) — The string at a path, if there is one.raw.has(path: text) → bool·cy_raw_has(a0 = &path, a1 = path_length, a2 = &out) — Something is at the path.raw.flag(path: text) → bool or none·cy_raw_flag(a0 = &path, a1 = path_length, a2 = &out) — The boolean at a path, if there is one.raw.count(path: text) → int or none·cy_raw_count(a0 = &path, a1 = path_length, a2 = &out) — The length of the array at a path, if there is one.raw.line() → text·cy_raw_line(a0 = &buf, a1 = capacity, a2 = &length) — The last line the session read: the hello, or the latest state.raw.extra(json: text)·cy_raw_extra(a0 = &json, a1 = json_length) — Adds fields the API does not cover to this tick's act; a key the API writes (v, type, tick, drive, forces, aim, scan, fire, drone, status, log) is refused with E_ARGUMENT.
session
session.log(line: text)·cy_session_log(a0 = &line, a1 = line_length) — Writes a line to standard error, never to the protocol.
Records
Each record's size and each field's offset from the record's start, in bytes. A double is 8 bytes, and a whole number, flag or enum a 4-byte word; _SIZE after a field's name gives its size too.
vec3,CY_VEC3_SIZE(24 bytes): A vector in world axes.xnumber atCY_VEC3_X(0),ynumber atCY_VEC3_Y(8),znumber atCY_VEC3_Z(16).rotation,CY_ROTATION_SIZE(24 bytes): A rotation rate or torque about the robot's own axes.yawnumber atCY_ROTATION_YAW(0),pitchnumber atCY_ROTATION_PITCH(8),rollnumber atCY_ROTATION_ROLL(16).direction,CY_DIRECTION_SIZE(16 bytes): A direction as a heading and an elevation.headingnumber atCY_DIRECTION_HEADING(0),pitchnumber atCY_DIRECTION_PITCH(8).attitude,CY_ATTITUDE_SIZE(72 bytes): The chassis axes as unit vectors in world axes.forwardvec3 atCY_ATTITUDE_FORWARD(0),rightvec3 atCY_ATTITUDE_RIGHT(24),upvec3 atCY_ATTITUDE_UP(48).applied,CY_APPLIED_SIZE(56 bytes): What the previous tick applied to you, after the battery scaled the drive.forcevec3 atCY_APPLIED_FORCE(0),torquerotation atCY_APPLIED_TORQUE(24),brakenumber atCY_APPLIED_BRAKE(48).hurt,CY_HURT_SIZE(32 bytes): The health you lost in the tick just simulated, by what took it, after armour; all 0 when you lost none. Never who or where it came from.shotnumber atCY_HURT_SHOT(0),burstnumber atCY_HURT_BURST(8),collisionnumber atCY_HURT_COLLISION(16),boundarynumber atCY_HURT_BOUNDARY(24).scan,CY_SCAN_SIZE(32 bytes): The scan that produced this tick's contacts: where the scanner points now, after slewing toward your previous act's scan.headingnumber atCY_SCAN_HEADING(0),pitchnumber atCY_SCAN_PITCH(8),arcnumber atCY_SCAN_ARC(16),rangenumber atCY_SCAN_RANGE(24).contact,CY_CONTACT_SIZE(72 bytes): A robot the sensors detect this tick.slotint atCY_CONTACT_SLOT(0),sourcesource atCY_CONTACT_SOURCE(4),rangenumber atCY_CONTACT_RANGE(8),bearingnumber atCY_CONTACT_BEARING(16),elevationnumber atCY_CONTACT_ELEVATION(24),bearing_errornumber atCY_CONTACT_BEARING_ERROR(32),range_errornumber atCY_CONTACT_RANGE_ERROR(40),positionvec3 atCY_CONTACT_POSITION(48).cue,CY_CUE_SIZE(40 bytes): The most accurate passive contact the Tracker holds: where to look, not where to shoot.sourcesource atCY_CUE_SOURCE(0),tickint atCY_CUE_TICK(4),bearing_errornumber atCY_CUE_BEARING_ERROR(8),positionvec3 atCY_CUE_POSITION(16).sighting,CY_SIGHTING_SIZE(48 bytes): One sighting of a robot, as the sensors measured it: no smoothing and no derived velocity.tickint atCY_SIGHTING_TICK(0),sourcesource atCY_SIGHTING_SOURCE(4),bearing_errornumber atCY_SIGHTING_BEARING_ERROR(8),range_errornumber atCY_SIGHTING_RANGE_ERROR(16),positionvec3 atCY_SIGHTING_POSITION(24).wall_margin,CY_WALL_MARGIN_SIZE(56 bytes): How far your edge is from the walls, from your position, your radius and the arena size.xnumber atCY_WALL_MARGIN_X(0),ynumber atCY_WALL_MARGIN_Y(8),znumber atCY_WALL_MARGIN_Z(16),nearestnumber atCY_WALL_MARGIN_NEAREST(24),normalvec3 atCY_WALL_MARGIN_NORMAL(32).solution,CY_SOLUTION_SIZE(24 bytes): Where to aim for a shot fired now to meet a target, and when it meets it.headingnumber atCY_SOLUTION_HEADING(0),pitchnumber atCY_SOLUTION_PITCH(8),timenumber atCY_SOLUTION_TIME(16).zone,CY_ZONE_SIZE(40 bytes): The sudden-death safe zone.shapeshape atCY_ZONE_SHAPE(0),reservedint atCY_ZONE_RESERVED(4),radiusnumber atCY_ZONE_RADIUS(8),centervec3 atCY_ZONE_CENTER(16).storm,CY_STORM_SIZE(72 bytes): The storm now.shapeshape atCY_STORM_SHAPE(0),reservedint atCY_STORM_RESERVED(4),radiusnumber atCY_STORM_RADIUS(8),dpsnumber atCY_STORM_DPS(16),centervec3 atCY_STORM_CENTER(24),velocityvec3 atCY_STORM_VELOCITY(48).hill,CY_HILL_SIZE(80 bytes): The king-of-the-hill zone now.shapeshape atCY_HILL_SHAPE(0),holderint atCY_HILL_HOLDER(4),contestedbool atCY_HILL_CONTESTED(8),moves_tickint atCY_HILL_MOVES_TICK(12),held_ticksint atCY_HILL_HELD_TICKS(16),best_held_ticksint atCY_HILL_BEST_HELD_TICKS(20),radiusnumber atCY_HILL_RADIUS(24),centervec3 atCY_HILL_CENTER(32),nextvec3 atCY_HILL_NEXT(56).pickup,CY_PICKUP_SIZE(40 bytes): A cell on the field.kindpickup_kind atCY_PICKUP_KIND(0),expires_tickint atCY_PICKUP_EXPIRES_TICK(4),amountnumber atCY_PICKUP_AMOUNT(8),positionvec3 atCY_PICKUP_POSITION(16).report,CY_REPORT_SIZE(72 bytes): Your drone's newest report, made at tick and delivered a report period later.statereport_state atCY_REPORT_STATE(0),tickint atCY_REPORT_TICK(4),flaresint atCY_REPORT_FLARES(8),reservedint atCY_REPORT_RESERVED(12),agenumber atCY_REPORT_AGE(16),saynumber atCY_REPORT_SAY(24),headingnumber atCY_REPORT_HEADING(32),pitchnumber atCY_REPORT_PITCH(40),positionvec3 atCY_REPORT_POSITION(48).drone_sighting,CY_DRONE_SIGHTING_SIZE(72 bytes): One thing your drone saw, as its noisy scanner measured it.kindsighting_kind atCY_DRONE_SIGHTING_KIND(0),tickint atCY_DRONE_SIGHTING_TICK(4),rangenumber atCY_DRONE_SIGHTING_RANGE(8),bearingnumber atCY_DRONE_SIGHTING_BEARING(16),elevationnumber atCY_DRONE_SIGHTING_ELEVATION(24),bearing_errornumber atCY_DRONE_SIGHTING_BEARING_ERROR(32),range_errornumber atCY_DRONE_SIGHTING_RANGE_ERROR(40),positionvec3 atCY_DRONE_SIGHTING_POSITION(48).compute,CY_COMPUTE_SIZE(16 bytes): How the match charges compute against the battery.knumber atCY_COMPUTE_K(0),quantaint atCY_COMPUTE_QUANTA(8),unitcompute_unit atCY_COMPUTE_UNIT(12).
Enums
source: What detected a contact.scan(CY_SOURCE_SCAN, 1),proximity(CY_SOURCE_PROXIMITY, 2),faint(CY_SOURCE_FAINT, 3),beam(CY_SOURCE_BEAM, 4),muzzle(CY_SOURCE_MUZZLE, 5),motion(CY_SOURCE_MOTION, 6),ping(CY_SOURCE_PING, 7),launch(CY_SOURCE_LAUNCH, 8),drone(CY_SOURCE_DRONE, 9).mode: The match's dimensions.2d(CY_MODE_TWO_D, 1),3d(CY_MODE_THREE_D, 2).ruleset: The ruleset.classic(CY_RULESET_CLASSIC, 1),inertial-2d(CY_RULESET_INERTIAL_2D, 2),gravity-flat(CY_RULESET_GRAVITY_FLAT, 3),gravity-hills(CY_RULESET_GRAVITY_HILLS, 4),zero-g(CY_RULESET_ZERO_G, 5).control: What the drive controls mean: direct speeds in classic, forces elsewhere.direct(CY_CONTROL_DIRECT, 1),forces(CY_CONTROL_FORCES, 2).terrain_kind: The ground.none(CY_TERRAIN_KIND_NONE, 1),flat(CY_TERRAIN_KIND_FLAT, 2),hills(CY_TERRAIN_KIND_HILLS, 3).shape: A region's shape: circle in 2D, sphere in 3D classic and zero-g, column (unbounded in height) under gravity.circle(CY_SHAPE_CIRCLE, 1),sphere(CY_SHAPE_SPHERE, 2),column(CY_SHAPE_COLUMN, 3).pickup_kind: What a pickup gives. 0 asks for any kind.energy(CY_PICKUP_KIND_ENERGY, 1),health(CY_PICKUP_KIND_HEALTH, 2),armour(CY_PICKUP_KIND_ARMOUR, 3).compute_unit: The meter compute is charged by; 0 when turns are not metered.operations(CY_COMPUTE_UNIT_OPERATIONS, 1),fuel(CY_COMPUTE_UNIT_FUEL, 2),cpu-ms(CY_COMPUTE_UNIT_CPU_MS, 3).event: What session.next read: the hello, a state, or the end of input.hello(CY_EVENT_HELLO, 1),state(CY_EVENT_STATE, 2),end(CY_EVENT_END, 3).report_state: Why a drone reported: flying, a periodic report; lost, its last as it was destroyed; ended, its last as its life ran out.flying(CY_REPORT_STATE_FLYING, 1),lost(CY_REPORT_STATE_LOST, 2),ended(CY_REPORT_STATE_ENDED, 3).sighting_kind: What a drone saw: a robot, or another drone.robot(CY_SIGHTING_KIND_ROBOT, 1),drone(CY_SIGHTING_KIND_DRONE, 2).