Intent

An Intent is an action performed on the game's back-end database. These actions range from a creep moving from one position to another using creep.move() to executing Game.market.deal(). Intents can be generated by players calling in-game functions in the API or using the external API. "Intent" can refer to either the functions called to generate intent requests or the registered actions for the back-end to process. Most functions generating intents cost an additional 0.2 CPU cost if they do not return an error.

Intent Basics

Intent actions

Intent actions occur at the final phase of each tick, appearing to occur "between ticks" from the players' code's perspective. This phase of the tick occurs after all players' code is executed and duplicates many of the same checks validated in the user-space functions that generate the request. The first part of this phase is deconfliction of actions (e.g. two creeps trying to move into the same tile) and applying all deconflicted, successful actions to the back-end database in preparation for the next tick.

In-game calls

Intent generating functions will return either error codes, or an OK, indicating a successful registration for the action to be processed. For an intent request to be generated, the method you are using must first pass all checks in the player's sandbox. Actions/methods used that do not return OK will not generate intent requests.

Not all intent generating functions that return OK will succeed. Checks are performed at the function call before returning OK, and again during the post-player code phase, before deconfliction. These post-tick checks are more comprehensive than the function calls, either due to the checks being literally impossible during player execution (e.g. creeps from multiple players moving to the same tile or a creep and tower repairing the same road together beyond the max HP), or where checks would cost too much CPU for the player to be worth it (a creep moving into a natural wall). Despite failing on these post-player checks, the calling player will still incur the additional 0.2 CPU cost.

Not all methods in the game's API create intents or cost the 0.2 CPU to execute, you can see which do and do not by checking the top-right of the method's API page 'cost estimation'. If it has an "A", hovering over it with your mouse will reveal a tool-tip that explains there is a cost associated when OK is returned.

External API calls

The External API is a semi-official means of communicating with the server, originally used solely by the game client. This API allows third-party tools to authenticate with a server as a player and call intent-generating and other functions. The client allowing you to place flags/construction sites, using the console, or editing items in the Memory tab all use the external API.

Artificial Cost

On October 2015, the developers added an artificial 0.2 CPU cost to intent generating functions. This was to limit increased workload on the database servers and keep tick times down. This artificial cost is in addition to the CPU usage the function already uses to perform checks. Some intent generating functions are notorious for costing 0.4 or more CPU, including functions on StructureLab and StructureTower.

Exceptions to the Artificial Cost

Although the vast majority of intents have an additional 0.2 CPU, not all of them do. The following list is a collection of known intents that are an exception to the rule. This is not an exhaustive list.

• Game.cpu.hault()
• Game.cpu.setShardLimits()
• Creep.say()
• Creep.pull()

Bypassing checks / Issuing direct intents

In mid-2020, someone posted on the slack a proof of concept to inject intents directly, bypassing the checks in the API functions. This was accomplished by circumventing security, using an exploit to gain access to different scopes. The developers have been clear in stating that users should not bypass checks or issue direct intents (thereby bypassing checks). Do not do it.