Usage

Documentation for classes and methods is available as Javadoc. You can either access it using your IDE when using the -full variant. Or you can view our hosted Javadoc site.

The goal of the Java-Bot Library is to make writing a bot as easy as possible.
To achieve this, the library gives you access to a collection of classes that can be used to interact with the game.

It also gives you access to the ChallengeBot and CreativeBot classes.
Your bot can use them as parent classes, so you only have to one method. The javabot repository contains example bots for both classes:

• ExampleChallengeBot
• ExampleCreativeBot

CubeCoordinates

TerraTactician-Expandoria uses CubeCoordinates as the coordinate system.
You can find a more detailed introduction here.

The Bot Library contains a CubeCoordiante class, which does most of the work for you.

Useful methods include:

• this.getRing(int): Returns a Java Iterator, which iterates over all tiles on the hexagon-circle around this with a radius int.
• this.getArea(int): Returns a Java Iterator, which iterates over all tiles in the area between this and the hexagon-circle with radius int.
• You can use the .add, .sub, .mul, .div, .neg methods to perform common vector operations.

ChallengeBot

The ChallengeBot class can be used to develop bots for challenge-compatible gamemodes (Challenge Mode, most Campaign-Levels, Zen Mode).
When extending the ChallengeBot class, you can put all your code into the executeTurn method. This method will be called once every second.
Your bot then has 40 ms to determine the next action and return from the method, ending the turn. \ If your bot takes too long to end its turn, it will be suspended for one turn.

You can use the Controller to specify your next turn.
A couple of examples:

@Override
public void executeTurn(World world, Controller controller) {
    // Places the first tile in your hand at (0,0,0), without checking if the
    // coordinate is valid or if the hand has cards.
    // Take a look at `world.getHand().len()` to check how many cards are in
    // the hand. `world.getBuildArea().contains(coord)` and 
    // `world.getMap().at(coord)` to check if the cell is empty.
    controller.placeTile(world.getHand().get(0), new CubeCoordinate(0, 0, 0));

    // The command above is equivalent to:
    controller.selectSlot(0);
    controller.placeTile(new CubeCoordinate(0, 0, 0));

    // You can also place tiles using their type
    // (assuming that you have them in your hand)
    controller.placeTile(TileType.Wheat, new CubeCoordinate(0, 0, 0));
    // If you want to pass data to the tile when placing it,
    // you can specify a class directly
    controller.placeTile(
        new MarketplaceTile().withFoodRatio(0.5),
        new CubeCoordinate(0, 0, 0));
    
    // You can also pick up cards:
    CubeCoordinate coord = /* ... */ ;
    // Make sure to check if the card can be picked up
    if (world.getMap().at(coord).takeable()) {
        // Pick up the card
        controller.takeTile(coord);
    }
 
    // You can collect rewards using the following method
    controller.collectReward(/* coord */);
    
    // Redraw cards
    controller.redraw();

    // If you want to configure the marketplace after placing it,
    // use the following method
    controller.configureMarket(/* coord */, /* food [0.0-1.0] */, /* materials [0.0-1.0] */);
}

You can find necessary information in the World class.

• BuildArea getBuildArea() - Returns an object with information about the build area.
• Hand getHand() - Returns an object containing all cards in the hand.
• Map getMap() - Returns an object containing all tiles placed in the world.
• Metrics getRedrawCosts() - Returns an object containing the current redraw price.
• double getRedrawTime() - Returns the time until the next free redraw, in seconds
• Metrics getResources() - Returns an object containing the amount of resources collected.
• Metrics getResourcesRate() - Returns an object containing the current production rate. (The amount of resources produced per second).
• Rewards getRewards() - Returns an object containing all the rewards that can be collected right now.
• int getRound() - Returns the current round starting with 0. (The UI starts with round 1.)
• double getRoundTime() - Returns the time left in the current round in seconds.
• Metrics getTargetResources() - Returns an object containing the current resource target.

CreativeBot

The CreativeBot class has fewer restrictions than the ChallengeBot class. However, it can only be used to develop bots that can be used in Creative Mode.

After establishing a connection to the game, the startGame method will be called.
The connection will be closed once you return from it.

Inside the method, you have the ability to communicate with the game using the ConnectionHandler.

It allows you to send Actions:
(You can find a list of all Actions in the Java-documentation.)

public void startGame(ConnectionHandler conn) {
    conn.send(new PlaceAction(new WheatTile(new CubeCoordinate(0, 0, 0))));
}

You can also listen to Events sent from the game:
(You can find a list of all Events in the Java-documentation.)

public void startGame(ConnectionHandler conn) {
    conn.register(EventType.TileClicked, (Event evt) -> {
        TileClickedEvent event = (TileClickedEvent) evt;
        System.out.println(event);
    });
}

Because the execution time of the startGame method is not limited, you can also use Thread.sleep to delay execution.

public void startGame(ConnectionHandler conn) {
   CubeCoordinate.AreaIterator iter = new CubeCoordinate(0, 0, 0).getArea(10);

   while (running && iter.hasNext()) {
       conn.send(new PlaceAction(new WheatTile(iter.next())));
       try {
           // Waits 2 seconds
           Thread.sleep(2000);
       } catch (Exception e) {}
   }
}