About this Document

Whilst I do not intend to change any of these numbers on a frequent basis, it would be wise to code your program to use those symbols where possible so that an unforseen need to change the rules won't totally destroy your careful work!

The Rules:

It's a contest of programming skill and algorithmic subtlety.

The Software You Must Write:

The software you write must consist of a single source file that compiles into either a '.DLL' or a '.so' library. These libraries are dynamically linked into the 'City Simulator' that runs the game.

Your library should export just one symbol - a function called 'runZilla'. For C++ programmers: This function must be declared 'extern "C"' so that it can be called with C calling conventions.

The runZilla() function takes a pointer to a simple structure as it's input and another pointer indicates where it should write its results:

  In C:

    void runZilla ( struct ZillaInputs  *input,
                    struct ZillaOutputs *output ) ;

  In C++:

    extern "C" void runZilla ( ZillaInputs  *input,
                               ZillaOutputs *output ) ;

Representation of Angles, Headings, Times and Distances

ZillaInputs

ZillaOutputs

The public Zilla structures look like this:

struct EnemyZilla
{
  int   visible ;    /* Remainder of structure is invalid if this is FALSE */
  float heading ;    /* Degrees, Zero is NORTH, positive anticlockwise */
  float energyRemaining  ; /* Expressed as a percentage of maximum en
ergy */
  float healthRemaining  ; /* Expressed as a percentage of full healt
h */
  enum ZillaAction action ;  /* What is he doing? */
} ;


struct ZillaInputs
{
  float energyRemaining  ; /* Expressed as a percentage of maximum energy */
  float healthRemaining  ; /* Expressed as a percentage of full health */
  int   collectable      ; /* Which collectable are you holding right now?
                              One of:
                                MAP_COLLECT_ENERGY
                                MAP_COLLECT_HEALTH
                                MAP_COLLECT_TIMESLOW
                                MAP_COLLECT_SPEED
                              or -1 if you have no collectable on board */
  int   usingSpeedup     ; /* 1 if you are using a Speed collectible, 0 otherwise */
  int   usingTimeSlow    ; /* 1 if you are using a Time-Slow collectible, 0 otherwise */
  float elapsedTime      ; /* Seconds elapsed since start of round */
  float currentHeading   ; /* Degrees: Zero is NORTH, positive anticlockwise */
                           /* Angle is always between -180 and 180. */
  int numRobotsRemaining ; /* The number of other bots still alive */

  unsigned char map [ MAP_SIZE ] [ MAP_SIZE ] ;  /* See documentation */
  struct EnemyZilla enemy [ NUM_ENEMY ]       ;  /* See documentation */
} ;


enum ZillaAction
{
  MOVE ,
  CHOMP,
  SHOOT,
  RAGE,
  USE_COLLECTABLE
} ;


struct ZillaOutputs
{
  float turnRate  ;  /* In degrees per second, positive is anticlockwise */
  float moveSpeed ;  /* In meters per second - always positive */

  enum ZillaAction action ;  /* Only one action per iteration! */
  char name [ MAX_NAME_LENGTH ] ;
  char speech [ MAX_LINES_OF_SPEECH ] [ MAX_SPEECH_LENGTH ] ;
} ;

The 'map' and 'enemy' arrays in the ZillaInputs structure are described below.

HEALTH AND ENERGY:

• If your health is depleted by being hit by the other robots or by touching the force field around the city. You are able to slowly push your way through buildings without taking damage. If your health hits zero, you die and are out of the game.

• Your energy is consumed by shooting - and drained completely if you touch the force field or do a 'rage' attack. Energy is replenished slowly over time whenever you if you do MOVE actions (even if you set the speed to zero in order to stand still). If your energy gets too low, you won't be able to shoot any more. You need a 100% energy burst to do a 'rage' attack. The robot is not damaged by running out of energy - it just limits your options until the energy gradually recovers.

THE MAP:

The map contains data to show where buildings, force-fields, rubble and enemy BotZilla's are. The value in each grid cell is either a number in the range 0..(NUM_ENEMY-1) or a #define'd token above that range.

• Zillas are approximately circular and are ZILLA_SIZE in diameter so you should expect to see many map grids filled with numbers in the range 0 to (NUM_ENEMY-1) when another machine is within visibility range. However, the resolution of the map is low so that the bots may not look smoothly circular.

• MAP_SELF: Since the map is always centered around your bot, it'll show a number of 'MAP_SELF' tokens clustered around the middle of the map.

