Difference between revisions of "XanderFramework"

From Robowiki
Jump to navigation Jump to search
m (→‎Radars, Gun, and Drives: minor javadoc fix)
(→‎Events: updated notes for framework v3.0)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
The Xander framework is an AdvancedRobot framework that makes it easy to build new bots by combining different guns, radars, and drives.  It is based on an abstract class named AbstractXanderBot that extends AdvancedRobot.  All framework classes are in the package xandercat.core.  When looking at any of my xandercat robots, anything outside of the xandercat.core package are components built for the Xander framework, not part of the Xander framework itself.
+
= Xander Framework =
 +
 
 +
The Xander framework is an AdvancedRobot framework that makes it easy to build new bots by combining different guns, radars, and drives.  It is based on an abstract class named AbstractXanderRobot that extends AdvancedRobot.  All basic framework classes are in the package xander.core.  As an optional add-on to the framework, some more advanced yet less mature guess factor and wave surfing classes are in package xander.gfws.  When looking at any of my Xander robots, anything outside of the xander.core and xander.gfws packages are components built for the Xander framework, not part of the Xander framework itself.
 +
 
 +
With a Xander robot, the main robot class need only set up a ''component chain'' populated with your guns, radars, and drives.  It can also optionally override methods to change basic configuration options and write battle statistics to disk.
 +
 
 +
Guns, radars, and drives must use the corresponding framework interfaces and can make use of a variety of framework resources and events.
 +
 
 +
The current framework version available for the last few years is considered v2.0.  Version 3.0 is current in development.  Version 3.0 brings several advancements over the older version through a revised component structure, including:
 +
*  Full melee support.
 +
*  Simplified components, but without losing any prior functionality.
 +
*  Reduced code size.
 +
*  Improved performance.
 +
 
 +
== Version Notes ==
 +
 
 +
Some interesting notes about each version of the framework.
 +
 
 +
=== Version 1.0 ===
 +
 
 +
Version 1.0 had the basics complete, but lacked some of the more advanced functionality like tracking wave history.
 +
 
 +
=== Version 2.0 ===
 +
 
 +
Version 2.0 added more advanced functionality like wave history and has been the main version from about 2013 up through 2017.  Version 2.0 was tailored primarily for 1 vs 1 combat, and had certain deficiencies when attempting to use it for other purposes.  It was structured to have 1 of each framework component, and only some of them were written to accommodate more than 1 opponent on the battlefield.
 +
 
 +
=== Version 3.0 ===
 +
 
 +
Version 3.0 is under development in 2017.  It's purpose is to add full melee or multi-opponent support, simplify some of the code, reduce code size, and improve performance in a few areas.  Version 3.0 takes on a new component strategy where some components that can apply to a single robot now only apply to a single robot.  This means some main framework components will now have 1 instance for each known robot, instead of a single instance that must handle all robots.  One of the challenges with this approach is that robot specific opponents are now generated as knowledge of their existence is gained, instead of existing from the very beginning of the battles.  This is a challenge because you can no longer always fully construct your robot at the very beginning, because some parts must be created or expanded as new robots are scanned.  The framework is being rewritten to support this in as convenient a fashion as possible.
 +
 
 +
The main framework components that will now have 1 for every robot (including self) include the SnapshotHistory, WaveHistory, and GunStats components.
 +
 
 +
Any listeners for robot specific components (anything that implements WaveListener, ScannedRobotListener, etc) must now implement an additional method getOpponentFocus() that tells the framework what robots to associate the component with.  Focus options include:
 +
* ALL_ROBOTS:  Component will receive events for all robots.
 +
* TARGETED_ROBOT:  Component will only receive events from the currently targeted robot (the targeted robot determined by what your radar is returning).
 +
* SPECIFIC_ROBOT_SCANNED:  Component will only receive events for one specific robot.  That robot will be the last scanned robot at time listener is added, or the next scanned robot if there is no last scanned robot.
 +
* SPECIFIC_ROBOT_TARGETED:  Component will only receive events for one specific robot.  That robot will be the last targeted robot at time listener is added, or the next targeted robot if there is no current target.
  
= Xander Framework =
 
The Xander framework is a framework on which Robocode robots can be built.  This section details the core framework.
 
 
== Base Robot Class ==  
 
== Base Robot Class ==  
Xander robots extend the '''AbstractXanderBot''' class.  The '''AbstractXanderBot''' class contains basic robot setup code and a basic processing loop.   
+
Xander robots extend the '''AbstractXanderRobot''' class, which in turn extends the Robocode '''AdvancedRobot''' class.  The '''AbstractXanderRobot''' class contains basic robot setup code and a basic processing loop.   
  
The basic setup code performs as follows:
+
'''The basic setup code performs as follows:'''
If it's the first round...
+
set all setXxxForRobotXxx values to true.
**  Create new configuration and call the configure(Configuration) method.
+
*  if first round:
*  Otherwise...
+
**  call configure(Configuration)
**  Get configuration from the ''static resource mananger''
+
**  call style(RobotStyle)
*  call methods setAdjustGunForRobotTurn(true), setAdjustRadarForGunTurn(true), and setAdjustRadarForRobotTurn(true)
+
**  initialize Resources
* apply robot styling
+
**  call addComponents(ComponentChain)
*  initialize ''robot history'' and ''bullet history''
+
apply robot styling (done every round in case win code changes styling)
* create or load radar, drive, and gun
+
issue round begin event
*  call initalizeForNewRound(AbstractXanderBot) on all static resources
 
create ''radar controller'', ''drive controller'', and ''gun controller''
 
call drive and gun initialize(...) methods
 
  
The basic processing loop performs as follows:
+
'''The basic processing loop performs as follows:'''
 +
*  issue turn begin event
 +
*  Process component chain to select radar, drive, and gun
 
*  Query radar for target
 
*  Query radar for target
 
*  If no target is locked...
 
*  If no target is locked...
Line 25: Line 58:
 
*  Otherwise...
 
*  Otherwise...
 
** Tell drive to drive with given target
 
** Tell drive to drive with given target
** If target is disabled...
+
** If target is disabled and configuration allows...
 
*** Fire on target with Head-On gun
 
*** Fire on target with Head-On gun
 
** Otherwise...
 
** Otherwise...
*** Fire on target with main gun
+
*** Fire on target with gun
* Notify turn listeners of turn event
+
* issue turn end event
 
* call execute()
 
* call execute()
  
A Xander robot ''must'' implement the following methods:
+
'''A Xander robot ''must'' implement the following methods:'''
*  void initialize(Components) - The drive, gun, and radar should be created and stored in the Components object using the appropriate setter methods. (Note: In early versions of the framework, there were separate methods for creating the gun, radar, and driveHowever, this made it more difficult to handle situations where coordination was required between two or more components.  It was for this reason that all three main components are now created within a single method.)
+
*  addComponents(ComponentChain) - for setting up component chain
 +
 
 +
'''In addition, a Xander robot may optionally override the following methods:'''
 +
*  void configure(Configuration) - allows basic configuration of the robot to be changed
 +
*  void style(RobotStyle) - allows setting styling options like robot colors
 +
*  boolean recordBattleStats(Map<String, String>) - allows robot to save battle statistics to file; key is statistic name, value is statistic value as String.  Statistics are saved in the '''BattleStats''' class which is written to file as a Java object using an ObjectOutputStream.
 +
 
 +
== Components / Component Chain ==
 +
In a Xander robot, guns, drives, and radars are referred to as ''components''.  Components are managed within a ''component chain'' represented by the '''ComponentChain''' class. The component chain follows the general concepts of the ''Chain of Responsibility'' design pattern.  It consists of a series of '''ComponentScenario''' objects that are responsible for selecting a radar, drive, and gun to use for each turn.  The chain is followed from the beginning to the end, each '''ComponentScenario''' passing off to the next, until a radar, drive, and gun have all been selected for the current turn.
 +
 
 +
The component chain is set up at the beginning of the first round by a call to the abstract method <pre>addComponents(ComponentChain)</pre>.  Each link in the chain has a '''Scenario''' that is responsible for deciding whether or not the components for that link should be used or notThis design makes it easy to handle situations where more than one component should be used in combination.  All specialized scenarios should be set up by calls to <pre>addComponents(...)</pre>, while main or default components to be used when no specialized scenario applies should be set up by a call to <pre>addDefaultComponents(...)</pre>.
 +
 
 +
'''Example:'''
 +
 
 +
Assume you have a mainRadar, mainDrive and mainGun for a robotAssume you also have a ramDrive and ramGun that should be used together against robots who use a ramming strategy.  For this, a Scenario ramScenario could be written to test if a robot is using a ramming strategy.  The component chain would then be set up as follows:
 +
<pre>
 +
protected void addComponents(ComponentChain chain) {
 +
...
 +
chain.addComponents(ramScenario, ramDrive, ramGun);
 +
chain.addDefaultComponents(mainRadar, mainDrive, mainGun);
 +
}
 +
