turnInfo [ int, int, int ]

[0] : Turn type, can be either: 0, 1 or 2. 0 = Deploy Phase, 1 = Action Phase, 2 = End Game.

[1] : Turn number, an integer representing the turn number, the game starts on turn 0.

[2] : Action phase frame number, starts with 0 every action phase, is -1 when a turn frame since not in action phase.

p1Stats, p2Stats [ int, float, float, int ]

[0] : Player Health

[1] : Structure Points (SP)

[2] : Mobile Unit Points (MP)

[3] : Time taken last turn in milliseconds

p1Units, p2Units [ [], [], [], [], [], [], [] ]

See UnitStats below for how units are formatted.

[0] : List of WALL units.

[1] : List of FACTORY units.

[2] : List of TURRET units.

[3] : List of SCOUT units.

[4] : List of DEMOLISHER units.

[5] : List of INTERCEPTOR units.

[6] : List of firewall locations marked to REMOVE.

[7] : List of locations where the firewall has an UPGRADE.

Unit Stats [ int, int, float, string ]

A single unit's stats are represented as a list as follows: [

[0] : X coordinate.

[1] : Y coordinate.

[2] : Unit health. For REMOVE this is number of turns before removal.

[3] : Unique string identifier for each game object. Will stay the same between frames throughout the game.

]

events { string: [] }

Contains various events that can trigger during the action phase.

{

  "selfDestruct": [],

  "breach": [],

  "damage": [],

  "shield": [],

  "move": [],

  "spawn": [],

  "death": [],

  "attack": [],

  "melee": [],

}

Unit Type int

Integer that corresponds to the array index of unit list in p1Units and p2Units and Unit Information. For example, 3 would correspond to a SCOUT.

selfDestruct [ [ [], [] , float, int, string, int ] , ... ]

List of self destruct events. Self destructs occur when a unit's path is blocked. Each occurance is its own list.

List describing single self destruct event: [

[0] : [ X, Y ] Formatted location of self destructing unit.

[1] : [ [ X1, Y1 ], [ X2, Y2 ] ... ] List of formatted locations of targets affected by self destruct damage.

[2] : Damage done by self destruct as a float.

[3] : Integer UnitType of unit that self destructed.

[4] : ID for unit that self destructs. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[5] : Player number for player that owns the unit that self destructed. Either 1 or 2.

]

breach [ [ [] , float, int, string, int ] , ... ]

List of breach events. A breach occurs when a unit scores by reaching the opposite side. Each occurance is its own list.

List describing single breach event: [

[0] : [ X, Y ] Formatted location of breaching unit.

[1] : Player health damage done by breach. Currently, will always be 1.

[2] : Integer UnitType of unit that breached.

[3] : ID for unit that breaches. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[4] : Player number for player that owns the unit that breached. Either 1 or 2.

]

damage [ [ [] , float, int, string, int ] , ... ]

List of damage events. Damage occurs when a unit takes damage from any source.

List describing single damage event: [

[0] : [ X, Y ] Formatted location of damaged unit.

[1] : Damage, as a float, taken by unit.

[2] : Integer UnitType of unit that was damaged.

[3] : ID for unit that got damaged. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[4] : Player number for player that owns the unit that was damaged. Either 1 or 2.

]

shield [ [ [] , [] , float, int, string, int ] , ... ]

List of shield events. Shield events occur when a STRUCTURE gives a shield to a mobile unit. Note that in some configs, the shield mechanic is not used.

List describing single shield event: [

[0] : [ X, Y ] Formatted location of unit that is giving the shield.

[1] : [ X, Y ] Formatted location of target tile that is being given a shield.

[2] : Shield amount, as a float.

[3] : Integer UnitType of unit that is being shielded.

[4] : ID for unit that gives the shield. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[5] : ID for unit that receives the shield. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[6] : Player number for player that owns the unit that gives sheild. Either 1 or 2.

]

move [ [ [] , [] , [] , int, string, int ] , ... ]

List of move events. Move events occur when a unit moves from one position to another.

