Code Tank Reference

1. Starting a tank

Every tank file has the same four parts: connect, set up, write a brain, run.

import codetank

tank = codetank.connect()
tank.set_name("Rolling Thunder")
tank.set_stats(armor=25, firepower=25, sensors=25, ballistics=25)


def brain(tank):
    tank.set_tracks(60, 60)
    tank.set_turret_power(50)
    if tank.can_fire():
        tank.fire()


tank.run(brain)

That file runs. It drives in a circle and fires at nothing, so it is a starting point and not much else.

What the brain function is

Your brain is a function that takes one argument, the tank. The game calls it about 20 times a second, and it has to finish and return each time. One pass of the brain is one decision.

To remember something from one tick to the next, keep it in a variable outside the brain and say global before you change it.

ticks = 0


def brain(tank):
    global ticks
    ticks += 1
    if ticks % 20 == 0:
        print("one second of battle")

print() goes to the output panel under the arena. If your brain raises an error, the game prints it once with the line number instead of spamming you twenty times a second.

2. The stat budget

You have 100 points for four stats. Every point you spend somewhere is a point you did not spend somewhere else.

tank.set_stats(armor=10, firepower=40, sensors=25, ballistics=25)

• The four numbers must add up to exactly 100.
• Each one has to be at least 1 and at most 97.
• Break either rule and set_stats raises a ValueError, so your tank never starts.
• Call it near the top of the file, before tank.run(brain).

What the points buy

The column headings are how many points you put in that stat.

Distances are in arena units. A tank is 30 units across, and the large arena is 600 by 450. Angles and arcs are in degrees.

Reading your own build

You do not have to copy your numbers into your code by hand. The tank knows them.

def brain(tank):
    print("I see", tank.scan_range, "and shoot", tank.bullet_range)

3. Driving

A tank has two tracks and no steering wheel. You set the power of each one and the tank goes where that takes it.

tank.set_tracks(left, right)   # each one from -100 to 100

This is not a move command that finishes. It is a setting. The tracks stay where you put them until you set them again, so you do not have to call it every tick.

Anything above 100 or below -100 is clamped, so set_tracks(250, 250) is just full ahead. More power on the right track than on the left makes tank.angle grow, which is clockwise on the screen. If your tank turns the wrong way, swap the two numbers.

Walls

The arena is a box. You cannot drive through the edge, and grinding along it wastes the whole fight.

def brain(tank):
    if tank.distance_to_wall() < 40:
        tank.set_tracks(-60, 60)      # turn away before you arrive
    else:
        tank.set_tracks(80, 80)

It already knows how big the arena is, so the same code works in the small, medium and large arenas. The ladder is always the large one, 600 by 450, and there is no Arena setting while you are climbing it: every rung is built on a distance, and what your build can see and reach does not shrink with the room. Survival and Versus are where the smaller arenas live.

4. The turret

The gun turns on its own. It does not care which way the body is pointing, and the body does not care which way the gun is pointing.

tank.set_turret_power(power)   # -100 to 100

• Positive turns the gun clockwise, negative turns it counter clockwise, and 0 stops it.
• Like the tracks, this is a setting. The gun keeps turning until you change it.
• How fast it turns at full power is tank.gun_turn_speed, which armor slows down.
• tank.gun_angle is where the gun is now pointing, from 0 to 360 degrees. 0 is to the right of the arena.

def brain(tank):
    tank.set_tracks(0, 0)             # the body can sit still
    tank.set_turret_power(60)         # while the gun sweeps round
    print("gun is on", round(tank.gun_angle))

5. Scanning

You can only see inside a cone in front of the gun. Nothing outside that cone exists as far as your code is concerned.

The cone is tank.scan_range long and tank.scan_arc degrees wide in total, so half of that arc sits each side of the gun. Dead tanks are not returned. Scanning costs nothing and takes no time, so you can do it every tick.

def brain(tank):
    tank.set_turret_power(60)

    enemy = tank.scan()
    if enemy:
        print(enemy.name, "is", round(enemy.distance), "units away")
        print("off my gun by", round(enemy.direction), "degrees")

What an Enemy carries

An Enemy is a snapshot taken when you called scan(). It does not update itself. Call scan() again next tick for fresh numbers.

More than one enemy

scan_all() hands you a list, and a list is something you can loop over or pick from.

def brain(tank):
    for enemy in tank.scan_all():
        print(enemy.name, round(enemy.distance), enemy.health)

6. Firing

The shot leaves along the gun, travels at tank.bullet_speed, and disappears after tank.bullet_range units whether it hit anything or not.

def brain(tank):
    enemy = tank.scan()
    if enemy and tank.is_aimed_at(enemy) and tank.can_fire():
        tank.fire()