</pre>
  
 +
== Resources ==
 +
Classes within a Xander robot have easy access to a number of resources which can be accessed through the '''Resources''' class. 
  
To aid in testing, it is valid to leave the drive, gun, and/or radar null within the Components object.  A null drive will cause the robot to stay in once place.  A null gun will cause the robot to not fire any bullets.
+
=== DriveStats ===
 +
Statistics related to the drives of your robot, such as drive time usage.
  
In addition, a Xander robot may optionally override the following methods:
+
=== GunStats ===
* void configure(Configuration) - allows basic configuration of the robot to be changed
+
Statistics related to the guns, including hit ratios and virtual gun hit ratios. As of v3.0, one GunStats will be created for each robot in the battle.
*  void style(RobotStyle) - allows setting styling options like robot colors
 
*  void doFinishingMoves() - moves to perform after winning a round
 
  
== Static Resources ==
+
=== RobotEvents ===
Classes within a Xander robot have easy access to a number of static resources which can be accessed through the ''Static Resource Manager''This includes a '''Timer''', '''Robot Proxy''', '''GunStats''', '''DriveStats''', '''Configuration''', and '''RobotStyle'''.
+
Manages all major event listeners, including all of the repackaged AdvancedRobot events.   
  
=== Timer ===
 
The timer simply keeps track of game time.  In addition to round time, it also maintains a cumulative battle time.
 
 
=== RobotProxy ===
 
=== RobotProxy ===
Access to all robot getXxx methods outside of the main robot class itself should be accessed via the RobotProxy object.  As a convenience, it is also passed as an argument to some interface methods.
+
Access to all robot getXxx methods outside of the main robot class itself should be accessed via the RobotProxy object.   
=== GunStats ===
+
 
Keeps track of hit ratios, virtual hit ratios, and other gun-based statistics.
+
=== SnapshotHistory ===
=== DriveStats ===
+
Robot history is available through the '''SnapshotHistory'''. Robot history for a particular point in time is stored in a ''snapshot'' via the '''Snapshot''' class, an immutable snapshot of a robot at a particular point in time.  As of v3.0, One SnapshotHistory will be created for each robot in the battle.
Keeps track of the amount of time each drive has been used, and other drive-based statistics.
+
 
=== Configuration ===
+
Each turn, a Xander robot takes a new snapshot for itself and stores it in the historyEach scan, a new snapshot for the scanned robot is generated and stored in the history.  Robot history allows the robot to look back at snapshots of itself and it's opponents back a set number of turns and scans.
Stores Xander framework configuration parametersFor the most part, it is the Xander framework itself that needs access to this static resource.
+
 
=== RobotStyle ===
+
=== WaveHistory ===
Stores robot vanity information, such as robot colors.
+
History of all bullet wavesAs of v3.0, one WaveHistory is created for each robot.
=== Guns, Radars, and Drives ===
 
All guns, radars, and drives are treated as static resources(Note: In an earlier version of the framework, guns, drives, and radars did not have to be static resources. However, this was more complicated than necessary, and was therefore changed.  The only downside to this change is that some components not meant to be static may have to clear out their variables between rounds in the initializeForNewRound(...) method.)
 
  
 
== Controllers ==
 
== Controllers ==
 
Radars, guns, and drives control the robot through ''controller'' classes.  The controllers for radar, gun, and drive provide  access to the radar, gun, and drive related setXxx methods of the robot.  This approach helps to prevent components from doing operations that are outside their area of responsibility, and also prevents components from calling the basic '''Robot''' control methods, or any methods that would immediately cause a turn to end.  Controllers may also have other helper methods.  
 
Radars, guns, and drives control the robot through ''controller'' classes.  The controllers for radar, gun, and drive provide  access to the radar, gun, and drive related setXxx methods of the robot.  This approach helps to prevent components from doing operations that are outside their area of responsibility, and also prevents components from calling the basic '''Robot''' control methods, or any methods that would immediately cause a turn to end.  Controllers may also have other helper methods.  
  
== Robot History ==
+
== Radar ==
Robot history is available through the '''RobotHistory''' class, and is accessible via the '''RobotProxy''' class, and is therefore available to all radars, drives, and guns.  Robot history for a particular point in time is stored in a ''robot snapshot'' via the '''RobotSnapshot''' class, an immutable snapshot of a robot at a particular point in time.
+
Radars must implement the '''Radar''' interface.  In a Xander robot, the radar is responsible for operating the radar and selecting a Snapshot of a robot for the drive and gun to focus on.
  
Each turn, a Xander robot takes a new snapshot for itself and stores it in the history.  Each scan, a new snapshot for the scanned robot is generated and stored in the history.  Robot history allows the robot to look back at snapshots of itself and it's opponents back a set number of turns and scans.
+
<pre>
 +
public interface Radar extends Component {
  
== Bullet History ==
+
/**
Bullet history provides information on enemy bullets fired.  Information about a fired bullet is stored as a '''BulletWave'''.  Bullet history is available through the '''BulletHistory''' class, and is accessible via the '''RobotProxy''' classThe bullet history also keeps track of the opponent's hit ratio.  Any component wishing to be informed of enemy bullet fired events can register itself as a '''BulletWaveListener'''.
+
* Prepare next sweep of radar and return snapshot of robot currently
 +
* being focused upon.
 +
*
 +
* @param radarController radar controller
 +
*
 +
* @return    snapshot of robot to attack
 +
*/
 +
public Snapshot search(RadarController radarController);
 +
}
 +
</pre>
  
== Radar ==
 
Radars must implement the '''Radar''' interface.
 
 
== Drive ==
 
== Drive ==
 
Drives must implement the '''Drive''' interface.
 
Drives must implement the '''Drive''' interface.
 +
 +
<pre>
 +
public interface Drive extends Component {
 +
 +
/**
 +
* Drive into optimal firing range of the given robot.
 +
*
 +
* @param opponentSnapshot  robot to drive against
 +
* @param driveController    drive controller
 +
*/
 +
public void driveTo(Snapshot opponentSnapshot, DriveController driveController);
 +
 +
/**
 +
* Drive without any specific target.
 +
*
 +
* @param driveController    drive controller
 +
*/
 +
public void drive(DriveController driveController);
 +
}
 +
</pre>
 +
 +
=== Drive Array ===
 +
 +
In cases were the robot should choose between a variety of drives based on some common criteria, a ''drive array'' can be set up using the '''DriveArray''' class.  A drive array must have a ''drive selector'', defined by the '''DriveSelector''' interface.
 +
 
== Gun ==
 
== Gun ==
 
Guns must implement the '''Gun''' interface.  However, rather than creating a gun class and directly implementing the gun interface, the recommended approach for a Xander robot is to use the '''XanderGun''' class.  The '''XanderGun''' class relies on two other interfaces:  '''Targeter''' and '''PowerSelector'''.  A '''PowerSelector''' decides on what fire power to use, while the '''Targeter''' determines how to aim the gun based on what the bullet velocity will be.  When using a '''XanderGun''', you create classes that implement '''Targeter''' and '''PowerSelector''', and the XanderGun takes care of the rest, including:
 
Guns must implement the '''Gun''' interface.  However, rather than creating a gun class and directly implementing the gun interface, the recommended approach for a Xander robot is to use the '''XanderGun''' class.  The '''XanderGun''' class relies on two other interfaces:  '''Targeter''' and '''PowerSelector'''.  A '''PowerSelector''' decides on what fire power to use, while the '''Targeter''' determines how to aim the gun based on what the bullet velocity will be.  When using a '''XanderGun''', you create classes that implement '''Targeter''' and '''PowerSelector''', and the XanderGun takes care of the rest, including:
Line 84: Line 168:
 
**  If power is more than is required to kill the target, reduce firepower to what is needed for a kill.
 
**  If power is more than is required to kill the target, reduce firepower to what is needed for a kill.
 
**  If target is not disabled and firing bullet would disable self, reduce firepower such that it will not disable self.
 
**  If target is not disabled and firing bullet would disable self, reduce firepower such that it will not disable self.
 +
 +
<pre>
 +
public interface Gun extends Component {
 +
 +
/**
 +
* Aim and fire upon the given opponent.  Since guns are also required
 +
* to have the getFiringVector method, this method can generally call that
 +
* method to get the aim.  The only extra work in this method is
 +
* actually turning the gun and firing.
 +
*
 +
* @param target          snapshot of opponent
 +
* @param myself          snapshot of self
 +
* @param gunController    gun controller
 +
*
 +
* @return          whether or not a bullet was fired
 +
*/
 +
public boolean fireAt(Snapshot target, Snapshot myself, GunController gunController);
 +
 +
/**
 +
* Returns the aim information for the given opponent. 
 +
*
 +
* @param target    the opponent to target
 +
* @param myself    snapshot of self
 +
*
 +
* @return          aim information for the given opponent
 +
*/
 +
public Aim getAim(Snapshot target, Snapshot myself);
 +
 +
/**
 +
* Returns whether or not this can is currently capable of aiming and
 +
* firing on the given robot.  This method should be lightweight (most
 +
* guns should just return true).
 +
*
 +
* @param target          snapshot of robot to fire at
 +
*
 +
* @return                whether or not gun can fire on opponent
 +
*/
 +
public boolean canFireAt(Snapshot target);
 +
}
 +