List describing single move event: [

[0] : [ X, Y ] Formatted location of unit before it moved.

[1] : [ X, Y ] Formatted location of unit, now, after it moved.

[2] : [ X, Y ] No longer used, deprecated. Was previously where the unit planned to move next.

[3] : Integer UnitType of unit that has moved.

[4] : ID for unit that has moved. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[5] : Player number for player that owns the unit that has moved. Either 1 or 2.

]

spawn [ [ [] , int, string, int ] , ... ]

List of spawn events. Spawn occurs when a new unit is added to the game.

List describing single spawn event: [

[0] : [ X, Y ] Formatted location of newly spawned unit.

[1] : Integer UnitType of unit that spawned.

[2] : ID for unit that spawned. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[3] : Player number for player that owns the unit that spawned. Either 1 or 2.

]

death [ [ [] , int, string, int, bool ] , ... ]

List of death events. Death occurs when a unit is removed from the game through getting damaged, player removal, or breaching.

List describing single death event: [

[0] : [ X, Y ] Formatted location of dead unit.

[1] : Integer UnitType of unit that died.

[2] : ID for unit that died. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[3] : Player number for player that owns the unit that died. Either 1 or 2.

[4] : Boolean, if true was a player removing their own firewall.

]

attack [ [ [] , [] , float, int, string, string, int ] , ... ]

List of attack events. Attack events occur when a unit attacks another unit. Does not include self destructs.

List describing single attack event: [

[0] : [ X, Y ] Formatted location of unit that is attacking.

[1] : [ X, Y ] Formatted location of target tile that is being attacked.

[2] : Damage, as a float, done by unit attacking.

[3] : Integer UnitType of unit that is doing the attack.

[4] : ID for unit that performs the attack. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[5] : ID for unit that gets attacked. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[6] : Player number for player that owns the unit that is attacking. Either 1 or 2.

]

melee [ [ [] , [] , float, int, string, int ] , ... ]

List of melee events. Melee is no longer used, deprecated. Melee previously occured when two opposing units occupied the same or adjacent spaces.

List describing single melee event: [

[0] : [ X, Y ] Formatted location of unit that is attacking with a melee.

[1] : [ X, Y ] Formatted location of target tile that is being attacked by melee.

[2] : Damage, as a float, done by unit in the melee.

[3] : Integer UnitType of unit that is doing a melee attack.

[4] : ID for unit that performs the melee attack. Unique string identifier for each game object. Will stay the same between frames throughout the game.

[5] : Player number for player that owns the unit melee attacking. Either 1 or 2.

]

endStats { ... }

Contains various stats about the finished game.

{

  "duration": Integer representing time in milliseconds that the game took to compute.

  "winner": Integer representing player who won the game 1 for player1, 2 for player2.

  "turns": Integer representing turns taken for game to finish.

  "frames": Integer representing total number of action frames that occurred during the game.

  "player1": { ... },

  "player2": { ... },

}

Player End Stats { ... }

Contains various stats about the player after a finished game.

{

"stationary_resource_spent": Float representing how many stationary units worth of resources were deployed.

"dynamic_resource_spoiled": Float representing how many resources used to deploy moving units were wasted from decay.

"crashed": Boolean describing if the algo crashed or timed out.

"name": String for the name of the algo, based on the folder the algo is saved in.

"dynamic_resource_destroyed": Float representing amount of resources spent on moving units who died before breaching.

"time_damage_taken": Float representing damage taken from going over the time limit.

"dynamic_resource_spent": Float representing total resources spent deploying moving units.

"stationary_resource_left_on_board": Float describing how many resources worth of stationary units remain on the board belonging to this player.

"timeout_death": Boolean representing if the algo failed to submit a move in time and was forced to skip its turn completely.

"points_scored": Float representing total amount of player health done to the enemy player.

"total_computation_time": Integer for the time in milliseconds the algo took to compute in total for the entire match.

}

debug { ... }

Contains various booleans that enable or disable what is printed when running a game.

