README for the Robocode Tank Royale API written in Nim version 2

Nim 2.0 is out and brings a lot of iprovements to the language. This is a rewrite of the Robocode Tank Royale API written in Nim to take advantage of the new features of the language.

Nim 2.0 Changes

Some diagrams to help understand the architecture of the API

Contexts

  C4Context
    
    Person_Ext(programmer, "Programmer", "imports the API nim library and uses it to create a bot")

    System(api, "API library in Nim", "Nim library that allows the programmer to create a bot")

    System_Ext(bot, "Bot", "The bot that the programmer creates")

    Boundary(robocode, "Robocode Tank Royale Components", "These are the software provided externnaly that we work with") {
      System_Ext(GUI, "Robocode GUI", "Java program that allows the users to setup battles and watch them")

      System_Ext(robocode, "Robocode Tank Royale", "Java engine of the game")

      System_Ext(booter, "Booter", "Java launcher for the bots")
    }

    Rel(robocode, booter, "use", "system")
    Rel(GUI, robocode, "use", "system")
    Rel(programmer, GUI, "use", "system")
    Rel(bot, api, "import", "Nim")
    Rel(programmer, bot, "code and compile", "Nim")
    BiRel(api, robocode, "interaction", "WebSocket")

Loading

Bot interactions TODO (taken from Schemas)

• Joining a Server
  • connect WebSocket
  • receive server-handshake from Server
  • send bot-handshake to Server
• Leaving a Server
  • disconnect WebSocket
• Partecipating in a Game
  • receive game-started-event-for-bot from Server
  • send bot-ready to Server
• Running turns of the game
  • receive round-started-event from Server
  • receive round-ended-event-for-bot from Server
  • receive tick-event-for-bot from Server
  • receive skipped-turn-event from Server
  • send bot-intent to Server
• end of the Game
  • receive game-ended-event-for-bot
  • receive won-round-event
• in-game events
  • receive game-aborted-event from Server
  • receive bot-death-event from Server when a bot dies
  • receive bot-hit-bot-event from Server when our bot collides with another bot
  • receive bot-hit-wall-event from Server when our bot collides with a wall
  • receive bullet-fired-event from Server when our bot fires a bullet
  • receive bullet-hit-bot-event from Server when our bullet has hit a bot
  • receive bullet-hit-bullet-event from Server when our bullet collided with another bullet
  • receive bullet-hit-wall-event from Server when our bullet has hit the wall
  • receive hit-by-bullet-event from Server when our bot has been hit by a bullet
  • receive scanned-bot-event from Server when our bot has scanned another bot
  • receive skipped-turn-event from Server when our bot skipped a turn (the intent was not received at the server in time)
  • receive tick-event-for-bot from Server when a new turn is about to begin
  • receive won-round-event from Server

IBaseBot methods to implement