</pre>
 +
 +
=== Gun Array ===
 +
 +
In cases were the robot should choose between a variety of guns based on some criteria, a ''gun array'' can be set up using the '''GunArray''' class.  A gun array must have a ''gun selector'', defined by the '''GunSelector''' interface.  A gun array can be set up to fire virtual bullets. 
 +
 +
Historical Note:  The GunArray operates much like the CompoundGun of the Xander 1.0 framework.  However, it is no longer intended for the construction of ''trees'' (though technically it is still possible to create one).  For the Xander 2.0 framework, most component selections are expected to be handled by the ''component chain''.
  
 
== Events ==
 
== Events ==
Robocode issues a number of different events to the robot.  A Xander framework robot repackages these events and also provides other custom events, and makes those available to other components.  Xander robots can make use of the following events:
+
Robocode issues a number of different events to the robot.  A Xander framework robot repackages these events and also provides other custom events, and makes those available to other components.  Xander robots can make use of the following events accessed through the RobotEvents class (v3.0):
 
{| border="1" cellpadding="4"
 
{| border="1" cellpadding="4"
 
! Listener Class
 
! Listener Class
! Events Issued By (Register With)
+
! Opponent Focusable?
 
! Purpose
 
! Purpose
 
|-
 
|-
| BulletListener
+
| BulletHitListener
| AbstractXanderBot
+
| Yes
| Repackages Robocode events onBulletHit, onBulletHitBullet, onBulletMissed, and onHitByBullet
+
| Repackages Robocode events onHitByBullet, onBulletHit, onBulletMissed, and onBulletHitBullet
|-
 
| BulletFiredListener
 
| AbstractXanderBot
 
| Provides basic information on enemy bullet fired at self, including snapshots of enemy, self, and energy of bullet. 
 
|-
 
| BulletWaveHitListener
 
| BulletHistory
 
| Provides details on enemy bullet waves as they are tracked by the bullet history, including when waves are created and destroyed, when they hit, and what wave matches any bullet that hits self.
 
 
|-
 
|-
 
| CollisionListener  
 
| CollisionListener  
| AbstractXanderBot
+
| No
 
| Repackages Robocode events onHitRobot and onHitWall
 
| Repackages Robocode events onHitRobot and onHitWall
 
|-
 
|-
| MyBulletFiredListener
+
| WaveListener
| GunController
+
| Yes
| Provides details on our own bullet waves, including when they are fired, when they are invalidated (by being old or after bullet hit bullet), when they hit the targeted opponent, and what the next wave to hit is.
+
| Handles events related to a robot's bullet waves.  The WaveHistory stores two sets of WaveListeners, one for actual bullet waves, and one for virtual bullet waves.  If listening for both, you can tell the difference between the two by the Wave method isVirtual().
 
|-
 
|-
 
| Painter  
 
| Painter  
| AbstractXanderBot
+
| No
 
| Repackages Robocode event onPaint, allowing other components to paint on the battlefield
 
| Repackages Robocode event onPaint, allowing other components to paint on the battlefield
 
|-
 
|-
| RoundListener  
+
| RoundBeginListener
| AbstractXanderBot
+
| No
| Repackages Robocode events onWin, onDeath, onBattleEnded, onRobotDeath, and onRoundEnded
+
| Handler for a single event that fires at the beginning of every round.  Can be used to initialize variables when a round begins.
 +
|-
 +
| RoundListener
 +
| No
 +
| Repackages Robocode events onRoundEnd and onBattleEnd
 
|-
 
|-
 
| ScannedRobotListener  
 
| ScannedRobotListener  
| AbstractXanderBot
+
| Yes
 
| Repackages Robocode event onScannedRobot
 
| Repackages Robocode event onScannedRobot
 +
|-
 +
| SurvivalListener
 +
| Yes
 +
| Repackages Robocode events onWin, onDeath, and onRobotDeath
 
|-
 
|-
 
| TurnListener  
 
| TurnListener  
| AbstractXanderBot
+
| No
| Event that fires on every iteration of the AbstractXanderBot main processing loop.  This event fires immediately before execute() is called.
+
| Handler for events that fire on every iteration of the AbstractXanderRobot main processing loop.  One event that fires at the beginning of a turn, and one event that fires at the end of a turn immediately before execute() is called.
 
|}
 
|}
  
= Xander Framework Components =
+
= Xander Utilities =
Most of these components are not considered part of the Xander framework core; they are more accurately thought of as components built for the Xander frameworkExceptions to this are '''CompoundDrive''' and '''CompoundGun''', which are part of the basic Xander philosophy of building ''drive trees'' and ''gun trees'', and the '''HeadOnTargeter''', as it is used by a Xander framework core class and must therefore be considered part of the framework.
+
 
== Xander Radars ==
+
== Logging ==
=== BasicRadar ===
+
 
Basic radar scan the field, and locks onto the first target it findsTarget can switch if another robot happens to be closer and drives through the scan beam.
+
The Xander framework provides basic logging services loosely based on the Log4J logging modelThough not nearly as configurable as Log4J logging, it is much more advanced than just using System.out.print statements.
 +
 
 +
Xander logs have the following levels, in order of significance:
 +
* DEBUG - Debugging messages.
 +
* INFO - Informational messages.  This is the default logging level.
 +
* WARNING - Warning messages. 
 +
* STAT - Statistics messagesThese are meant to be messages that are useful during development, but also of interest for a finished robot.
 +
* ERROR - Error messages.
  
== Xander Guns ==
+
Log levels are defined by the nested Enum named Level in the Log class (e.g. the level INFO would be accessed via Log.Level.INFO)
Xander guns must implement the '''Gun''' interface.
 
  
=== AntiMirrorGun ===
+
Logging consists of two classes:  Logger and LogEach class can have it's own Log. A Log is created by the Logger.   
Specifically for targeting opponents who use a mirroring drive strategyMust be used in combination with the '''AntiMirrorDrive'''.
 
=== BSProtectedGun ===
 
A wrapper for other guns that provides support for counteracting bullet shielding.
 
=== CircularTargeter ===
 