Calling fire() while reloading is not an error. Nothing happens and you get None back. Firing does not cost fuel, and you can fire with the tracks stopped.

Following a bullet

You can watch a shot you fired. You will not need this to shoot well, but it is there.

def brain(tank):
    shot = tank.fire()
    if shot:
        print("shot", shot.id, "is away")

7. What your tank knows about itself

All of these are properties, not calls, so there are no parentheses after them. Reading one is instant.

def brain(tank):
    print(tank.health, "hp,", round(tank.fuel_percentage), "percent fuel")
    print(tank.enemies_remaining, "still out there")

8. Fuel

Driving uses fuel. When it runs out the tracks stop for the rest of the round, and that is that.

Things worth knowing:

• Fuel pays for distance covered, not for time. Sitting still is free.
• Turning the gun is free, firing is free, and spinning the body in place costs almost nothing because you do not go anywhere.
• A heavy tank carries more fuel and burns it faster, so every build can drive about the same total distance. No build is secretly thriftier.
• Out of fuel is not out of the fight: the gun still turns and still shoots.
• Fuel is refilled for a new round, and in Survival it is refilled when a wave is cleared.

def brain(tank):
    if not tank.has_fuel:
        tank.set_turret_power(50)     # nothing else to do but look
        return

    tank.set_tracks(70, 70)

9. When something happens

Some things do not wait for your brain to ask. You can hand the game a function and it will call it when that thing happens.

def on_hit(event):
    print("ow,", event.damage, "damage from", round(event.angle))


tank.on_hit_by_bullet = on_hit

Write the function, then set it on the tank with no parentheses. You are handing over the function itself, not calling it. All of this goes before tank.run(brain). Your callback is given one argument, an Event.

Every hook there is

What an Event carries

Every event has all of these fields. The ones that do not apply are 0 or an empty string, so only read the ones the table above lists for that hook.

A new round puts positions, health and fuel back as they were. It does not touch your variables, so anything you were counting keeps its value into the next round. on_new_round is where you put it back yourself if you want that.

hits_taken = 0


def on_hit(event):
    global hits_taken
    hits_taken += 1


tank.on_hit_by_bullet = on_hit


def brain(tank):
    if hits_taken > 3:
        print("this is going badly")

10. Other battle types

Everything above works in every battle type. These are the extras. Reading one of them in a mode it does not belong to is not an error. You get a harmless default instead, such as 0, an empty string, or -1 where an id would go.

Team Deathmatch

The arena is split into a blue side and a red side.

def brain(tank):
    for other in tank.scan_all():
        if other.is_teammate():
            continue
        print("enemy:", other.name, round(other.distance))

Survival

Waves of tanks come at you, each wave harder than the last, and you have lives instead of one life.

The three Survival hooks are on_wave_started, on_wave_complete and on_respawned. See section 9.

def brain(tank):
    if tank.between_waves:
        tank.set_tracks(0, 0)         # nothing to shoot at yet
        return

    print("wave", tank.wave, "with", tank.wave_enemies_remaining, "left")

King of the Hill

There is a circle in the middle of the arena and the match is won by standing in it. Being destroyed is a few seconds out, not the end, so the scoreboard decides it. The hill is always centered on (0, 0), and these five properties tell you about it.

Your own id is not something you can read, so compare tank.hill_owner against an enemy.id from a scan when you want to know whether the tank holding it is one you can see. tank.in_hill is the quicker question about yourself.

def brain(tank):
    if tank.in_hill:
        print("on the hill,", round(tank.hill_score), "of", tank.points_to_win)
    elif tank.hill_owner == -1:
        print("the hill is empty")
    else:
        print("someone else is holding the hill")

Two callbacks go with them, tank.on_hill_captured and tank.on_hill_lost. Both are called with an Event that has nothing on it worth reading: the fact that it happened is the whole message. on_respawned fires here too when you come back, carrying event.x and event.y.

You can still work out where the middle is yourself, which is useful for steering towards it rather than just asking whether you have arrived.

import math


def brain(tank):
    from_middle = math.hypot(tank.x, tank.y)
    print("I am", round(from_middle), "from the middle")

11. How a match is won

Destroying everybody is one way for a match to end. It is not the only one, and a match you won without firing a shot still counts.

Last one standing

In an ordinary battle the match ends the moment only one tank is still alive, and that tank wins. If the last two are destroyed at the same instant, nobody is left and it is a draw.

The clock

A battle is given 180 seconds, which is three minutes of arena time. If the clock runs out with more than one tank alive, the match is decided on health, and this is the part worth reading twice:

• What is compared is health as a fraction of what you started with, not health in hit points.
• The highest fraction wins.
• If the two best are exactly level, the match is a draw.

