AO RTS

Goal

Write an AI to command your troops to gather the most resources in the time allotted. You gather resources by exploring the map, finding resources, executing a gather action, and then returning to your base with the gathered resources. The AI communicates over TCP via a JSON protocol.

API

The server will connect to your client. You will start receiving messages in the format:

{
  player: 0,
  turn: 12,
  time: 300000, // time remaining in game
  'unit_updates': [{ // your unit's updates
    id:16,
    player_id: 0,
    x: 0, y: 0,
    status:"moving",
    type:"worker",
    resource:0,
    health:5,
    can_attack:true // cooldown is ready
  }],
  'tile_updates': [{
    // relative to your base
    x: 7, y: -9,
    visible: true,
    blocked: false,
    resources: {
      id: 12,
      type: "small",
      total:200,
  value:10
    },
    units: [{
      id:60,
      type:"tank",
      status:"unknown", // tile update statuses can only be unknown or dead
      player_id: 1,
      health: 10
    }]}
  ],
}

unit_updates

Any time something about one of your units changes, (position, status, etc), you will receive an update.

tile_updates

Any time something about a tile changes, (enemy units, visibility, etc), you will receive an update.

time

This is the amount of time remaining in the game (in milliseconds).

turn

This is the current turn of the game. Each turn is 200ms.

Sending commands

To command your units, send messages to the server using the format:

{
  commands: [
    {command: "MOVE", unit: 2, dir: "N"},
    {command: "MOVE", unit: 3, dir: "S"},
    {command: "GATHER", unit: 7, dir: "S"},
    {command: "DROP", unit: 9, dir: "E", value: 10},
    {command: "CREATE", type: "worker"},
    {command: "SHOOT", unit: 4, dx: 3, dy: 2},
    {command: "MELEE", unit: 4, target: 2},
  ]
}

Warning!

The protocol is newline delimited. Make sure your JSON has all but its last newline stripped!

Commands

Commands are your AI's way of telling the server what you want your units to do. Some commands take many turns to complete. When finished executing a command, a unit's status will be set to idle.

MOVE: unit,dir Move a unit by id in a given direction N,S,E,W. Command will be ignored if the unit cannot move in the specified direction or is currently executing a previous MOVE command. Units can occupy the same location.

GATHER: unit,dir Tell a unit to collect from a resource in the specified direction N,S,E,W. Command will be ignored if the unit cannot gather in the specified direction. Resources are automatically deposited by walking over the players base.

DROP: unit,dir, value Tell a unit to drop value resources in the specified direction N,S,E,W. Command will be ignored if the unit cannot drop in the specified direction (unit in the way).

CREATE: type Create a new unit by type: worker,scout,tank. Command is ignored if the player's base does not have enough resources.

SHOOT: unit,dx,dy Tell the unit to shoot a location relative to the attacker. All units at the location will be damaged (including your own). Command is ignored if the location is out of the attacker's range (within unit vision). Each unit has an attack cooldown. can_attack will be sent down as true when they can attack again.

MELEE: unit,target Tell the unit to melee a nearby unit. Command is ignored if target unit is more than a single tile away. Each unit has an attack cooldown. can_attack will be sent down as true when they can attack again.

IDENTIFY: unit, name Name the unit (or player if left blank). This name will only show on the graphical server window. Command is ignored if the unit is owned by another player.

Note:

When a unit has died, its status will be set to "dead".
Dead units will no longer respond to your commands.

Units

BASE: When joining the game, your base will be placed at a random location on the map. Map locations will be sent from the server relative to your base's location (i.e. A location of x: 1, y: 1 would indicate the tile 1 step east and 1 step south of your base).

WORKER: You will start the game with 6 workers. Workers are the only unit that can carry resources. They have average vision, speed, health, and a weak melee attack. Cost: 100.

SCOUT: Scouts have longer vision, faster speed, lower health, and a weak melee attack. Cost 130.

TANK: Tanks have average vision, slower speed, higher health, and a ranged attack. Cost 150.

^*turns per tile (tpt): Number of turns required to move from one grid location to the next. Smaller is faster.

Communication Overview

Your chosen starter kit should implement the basic communication protocol with the server.

The server will send updates to each connected AI at the beginning of a turn. The server then waits a specifed amount of time (defaults to 200ms) for each AI to send commands. It processes any received commands and then advances to the next turn.

Note that in fast mode (which will be used in the tournament) the server will advance to the next turn after it receives a single message from each AI (or the time limit expires) and so you'll want to batch your commands for each turn into a single message.

Ask your coach if you need detail in addition to what's listed here.

JSON Schema

Message from Server

Unit

* Optional: may or may not be present depending on the unit type.

Tile

Tile Resource

Enemy Units

Game Info

Unit Info

Results

Setting Up the game

• checkout repo
• install ruby 2.3.x or newer
• install Gosu dependencies (mac | linux)
• install bundler: gem install bundler
• cd server
• bundle install
• ruby src/app.rb

Running the game

$ruby src/app.rb --help
usage: src/app.rb [options]
  -p1, --p1_host     player 1 host [localhost]
  -p1p, --p1_port    player 1 port [9090]
  -p2, --p2_host     player 2 host
  -p2p, --p2_port    player 2 port [9090]
  -m, --map          map filename to play (json format) [map.json]
  -l, --log          log entire game to game-log.txt
  -f, --fast         advance to the next turn as soon as all clients have sent a message
  -fs, --fullscreen  Run in fullscreen mode
  -nu, --no_ui       No GUI; exit code is winning player
  -t, --time         length of game in ms [300000]
  -drb, --drb_port   debugging port for tests
  -p1n, --p1_name    player 1 name
  -p2n, --p2_name    player 2 name
  --help             print this help

Notes

1. Disconnecting. Game will continue, but you will lose control of your units.
2. Games are logged to game-log.txt

Creating your own maps

You may want to test out edge cases or set up situations for testing that are not in the training maps. Maps are built using Tiled. To build your own:

• Download and Install Tiled
• Copy an existing map
• Update layers
  • blocked layer has cells filled in that are not walkable
  • objects has resources and base starting locations (copying existing resources/bases will maintain needed type properties)
  • environment has decorative tiles
• export the map as JSON with Map -> Properties -> Tile Layer Format set to CSV