• MAP_BUILDING: The City is organised in perfectly regular 'blocks' with North/South and East/West roads between them. The blocks are all BLOCK_SIZE across and the roads are ROAD_SIZE wide. Some blocks may contain empty space, others will contain buildings - or (increasingly as the game progresses) smoking rubble!

• MAP_RUBBLE: When a building is destroyed, it turns instantly to rubble. On-screen, this looks like a gradual process - but the bot's see an instantaneous change in the entries of the map changing from MAP_BUILDING to MAP_RUBBLE. If there is a robot standing amongst the rubble, the map will show the number of that robot (or MAP_SELF if it's you).

• MAP_FORCE_FIELD: The humans in the area have managed to constrain the area of combat using force fields. If a BotZilla touches a force field, it's energy will be instantly drained to zero and it'll take damage for every second it remains in contact with it.

• MAP_COLLECT_ENERGY/MAP_COLLECT_HEALTH/MAP_COLLECT_TIMESLOW/MAP_COLLECT_SPEED: One of the available 'collectables' is at this location. Collectables are valuable and powerful objects - your robot only has to come in contact with it to pick it up. Collectables do not impeded motion or stop weapons effects.

• MAP_EMPTY: Areas of the map (roads) containing nothing else.

When a zilla just drives mindlessly into another bot or into a building, it'll gradually do damage to it - but not as fast as a series of 'CHOMP' attacks.

THE FORCEFIELD