Fractions rather than hit points, because builds do not start level. A heavy tank with 244 health sitting on 100 has 41 percent of itself left. A light tank with 52 health sitting on 30 has 58 percent, so the light one takes the match even though it has less than a third of the other one's hit points.

Your own fraction is two properties you already have.

def brain(tank):
    share = tank.health / tank.max_health
    print("I have", round(share * 100), "percent of myself left")

A round somebody ends

There is an End round button in the header while a battle is on. It stops the round where it is and decides it on exactly the rules above: the hill in King of the Hill, the health of each side in Team Deathmatch, and otherwise the fraction of health each tank has left. Level is still a draw.

It is there for a round that is clearly going nowhere with minutes of clock still to run. Nothing is skipped: the round is decided, everybody is told, and a best of three carries on to the next round. It is not the same as Reset, which throws the battle away and settles nothing. A round decided this way does not pass a ladder rung, for the same reason the clock does not: nothing was destroyed.

A draw by stalemate

If 120 seconds go by with no hit landing on anybody, and two or more tanks are still alive, the match is declared a draw there and then. Two tanks that cannot find each other, or cannot reach each other, do not get to sit there for ever.

The downloadable game handles this differently: it picks everybody up and puts them down somewhere else to get the fight going again, which is what tank.on_stalemate_respawn is for. The browser does not move anybody. It draws.

King of the Hill has no stalemate clock, because standing still on the hill and refusing to be drawn off it is the game rather than a problem.

Team Deathmatch

A side is finished when nobody on it is standing, and the other side wins. The win is credited to everyone on the winning side, including any of them that were destroyed getting there. It was a team that won it.

On the clock it goes to the side in better shape: every living tank's health is turned into a fraction of its own maximum, the fractions are added up for each side, and the bigger total wins. Adding fractions rather than hit points means a side of two is not beaten simply by a side of three being larger. Level totals are a draw.

King of the Hill

The match goes to the first tank to hold the hill for tank.points_to_win seconds. Holding it means being the only tank in the circle: with two of you inside, the clock stops for both and tank.hill_owner is -1.

Being destroyed here is a five second wait and then you are back, with full health and full fuel, placed clear of the hill. Nobody is ever knocked out of the match, so there is no last one standing to find and no clock to run out. It ends on the scoreboard.

Survival

Survival is not won, it is survived. Waves keep coming, each one harder, and there is no match clock at all. You start with 3 lives; the run ends when you are destroyed with none left, and the answer is how far you got: tank.wave and tank.score, which is ten points a kill multiplied by the wave it happened on.

Passing a rung on the ladder

Beating a ladder tank once does not pass it. It takes 2 wins against the same rung, and the page shows you where you are, as 1 of 2 wins. One win can turn on nothing more than where the two tanks happened to be put at the start, and that is not evidence that your tank is better.

Three more things about the counting:

• A rung is passed by destroying it. The clock running out with you ahead on health is a win, and the page says so, but it passes no rung. A tank that only has to be ahead after three minutes can be beaten by the code the editor starts you with, which is why the ladder asks for the kill.
• A draw counts for nobody. It is not a loss, but it does not move you up either.
• Fuel on and fuel off are two separate ladders. Wins with the fuel switched off are kept apart and never added to the others, because a tank that can drive for ever is solving a different problem. Beating a rung one way leaves it still to beat the other way.

12. Common mistakes

1. Looping inside the brain. A while True: in your brain hangs your tank and it is thrown out of the match. The brain must return. The game is the loop.
2. Sleeping inside the brain. time.sleep() does not slow the game down, it only wastes your tick. Count ticks in a variable instead: 20 of them is a second.
3. Turning the body to look around. Scanning follows the gun. If you want to see somewhere else, use set_turret_power.
4. Forgetting that scan() can be None. enemy.distance on an empty scan is an AttributeError. Write if enemy: first, every time.
5. Treating enemy.direction as a bearing. It is an offset from your gun. Zero does not mean north, it means you are on target.
6. Points that do not add up to 100. set_stats raises a ValueError and your tank never reaches the arena. Add the four numbers up yourself before you run it.
7. Calling set_stats or set_name after run. Nothing after tank.run(brain) happens until the match is over. Setup goes above it, and run is the last line.
8. Changing a variable outside the brain without global. Python quietly makes a new local instead, so your tank forgets everything between ticks.
9. Keeping an Enemy from an older tick. Its distance and direction were true when you scanned and are not true now. Scan again.
10. Firing without asking can_fire(). Shots while the gun is reloading do nothing at all.
11. Shooting at something further away than tank.bullet_range. The bullet expires in mid air. Seeing a tank and being able to reach it are two different questions.
12. Typing in 600 and 450. That is the large arena. Read tank.arena_width and tank.arena_height, or let distance_to_wall() do it for you.