{

"printMapString": Boolean, if true will print a text version of the map to console.

"printTStrings": Boolean, if true will print a list of all units currently on the board at the start of every turn.

"printActStrings": Boolean, if true will print a list of all units currently on the board at the start of every action frame.

"printHitStrings": Boolean, if true will print whenever a unit attacks another unit.

"printPlayerInputStrings": Boolean, if true will print the string received by the each player at the end of every turn.

"printBotErrors": Boolean, if true will print the standard error printed by each algo.

"printPlayerGetHitStrings": Boolean, if true will print whenever a unit breaches and does player health damage.

}

unitInformation [ {}, {}, {}, {}, {}, {}, {} ]

List containing dictionary objects describing stats about each unit. The list index corresponds to a units UnitType.

{

[0]: Stationary unit config describing WALL.

[1]: Stationary unit config describing FACTORY.

[2]: Stationary unit config describing TURRET.

[3]: Moving unit config describing SCOUT.

[4]: Moving unit config describing DEMOLISHER.

[5]: Moving unit config describing INTERCEPTOR.

[6]: Remove config describing REMOVE.

[7]: Upgrade config describing UPGRADE.

}

Stationary Unit Config { ... }

Contains config variables for stationary units in the game WALL, FACTORY, TURRET.

{

"damage": Float describing how much damage the unit will do to enemies if they are in range.

"cost": Float representing how many stationary resources are required to deploy the unit.

"getHitRadius": Float describing how big this units hitbox is.

"display": String for the name of the unit.

"range": Float for the range of the unit.

"shorthand": String for the shorthand of the unit, is used to communicate what units an algo wishes to deploy.

"stability": Float for the health of the unit. When it is 0 or below the unit will die.

"generatesResource1": Float for the amount of MP this unit will generate each round

"generatesResource2": Float for the amount of SP this unit will generate each round

}

Moving Unit Config { ... }

Contains config variables for dynamic moving units in the game SCOUT, DEMOLISHER, INTERCEPTOR.

{

"icon": String used on playground to select an icon for the unit.

"iconxScale": Float used on playground to scale the unit icon

"iconyScale": Float used on playground to scale the unit icon

"damageI": Float describing how much damage the unit will do to moving units in range.

"damageToPlayer": Float describing how much damage the unit will do to player health if it breaches.

"cost": Float representing how many dynamic resources are required to deploy the unit.

"getHitRadius": Float describing how big this units hitbox is.

"damageF": Float describing how much damage the unit will do to stationary units in range.

"display": String for the name of the unit.

"range": Float for the range of the unit.

"shorthand": String for the shorthand of the unit, is used to communicate what units an algo wishes to deploy.

"stability": Float for the health of the unit. When it is 0 or below the unit will die.

"speed": Float for the speed of a unit, (1 / speed) determines how many frames it takes before the unit will move.

}

Removal Config { ... }

Contains config variables for REMOVE.

{

"display": String for the name of the unit.

"shorthand": String for the shorthand of the unit, is used to communicate what units an algo wishes to deploy.

}

Upgrade Config { ... }

Contains config variables for UPGRADE.

{

"display": String for the name of the unit.

"shorthand": String for the shorthand of the unit, is used to communicate what units an algo wishes to deploy.

}

timingAndReplay { ... }

Contains various variables relating to how long each algo has per turn and whether replays are saved. Note times are split between PLAY-MODE, values used for playground games, and WORK-MODE used for ranked games. When running the engine locally it uses WORK-MODE values, play values can be ignored.