After some unspecified time (typically a couple of minutes), the force field will start to shrink. This forces the game to end within a finite amount of time no matter how stupidly (or effectively) the bots are being driven. The forcefield will start to shrink when the 'elapsedTime' field reaches FORCEFIELD_SHRINK_START_TIME and will have shrunk to zero size (killing all 'bots in the process) by FORCEFIELD_SHRINK_FINISH_TIME.

If you touch the forcefield while it's shinking, it'll be very hard to avoid being completely embedded in it which is certain death for a bot. It's essential to give the forcefield a wide berth once it's shrinking!

THE ENEMY ARRAY:

Each structure contain a boolean called 'visible' which tells you whether you can see this enemy on the map, also the current 'heading' that the robot is pointing at (0==NORTH, positive anticlockwise, all numbers in the range -180 to 180). There are also 'energyRemaining' and 'healthRemaining' fields so you can see how the other robot is doing.

ATTACKING:

If a Zilla does a 'CHOMP' action while standing next to a building - or attempts to walk through the building, it'll damage it. Shooting or doing a rage attack will also damage buildings that happen to get in the way. The amount of this damage is listed in the header file. Whilst a chomp attack consumes no energy, your bot doesn't recover energy during the time the chomp takes - so it's not without cost.

Shooting drains the Zilla's energy reserves. Each shoot action reduces your reserves by an amount defined in zilla_internals.h - and does damage to any Zilla standing directly in front of you, providing it is within range and with no buildings or other Zilla's are in the way.

A 'Rage Attack' is a blast of energy that radiates out in all directions, and consumes 100% of your energy reserves. The blast damages any Zilla within range - regardless of whether they are hiding behind something - and it instantly flattens any buildings that are within the blast range.

If you do an attack inappropriately (eg if you don't have enough energy - or if you weren't close enough), you don't pay the energy penalty - but you do get held up for the time an attack would actually take.

MOVING:

COLLECTABLES:

Each robot can only hold one collectable at a time. There is a special action called 'USE_COLLECTABLE' which activates (and removes) whatever collectable you are currently holding. You can then pick up another one - even while the effects of the first are still working.

On-screen, the four collectable types are marked with a spinning icon with a letter on it:

• E - Energy - Your energy level is instantly restored to 100%.
• H - Health - Using this collectable gives you 30% more health - but it cannot increase health over 100% or resurrect a dead robot.
• S - Speed - Temporarily increases the maximum speed your robot can move by a factor of SPEEDUP_RATE. The effect lasts for SPEEDUP_DURATION.
• T - Time Slow - Temporarily slows the progress of time for everyone and everything except your robot. From your perspective, buildings collapse more slowly, other bots move slowly and attack less frequently. It's better than 'Speed' because you can attack more rapidly than everyone else and their energy replenishes more slowly than yours. Time slows by a factor of 'TIME_SLOW_RATE' and the effect lasts (from your perspective) for 'TIME_SLOW_DURATION'.

NOTE 2: BEWARE: If you slow time, the damage you take from a forcefield accumulates at a normal rate for you - whilst everyone else is taking forcefield damage more slowly.

You can tell what collectable you are carrying from the ZillaInputs structure - also whether you are currently slowing everyone elses time down and/or are under the influence of a Speed collectable. Robots who are being slowed down can't tell (except by the fact that one of the other robots is moving so much faster!)

SPEECH BALLOONS:

eg:

   strcpy ( input.speech[0], "Hello" ) ;
   strcpy ( input.speech[1], "World" ) ;

INITIALISATION:

For One-On-One competitions:

For All-Against-All competitions:

The Fine Print:

1. The program must be delivered in a SINGLE source file called 'robot.c' (or 'robot.cxx' if it's in C++). No header files, data files or other libraries are allowed.

2. All global symbols used within the program must be declared 'static' except for ONE external function that must be named: runZilla.

3. The only header file you are allowed to include is 'zilla_interface.h'

4. The only library functions you are allowed to call are defined for you in zilla_interface.h - they are:
   • From the C standard library: rand, malloc, free (new and delete are allowed in C++)
   • From the C standard math library: sin, cos, tan, atan, atan2, sqrt, pow
   • From the C standard string library: memcpy, memset, strcpy, strlen, strcat
   Notice that no standard I/O or stream I/O functions are included.

5. The runZilla() function takes a pointer to a simple structure as it's input and another pointer indicates where it should write its results:

     In C:
   
       void runZilla ( struct ZillaInputs  *input,
                       struct ZillaOutputs *output ) ;
   
     In C++:
   
       extern "C" void runZilla ( ZillaInputs  *input,
                                  ZillaOutputs *output ) ;
   
   

   The contents of the two interface structures are defined in "zilla_interface.h"

6. The runZilla function will be called between 10 and 100 times per simulated second. (If the underlying hardware can't run things that fast, simulation time will run slower than realtime). The current simulation time is provided in the ZillaInputs structure on each call. Don't rely on a particular iteration rate to make your algorithm work!! When timeslow is activated, all robots will be told time from their perspective.

7. To keep the game running smoothly for the sake of the audience, your function must return within 1 millisecond on our target hardware (which will have at least a 2GHz CPU).

8. Programs may not return Not-A-Number (NaN) or Infinite (Inf) numbers in their ZillaOutput structures. The consequences of doing so are to cause the 'bot to freeze for that iteration - taking damage as usual but unable to move, shoot, rage or chomp.

9. You may not consume more than 1Mbyte of RAM within your library.

10. The C or C++ library must conform to current C/C++ standards without using compiler-specific extensions. The final contest will be run on a Linux PC with a recent GCC/G++ compiler used to compile the bot programs.

11. All robot programs must be provided as source code via email to the contest organiser in time for them to be judged for illegal content and tested to give a reasonable indication that they are robust and do not routinely crash.

12. Code must be provided free of copyright and must not contain licensed or patented material and will be published as example programs for the following year's contest.

13. Programs that attempt to gain advantage by deliberately corrupting memory or otherwise disrupting the operation of the simulation will be eliminated from the competition.

14. Any program that crashes the simulation or breaks any of the rules is eliminated from the competition. Since it is sometimes hard to determine which part of the system caused a crash, the Judge's opinion is final. If any of those situations arise during the 'last man standing' round then the round will be restarted without the offending robot. Please work hard to make sure this doesn't happen because of you!

15. The City Simulator software is subject to change in the unlikely case that serious bugs are found in it leading up to the competition. All effort will be made to keep the interface to the your function the same.

A WARNING ABOUT THE GRAPHICS:

For example:

• The graphic robots are larger than the ones in the simulation (relative to the size of buildings and roads. The real robots are circular and their diameter is about the same as the distance between the feet of the graphical robots. The long heads and tails are not 'really' there and all of the animation is pure eye-candy.

• There is a mixture of short buildings and tall ones in the graphics - some don't completely fill the block. Whilst it looks like you could shoot over a low building or around a narrow one to hit a robot behind it, in reality, if you try to shoot 'through' a block containing a building of *any* size, the beam will hit the building no matter what it's graphic appears to be. Only when you have a clear shot will the graphics show you aiming at the target.

• All rubble is flat and the various graphical fire and smoke effects are eye-candy that means nothing to the bots.

• When you take an action like SHOOT, CHOMP or RAGE, the effect is immediate and instantaneous. Then your bot sits and recovers for whatever amount of time is defined for that effect. In the graphics, this time is filled with an animation sequence that makes it look like the actual effect happens a little later. This looks cool - but doesn't represent the 'ground truth' - which is that all actions happen immediately they are called for.

  This effect is especially noticable during time-slow where it may appear that the robot that's moving at normal speed was able to dodge some effect when in fact the effect happened instantaneously.