Commands
Move, turn, look, shoot, punch, recharge and use items.
In JavaScript and TypeScript, this.command(…); in Python, Ruby and Lua, names are snake_case (self.turn_radar(…); in Ruby self is optional). A command holds until it’s replaced: the robot keeps moving or turning what’s left.
Main commands
| JavaScript / TypeScript | Python / Ruby / Lua | What it does |
|---|---|---|
| run() | run() | Called once, when the battle starts: the loop is yours. Inside it, scan() ends each turn. |
| scan() | scan() | Ends the turn (the commands given so far take effect) and returns the state of the next one. |
| walk(distance) | walk(distance) | Moves and waits to get there (gives up after 15 turns without progress). While it waits, the robot does not react. |
| rotate(angle) | rotate(angle) | Turns the body and waits until it is done. |
| walkTo(x, z) | walk_to(x, z) | go_to that waits: follows the route around obstacles and returns {ok, reason} on arrival or when it gives up (outside_map, obstacle, no_path, cancelled, stuck). |
| wait(turns) | wait(turns) | Lets turns pass (1 without an argument). |
| goTo(x, z) | go_to(x, z) | Plans and follows a route. Returns {ok:true} or {ok:false, reason: outside_map/obstacle/no_path}. Follow the arrival in state.navigation. move/turn/recharge cancel the route. |
| recharge() | recharge() | Stops and waits 1 s before recharging until full. Repeating doesn't restart it; moving, turning, shooting or punching cancel it. The radar is paused. |
| special() | special() | An area explosion around the robot. It can only be used once, when health reaches 30% or less; check state.me.specialReady. |
| useItem(id) | use_item(id) | Uses the ability of an item the robot carries (nitro, repair_kit, bubble, overcharge, mine, emp, cloak, dash). One per tick; the result arrives in events (item_used or item_failed). |
| canUse(id) | can_use(id) | True if use_item(id) would work now: has the item, no cooldown, uses and energy left. In Ruby also can_use?. |
| move(distance) | move(distance) | Moves `distance` units (negative = reverse). |
| turn(angle) | turn(angle) | Turns the body `angle` radians. The cannon is on the arm: aiming means turning the body (turn(target.bearing)). |
| strafe(distance) | strafe(distance) | Strafes `distance` units without turning (positive = right). Only with legs or spider legs; wheels and treads ignore it. |
| turnRadar(angle) | turn_radar(angle) | Turns the head's sensors `angle` radians. |
| fire(power) | fire(power) | Fires ahead of the body with power between 0.1 and 3 (minigun: up to 1.5): costs 3 × power in energy and gives it back on a hit; stronger deals more damage and heats the cannon more. The weapon changes all of this. |
| punch() | punch() | Punches whoever is right in front of you (up to ~5 away, in a ~40° cone): 7 damage (5.5 off treads), pushes the other robot and costs 4 energy. Waits 1.5 s between punches (me.punchCooldown). |
Special attack
The special attack deals area damage around the robot and can be used only once, when health drops to 30% or less. Check state.me.specialReady before calling this.special() (Python/Ruby: self.special()).
Shortcuts and helpers
| JavaScript / TypeScript | Python / Ruby / Lua | What it does |
|---|---|---|
| follow(radius) | follow(radius) | Helper: orbits the owner (default radius 4). |
| fireAt(x, z) | fire_at(x, z) | Helper: shoots at the point, if within range and the weapon is ready. |
| followOwner(state) | follow_owner(state) | Drone: the follow mode (orbits the owner and shoots the nearest enemy). Rewrite it in a subclass to change it. |
| attackTarget(state) | attack_target(state) | Drone: the attack mode (chases the target and shoots). |
| guardOwner(state) | guard_owner(state) | Drone: the guard mode (protects the owner with a shield). |
| repairOwner(state) | repair_owner(state) | Drone: the repair mode (gives the owner health back). |
| aim(state, enemy) | aim(state, enemy) | Drone: shoots where the enemy will be when the shot arrives. |
| shield() | shield() | Helper: shield this tick (takes 85% of the damage, doesn't shoot). |
| repair() | repair() | Helper: repairs the owner this tick, if close (doesn't shoot). |
| ahead(distance) | ahead(distance) | Moves forward. |
| back(distance) | back(distance) | Moves in reverse. |
| turnLeft(angle) | turn_left(angle) | Turns the body to the left. |
| turnRight(angle) | turn_right(angle) | Turns the body to the right. |
| strafeLeft(distance) | strafe_left(distance) | Strafes to the left. |
| strafeRight(distance) | strafe_right(distance) | Strafes to the right. |
| turnRadarLeft(angle) | turn_radar_left(angle) | Turns the head's sensors to the left. |
| turnRadarRight(angle) | turn_radar_right(angle) | Turns the head's sensors to the right. |
| log(texto) | log(texto) | Writes to the battle log. |
| normalizeAngle(angle) | normalize_angle(angle) | Normalizes an angle to the range (-π, π]. |