• addCustomEvent​(Condition condition) #Adds an event handler that will be automatically triggered onCustomEvent(dev.robocode.tankroyale.botapi.events.CustomEvent) when the Condition.test() returns true.
• bearingTo​(double x, double y) #Calculates the bearing (delta angle) between the current direction of the bot's body and the direction to the point x,y.
• calcBearing​(double direction) #Calculates the bearing (delta angle) between the input direction and the direction of this bot.
• calcBulletSpeed​(double firepower) #Calculates the bullet speed given a fire power.
• calcDeltaAngle​(double targetAngle, double sourceAngle) #Calculates the difference between two angles, i.e. the number of degrees from a source angle to a target angle.
• calcGunBearing​(double direction) #Calculates the bearing (delta angle) between the input direction and the direction of the gun.
• calcGunHeat​(double firepower) #Calculates gun heat after having fired the gun.
• calcMaxTurnRate​(double speed) #Calculates the maximum turn rate for a specific speed.
• calcRadarBearing​(double direction) #Calculates the bearing (delta angle) between the input direction and the direction of the radar.
• clearEvents() #Clears the remaining events that have not been processed yet.
• directionTo​(double x, double y) #Calculates the direction (angle) from the bot´s coordinates to a point x,y.
• distanceTo​(double x, double y) #Calculates the distance from the bot's coordinates to a point x,y.
• getArenaHeight() #Height of the arena measured in units.
• getArenaWidth() #Width of the arena measured in units.
• getBodyColor() #Returns the color of the body.
• getBulletColor() #Returns the color of the fired bullets.
• getBulletStates() #Current bullet states.
• getDirection() #Current driving direction of the bot in degrees.
• getEnemyCount() #Number of enemies left in the round.
• getEnergy() #Current energy level.
• getEventPriority​(java.lang.Class eventClass) #Returns the event priority for a specific event class.
• getEvents() #Events that remain to be processed in event handlers, which is useful to see the events that remain from event handlers being called before other event handlers.
• getFirepower() #Returns the firepower.
• getGameType() #Game type, e.g.
• getGunColor() #Returns the color of the gun.
• getGunCoolingRate() #Gun cooling rate.
• getGunDirection() #Current direction of the gun in degrees.
• getGunHeat() #Current gun heat.
• getGunTurnRate() #Returns the gun turn rate in degrees per turn.
• getMaxGunTurnRate() #Returns the maximum gun turn rate in degrees per turn.
• getMaxInactivityTurns() #The maximum number of inactive turns allowed the bot will become zapped by the game for being inactive.
• getMaxRadarTurnRate() #Returns the maximum radar turn rate in degrees per turn.
• getMaxSpeed() #Returns the maximum speed in units per turn.
• getMaxTurnRate() #Returns the maximum turn rate of the bot in degrees per turn.
• getMyId() #Unique id of this bot, which is available when the game has started.
• getNumberOfRounds() #The number of rounds in a battle.
• getRadarColor() #Returns the color of the radar.
• getRadarDirection() #Current direction of the radar in degrees.
• getRadarTurnRate() #Returns the radar turn rate in degrees per turn.
• getRoundNumber() #Current round number.
• getScanColor() #Returns the color of the scan arc.
• getSpeed() #The current speed measured in units per turn.
• getTargetSpeed() #Returns the target speed in units per turn.
• getTimeLeft() #The number of microseconds left of this turn before the bot will skip the turn.
• getTracksColor() #Returns the color of the tracks.
• getTurnNumber() #Current turn number.
• getTurnRate() #Returns the turn rate of the bot in degrees per turn.
• getTurnTimeout() #The turn timeout is important as the bot needs to take action by calling go() before the turn timeout occurs.
• getTurretColor() #Returns the color of the gun turret.
• getVariant() #The game variant, which is "Tank Royale".
• getVersion() #Game version, e.g. "1.0.0".
• getX() #Current X coordinate of the center of the bot.
• getY() #Current Y coordinate of the center of the bot.
• go() #Commits the current commands (actions), which finalizes the current turn for the bot.
• gunBearingTo​(double x, double y) #Calculates the bearing (delta angle) between the current direction of the bot's gun and the direction to the point x,y.
• isAdjustGunForBodyTurn() #Checks if the gun is set to adjust for the bot turning, i.e. to turn independent of the bot's body turn.
• isAdjustRadarForBodyTurn() #Checks if the radar is set to adjust for the body turning, i.e. to turn independent of the body's turn.
• isAdjustRadarForGunTurn() #Checks if the radar is set to adjust for the gun turning, i.e. to turn independent of the gun's turn.
• isDisabled() #Specifies if the bot is disabled, i.e., when the energy is zero.
• isStopped() #Checks if the movement has been stopped.
• normalizeAbsoluteAngle​(double angle) #Normalizes an angle to an absolute angle into the range [0,360[
• normalizeRelativeAngle​(double angle) #Normalizes an angle to an relative angle into the range [-180,180[
• onBotDeath​(BotDeathEvent botDeathEvent) #The event handler triggered when another bot has died.
• onBulletFired​(BulletFiredEvent bulletFiredEvent) #The event handler triggered when the bot has fired a bullet.
• onBulletHit​(BulletHitBotEvent bulletHitBotEvent) #The event handler triggered when the bot has hit another bot with a bullet. onBulletHitBullet​(BulletHitBulletEvent bulletHitBulletEvent) #The event handler triggered when a bullet fired from the bot has collided with another bullet.
• onBulletHitWall​(BulletHitWallEvent bulletHitWallEvent) #The event handler triggered when a bullet has hit a wall.
• onConnected​(ConnectedEvent connectedEvent) #The event handler triggered when connected to the server.
• onConnectionError​(ConnectionErrorEvent connectionErrorEvent) #The event handler triggered when a connection error occurs.
• onCustomEvent​(CustomEvent customEvent) #The event handler triggered when some condition has been met.
• onDeath​(DeathEvent deathEvent) #The event handler triggered when this bot has died.
• onDisconnected​(DisconnectedEvent disconnectedEvent) #The event handler triggered when disconnected from the server.
• onGameEnded​(GameEndedEvent gameEndedEvent) #The event handler triggered when a game has ended.
• onGameStarted​(GameStartedEvent gameStatedEvent) #The event handler triggered when a game has started.
• onHitBot​(HitBotEvent botHitBotEvent) #The event handler triggered when the bot has collided with another bot.
• onHitByBullet​(HitByBulletEvent hitByBulletEvent) #The event handler triggered when the bot has been hit by a bullet.
• onHitWall​(HitWallEvent botHitWallEvent) #The event handler triggered when the bot has hit a wall.
• onRoundEnded​(RoundEndedEvent roundEndedEvent) #The event handler triggered when a round has ended.
• onRoundStarted​(RoundStartedEvent roundStartedEvent) #The event handler triggered when a new round has started.
• onScannedBot​(ScannedBotEvent scannedBotEvent) #The event handler triggered when the bot has skipped a turn.
• onSkippedTurn​(SkippedTurnEvent skippedTurnEvent) #The event handler triggered when the bot has skipped a turn.
• onTick​(TickEvent tickEvent) #The event handler triggered when a game tick event occurs, ie., when a new turn in a round has started.
• onWonRound​(WonRoundEvent wonRoundEvent) #The event handler triggered when the bot has won a round.
• radarBearingTo​(double x, double y) #Calculates the bearing (delta angle) between the current direction of the bot's radar and the direction to the point x,y.
• removeCustomEvent​(Condition condition) #Removes triggering a custom event handler for a specific condition that was previously added with addCustomEvent(dev.robocode.tankroyale.botapi.events.Condition).
• setAdjustGunForBodyTurn​(boolean adjust) #Sets the gun to adjust for the bot's turn when setting the gun turn rate.
• setAdjustRadarForBodyTurn​(boolean adjust) #Sets the radar to adjust for the body's turn when setting the radar turn rate.
• setAdjustRadarForGunTurn​(boolean adjust) #Sets the radar to adjust for the gun's turn when setting the radar turn rate.
• setBodyColor​(Color color) #Sets the color of the body.
• setBulletColor​(Color color) #Sets the color of the fired bullets.
• setEventPriority​(java.lang.Class eventClass, int priority) #Changes the event priority for an event class.
• setFire​(double firepower) #Sets the gun to fire in the direction that the gun is pointing with the specified firepower.
• setFireAssist​(boolean enable) #Enables or disables fire assistance explicitly.
• setGunColor​(Color color) #Sets the color of the gun.
• setGunTurnRate​(double gunTurnRate) #Sets the turn rate of the gun, which can be positive and negative.
• setInterruptible​(boolean interruptible) #Call this method during an event handler to control continuing or restarting the event handler, when a new event occurs again for the same event handler while processing an earlier event.
• setMaxGunTurnRate​(double maxGunTurnRate) #Sets the maximum turn rate which applies to turn the gun to the left or right.
• setMaxRadarTurnRate​(double maxRadarTurnRate) #Sets the maximum turn rate which applies to turn the radar to the left or right.
• setMaxSpeed​(double maxSpeed) #Sets the maximum speed which applies when moving forward and backward.
• setMaxTurnRate​(double maxTurnRate) #Sets the maximum turn rate which applies to turn the bot to the left or right.
• setRadarColor​(Color color) #Sets the color of the radar.
• setRadarTurnRate​(double gunRadarTurnRate) #Sets the turn rate of the radar, which can be positive and negative.
• setRescan() #Sets the bot to rescan with the radar.
• setResume() #Sets the bot to scan (again) with the radar.
• setScanColor​(Color color) #Sets the color of the scan arc.
• setStop() #Set the bot to stop all movement including turning the gun and radar.
• setTargetSpeed​(double targetSpeed) #Sets the new target speed for the bot in units per turn.
• setTracksColor​(Color color) #Sets the color of the tracks.
• setTurnRate​(double turnRate) #Sets the turn rate of the bot, which can be positive and negative.
• setTurretColor​(Color color) #Sets the color of the gun turret.
• start() #The method used to start running the bot.

