Tanks Documentation

Introduction

You are the proud new operator of a M-375 Pflanzarr Tank. Your tank is equipped with a powerful laser cannon, independently rotating turret section, up to 10 enemy detection sensors, and a standard issue NATO hull. Unfortunately, it lacks seats, and thus must rely own its own wits and your skills at designing those wits to survive.

Programming Your Tank

Your tanks are programmed using the Super Useful Command and Kontrol language, the very best in laser tank AI languages. It includes amazing features such as comments (Started by a #, ended at EOL), logic, versatility, and semi-colons (all lines must end in one). As with all new military systems it utilizes only integers; we must never rest in our diligence against the communist floating point conspiracy. Whitespace is provided by trusted contractors, and should never interfere with operations.

Your program should be separated into Setup and AI commands. The definitions section lets you designated the behaviors of its sensors and memory. Each setup command must begin with a '>'. Placing setup commands after the first AI command is a violation of protocol. Here are some examples of correct setup commands:

>addsensor(80, 90, 33);
>addsensor(50, 0, 10, 1);
>addtimer(3);

The AI section will act as the brain of your tank. Each AI line is separated into a group of conditions functions and a group of action functions. If all the conditions are satisfactory (true), all of the actions are given as orders. Conditions are separated by ampersands, actions separated by periods. Here are some examples of AI commands:

sense(1) & sense(2) & fireready() : fire();
sense(0,0)&sin(5): move(40, 30) . turretcw(50);
sense(4) & random(4,5) :
led(1).settoggle(0,1);

Your tank will execute its program each turn(frame), and attempt to the best of its abilities to carry out its orders (or die trying). Like any military mind, your tank may receive a plethora of often conflicting orders and information. This a SMART TANK, however. It knows that the proper thing to do with each subsystem is to have that subsystem follow only the last order given each turn.

#Setup commands define your tank when your program
#compiles
>addsensor(50, 0, 5, 1); # 0-Fire Sensor
>addsensor(30, 0, 180); # 1-Anti-collision sensor

# These commands execute each frame.
# Blank condition sections are true.
         : move(90, 100).
           turretset(0);
sense(0) : fire();
sense(1) : move(-100, 100)

Setup Actions:

These functions can be used to setup your tank. Abuse of these functions has, in the past, resulted in mine sweeping duty. With a broom.

addsensor(range, angle, width, [turretAttached])

Add a new sensor to the tank.

Sensors are an arc (pie slice) centered on the tank that detect other tanks within their sweep.
A sensor is 'on' if another tank is within this arc.

Sensors are numbered, starting at 0, in the order they are added.

range - The range of the sensor, as a percent of the tanks max range.
angle - The angle of the center of the sensor, in degrees.
width - The width of the sensor, in degrees.
turretAttached - Normally, the angle is relative to the front of the tank.
When this is set, the angle is relative to the current turret direction.

addtimer(timeout)

Add a new timer (they're numbered in the order added, starting from 0), with the given timeout.

The timeout is in number of turns.
The timer is created in inactive mode.
You'll need to do a starttimer() action to reset and start the timer.
When the timer expires, the timer() condition will begin to return True.

addtoggle([state])

Add a toggle to the tank.

The state of the toggle defaults to 0 (False).
These essentially act as a single bit of memory.
Use the toggle() condition to check its state and the settoggle, cleartoggle, and toggle actions to change the state.
Toggles are named numerically, starting at 0.

Conditions:

These functions are used to check the state of reality. If reality stops being real, refer to chapter 5 in your girl scout handbook.

cos(T)

A cos wave with period T (in turns).

Returns True when the wave is positive.
A wave of period 1 is always True.
Period 2 is True every other turn, etc.

firenotready()

True when the tank can not fire.

fireready()

True when the tank can fire.

random(n,m)

Generate a random number.

Takes two arguments, n and m.
Generates a random number between 1 and m (inclusive) each time it's checked.
If the random number is less than or equal to n, then the condition returns True.
Returns False otherwise.

sense(#, [invert])

True when a sensor is activated.

Takes a Sensor number as an argument.
Returns True if the given sensor is currently activated, False otherwise.
If the option argument invert is set to true then logic is inverted, and then sensor returns True when it is NOT activated, and False when it is.
Invert is false by default.

sin(T)

A sin wave of period T (in turns).

Returns True when the wave is positive.
A wave with period 1 or 2 is always False (it's 0 each turn), only at periods of 3 or more does this become useful.

timer(#, [invert])

Checks the state of timer # 'key'.

Returns True if time has run out.
If invert is given (and true), then True is returned if the timer has yet to expire.

toggle(#)

Returns True if the given toggle is set, False otherwise.

Actions:

These actions are not for cowards. Remember, if actions contradict, your tank will simply do the last thing it was told in a turn. If ordered to hop on a plane to hell it will gladly do so. If order to make tea shortly afterwards, it will serve it politely and with cookies instead.

cleartimer(#)

Clear the given timer such that it is no longer active (inactive timers are always False).

fire()

Attempt to fire the tanks laser cannon.

Its range is 50% of your sensor range.

led(state)

Set the tank's LED to state (true is on, false is off).

The led is a light that appears behind the tanks turret.
It remains on for a single turn.

move(left tread speed, right tread speed)

Set the speeds for the tanks right and left treads.

The speeds should be a number (percent power) between -100 and 100.

settoggle(key, state)

Set toggle 'key' to 'state'.

starttimer(#)

Start (and reset) the given timer, but only if it is inactive.

toggle(key)

Toggle the value of toggle 'key'.

turretccw([percent speed])

Rotate the turret counter clockwise as a percentage of the max speed.

turretcw([percent speed])

Rotate the turret clockwise at a rate preportional to speed.

turretset([angle])

Set the turret to the given angle, in degrees, relative to the front of the tank.

Angles increase counterclockwise.
The angle can be left out; in that case, this locks the turret to its current position.