{

"waitTimeBotMax": Integer, time in milliseconds before an algo will skip its turn for WORK-MODE.

"playWaitTimeBotMax": Integer, time in milliseconds before an algo will skip its turn for PLAY-MODE.

"waitTimeManual": Integer, time in milliseconds before a player playing by hand will skip their turn in PLAY-MODE.

"waitForever": Boolean, if true will grant infinite time for all modes and all player types.

"waitTimeBotSoft": Integer, time in milliseconds before an algo will start taking damage for taking too long for its turn in WORK-MODE.

"playWaitTimeBotSoft": Integer, time in milliseconds before an algo will start taking damage for taking too long for its turn in PLAY-MODE.

"replaySave": Integer, for WORK-MODE. If set to 0 will not save any replays, if set to 1 will save replays in player1's perspective, if set to 2 will save in player2's perspective, and 3 will save two replays for both player1 and player2 perspectives.

"playReplaySave": Integer, for PLAY-MODE. If set to 0 will not save any replays, if set to 1 will save replays in player1's perspective, if set to 2 will save in player2's perspective, and 3 will save two replays for both player1 and player2 perspectives.

"storeBotTimes": Boolean, if true will save how long each algo took in milliseconds last turn. Turning this to false can cause problems in algo frame parsing so it is advised to always keep this set to true.

"waitTimeStartGame": Integer, time in milliseconds spent waiting before a game starts. Is set to allow algos time to initialze and load in dependencies.

"waitTimeEndGame": Integer, time in milliseconds after the game ends before the process will terminate. Is set to allow time for all socket messages to send to their destinations including algo error logs and buffered frames. Also allows algos to save any information as algos will terminate when the engine terminates. For local play can be set to a much lower value.

}

resources { ... }

Contains various variables related to resources given to players throughout the game. Bits and Cores are legacy terms for MP and SP.

{

"turnIntervalForBitCapSchedule": Integer, deprecated was previously used for a slowly ramping maximum MP.

"turnIntervalForBitSchedule": Integer, every time this number of turns occurs, MP given per turn increases by the amount given by "bitGrowthRate".

"bitRampBitCapGrowthRate": Float, deprecated was previously used for a slowly ramping maximum MP.

"bitGrowthRate": Float, determines how many additional MP per turn players get every "turnIntervalForBitSchedule".

"startingHP": Float, determines how much starting player health each player gets.

"maxBits": Float, maximum amount of MP a player can hold. In most configs, the bit decay mechanic is the limiting factor on MP a player can store.

"bitsPerRound": Float, amount of MP per round a player will receive at the start of a match. The actual amount the player receives later in the game will be influenced by the current turn number, "turnIntervalForBitSchedule" and "bitGrowthRate".

"coresPerRound": Float, amount of SP per round a player will receive throughout the match.

"coresForPlayerDamage": Depricated, replaced by "metalForBreach" so it can be customized per-unit. Metal is another legacy term for SP.

"startingBits": Float, amount of MP players receive when starting the match.

"bitDecayPerRound": Float, at the end of every round before extra MP are allocated a percentage of the players current MP are discarded. This mechanic is to balance deploying a large stack of units all at once and give a tradeoff between saving MP and deploying them periodically.

"startingCores": Float, amount of SP given to each player at the start of a match.

}

mechanics { ... }

Contains various variables that influence gameplay mechanics.

{

"basePlayerHealthDamage": Float, how much player health damage will be received on a breach.

"damageGrowthBasedOnY": Float, depracated determined how much player health damage was done based on how deep the unit was in enemy territory when breaching.

"bitsCanStackOnDeployment": Boolean, if true will allow more than one moving unit to be deployed on the same location.

"destroyOwnUnitRefund": Float, determines what fraction of a unit's cost is refunded when a stationary unit is removed by the player who owns it.

"destroyOwnUnitsEnabled": Boolean, if true allows players to remove their own stationary units.

"stepsRequiredSelfDestruct": Integer, minimum number of steps a unit has to take before its self destruct does damage. Used to balance the self destruct mechanic.

"selfDestructRadius": Float, radius from the self destructing unit's center that determines what units will be damaged by a self destruct.

"shieldDecayPerFrame": Float, what fraction of a shield will decay per frame.

"meleeMultiplier": Float, depracated determines how much damage a melee attack does, melee attacks are no longer used.

"destroyOwnUnitDelay": Integer, number of turns before a unit will be removed when a player attempts to remove their own stationary unit.

"rerouteMidRound": Boolean, deprecated determines if a unit will reroute when a stationary unit is destroyed in the middle of a round. This is not currently supported, setting this to false will cause undefined behavior.

"firewallBuildTime": Integer, deprecated determines how many turns a stationary unit will take to spawn. This is not currently supported, setting this variable higher than 0 may cause undefined behavior.

}