API reference


To play a game, you have to learn to talk with our A.T.H.E.N.A. battle-system. To do that, you use A.T.H.E.N.A.'s Application Programming Interface (API). The API describes a set of "magic words" to:
a) tell A.T.H.E.N.A. you want to perform an action in the game, or
b) ask A.T.H.E.N.A. for information



Game API

In the game, your Javascript code gets access to a special Game object. This Game object provides the API for you to perform actions on each round of the game. (If you're curious, all the actual code for the functions listed below is here: game.js)
Game.moveTo(dragonID, x, y)
Move your Dragon (specified by dragonID) to position (x, y) on the board.
Game.attack(dragonID, target)
Order your Dragon (specified by dragonID) to attack a target. target can be an enemy Dragon's ID, or a position on the board (E.g., {x: 0 y: 0}).
Game.carryOrb(dragonID)
Order your Dragon to pick up an Orb. Your Dragon will pick up an Orb if it is within range. Otherwise, this function has no effect. Your Dragon moves slower when it is carrying an Orb.
Game.dropOrb(dragonID)
Order your Dragon to drop the Orb it is carrying. If it is not carrying an Orb, this function has no effect.
Game.mark(dragonID, mark)
Mark a Dragon on the screen. mark can by any text string. Note that this does not affect the game in any way. It is just to help you identify friendly or enemy Dragons on the screen.
Game.getAvailableHeroClasses()
Get the available hero classes you may summon in the current game using Game.setClass(). You will get the names of the hero classes as well as how many of each you may summon. Example structure returned by this function: {'bighorn': 1, 'longtail': 1, 'little-wing': 1}.
Game.setClass(dragonID, className)
Before a game starts, you may transform one of your Dragons into a hero Dragon. Hero Dragons are available if you have unlocked them from the Solo Quests and they are playable for a particular map/level/game. The possible hero Dragon classNames are 'bighorn', 'longtail', 'little-wing' and 'brightfang'. You may only call this function from your init function, which you pass to Game.registerInit().
Game.setPlayerColor(colorHex)
Before a game starts, you may change the color of your Dragons. E.g., Game.setPlayerColor("#00FF00"). You may only call this function from your init function, which you pass to Game.registerInit().
Game.registerInit(init)
Register a function that runs once before the game starts.
Game.register(run)
Register a function that runs on each round of the game.
Game.log(msg)
Print to the browser's console. This is useful for debugging. In the Chrome browser, press F12 to open the console to see everything you print with Game.log(). Logs for each round are collected and printed together in a group.


Helper API

For your convenience, your Javascript code also gets access to a Helper library during the game. None of the functions in Helper are essential -- they are just to help you get started. You might find that as your coding skills evolve, you'll outgrow these functions and start writing your own ones to replace them. (If you're curious, all the actual code for the functions listed below is here: gamehelper.js)
Helper.computeDistance(a, b)
Compute the distance between two points a and b. Each point must be of the form {x:, y:}.
Helper.computeRetreatPoint(dragonPos, enemyPos)
Compute where to move to retreat from an enemy Dragon. Pass this function the positions of your Dragon and an enemy Dragon. This function returns a point in the form of {x:, y:}, which you can pass to Game.moveTo(). This moves your Dragon away from the enemy Dragon.
Helper.getMyUnits(state)
This function returns an array of your Dragon units. Call this function with the state object that is passed to your run() function on each round. Note that this function returns both alive and dead Dragons. To check if a Dragon is alive, you can check dragon.isAlive or dragon.health > 0.
Helper.getAliveEnemyUnits(state)
Returns an array of enemy Dragon units that are still alive. Call this function with the state object that is passed to your run() function on each round.
Helper.getClosestEnemy(state, dragonUnit)
Returns the closest enemy to one of your units. Pass this function a Dragon unit object (E.g., one of the units returned by getMyUnits()).
This function returns {unit:, dist:}, where unit is the closest enemy Dragon unit and dist is how far away it is. If there are no alive enemy Dragons, null is returned.
Helper.getClosestOrb(state, dragonUnit)
Returns the Orb closest to Dragon unit. If there are no Orbs, null is returned.
Helper.getClosestBase(state, dragonUnit)
Returns the friendly Base closest to a Dragon unit. If there are no friendly Bases, null is returned.
Helper.getClosestEnemyBase(state, dragonUnit)
Returns the enemy Base closest to Dragon unit. If there are no enemy Bases, null is returned.


Secret goodies (for advanced coders)

The state object that gets passed to your run() function on each round: 
 
  state = {
    units: [
      [{ 
        id: 0,
        name: "normal", // unlock "bighorn", "longtail" 
                        // or "little-wing" via Solo Quests
        health: 100,
        maxHealth: 100,
        shields: 100,
        maxShields: 100,
        speed: 80,
        pos: {x:0, y:0},
        target: {x:0, y:0}, // or null if not attacking
        cargo: null, // to check if carrying Orb
        canKeepAttacking: true,
        isAlive: true
      }], // player 1 units
      [{
        ...
      }]  // player 2 units
    ],
    orbs: [{
      id: 0,
      isAvailable: true,
      capturedByPlayerId: null,
      pos: {x:0, y:0}
    }],
    bases: [
      [{
          id: 0,
          pos: {x:0, y:0}
      }], // player 1 bases
      [{
        ...
      }]  // player 2 bases
    ]
  }
A few examples of how to get game info directly from state: 

  // 1. get your Dragons
  var myDragons = state.units[Game.getPlayerId()];
  
  // 2. find out how many Dragons you have
  var numDragons = myDragons.length;
  
  // 3. loop through all your Dragons
  for (var i=0; i < numDragons; i++)
  {
      var dragon = myDragons[i];
      // TODO: do something with 'dragon'
  }