This gun is for targeting opponents that drive in circles.  If the opponent does not appear to be going in circles, this gun will not fire on the targetOne advantage this gun has over some other circular targeting implementations is that it works for circular paths that are centered anywhere, and is not limited to circular paths centered at the location bullet wave was fired from.  This gun pulverizes SpinBot.
 
  
=== HeadOnTargeter ===
+
A Log can currently be created in a manner similar to as follows:
Head-on shots.
+
<pre>
=== LinearTargeter ===
+
public class ExampleClass {
This gun is for targeting opponents that drive in a straight line.  It fires on the opponent based on the opponents current speed and heading.  It does not attempt to determine whether the target is actually moving in a straight line or not, but does compensate for battlefield bounds (don't shoot off the grid).  The linear intercept calculation is precise (not iterative nor an approximation).
 
  
=== StatTargeter ===
+
private static final Log log = Logger.getLog(ExampleClass.class);
This gun is a "guess factor" gun that relies on statistics to determine how to aim. It relies on a Segmenter to determine how to categorize the statistics it collects (Segmenter is a separate interface).  It requires a certain ''load'' before a segment will be used; when under that load, it uses an overall factor array with no segmentation.
 
  
=== AdvancedStatTargeter ===
+
}
Extends the StatGun, adding the capability of using an '''AdvancedSegmenter''' such that multiple combinations of segmenters can be used on the fly.
+
</pre>
 +
Once created, it can be used by calling the appropriate methods of the Log class as in the following example:
 +
<pre>
 +
log.info("This is an informational message.");
 +
</pre>
 +
Similar to Log4J, log messages will only be printed if the level of the message is at or above the level set in the Log.  By default, all Logs are at level INFO.  This can be changed globally on startup through the Logger class, or on a Log by Log basis.
  
=== CompoundGun ===
+
== Mathematics ==
Combines two or more other guns.  Compound gun delegates gunning to other guns based on a '''GunSelector'''.  By default, a '''CompoundGun''' uses the '''FirstAvailGunSelector'''.
 
  
==== GunSelector ====
+
=== RCMath ===
Compound guns can be set up with different gun selection modulesSome available gun selection modules include:
+
This class provides generic math helper functionsMost are targeted at solving Robocode problems, but are still usable in a more generic sense.
* '''FirstAvailGunSelector''' - original behavior before gun selectors, this one just hands off to the first gun it finds that claims it can fire at the target.
 
* '''HitRatioGunSelector''' - this gun selector looks at gun hit ratios and bullets fired for each gun to determine which gun to fire with.
 
* '''VirtualHitRatioGunSelector''' - this gun selector looks at ''virtual'' hit ratios for all guns to determine what gun to fire with.
 
  
== Xander Drives ==
+
=== RCPhysics ===
Xander drives must implement the '''Drive''' interface.
+
This class provides constants and methods that are only useful within the context of Robocode physics.  Some of what it provides is obsolete due to various additions to the Robocode API over the last few years -- specifically the Robocode Rules and Utils classes -- but I leave it there for posterity.
  
=== AntiMirrorDrive ===
+
== CPU Utilization ==
Drive specifically for use with opponents who use a mirroring drive strategyThis drive must be used in combination with the '''AntiMirrorGun'''.
+
The Xander framework also provides a few ways to track processing time.
 +
=== RunTimeLogger ===
 +
Provides an easy-to-use means for testing average and peak run times for any particular block of codeResults are logged to the console at the end of each round.
 +
=== CPU Utilization Painting ===
 +
CPU utilization can be graphed on screen by setting the ''drawCPUUtilization'' flag to true in the '''Configuration'''.
  
=== BasicSurferDrive ===
+
= Guess Factors and Wave Surfing =
This drive is an adaptation of the Wave Surfing drive used in the BasicGFSurfer robot.
+
At the fringe of the framework are a variety of classes for handling guess factors and wave surfing.  These classes are in package xander.gfws.  This package might be best described as an add-on to the framework, and is somewhat less mature than the core framework.
  
=== CompoundDrive ===
+
== Factor Array Processors ==
A drive that combines multiple other drives.  A CompoundDrive forms a ''branch'' of the ''drive tree'', with individual drives forming the ''leaves''.  Which drive to use is determined by a '''DriveSelector'''.
 
==== DriveSelector ====
 
Interface that provides the means for selecting between drives.
 
  
=== OrbitalDrive ===
+
A ''factor array processor'', defined by the '''FactorArrayProcessor''' interface, is responsible providing factor arrays for wavesOriginally, they were also meant to handle logging wave data, but some of the latest implementations let other classes handle logging data.
This drive approaches the target using linear targeting and then, when it range, orbits around the target, changing direction periodicallyIt originally also used "inverse gravity bullet avoidance", although this is no longer the case; this feature was an early experimental feature of the framework, and has since been removed in favor of tracking bullet "waves" without predicting the firing direction.
 
  
=== RamboDrive ===
+
The '''AbstractFactorArrayProcessor''' provides a basic implementation of this interface designed to work in both guess factor guns and and wave surfing drivesThis is an older implementation that is intended to handle logging data in addition to building factor arrays.
This drive attempts to ram the enemyIt can be configured so that it does not approach the enemy in a straight line, but the effectiveness may still be limited against the better bots out there.
 
  
=== RamEscapeDrive ===
+
== Distributers ==
For getting away from needy robots who always want a hug.
 
  
=== StatDrive ===
+
A ''distributer'', defined by the '''WeightDistributer''' interface, is responsible for distributing a set amount of weight into a factor array.
This drive is a Wave Surfing drive of my own design.  Similar to the StatGun, it supports using a segmenter, and a compound drive segmenter is available to combine the effects of multiple drive segmenters.
 
  
=== AdvancedStatDrive ===
+
Current available distributers include:
Extends the '''StatDrive''', adding the capability of using an '''AdvancedSegmenter'''.
+
*  '''PointDistributer''' - dumps all weight onto a single index.
 +
'''TriangleDistributer''' - weight is logged into a triangular region whose base width, by default, is equivalent to the width of the robot.
 +
'''WaveDistributer''' - weight is logged across the entire factor range, with weight decreasing exponentially the further it gets from the hit index.
  
 
== Segmentation ==
 
== Segmentation ==
Drives and guns now use a single set of segmenters.  Basic segmenters must implement the '''Segmenter''' interface.  Current available segmenters include:
+
 
'''AdvancedCompoundSegmenter''' - implements the '''AdvancedSegmenter''' interface, which in turn extends the '''Segmenter''' interface.  This is the most advanced form of segmenter that combines multiple other segmenters in a way where different combinations of those segmenters can be used independently.  It is used by the '''AdvancedStatDrive''' and '''AdvancedStatGun'''.
+
Wave surfing drives and guess factor guns can use segmenters.  Basic segmenters must implement the '''Segmenter''' interface.  There is also an '''AbstractSegmenter''' class for simple segmenters that operate on values within a fixed range.
*  '''CompoundSegmenter''' - A segmenter that combines multiple other segmenters.  The combined segmenters are always analyzed together in combination.
+
 
*  '''BulletSpeedSegmenter''' - segments on bullet speed
+
Current available segmenters include:
 +
*  '''AttackerBearingSegmenter''' - segments on the attacker's bearing from the back-as-front heading of the defender
 
*  '''BulletTravelTimeSegmenter''' - segments on bullet travel time
 
*  '''BulletTravelTimeSegmenter''' - segments on bullet travel time
 
*  '''DefenderAccelerationSegmenter''' - segments on defender acceleration
 
*  '''DefenderAccelerationSegmenter''' - segments on defender acceleration
 
*  '''DefenderSpeedSegmenter''' - segments on defender speed
 
*  '''DefenderSpeedSegmenter''' - segments on defender speed
*  '''DistanceSegmenter''' - segments on distance between robots
+
*  '''LateralVelocitySegmenter''' - segments on defender lateral velocity
*  '''LateralVelocitySegmenter''' - segments on lateral velocity
 
 
*  '''NullSegmenter''' - provides no segmentation (a segmenter with only a single segment).
 
*  '''NullSegmenter''' - provides no segmentation (a segmenter with only a single segment).
*  '''RelativeDirectionSegmenter''' - segments on whether opponent appears to be orbiting clockwise or counter-clockwise.
 
 
*  '''WallSmoothingSegmenter''' - segments on whether it appears defender will have to wall smooth clockwise, counter-clockwise, both directions (in corner), or not at all.
 
*  '''WallSmoothingSegmenter''' - segments on whether it appears defender will have to wall smooth clockwise, counter-clockwise, both directions (in corner), or not at all.
 +
*  '''WallStickSegmenter''' - segments on opponent distance to wall in the forward or reverse direction of the defenders current direction.
 +
 +
== Utilities ==
  
= Xander Utilities =
+
A '''FactorArrays''' utility class provides static methods for common factor array functions such as converting between factor angles and factor indexes.
  
== Logging ==
+
== Drives ==
  
The Xander framework provides basic logging services loosely based on the Log4J logging modelThough not nearly as configurable as Log4J logging, it is much more advanced than just using System.out.print statements.
+
The '''DirectWaveSurfingDrive''' (named '''DWaveSurfingDrive''' in v9.3 of XanderCat) class provides the basic implementation for a ''direct'' wave surfing drive, relying on a ''direct surf selector'' to choose the factor angle and direct heading to use for each waveSurf selectors are defined by the '''DirectSurfSelector''' interface.
  
Xander logs have the following levels, in order of significance:
+
This drive is capable of surfing 2 waves at once, though only surfs a single wave by default.  It is a Go-To style wave surfing drive, but will reprocess where to go on the same wave under the following situations:
* DEBUG - Debugging messages.
+
* when surf wave is updated (such as when a newly fired bullet creates new bullet shadows)
* INFO - Informational messages.  This is the default logging level.
+
* when opponent position deviates significantly from prediction.  This is done primarily for the sake of distancing.
* WARNING - Warning messages. 
 
* STAT - Statistics messages.  These are meant to be messages that are useful during development, but also of interest for a finished robot.
 
* ERROR - Error messages.
 
  
Log levels are defined by the nested Enum named Level in the Log class (e.g. the level INFO would be accessed via Log.Level.INFO)
+
The xander.gfws package does not provide any surf selector implementations. However, XanderCat 9.3+ uses a surf selector named '''GreenBeeSurfSelector''' which other surf selectors might be modeled from. It uses a ''factor array processor'' for managing the drive data, along with a '''DirectDrivePredictor''' and '''DistancingEquation''' from the Xander core classes to aid in choosing what direction to move in.
  
Logging consists of two classes:  Logger and Log.  Each class can have it's own Log.  A Log is created by the Logger. 
+
== Guns ==
  
A Log can currently be created in a manner similar to as follows:
+
The '''GuessFactorTargeter''' class provides the basic implementation of a guess factor targeter, and utilizes a ''factor array processor'' and ''weight distributer'' for it's operation.
<pre>
 
public class ExampleClass {
 
  
private static final Log log = Logger.getLog(ExampleClass.class);
+
= Components Built on Xander =
 +
The components listed in this section are not considered part of the Xander framework core; they are example components built for the Xander framework that I use in my various robots. Exceptions to this are the '''HeadOnTargeter''', as it is used by a Xander framework core class and must therefore be considered part of the framework.
  
}
+
== Xander Radars ==
</pre>
 
Once created, it can be used by calling the appropriate methods of the Log class as in the following example:
 
<pre>
 
log.info("This is an informational message.");
 
</pre>
 
Similar to Log4J, log messages will only be printed if the level of the message is at or above the level set in the Log.  By default, all Logs are at level INFO.  This can be changed globally on startup through the Logger class, or on a Log by Log basis.
 
  
The main Xander robot class, AbstractXanderBot, provides a protected method getDefaultLogLevel() for setting the global logging level on startupRobots using the Xander framework can override this method to change the default logging level for all Logs.
+
=== BasicRadar ===
 +
Basic radar scan the field, and locks onto the first target it findsTarget can switch if another robot happens to be closer and drives through the scan beam.
  
== Mathematics ==
+
== Xander Guns and Targeters ==
  
=== Circular ===
+
=== AntiMirrorGun ===
This class contains methods specific to circular targeting.  These methods are available outside the CircularGun because it is possible that other components may have use for calculating circular paths.
+
Specifically for targeting opponents who use a mirroring drive strategy.  Must be used in combination with the '''AntiMirrorDrive'''.
 +
=== BSProtectedGun ===
 +
A wrapper for other guns that provides support for counteracting bullet shielding.
 +
=== CircularTargeter ===
 +
This targeter is for targeting opponents that drive in circlesIf the opponent does not appear to be going in circles, this gun will not fire on the target.  One advantage this gun has over some other circular targeting implementations is that it works for circular paths that are centered anywhere, and is not limited to circular paths centered at the location bullet wave was fired from.  This gun pulverizes SpinBot.
  
=== Linear ===
+
=== HeadOnTargeter ===
This class contains methods specific to linear targeting.  These methods are available outside the LinearGun because it is possible thar other components may have use for calculating linear pathsFor example, a drive may be interested in approaching an opponent using a linear intercept path.
+
Head-on shots.
 +
=== LinearTargeter ===
 +
This targeter is for targeting opponents that drive in a straight line.  It fires on the opponent based on the opponents current speed and headingIt does not attempt to determine whether the target is actually moving in a straight line or not, but does compensate for battlefield bounds (don't shoot off the grid)The linear intercept calculation is precise (not iterative nor an approximation).
  
=== MathUtil ===
+
== Xander Drives ==
This class provides generic math helper functions.  Most are targeted at solving Robocode problems, but are still usable in a more generic sense. 
 
  
=== RoboPhysics ===
+
=== AntiMirrorDrive ===
This class provides constants and methods that are only useful within the context of RobocodeSome of what it provides is obsolete due to various additions to the Robocode API over the last few years -- specifically the Robocode Rules and Utils classes -- but I leave it there for posterity.
+
Drive specifically for use with opponents who use a mirroring drive strategyThis drive must be used in combination with the '''AntiMirrorGun'''.
  
= Xander Code Examples =
+
=== BasicSurferDrive ===
== Radars, Gun, and Drives ==
+
This drive is an adaptation of the Wave Surfing drive used in the BasicGFSurfer robot.
Radars, Guns, and Drives all follow a similar pattern.  Each must implement an interface.  The methods defined in the interfaces provide a ''controller'' as an argumentControllers are actually wrappers for the main robot class that limit exposure of main class methods to only those methods they should be allowed to callFor example, a Gun is allowed to call methods to turn the gun, but is not allowed to call methods that would turn the radar or robot body.
+
 
 +
=== GreenBeeSurfSelector ===
 +
This class is a ''direct surf selector'' which can be used in a '''DirectWaveSurfingDrive'''.  It utilizes a ''factor array processor'' for managing data and building a factor array to surfIt also utilizes the '''DirectDrivePredictor''' and '''DistancingEquation''' classes from the Xander core in it's operation.
  
As an example, below is the Gun interface.  However, note that it will likely change before the Xander framework is considered complete:
+
The basic steps in it's operation are:
<pre>
+
#  Create two sets of test drive angles, one for clockwise, one for counter-clockwise.
/**
+
#  Determine greatest reachable factors and end positions when driving at each test angle.
  * Interface to be implemented by Xander gun classes.
+
# Reduce the set of test angles to consider based on the distancing provided by the '''DistancingEquation'''.
  *
+
# Determine greatest reachable factor range after distancing is applied.
  * @author Scott Arnold
+
# If reachable factor range after distancing is applied is too constricted, expand the test range back out until it is not.
  */
+
# Use the '''FactorArrayProcessor''' to get the factor array to surf.
public interface Gun extends StaticResource {
+
#  Choose which factor angle to move to in the surf array.
 +
#  Choose test angle that optimizes distancing while still reaching the chosen factor angle for the wave.
  
/**
+
=== IdealPositionDrive ===
* Returns the name of this gun.  The name should be unique among guns.
+
Attempts to ideally position the robot on the battlefield.  This should only be used when no enemy bullets are in play.
*
 
* @return    name of gun
 
*/
 
public String getName();
 
 
/**
 
* If this gun is a wrapper for another gun or guns, this method should
 
* return the name of the gun that is wrapped or would be used for
 
* firing bullets.  Otherwise, this method should just return getName().
 
*
 
* @return
 
*/
 
public String getNestedName();
 
 
/**
 
* Controllers are recreated at the beginning of each round.  This
 
* method can be used to initialize the gun at the beginning of
 
* each round with the new gun controller.
 
*
 
* @param gunController    the gun controller
 
*/
 
public void initializeForNewRound(GunController gunController);
 
 
/**
 
* Returns whether or not this can is currently capable of aiming and
 
* firing on the given robot.  This method should be lightweight (most
 
* guns should just return true).
 
*
 
* @param target          snapshot of robot to fire at
 
* @param gunController    gun controller
 
*
 
* @return                whether or not gun can fire on opponent
 
*/
 
public boolean canFireAt(RobotSnapshot target, GunController gunController);
 
 
/**
 
* Aim and fire upon the given opponent.  Since guns are also required
 
* to have the getAim method, this method can generally call that
 
* method to get the aim.  The only extra work in this method is
 
* actually turning the gun and firing.
 
*
 
* @param target          snapshot of opponent
 
* @param myself          snapshot of self
 
* @param gunController    gun controller
 
*/
 
public void fireAt(RobotSnapshot target, RobotSnapshot myself, GunController gunController);
 
  
/**
+
=== RamEscapeDrive ===
* Returns the aim information for the given opponent. 
+
For getting away from needy robots who always want a hug.
*
 
* @param target    the opponent to target
 
* @param myself    snapshot of self
 
*
 
* @return          aim information for the given opponent
 
*/
 
public Aim getAim(RobotSnapshot target, RobotSnapshot myself);
 
}
 
</pre>
 
At present, Controllers are recreated at the beginning of each round.  It is primarily for this reason that the initialize(...) method is provided.
 
  
== Main Robot Class ==
+
= Xander Code Examples =
  
'''Note:  This section is way outdated and needs to be updated.'''
+
== Example Robot Class ==
  
As an example of how the Xander framework is used, below is the source for the main robot class of XanderCat 2.0.
+
Stripped version of XanderCat main robot class (some content removed to provide simplified example):
 
<pre>
 
<pre>
/**
+
public class XanderCat extends AbstractXanderRobot {
* 1-on-1 robot built on the Xander framework.  Also suitable for melee.
+
 
*
 
* @author Scott Arnold
 
*/
 
public class XanderCat extends AbstractXanderBot {
 
 
 
@Override
 
@Override
protected Level getLogLevel() {
+
protected void style(RobotStyle robotStyle) {
return Log.Level.INFO;
+
robotStyle.setColors(Color.WHITE, Color.BLACK, Color.GREEN);
 
}
 
}
  
 
@Override
 
@Override
protected Radar createRadar() {
+
protected void configure(Configuration configuration) {
return new BasicRadar(this, 45, 5);
+
configuration.setLogComponentRunTimes(true);
 +
configuration.setLogDriveTimes(true);
 
}
 
}
  
 
@Override
 
@Override
protected Drive createDrive() {
+
protected boolean recordBattleStats(Map<String, String> oppStats) {
return new OrbitalDrive(this, 200, 40, 0.5f);
+
GunStats gunStats = Resources.getGunStats();
 +
double oHR = gunStats.getOverallOpponentHitRatio();
 +
double mHR = gunStats.getOverallHitRatio();
 +
oppStats.put("OppHitRatio", Logger.format(oHR,3));
 +
oppStats.put("MyHitRatio", Logger.format(mHR,3));
 +
return true;
 
}
 
}
  
 
@Override
 
@Override
protected Gun createGun() {
+
protected void addComponents(ComponentChain chain) {
FiringProfile firingProfile = new FiringProfile(
+
1.0d, 500d, 3.0d, 150d, 0.5d, 450d, 700d);
+
// RADAR
Segmenter segmenter = new CompoundSegmenter(
+
new BulletTravelTimeSegmenter(getName(), 12, getBattlefieldBounds()),
+
chain.addDefaultComponents(new BasicRadar(45, 5));
new RelativeDirectionSegmenter(10));
+
return new CompoundGun(
+
// DRIVES
new StatGun(this, firingProfile, 1000, 10, 30, segmenter, true),
+
new CircularGun(firingProfile),
+
Path2D.Double driveBounds = DriveBoundsFactory.getSmoothedRectangleBounds(getBattleFieldSize());
new LinearGun(firingProfile));
+
 
}
+
RamFactory.addAntiRamComponents(chain);
 +
 +
MirrorFactory.addAntiMirrorComponents(chain, 12);
  
 +
Scenario ipScenario = new NoOpponentWavesScenario();
 +
Drive ipDrive = new IdealPositionDrive();
 +
chain.addComponents(ipScenario, ipDrive);
 +
 +
...
 +
Drive mainDrive = ...
 +
...
 +
Drive tdDrive = ...
 +
DriveSelector driveSelector = new HighPerformanceDriveSelector(mainDrive, 50, 0.08);
 +
DriveArray driveArray = new DriveArray(driveSelector, mainDrive, tdDrive);
 +
 +
chain.addDefaultComponents(driveArray);
 +
 +
// GUNS 
 +
 +
// a special scenario just for our circular drivers out there!
 +
XanderGun circularGun = new XanderGun(new CircularTargeter(), mainPowerSelector);
 +
circularDriverScenario = new CircularDriveScenario(circularGun);
 +
chain.addComponents(circularDriverScenario, circularGun);
 +
 +
// main guess factor guns
 +
...
 +
Gun[] guns = new Gun[2];
 +
...
 +
VirtualHitRatioGunSelector gunSelector = new VirtualHitRatioGunSelector();
 +
gunSelector.setRollingRatioWeight(0.25);
 +
GunArray gunArray = new GunArray(gunSelector, guns);
 +
 +
chain.addDefaultComponents(gunArray);
 +
}
 
}
 
}
 
</pre>
 
</pre>
Line 377: Line 484:
 
In order to remember information from one battle to the next, it is necessary to save that information in some static variable or object.  However, this would seem to cause problems if you want to pit a robot against itself, or if you want to run two different robots off of the same base framework classes.  This would seem to be a problem because suddenly you have two or more distinct robots sharing certain static resources, when each robot should have it's own unique set.  However, Robocode uses a separate class loader for every robot, putting each robot in it's own isolated sandbox.  This means static variables are not shared among robots.
 
In order to remember information from one battle to the next, it is necessary to save that information in some static variable or object.  However, this would seem to cause problems if you want to pit a robot against itself, or if you want to run two different robots off of the same base framework classes.  This would seem to be a problem because suddenly you have two or more distinct robots sharing certain static resources, when each robot should have it's own unique set.  However, Robocode uses a separate class loader for every robot, putting each robot in it's own isolated sandbox.  This means static variables are not shared among robots.
  
The Xander framework attempts to adhere to good object oriented practices; declaring variables or objects as static to preserve them between rounds is considered contrary to this.  Therefore, the Xander framework provides a ''static resource manager''.  The static resource manager is a singleton that stores objects in a static Map.  Whenever a variable or object needs to be kept or retrieved from round to round, the static resource manager instance is obtained, and then the variable or object is stored or retrieved from it.
+
The Xander framework attempts to adhere to good object oriented practices; declaring variables as static to preserve them between rounds is considered contrary to this.  Therefore, the Xander framework hides this necessity by storing most objects as static behind the scenes, rather than relying on overuse of static variables.
 
 
The static resource manager supports storing three different kinds of objects, which are referred to as ''resources'', ''properties'', and ''static objects'':
 

Latest revision as of 18:01, 16 April 2017

Xander Framework

The Xander framework is an AdvancedRobot framework that makes it easy to build new bots by combining different guns, radars, and drives. It is based on an abstract class named AbstractXanderRobot that extends AdvancedRobot. All basic framework classes are in the package xander.core. As an optional add-on to the framework, some more advanced yet less mature guess factor and wave surfing classes are in package xander.gfws. When looking at any of my Xander robots, anything outside of the xander.core and xander.gfws packages are components built for the Xander framework, not part of the Xander framework itself.

With a Xander robot, the main robot class need only set up a component chain populated with your guns, radars, and drives. It can also optionally override methods to change basic configuration options and write battle statistics to disk.

Guns, radars, and drives must use the corresponding framework interfaces and can make use of a variety of framework resources and events.

The current framework version available for the last few years is considered v2.0. Version 3.0 is current in development. Version 3.0 brings several advancements over the older version through a revised component structure, including:

  • Full melee support.
  • Simplified components, but without losing any prior functionality.
  • Reduced code size.
  • Improved performance.

Version Notes

Some interesting notes about each version of the framework.

Version 1.0

Version 1.0 had the basics complete, but lacked some of the more advanced functionality like tracking wave history.

Version 2.0

Version 2.0 added more advanced functionality like wave history and has been the main version from about 2013 up through 2017. Version 2.0 was tailored primarily for 1 vs 1 combat, and had certain deficiencies when attempting to use it for other purposes. It was structured to have 1 of each framework component, and only some of them were written to accommodate more than 1 opponent on the battlefield.

Version 3.0

Version 3.0 is under development in 2017. It's purpose is to add full melee or multi-opponent support, simplify some of the code, reduce code size, and improve performance in a few areas. Version 3.0 takes on a new component strategy where some components that can apply to a single robot now only apply to a single robot. This means some main framework components will now have 1 instance for each known robot, instead of a single instance that must handle all robots. One of the challenges with this approach is that robot specific opponents are now generated as knowledge of their existence is gained, instead of existing from the very beginning of the battles. This is a challenge because you can no longer always fully construct your robot at the very beginning, because some parts must be created or expanded as new robots are scanned. The framework is being rewritten to support this in as convenient a fashion as possible.

The main framework components that will now have 1 for every robot (including self) include the SnapshotHistory, WaveHistory, and GunStats components.

Any listeners for robot specific components (anything that implements WaveListener, ScannedRobotListener, etc) must now implement an additional method getOpponentFocus() that tells the framework what robots to associate the component with. Focus options include:

  • ALL_ROBOTS: Component will receive events for all robots.
  • TARGETED_ROBOT: Component will only receive events from the currently targeted robot (the targeted robot determined by what your radar is returning).
  • SPECIFIC_ROBOT_SCANNED: Component will only receive events for one specific robot. That robot will be the last scanned robot at time listener is added, or the next scanned robot if there is no last scanned robot.
  • SPECIFIC_ROBOT_TARGETED: Component will only receive events for one specific robot. That robot will be the last targeted robot at time listener is added, or the next targeted robot if there is no current target.

Base Robot Class

Xander robots extend the AbstractXanderRobot class, which in turn extends the Robocode AdvancedRobot class. The AbstractXanderRobot class contains basic robot setup code and a basic processing loop.

The basic setup code performs as follows:

  • set all setXxxForRobotXxx values to true.
  • if first round:
    • call configure(Configuration)
    • call style(RobotStyle)
    • initialize Resources
    • call addComponents(ComponentChain)
  • apply robot styling (done every round in case win code changes styling)
  • issue round begin event

The basic processing loop performs as follows:

  • issue turn begin event
  • Process component chain to select radar, drive, and gun
  • Query radar for target
  • If no target is locked...
    • Tell drive to drive without a target
  • Otherwise...
    • Tell drive to drive with given target
    • If target is disabled and configuration allows...
      • Fire on target with Head-On gun
    • Otherwise...
      • Fire on target with gun
  • issue turn end event
  • call execute()

A Xander robot must implement the following methods:

  • addComponents(ComponentChain) - for setting up component chain

In addition, a Xander robot may optionally override the following methods:

  • void configure(Configuration) - allows basic configuration of the robot to be changed
  • void style(RobotStyle) - allows setting styling options like robot colors
  • boolean recordBattleStats(Map<String, String>) - allows robot to save battle statistics to file; key is statistic name, value is statistic value as String. Statistics are saved in the BattleStats class which is written to file as a Java object using an ObjectOutputStream.

Components / Component Chain

In a Xander robot, guns, drives, and radars are referred to as components. Components are managed within a component chain represented by the ComponentChain class. The component chain follows the general concepts of the Chain of Responsibility design pattern. It consists of a series of ComponentScenario objects that are responsible for selecting a radar, drive, and gun to use for each turn. The chain is followed from the beginning to the end, each ComponentScenario passing off to the next, until a radar, drive, and gun have all been selected for the current turn.

The component chain is set up at the beginning of the first round by a call to the abstract method

addComponents(ComponentChain)

. Each link in the chain has a Scenario that is responsible for deciding whether or not the components for that link should be used or not. This design makes it easy to handle situations where more than one component should be used in combination. All specialized scenarios should be set up by calls to

addComponents(...)

, while main or default components to be used when no specialized scenario applies should be set up by a call to

addDefaultComponents(...)

.

Example:

Assume you have a mainRadar, mainDrive and mainGun for a robot. Assume you also have a ramDrive and ramGun that should be used together against robots who use a ramming strategy. For this, a Scenario ramScenario could be written to test if a robot is using a ramming strategy. The component chain would then be set up as follows:

protected void addComponents(ComponentChain chain) {
	...
	chain.addComponents(ramScenario, ramDrive, ramGun);
	chain.addDefaultComponents(mainRadar, mainDrive, mainGun);
}

Resources

Classes within a Xander robot have easy access to a number of resources which can be accessed through the Resources class.

DriveStats

Statistics related to the drives of your robot, such as drive time usage.

GunStats

Statistics related to the guns, including hit ratios and virtual gun hit ratios. As of v3.0, one GunStats will be created for each robot in the battle.

RobotEvents

Manages all major event listeners, including all of the repackaged AdvancedRobot events.

RobotProxy

Access to all robot getXxx methods outside of the main robot class itself should be accessed via the RobotProxy object.

SnapshotHistory

Robot history is available through the SnapshotHistory. Robot history for a particular point in time is stored in a snapshot via the Snapshot class, an immutable snapshot of a robot at a particular point in time. As of v3.0, One SnapshotHistory will be created for each robot in the battle.

Each turn, a Xander robot takes a new snapshot for itself and stores it in the history. Each scan, a new snapshot for the scanned robot is generated and stored in the history. Robot history allows the robot to look back at snapshots of itself and it's opponents back a set number of turns and scans.

WaveHistory

History of all bullet waves. As of v3.0, one WaveHistory is created for each robot.

Controllers

Radars, guns, and drives control the robot through controller classes. The controllers for radar, gun, and drive provide access to the radar, gun, and drive related setXxx methods of the robot. This approach helps to prevent components from doing operations that are outside their area of responsibility, and also prevents components from calling the basic Robot control methods, or any methods that would immediately cause a turn to end. Controllers may also have other helper methods.

Radar

Radars must implement the Radar interface. In a Xander robot, the radar is responsible for operating the radar and selecting a Snapshot of a robot for the drive and gun to focus on.

public interface Radar extends Component {

	/**
	 * Prepare next sweep of radar and return snapshot of robot currently
	 * being focused upon.
	 * 
	 * @param radarController  radar controller
	 * 
	 * @return     snapshot of robot to attack
	 */
	public Snapshot search(RadarController radarController);
}

Drive

Drives must implement the Drive interface.

public interface Drive extends Component {
	
	/**
	 * Drive into optimal firing range of the given robot.
	 * 
	 * @param opponentSnapshot   robot to drive against
	 * @param driveController    drive controller
	 */
	public void driveTo(Snapshot opponentSnapshot, DriveController driveController);
	
	/**
	 * Drive without any specific target.
	 * 
	 * @param driveController    drive controller
	 */
	public void drive(DriveController driveController);
}

Drive Array

In cases were the robot should choose between a variety of drives based on some common criteria, a drive array can be set up using the DriveArray class. A drive array must have a drive selector, defined by the DriveSelector interface.

Gun

Guns must implement the Gun interface. However, rather than creating a gun class and directly implementing the gun interface, the recommended approach for a Xander robot is to use the XanderGun class. The XanderGun class relies on two other interfaces: Targeter and PowerSelector. A PowerSelector decides on what fire power to use, while the Targeter determines how to aim the gun based on what the bullet velocity will be. When using a XanderGun, you create classes that implement Targeter and PowerSelector, and the XanderGun takes care of the rest, including:

  • Preparing information for self and target. This takes the latest snapshots and predicts them one turn into the future (necessary for a more accurate aim due to how the Robocode processing loop operates), and passes those to the Targeter for aiming.
  • Calling the setXxx methods to aim the gun and fire bullets.
  • Auto-adjusting the fire power for low energy situations (so long as the PowerSelector allows it). Fire power is modified based on the current state of the target and self. Power selection steps are as follows:
    • Get preferred fire power from the PowerSelector.
    • If power is more than is required to kill the target, reduce firepower to what is needed for a kill.
    • If target is not disabled and firing bullet would disable self, reduce firepower such that it will not disable self.
public interface Gun extends Component {
	
	/**
	 * Aim and fire upon the given opponent.  Since guns are also required
	 * to have the getFiringVector method, this method can generally call that 
	 * method to get the aim.  The only extra work in this method is 
	 * actually turning the gun and firing.
	 * 
	 * @param target           snapshot of opponent
	 * @param myself           snapshot of self
	 * @param gunController    gun controller
	 * 
	 * @return          whether or not a bullet was fired
	 */
	public boolean fireAt(Snapshot target, Snapshot myself, GunController gunController);

	/**
	 * Returns the aim information for the given opponent.  
	 * 
	 * @param target    the opponent to target
	 * @param myself    snapshot of self
	 * 
	 * @return          aim information for the given opponent
	 */
	public Aim getAim(Snapshot target, Snapshot myself);
	
	/**
	 * Returns whether or not this can is currently capable of aiming and 
	 * firing on the given robot.  This method should be lightweight (most
	 * guns should just return true).
	 * 
	 * @param target           snapshot of robot to fire at
	 * 
	 * @return                 whether or not gun can fire on opponent
	 */
	public boolean canFireAt(Snapshot target);
}

Gun Array

In cases were the robot should choose between a variety of guns based on some criteria, a gun array can be set up using the GunArray class. A gun array must have a gun selector, defined by the GunSelector interface. A gun array can be set up to fire virtual bullets.

Historical Note: The GunArray operates much like the CompoundGun of the Xander 1.0 framework. However, it is no longer intended for the construction of trees (though technically it is still possible to create one). For the Xander 2.0 framework, most component selections are expected to be handled by the component chain.

Events

Robocode issues a number of different events to the robot. A Xander framework robot repackages these events and also provides other custom events, and makes those available to other components. Xander robots can make use of the following events accessed through the RobotEvents class (v3.0):

Listener Class Opponent Focusable? Purpose
BulletHitListener Yes Repackages Robocode events onHitByBullet, onBulletHit, onBulletMissed, and onBulletHitBullet
CollisionListener No Repackages Robocode events onHitRobot and onHitWall
WaveListener Yes Handles events related to a robot's bullet waves. The WaveHistory stores two sets of WaveListeners, one for actual bullet waves, and one for virtual bullet waves. If listening for both, you can tell the difference between the two by the Wave method isVirtual().
Painter No Repackages Robocode event onPaint, allowing other components to paint on the battlefield
RoundBeginListener No Handler for a single event that fires at the beginning of every round. Can be used to initialize variables when a round begins.
RoundListener No Repackages Robocode events onRoundEnd and onBattleEnd
ScannedRobotListener Yes Repackages Robocode event onScannedRobot
SurvivalListener Yes Repackages Robocode events onWin, onDeath, and onRobotDeath
TurnListener No Handler for events that fire on every iteration of the AbstractXanderRobot main processing loop. One event that fires at the beginning of a turn, and one event that fires at the end of a turn immediately before execute() is called.

Xander Utilities

Logging

The Xander framework provides basic logging services loosely based on the Log4J logging model. Though not nearly as configurable as Log4J logging, it is much more advanced than just using System.out.print statements.

Xander logs have the following levels, in order of significance:

  • DEBUG - Debugging messages.
  • INFO - Informational messages. This is the default logging level.
  • WARNING - Warning messages.
  • STAT - Statistics messages. These are meant to be messages that are useful during development, but also of interest for a finished robot.
  • ERROR - Error messages.

Log levels are defined by the nested Enum named Level in the Log class (e.g. the level INFO would be accessed via Log.Level.INFO)

Logging consists of two classes: Logger and Log. Each class can have it's own Log. A Log is created by the Logger.

A Log can currently be created in a manner similar to as follows:

public class ExampleClass {

	private static final Log log = Logger.getLog(ExampleClass.class);

}

Once created, it can be used by calling the appropriate methods of the Log class as in the following example:

	log.info("This is an informational message.");

Similar to Log4J, log messages will only be printed if the level of the message is at or above the level set in the Log. By default, all Logs are at level INFO. This can be changed globally on startup through the Logger class, or on a Log by Log basis.

Mathematics

RCMath

This class provides generic math helper functions. Most are targeted at solving Robocode problems, but are still usable in a more generic sense.

RCPhysics

This class provides constants and methods that are only useful within the context of Robocode physics. Some of what it provides is obsolete due to various additions to the Robocode API over the last few years -- specifically the Robocode Rules and Utils classes -- but I leave it there for posterity.

CPU Utilization

The Xander framework also provides a few ways to track processing time.

RunTimeLogger

Provides an easy-to-use means for testing average and peak run times for any particular block of code. Results are logged to the console at the end of each round.

CPU Utilization Painting

CPU utilization can be graphed on screen by setting the drawCPUUtilization flag to true in the Configuration.

Guess Factors and Wave Surfing

At the fringe of the framework are a variety of classes for handling guess factors and wave surfing. These classes are in package xander.gfws. This package might be best described as an add-on to the framework, and is somewhat less mature than the core framework.

Factor Array Processors

A factor array processor, defined by the FactorArrayProcessor interface, is responsible providing factor arrays for waves. Originally, they were also meant to handle logging wave data, but some of the latest implementations let other classes handle logging data.

The AbstractFactorArrayProcessor provides a basic implementation of this interface designed to work in both guess factor guns and and wave surfing drives. This is an older implementation that is intended to handle logging data in addition to building factor arrays.

Distributers

A distributer, defined by the WeightDistributer interface, is responsible for distributing a set amount of weight into a factor array.

Current available distributers include:

  • PointDistributer - dumps all weight onto a single index.
  • TriangleDistributer - weight is logged into a triangular region whose base width, by default, is equivalent to the width of the robot.
  • WaveDistributer - weight is logged across the entire factor range, with weight decreasing exponentially the further it gets from the hit index.

Segmentation

Wave surfing drives and guess factor guns can use segmenters. Basic segmenters must implement the Segmenter interface. There is also an AbstractSegmenter class for simple segmenters that operate on values within a fixed range.

Current available segmenters include:

  • AttackerBearingSegmenter - segments on the attacker's bearing from the back-as-front heading of the defender
  • BulletTravelTimeSegmenter - segments on bullet travel time
  • DefenderAccelerationSegmenter - segments on defender acceleration
  • DefenderSpeedSegmenter - segments on defender speed
  • LateralVelocitySegmenter - segments on defender lateral velocity
  • NullSegmenter - provides no segmentation (a segmenter with only a single segment).
  • WallSmoothingSegmenter - segments on whether it appears defender will have to wall smooth clockwise, counter-clockwise, both directions (in corner), or not at all.
  • WallStickSegmenter - segments on opponent distance to wall in the forward or reverse direction of the defenders current direction.

Utilities

A FactorArrays utility class provides static methods for common factor array functions such as converting between factor angles and factor indexes.

Drives

The DirectWaveSurfingDrive (named DWaveSurfingDrive in v9.3 of XanderCat) class provides the basic implementation for a direct wave surfing drive, relying on a direct surf selector to choose the factor angle and direct heading to use for each wave. Surf selectors are defined by the DirectSurfSelector interface.

This drive is capable of surfing 2 waves at once, though only surfs a single wave by default. It is a Go-To style wave surfing drive, but will reprocess where to go on the same wave under the following situations:

  • when surf wave is updated (such as when a newly fired bullet creates new bullet shadows)
  • when opponent position deviates significantly from prediction. This is done primarily for the sake of distancing.

The xander.gfws package does not provide any surf selector implementations. However, XanderCat 9.3+ uses a surf selector named GreenBeeSurfSelector which other surf selectors might be modeled from. It uses a factor array processor for managing the drive data, along with a DirectDrivePredictor and DistancingEquation from the Xander core classes to aid in choosing what direction to move in.

Guns

The GuessFactorTargeter class provides the basic implementation of a guess factor targeter, and utilizes a factor array processor and weight distributer for it's operation.

Components Built on Xander

The components listed in this section are not considered part of the Xander framework core; they are example components built for the Xander framework that I use in my various robots. Exceptions to this are the HeadOnTargeter, as it is used by a Xander framework core class and must therefore be considered part of the framework.

Xander Radars

BasicRadar

Basic radar scan the field, and locks onto the first target it finds. Target can switch if another robot happens to be closer and drives through the scan beam.

Xander Guns and Targeters

AntiMirrorGun

Specifically for targeting opponents who use a mirroring drive strategy. Must be used in combination with the AntiMirrorDrive.

BSProtectedGun

A wrapper for other guns that provides support for counteracting bullet shielding.

CircularTargeter

This targeter is for targeting opponents that drive in circles. If the opponent does not appear to be going in circles, this gun will not fire on the target. One advantage this gun has over some other circular targeting implementations is that it works for circular paths that are centered anywhere, and is not limited to circular paths centered at the location bullet wave was fired from. This gun pulverizes SpinBot.

HeadOnTargeter

Head-on shots.

LinearTargeter

This targeter is for targeting opponents that drive in a straight line. It fires on the opponent based on the opponents current speed and heading. It does not attempt to determine whether the target is actually moving in a straight line or not, but does compensate for battlefield bounds (don't shoot off the grid). The linear intercept calculation is precise (not iterative nor an approximation).

Xander Drives

AntiMirrorDrive

Drive specifically for use with opponents who use a mirroring drive strategy. This drive must be used in combination with the AntiMirrorGun.

BasicSurferDrive

This drive is an adaptation of the Wave Surfing drive used in the BasicGFSurfer robot.

GreenBeeSurfSelector

This class is a direct surf selector which can be used in a DirectWaveSurfingDrive. It utilizes a factor array processor for managing data and building a factor array to surf. It also utilizes the DirectDrivePredictor and DistancingEquation classes from the Xander core in it's operation.

The basic steps in it's operation are:

  1. Create two sets of test drive angles, one for clockwise, one for counter-clockwise.
  2. Determine greatest reachable factors and end positions when driving at each test angle.
  3. Reduce the set of test angles to consider based on the distancing provided by the DistancingEquation.
  4. Determine greatest reachable factor range after distancing is applied.
  5. If reachable factor range after distancing is applied is too constricted, expand the test range back out until it is not.
  6. Use the FactorArrayProcessor to get the factor array to surf.
  7. Choose which factor angle to move to in the surf array.
  8. Choose test angle that optimizes distancing while still reaching the chosen factor angle for the wave.

IdealPositionDrive

Attempts to ideally position the robot on the battlefield. This should only be used when no enemy bullets are in play.

RamEscapeDrive

For getting away from needy robots who always want a hug.

Xander Code Examples

Example Robot Class

Stripped version of XanderCat main robot class (some content removed to provide simplified example):

public class XanderCat extends AbstractXanderRobot {

	@Override
	protected void style(RobotStyle robotStyle) {
		robotStyle.setColors(Color.WHITE, Color.BLACK, Color.GREEN);
	}

	@Override
	protected void configure(Configuration configuration) {
		configuration.setLogComponentRunTimes(true);
		configuration.setLogDriveTimes(true);
	}

	@Override
	protected boolean recordBattleStats(Map<String, String> oppStats) {
		GunStats gunStats = Resources.getGunStats();
		double oHR = gunStats.getOverallOpponentHitRatio();
		double mHR = gunStats.getOverallHitRatio();
		oppStats.put("OppHitRatio", Logger.format(oHR,3));
		oppStats.put("MyHitRatio", Logger.format(mHR,3));
		return true;
	}

	@Override
	protected void addComponents(ComponentChain chain) {
				
		// RADAR
		
		chain.addDefaultComponents(new BasicRadar(45, 5));
		
		// DRIVES
		
		Path2D.Double driveBounds = DriveBoundsFactory.getSmoothedRectangleBounds(getBattleFieldSize());

		RamFactory.addAntiRamComponents(chain);
		
		MirrorFactory.addAntiMirrorComponents(chain, 12);

		Scenario ipScenario = new NoOpponentWavesScenario();
		Drive ipDrive = new IdealPositionDrive();
		chain.addComponents(ipScenario, ipDrive);
		
		...
		Drive mainDrive = ...
		...
		Drive tdDrive = ...		
		DriveSelector driveSelector = new HighPerformanceDriveSelector(mainDrive, 50, 0.08);
		DriveArray driveArray = new DriveArray(driveSelector, mainDrive, tdDrive);		
						
		chain.addDefaultComponents(driveArray);
		
		// GUNS  
		
		// a special scenario just for our circular drivers out there!
		XanderGun circularGun = new XanderGun(new CircularTargeter(), mainPowerSelector);
		circularDriverScenario = new CircularDriveScenario(circularGun);
		chain.addComponents(circularDriverScenario, circularGun);
		
		// main guess factor guns
		...
		Gun[] guns = new Gun[2];
		...
		VirtualHitRatioGunSelector gunSelector = new VirtualHitRatioGunSelector();
		gunSelector.setRollingRatioWeight(0.25);
		GunArray gunArray = new GunArray(gunSelector, guns);
				
		chain.addDefaultComponents(gunArray);
	}	
}

Handling Static Data

In order to remember information from one battle to the next, it is necessary to save that information in some static variable or object. However, this would seem to cause problems if you want to pit a robot against itself, or if you want to run two different robots off of the same base framework classes. This would seem to be a problem because suddenly you have two or more distinct robots sharing certain static resources, when each robot should have it's own unique set. However, Robocode uses a separate class loader for every robot, putting each robot in it's own isolated sandbox. This means static variables are not shared among robots.

The Xander framework attempts to adhere to good object oriented practices; declaring variables as static to preserve them between rounds is considered contrary to this. Therefore, the Xander framework hides this necessity by storing most objects as static behind the scenes, rather than relying on overuse of static variables.