Client Library

To use the StratagusAI client API the main task is to create your own implementation of the Controller interface, and to write a configuration file. The Controller interface methods are called to inform the implementing class when various events occur. These method calls give the implementor a chance to set actions for the player's units, to begin collecting evaluation statistics, or to reset the state at the start of an episode. The relationships between the main classes are shown in the UML diagram below.

The Controller event methods are documented in the code as follows:

    /**
     * Set parameters from the configuration.
     */
    public void configure(ControllerConfig conf);
    
    /**
     * Set the next actions of a Player's objects.  Called on every
     * frame update.
     */
    void nextActions(GameProxy game);

    /**
     * A session consists of evaluation or training cycles.
     */
    void beginSession(GameProxy game);

    /**
     * Begin training or evaluation cycle.
     */
    void beginCycle(GameProxy game, boolean training);

    /**
     * Begin an episode.  An episode is one stratagus game.
     */
    void beginEpisode(GameProxy game);

    /**
     * Notify controller when game is over.
     */
    void endEpisode(GameProxy game);

    /**
     * Training or evaluation cycle is done.
     */
    void endCycle(GameProxy game, boolean training);

    /**
     * Notify controller when all episodes are done.  Time to clean up.
     */
    void endSession(GameProxy game);

The client library contains two example Controller implementations: HeuristicAgent, and RandomAgent. The RandomAgent randomly chooses an enemy unit for each allied unit to attack. The HeuristicAgent chooses the closest enemy unit to each allied unit to attack.

The GameRunner class implements a game loop that calls the Controller methods and updates the GameProxy state. The GameTrainer is a subclass of GameRunner that alternates training and evaluation cycles. These classes and the Controller classes can be configured using a YAML configuration file that is passed to the Main class.

Here's an example YAML file that configures a GameRunner to run 30 episodes on 2 stratagus maps, and configures two competing Controllers from the stratsim project to play the episodes:

!!orst.stratagusai.config.Config
# Episodes to run.  250 episodes run in about 20 minutes
episodes: 30
mapPaths: [../../maps/the-right-strategy.smp,../../maps/the-right-strategy_switched.smp]
agentConfigs:
- !!orst.stratagusai.config.ControllerConfig
  controllerClassName: orst.stratagusai.stratplan.mgr.StrategyController
  params: !!map
    re-plan: true
    planner: !!map
      className: orst.stratagusai.stratsim.planner.GoalDrivenPlanner
      strategy: footmans_rush_7_mass
      opponent: footmans_rush_7_mass
    tactical: orst.stratagusai.taclp.TacticalManager
    production: orst.stratagusai.prodh.ProductionManager
- !!orst.stratagusai.config.ControllerConfig
  controllerClassName: orst.stratagusai.stratplan.mgr.StrategyController
  params: !!map
    re-plan: true
    planner: !!map
      className: orst.stratagusai.stratsim.planner.GoalDrivenPlanner
      strategy: footmans_rush_7_mass
    tactical: orst.stratagusai.taclp.TacticalManager
    production: orst.stratagusai.prodh.ProductionManager

To run your own Controllers you will also need to make a shell script that sets the Java classpaths to include your Controller code. Here's an example:

@echo off

REM add common JARS to classpath.  classpaths.bat in stratagusai/tools.
call ..\..\tools\classpaths

REM Your Controller JARs.  %M2% is the location of Maven JAR repository set in classpaths above
SET CP=%CP%;%M2%\orst\your-project\1.0-SNAPSHOT\your-project-1.0-SNAPSHOT.jar

SET JAVA_CMD="java"

%JAVA_CMD% -ea -classpath %CP% orst.stratagusai.Main %*

Then your Controllers can be run using the command:

client -c config.yaml