IBot methods to implement

• back​(double distance) #Moves the bot backward until it has traveled a specific distance from its current position, or it is moving into an obstacle.
• fire​(double firepower) #Fire the gun in the direction as the gun is pointing.
• forward​(double distance) #Moves the bot forward until it has traveled a specific distance from its current position, or it is moving into an obstacle.
• getDistanceRemaining() #Returns the distance remaining till the bot has finished moving after having called IBot.setForward(double), IBot.setBack(double), IBot.forward(double), or IBot.back(double).
• getGunTurnRemaining() #Returns the remaining turn in degrees till the gun has finished turning after having called IBot.setTurnGunLeft(double), IBot.setTurnGunRight(double), IBot.turnGunLeft(double), or IBot.turnGunRight(double).
• getRadarTurnRemaining() #Returns the remaining turn in degrees till the radar has finished turning after having called IBot.setTurnRadarLeft(double), IBot.setTurnRadarRight(double), IBot.turnRadarLeft(double), or IBot.turnRadarRight(double).
• getTurnRemaining() #Returns the remaining turn in degrees till the bot has finished turning after having called IBot.setTurnLeft(double), IBot.setTurnRight(double), IBot.turnLeft(double), or IBot.turnRight(double).
• isRunning() #Checks if this bot is running.
• rescan() #Scan (again) with the radar.
• resume() #Resume the movement prior to calling the IBaseBot.setStop() or IBot.stop() method.
• setBack​(double distance) #Set the bot to move backward until it has traveled a specific distance from its current position, or it is moving into an obstacle.
• setForward​(double distance) #Set the bot to move forward until it has traveled a specific distance from its current position, or it is moving into an obstacle.
• setGunTurnRate​(double turnRate) #Sets the turn rate of the gun, which can be positive and negative.
• setRadarTurnRate​(double turnRate) #Sets the turn rate of the radar, which can be positive and negative.
• setTargetSpeed​(double targetSpeed) #Sets the new target speed for the bot in units per turn.
• setTurnGunLeft​(double degrees) #Set the gun to turn to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• setTurnGunRight​(double degrees) #Set the gun to turn to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees.
• setTurnLeft​(double degrees) #Set the bot to turn to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• setTurnRadarLeft​(double degrees) #Set the radar to turn to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• setTurnRadarRight​(double degrees) #Set the radar to turn to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees.
• setTurnRate​(double turnRate) #Sets the turn rate of the bot, which can be positive and negative.
• setTurnRight​(double degrees) #Set the bot to turn to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees.
• stop() #Stop all movement including turning the gun and radar.
• turnGunLeft​(double degrees) #Turn the gun to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• turnGunRight​(double degrees) #Turn the gun to the right (following the decreasing degrees of the unit circle) until it turned the specified amount of degrees.
• turnLeft​(double degrees) #Turn the bot to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• turnRadarLeft​(double degrees) #Turn the radar to the left (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• turnRadarRight​(double degrees) #Turn the radar to the right (following the increasing degrees of the unit circle) until it turned the specified amount of degrees.
• turnRight​(double degrees) #Turn the bot to the right (following the increasing degrees of the unit circle) until it turned the specified amount of degrees. waitFor​(Condition condition) #Blocks until a condition is met, i.e. when a Condition.test() returns true.

planned TODO

• init a new Bot importing the library crete a new bot inheriting from a Bot object
• init the bot passing a standard json file (read create a json file for bot info)
• have a "run" method
• open WebSocket to Server to start the connection handshake
• find out how to call a method that can be overridden from a new bot
• find elegant method to convert between json and Messages object
• implement all Messages objects
• connect to server completing the handshake
• implement all IBaseBot methods
• implement all IBot methods
• write bash launcher (maybe with input functionality)
• complete standard bot bits and bobs necessary to make a working version 1.0.0