Difference between revisions of "Intent"
(categorized) |
|||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| + | 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 <code>creep.move()</code> to executing <code>Game.market.deal()</code>. 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 == |
||
| − | An Intent is action a user is taking in game that results in a change to the game's database, this can range from a creep moving from one position to another using <code>.move()</code> to executing a <code>.deal()</code> in the market, to many, many other things. For an intent to be created, the method you are using must first pass all checks on the game's side and return a code of <code>OK</code>. Actions/methods used that do not return OK, do not create intents. At that point, the intent will go into the queue to be executed for the user. The game charges a tax of 0.2 CPU for any intent that has an <code>OK</code> returned to the user, regardless of if the intent is valid after the OK return. |
||
| + | === Intent actions === |
||
| − | Mainly, this means if you stack methods that all return OK, but conflict with each other or have a redundant effect, you will still be charged the 0.2 CPU for each intent regardless of the result. EX: A creep attempts to move into a wall terrain position, a tower attempts to repair a road that a creep is also repairing to full that tick. Both of these examples should (at time of writing) get you an OK return code, but will fail when the game attempts to execute your intent. |
||
| + | 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. |
||
| ⚫ | 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. |
||
| + | === In-game calls === |
||
| + | Intent generating functions will return either error codes, or an <code>OK</code>, 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 [[IVM|sandbox]]. Actions/methods used that do not return <code>OK</code> will not generate intent requests. |
||
| − | == Additional costs == |
||
| + | Not all intent generating functions that return <code>OK</code> will succeed. Checks are performed at the function call before returning <code>OK</code>, 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.[[File:Intent1.jpg|thumb|]] |
||
| − | While most if not all intents do cost a flat 0.2 tax for changing the server side game-state, there are some additional costs to consider. Keep in mind that any time a user is executing a method, say <code>.harvest()</code> on a creep for example, the game must first check to see if its possible for you to preform that action. These checks go against your CPU, as your the one running them. Avoiding needless checks and duplicate/conflicting intents is a great way to keep your CPU usage low. |
||
| ⚫ | 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 [https://blog.screeps.com/2015/10/Important-change-CPU-cost-of-API-methods| 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. |
||
| + | |||
| + | *[https://docs.screeps.com/api/#Game.cpu.halt| Game.cpu.hault()] |
||
| + | *[https://docs.screeps.com/api/#Game.cpu.setShardLimits| Game.cpu.setShardLimits()] |
||
| + | *[https://docs.screeps.com/api/#Creep.say| Creep.say()] |
||
| + | *[https://docs.screeps.com/api/#Creep.pull| Creep.pull()] |
||
== Bypassing checks / Issuing direct intents == |
== Bypassing checks / Issuing direct intents == |
||
| − | The developers have been clear in stating that users should not bypass checks |
+ | 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. |
| ⚫ | |||
Latest revision as of 12:20, 28 October 2020
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[edit | edit source]
Intent actions[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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.
Bypassing checks / Issuing direct intents[edit | edit source]
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.