#ifndef LIBARENA #define LIBARENA 1 /******************************************************************************* * The AIARENA * ~~~~~~~~~~~ * The AIARENA is the simulator for programs that fight beetwen * them self, itsuport up to 16 'robots', they also can be * ogranized in the teams. * * The 'Arena' is a large 1000x1000 area. Each robot can move a * maximum of speed/100 squares per move. * * The arena is displayed as a large white box occupying most of the * screen.Inside this box you will see any obstacles that have been * placed on the map (see later section for a description of the map * file). All obstacles have a white border displayed around the * square, and are defined as below: * * White - A wall - Robots can see through this, but they can't move * or fire shells through it. If a robot collides with a wall it will * lose 1 armour point. * * * Red - A damage trap - A robot loses 1 armour point for every turn it * is on one of these squares. * * * Blue - A refueling point - If a robot comes to rest on one of these * points, it will regain some battery power (see later section for * more details). There can be up to 10 refueling points per arena. * * The map * ~~~~~~~ * The arena is divided into 10x10 pixel squares (that's 100x100 * squares in the whole arena). * Ideally, a complete map will consist of 100 lines of 100 * characters each. However, any lines which are not 100 lines * long will be assumed to be padded with empty area. If 100 * lines don't exist, then the last lines will be padded with * empty area. * * The possible characters (at the moment) are: * * '.' - this is an empty square - internally has the value * set by 'ARENA_FREE' * * 'X' - this is a wall - internally has the value set by * 'ARENA_WALL' * * 'M' - this is a damaging mine trap - internally has the value * set by 'ARENA_DAMAGE' * * 'R' - this is a refueling point - internally has the value * set by 'ARENA_REFUEL' * * [0-9,A-F] - these are the starting positions for robot * teams. They are not marked on the maps. * * The robot's scanner will see straight through walls, so to * avoid collisions, the robot should periodically call * 'get_local_map' to see a 9x9 area around the robot. * * Shells will not pass through walls, so although another * robot may see you hiding behind a wall, it will not be able * to damage you unless it moves around the wall. To see if a * shell has hit a wall you'll have to call the * 'get_shell_status' routine, which will tell you if the last * shell to land hit a wall or a robot. * * Robot Batteries * ~~~~~~~~~~~~~~~ * * Robots are powered by electrical batteries. * These batteries are constantly being charged by a solar panel, * and are constantly being discharged by robot motion. * * The battery starts off being charged with 'batt_cap' units of * energy. * * Each turn the battery will be charged by 'batt_rec' units. Each * turn that the robot moves the battery will be discharged by the * current speed / 10. The battery can not be charged above the * batt_cap unit level. * * If the battery is flat, the robot will come to a * standstill,until the battery is charged again. This means * that the robot must issue a 'move' command to start the * robot moving again. * * Battery power may be traded to buy more shells, or more armour. * Alternatively, armour may be traded to buy more battery power. * * If a robot is destroyed, any battery power remaining is * transferred to the robot which dealt the death blow. * * Recharging Stations * ~~~~~~~~~~~~~~~~~~~ * * A map may contain between 0 and 10 refueling stations where * robots can replenish their batteries. * * These refueling stations are simply large quick charging * batteries themselves. They recharge at a rate of 5 units per * turn, as long as no robot is currently being recharged from * hem. Recharging units may not acquire more than 2000 units * of charge. * * A robot must be stationary and visible on a refueling * station in order to recharge its batteries. It will take 10 * units of charge from the refueling station as long as there * is sufficient charge in the refueling station's batteries. * * Robot Configuration * ~~~~~~~~~~~~~~~~~~~ * * Robots may now be customised to suit a specific task, you do * this by calling the configure routine, with the appropriate * parameters. * * The configuration call *must* be the first call in the program. * If you do not call it, all the parameters will be set to their * '2' value in the table below. * * Value Speed Manouevre Range Armour Acceleration * 0 50 20% 300 50 5 * 1 75 35% 500 75 7 * 2 100 50% 700 100 10 * 3 150 75% 1000 150 15 * 4 200 100% 1500 200 20 * * Value Battery_ Capacity Battery_Recharge Invisibility * 0 500 2 0 * 1 750 3 1 * 2 1000 4 2 * 3 1500 5 3 * 4 2000 6 4 * * You have a maximum of 10 points to allocate to the robot. If * you try to allocate more points to the robot, some items * will have a value of '0'. * * It is also possible to buy an 'invisibility' device using * this function. Normally a robot will start with 1000 shells * at the beginning of a game. If you take the invisibility * device this will be reduced to 900 shells. * * Invisibility * ~~~~~~~~~~~~ * * Invisibility is a purely defensive system, and will be of * negligible use in a 'dumb' robot. * * When your robot goes invisible it will be undetectable by * other robots' scanners, however, shells landing in the * vicinity will still damage the robot. * * Also, invisibility places the following limitations on your * robot: * * - Scanning is not possible * - Firing the cannon is not possible * * Value Energy_usage Battery_recharge_rate * 0 NO INVISIBLITY DEVICE * 1 2 * Normal 0 * 2 Normal 0 * 3 Normal 1 * 4 Normal 2 * * The main use of invisibility would be to hide while running * to a safer location (to stop some 'chase' robots from * following you there). When there it would be possible to * become visible to recharge the batteries. * * When the robot is invisible an 'I' will appear next to the * robot's name. * * A robot can only stay invisible for a maximum of 100 turns, * it will then automatically become visible again. After a * robot has become visible it must remain visible for as many * turns as it was invisible before it can turn invisible * again. Thus, if a robot was invisible for 50 turns, it must * be visible for at least 50 turns before it can go invisible * again. * * Debugging Aids * ~~~~~~~~~~~~~~ * There are several features to help you to debug robots. * * The most basic is the use of the 'debug flags'. These can * indicate certain 'modes' of operation of the robot, for * instance a robot may have a 'running' mode and an 'attack' * mode. A debug flag indicator could be used to let you see at * a glance which mode the robot is in. * * You can also use stdout to print messages * * Robot Time Limit * ~~~~~~~~~~~~~~~~ * * There is configurable time limit for the robots, default is 3 seconds * * This time limit is not meant to seriously limit robots, it * is merely meant as a protection against robots getting stuck * in a loop like: * * do * { * getxy(&x,&y); * } * while (x>100); * ******************************************************************************/ void swaptask(void); /****************************************************************************** * This procedure will simply end the current robot's turn if it has * nothing else to do. Use this if, for instance, you're waiting for * the robot to move to a certain location. *****************************************************************************/ int movement(int speed,double angle); /****************************************************************************** * This procedure will cause the robot to start moving in * the specified direction at the specified speed. * * speed = 0 - max speed of robot (<=200) * angle = 0 - 359 degrees * * The speed will change to the target speed at the * maximum acceleration rate specified for this robot. * * If the robot is going above its manouvrability speed, * then it will not be able to change direction. It must * slow down first. * * The return value is 1 if movement was sucesfull or 0 if failure * * This procedure will cause the current robot's turn to * end. ******************************************************************************/ int movementr(int speed,double angle); /****************************************************************************** * This is same function as 'movement' but here angle is in radians ******************************************************************************/ int scan(int angle,int res,int *range); /****************************************************************************** * This function will cause the robot to scan for other * robots in the specified direction. * * angle = 0 - 359 degrees * res = 0 - 45 degrees * * returns 1 if some robots was detected, or 0 if no robot was detected. * * The range is array with maximum number in arena(see 'max_robots'), * values in array are sorted by robot's ID * - positive number, range from your robot * - 0, it is you * - negative value you did not detectet ths robot in previous scan * * The scan function will scan along a specified direction * with the specified resolution. For instance a * scan(300,5,....) will look at the angles from 295 * degrees to 305 degrees. * * This function will cause the current robot's turn to end. ******************************************************************************/ int scanr(double angle,double res,int *range); /****************************************************************************** * This is same function as 'scan' but here angle,and res(0,PI/4) * are in radians. ******************************************************************************/ int shoot(int angle,int range); /****************************************************************************** * This function causes the robot to fire a shell in the * specified direction for the specified range. The shell * will be fired into the air, so it will not hit any * targets before the range is reached. * * angle = 0 - 359 degrees * range = 0 - max range of robot's cannon * * if the robot was able to fire a shell then the function * will return the shell's Id value (used with the * 'get_ashell_status' function, if it was unable to fire * a shell for any reason, then it will return 0. * * The robot's turret is independant of the robot's * heading, so shells can be fired in any direction. * * Seven shells per robot are allowed in the air at once. * Also, the cannon takes 50 ticks to reload. * * The robot normally starts with only 1000 shells, if * these all run out (very unusual!), then the robot will * be unable to fire its cannon, unless it purchases more * shells (see 'buy_shells' function). * * This function will cause the current robot's turn to * end. ******************************************************************************/ int shootr(double angle,int range); /****************************************************************************** * This is same function as 'shoot' but here angle is in radians ******************************************************************************/ void getxy(int *x,int *y); /****************************************************************************** This function will return the current position of the robot. The x and y coordinates of the robots are returned in the x and y parameters (possible values are 0 - 999). ******************************************************************************/ int transmit(int id,int data); /****************************************************************************** This function will transmit the specified data to the specified robot. target = target robot id - as obtained from the scan function. data = data word to send to the robot. If the data could not be sent for any reason, the function will return 0, otherwise it will return 1. It costs one battery unit to transmit a word of data. Robots have a 20 word FIFO receive queue where received data is stored until it is read. If this buffer is full, or the target robot does not exist, then this function will return a 0. Success of the call does *not* mean that the target robot has actually looked at the received data. ******************************************************************************/ int receive(int *source,int *data); /****************************************************************************** This function allows a robot to see if any data has been sent to it by another robot. The function will return 1 if data exists, or 0 if the receive buffer is empty. If data exists, then source will be set to the id number of the sending robot, and data will be set to the data which was sent. If the receive buffer was empty, then source and data will be undefined. Because this function does not cause the current robot's turn to end, it is recommended that this function is called periodically to clear up the robot's input buffer, even if the data is subsequently ignored. ******************************************************************************/ int damage(void); /****************************************************************************** This function will return the current damage status of the robot. The lower the value, the more damaged the robot is. The initial value depends on the robot's configuration, but is normally 100. ******************************************************************************/ int speed(void); /****************************************************************************** * This function will return the current speed of the robot. ******************************************************************************/ int battery(void); /****************************************************************************** * This function will return the current status of the battery. ******************************************************************************/ long int ticks(void); /****************************************************************************** * This function will return the number of game ticks since the * beginning of the game. This is not related to real time, just the * number of complete turns that have elapsed. ******************************************************************************/ void debug_flags(int flag_nbr,int flag_set); /****************************************************************************** This procedure allows you to set or clear two flag markers by the side of the robot's name down the right hand side of the screen. flag_no = 0 or 1 flag_set= 0 or 1 These two flags may be used for whatever purpose you want, but they are often useful for debugging purposes. ******************************************************************************/ void buy_armor(int units); /****************************************************************************** This procedure lets your robot buy or sell armour. units = number of units to buy. If 'units' is negative, then armour will be sold. Armour units currently are worth 50 battery units, so if a robot has a high battery charge it is possible to sell some units to repair damaged armour. Also, if a robot needs some battery power, it can sell armour in exchange for some more battery power. The armour rating can not go above the robot's initial armour rating, any extra purchased units will be wasted. It is quite possible to commit suicide using this call. ******************************************************************************/ void buy_shells(int units); /****************************************************************************** This procedure lets you purchase more cannon shells. units = number of shells to buy. It is not possible to sell shells in exchange for battery power. Shells cost 10 battery units each. ******************************************************************************/ int shells_left(void); /****************************************************************************** This function lets your robot determine how many cannon shells it has remaining. Returns the number of shells remaining. ******************************************************************************/ void get_local_map(char *map); /****************************************************************************** This procedure lets you obtain a map of the area local to the robot. You will receive a 9x9 square map of the local area, the robot's current position will be in the centre square of the map. See the section on the map for details of the contents of the map. The map array should be 81 bytes long. ******************************************************************************/ void invisibilty(int flag); /****************************************************************************** This procedure allow the robot to become invisible or visible. flag = 0 - robot is visible, = 1 - robot is invisible. If the robot isn't capable of becoming invisible, then this procedure will do nothing. ******************************************************************************/ int isinvisible(void); /****************************************************************************** This function will return a flag indicating whether the robot is invisible or not. Return value: 0 - robot is visible, 1 - robot is invisible. ******************************************************************************/ int get_shell_status(void); /****************************************************************************** This function will return a status value reporting what happened to the last shell to land. Return value: 0 - shell missed totally 1 - shell hit a wall 2 - shell hit a robot within a 50 square radius 3 - shell hit a robot within a 25 square radius 4 - shell hit a robot within a 5 square radius This can be useful to see if a shell is firing at a robot which is hiding behind a wall. ******************************************************************************/ int get_robot_id(void); /****************************************************************************** This function will return the robot ID of the current robot. ******************************************************************************/ void register_iff(const char *iff_string); /****************************************************************************** This function will inform AIARENA of the 'IFF' string for this particular robot. The IFF string may only be set once. The 'iff_string' parameter is a C format zero-terminated string. ******************************************************************************/ int check_iff(int id); /****************************************************************************** This function will check to see if the robot with id 'id' has the same 'IFF' string as the current robot. It will return 1 if the strings match, or 0 otherwise. ******************************************************************************/ void register_name(const char *name_string); /****************************************************************************** This function will inform AIARENA the name of this robot. The name may only be set once. The 'name_string' parameter is a C format zero-terminated string. ******************************************************************************/ int find_name(int id,const char *name_string); /****************************************************************************** This function will search for a specified name. The search will start at 'id' and end when there are no more robots to check. If no robot is found, it will return -1, otherwise it will return the robot id. The 'name_string' parameter is a C format zero-terminated string. ******************************************************************************/ int get_team_id(void); /****************************************************************************** This function will return the team which the current robot is on. -1 will be returned if it is a 'loner', otherwise the team number will be returned. ******************************************************************************/ int get_ashell_status(int shellid); /****************************************************************************** This function will return the status of a shell which was fired in the past. Only the 10 most recent shells are remembered (including those currently in flight). The return value is similar to that obtained from 'get_shell_status', but with these extra possibilities: 5 - The shell is unknown (it hasn't been fired yet, or it is more than 10 shells old). 6 - The shell is still in flight The shellid value is obtained from the 'shoot' function. ******************************************************************************/ int configure(int speed,int manouevre,int range,int armour,int acceleration, int batt_rec,int batt_cap,int invisibility); /****************************************************************************** This function allows you to configure the robot to suit the program. It *must* be called as the first thing in the program. For values of the parameters, look at the 'robot configuration' section. This function returns 0 if it was not the first AIARENA call in the program (in which case it was ignored). If this function was called as the first thing in the program, then it will return the AIARENA version number in the two bytes of the return value. The high byte will be the 'major' version number, and the low byte will be the 'minor' version number. For instance V1.30 will return 0x0130. ******************************************************************************/ int max_robots(void); /****************************************************************************** This function will return maximum number of robots in arena, useful for 'scan' ******************************************************************************/ /* '#define'd values returned by 'get_local_map' */ #define ARENA_FREE 0 #define ARENA_WALL 1 #define ARENA_DAMAGE 3 #define ARENA_REFUEL 30 /* '#define'd values returned by 'get_shell_status' */ #define SHELL_MISSED 0 #define SHELL_HIT_WALL 1 #define SHELL_CLOSE_BLAST 2 #define SHELL_NEAR_MISS 3 #define SHELL_DIRECT_HIT 4 #define SHELL_NOT_KNOWN 5 #define SHELL_IN_FLIGHT 6 #endif