Difference between revisions of "AI"

From The Perfect Tower II
Jump to navigation Jump to search
m (Fixed minor spelling error)
(Add signatures for worker APIs)
 
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
The AI (short for "Artificial Intelligence") is a feature of the [[Headquarters]] that unlocks upon reaching [[Military Tier]] 4. It is an extremely versatile tool that allows the user to automate almost any task in the game. As of "v0.8.5 B1 - Workers!" (see [[Version history]]), [[Workers]] were added to the game as a "pre-AI automation system". According to the developers, Workers "can do exactly one specific task of your choice at a selected speed" so they aren't meant to take place of AI in any way, as AI is still more powerful in its capabilities.
+
The facility AI (short for "Artificial Intelligence") is a feature of the [[Headquarters]] that unlocks upon reaching [[Military Tier]] 4 and finishing the associated software. It is an extremely versatile tool that allows the user to automate almost any task in the game.
  
−
To use the AI you have to create AI scripts in the headquarters, or obtain import codes for scripts that other players have written. For more information on learning how to create scripts, see [[Using the AI]]. For a list of recommended scripts, see [[AI Scripts Guide]].
+
Compared to workers, AI scripts are far more versatile as they can interact with almost every system in the game and even for systems for which there is no current APIs that the AI could use to interact it can always perform mouse clicks to simulate such behavior. This is currently limited as the AI can only click on in-game UI buttons so things like region [[artifacts]] must still be performed manually, additionally the AI cannot perform right or middle mouse clicks. However AI cannot run while the game is closed (or more accurately during the simulated time when opening a save file) or interact with buildings which are not open. Workers can do both of these things, appear before AI (MT1 rather than MT4) and are far simpler to use without community assistance so while AI may have more power to automate the game, neither is a replacement for the other.  
  
−
==AI Scripts==
+
To use the AI you must first obtain a script to execute. There are several ways to do this:
 +
 
 +
*Create an AI script in the headquarters. For more information on learning how to create scripts, see [[Using the AI]].
 +
*Obtain import codes for scripts that other players have written. For a list of available scripts, see the [https://discord.com/channels/488444879836413975/1093895780865163284 discord forum].
 +
*Use machine learning (a macro system). This is done by pressing F7 while the AI overlay is active.
 +
 
 +
==AI Script Format==
 
An AI script contains three sections that control its behavior:
 
An AI script contains three sections that control its behavior:
  
Line 10: Line 16:
 
*Actions
 
*Actions
  
−
===Impulse===
+
All scripts have a limit of impulses, conditions and actions. Impulses and conditions have a cap of 10, actions a cap pf 50.
−
An Impulse can refer to any button press or event that directly activates an AI script. It is not to be confused with the Basic:Execute command which is not considered an impulse, as it is not a way for a player to directly trigger an AI script, but rather a way of calling the script inside of another AI script much like helper methods in high level programming languages. An AI script can contain 0 - 3 impulses, each of which can trigger the AI script, regardless if it has already been triggered. It is possible that a script can trigger multiple times before it has finished execution. In this case multiple instances of this script can run in parallel.
 
−
 
 
−
'''Impulse List:'''
 
−
 
 
−
*Wake Up (<code>impulse wakeup()</code>)
 
−
**Triggers whenever the AI switches from inactive to active.
 
−
*New Round (<code>impulse game.newround()</code>)
 
−
**Triggers whenever a new [[Tower Testing]] round starts.
 
−
*Open: [[Buildings]] (<code>impulse open.&lt;building&gt;()</code>)
 
−
**Triggers whenever the window of the building is being opened (ex: Open: Arcade)
 
−
*Key: 0-9, A-Z (<code>impulse key.#()</code>)
 
−
**Triggers whenever the 0-9 or A-Z key is being pressed (not numpad). (ex: Key: 0)
 
  
−
===Condition===
+
===Impulses===
−
A Condition is a requirement that has to be fulfilled in order for the script to start executing. If any of the specified conditions is not met then the whole script will not be executed once it is triggered by an impulse. During the execution the specified conditions have no effect. All conditions are of data Type:Bool, and any expression that returns a bool can be used as a condition.
+
An Impulse can refer to any button press or event that directly activates an AI script. It is not to be confused with the Basic:Execute command which is not considered an impulse, as it is not a way for a player to directly trigger an AI script, but rather a way of calling the script inside of another AI script much like helper methods in high level programming languages. Each impulse can trigger the AI script, regardless if it has already been triggered. It is possible that a script can trigger multiple times before it has finished execution. In this case multiple instances of this script can run in parallel.
  
−
'''Condition List:'''
+
===Conditions===
 +
A Condition is a requirement that has to be fulfilled in order for the script to start executing. If any condition in the script is false then the script will not be executed when an impulse is triggered by a player action. During the execution the specified conditions have no effect. All conditions are of data Type:Bool, and any expression that returns a bool can be used as a condition
  
−
*Comparison: Bool (<code>bool comparison.bool(bool: lhs, string: op_comp, bool: rhs</code>)
+
===Actions===
−
**Compares two boolean values based on the selected operator. Allowed operators are "=="/"=" (Equals), "!=" (Not Equal), "&&"/"&" (Both must be true), "||"/"|" (Either has to be true).
+
An Action is something that the AI does when the script becomes active. The Actions are executed one by one, in order from top to bottom. Actions will continue to be executed until either the AI menu is closed, or the script terminates normally. Within one instance of a script, as many actions as the script budget will allow can be executed in one frame. Atomic actions (those with a red symbol) cost 0 budget, all others cost 100. The script is executed in sequence until the budget is reached at which point execution is given to the next script.
−
*Comparison: Int/Double (<code>bool comparison.&lt;type&gt;(type: lhs, string: op_comp, type: rhs</code>)
 
−
**Compares two &lt;type&gt; values based on the selected operator. Allowed operators are "=="/"=" (Equals), "!=" (Not Equal), ">", ">=", "<", "<=".
 
−
*Comparison: String (<code>bool comparison.string(string: lhs, string: op_comp, string: rhs</code>)
 
−
**Compares two string values based on the selected operator. Allowed operators are "=="/"=" (Equals), "!=" (Not Equal).
 
−
*Factory: Is Processing (<code>bool active(string: machine)</code>)
 
−
**Returns true if the machine with ID [[Machine]] is currently processing items. (ex: Factory: Is Processing (Oven)). Always returns false outside the factory.
 
−
*Mine: Has Layers (<code>bool hasLayers()</code>)
 
−
**Returns true if the current active mining tab can generate at least 1 layer. Always returns false outside the mine.
 
−
*Museum: Fill Inventory (<code>bool isfill()</code>)
 
−
**Returns the current Fill Inventory state. Always returns false outside the museum.
 
−
*String: Contains (<code>bool contains(string: str, string: substr)</code>)
 
−
**Returns true if the string <code>str</code> contains the string <code>substr</code>. (ex: "Catch" Contains "Cat")
 
−
*Tower: Is Stunned (<code>bool stunned()</code>)
 
−
**Returns true if the tower is stunned and false if the tower is either not stunned or does not exist.
 
−
*Town: Window Open (<code>bool isopen(string: window)</code>)
 
−
**Returns true if the [[Buildings]] window is active and visible on the screen. (ex: [[Tower Testing]] is open)
 
  
−
===Action===
 
−
An Action is something that the AI does when the script becomes active. The Actions are executed one by one, in order from top to bottom. Actions will continue to be executed until either the AI menu is closed, or the script terminates normally. Within one instance of a script, there is no way to execute more than one Action at a time (but by launching multiple copies of a script, this can be achieved).
 
−
 
−
'''Action List:'''
 
−
 
−
*Basic: Goto (<code>goto(int: line)</code>)
 
−
**Jumps to line <code>line</code>. The first line in the script equals 1. Entering an invalid line number will result in the value being clamped between the min. and max. boundaries during execution.
 
−
*Basic: Goto-If (<code>goto(int: line, bool: condition)</code>)
 
−
**Jumps to line <code>line</code> in the current script if <code>condition</code> is True. First line equals 1.
 
−
*Basic: Click (<code>click(vector: pos)</code>)
 
−
**Performs a mouse click at following location: <code>pos</code>.
 
−
*Basic: Slider (<code>slider(vector: where, double: value)</code>)
 
−
**Sets the slider position <code>where</code> on the screen to <code>value</code> with 0 being the leftmost and 1 being the rightmost end.
 
−
*Basic: Scrollrect (<code>scrollbar(vector: where, double: horizontal, double: vertical)</code>)
 
−
**Scrolls within a scrollable container at <code>where</code> to <code>horizontal</code> (horizontally) and <code>vertical</code> (vertically) with 0 being the left/lower end and 1 being the right/upper end. Use a negative value to ignore an axis.
 
−
*Basic: Wait (<code>wait(double: value)</code>)
 
−
**A simple wait function that stops the current script for a total of <code>value</code> seconds.
 
−
*Basic: Wait Until (<code>waituntil(bool: condition)</code>)
 
−
**Stops the current script until <code>condition</code> becomes True.
 
−
*Basic: Wait While (<code>waitwhile(bool: condition)</code>)
 
−
**Stops the current script as long as <code>condition</code> is True.
 
−
*Basic: Execute (<code>execute(string: script)</code>)
 
−
**Executes the first script in the list which is named <code>script</code> without requiring an impulse. Conditions of the script called still have to be fulfilled. Executed scripts are put at the end of the script list, and because of this they (usually) will run their first action in the same frame, since the script list pointer is still on the calling script, earlier in the script list.
 
−
*Basic: Execute (Sync) (<code>executesync(string: script)</code>)
 
−
**Executes the first script in the list which is named <code>script</code> and waits until the execution is completed. Conditions of the script still have to be fulfilled. '''As of 0.9.2, this has some bugs:''' If the conditions of the script are ''not'' fulfilled, <code>executesync</code> will wait forever without running anything. Also, if the executed script is killed with <code>stop</code>, execution will not continue.
 
−
*Basic: Stop (<code>stop(string: script)</code>)
 
−
**Stops the execution of all scripts and script instances which are named <code>script</code>. '''Important bug/feature:''' If a script stops ''itself'', the script list pointer is reset to the beginning, effectively giving everything before this script an "extra" cycle. Because scripts that have reached the end aren't cleaned up until the end-of-frame processing, this means that scripts on their last line (or that have jumped to 99) will re-execute their last line, which can cause bugs. This behavior is known as "Turbo Exec," since it can be used to build programs that execute much faster than the typical one-action-per-frame.
 
−
*Global: Set (Double / Int / String)
 
−
**Creates or changes the global variable "[EmptyX]" to contain the value [x.0 or if x has a decimal uses that instead] / [x] / string "[EmptyY]".
 
−
*Global (Unset)
 
−
**Deletes the global variable with the name "Empty".
 
−
*Local: Set (Double / Int / String)
 
−
**Creates or changes the local variable "[EmptyX]" to contain the value [x.0 or if x has a decimal uses that instead] / [x] / string "[EmptyY]".
 
−
*Local: (Unset)
 
−
**Deletes the local variable with the name "[Empty]".
 
−
*Tower: Use (Instantly)
 
−
**Orders the Tower to use the [[Modules]] at slot [x] where slot 1 refers to the module at the very top of the skill menu. Entering an invalid slot will do nothing.
 
−
*Tower: Use (Position)
 
−
**Orders the tower to use the module at slot [x] where slot 1 refers to the module at the very top of the skill menu at an offset of (X:[x], Y:[y])
 
−
*Tower: Restart
 
−
**Restarts the current [[Tower Testing]] run. Can only be can only be executing during or at the end of a run that took equal or longer than a second.
 
−
*Town: Open Window
 
−
**Opens the [[Tower Testing]] window if True is True, otherwise it will be closed. Opening or closing windows this way does not play the transition animation!
 
−
*Mine: Dig
 
−
**Digs up the tile at X: [x] and Y: [y] of the currently selected resource in the [[Mine]] with (0, 0) being the top left corner. Only works if the [[Mine]] window is active!
 
−
*Mine: New Layer
 
−
**Generates a new layer of the currently selected resource in the [[Mine]]. Only works if the [[Mine]] window is active!
 
−
*Mine: Open Tab
 
−
**Opens the mining tab at position [x]. Position 1 is the first tab (Orange) and position 12 is the last tab (Black).
 
−
*Mine: Delete Cluster
 
−
**Removes the asteroid cluster at list position [x] where 1 represents the first cluster in the list.
 
−
*Factory: Try Craft
 
−
**Tries to craft "[Item]" (T[X]) a total of [y.0 or if y has a decimal uses that instead] times by using only items inside the main inventory. If that is not possible then no items are being crafted. Only works if the [[Factory]] screen is visible.
 
−
*Factory: Try Produce
 
−
**Tries to put [x.0 or if x has a decimal uses that instead] x [Item] (T[y]) into machine Oven. If too few items are available or the selected machine is currently busy with a different item type then nothing will happen. Ignores the tier if the selected item ID is rubber.
 
−
*Factory: Trash
 
−
**Tries to put [x.0 or if x has a decimal uses that instead] x [Item] (T[y]) into the trash can of the [[Factory]]. If too few items are present in the inventory and the crafting grid of the [[Factory]] then it will still try to remove as many as possible. Ignores the tier for items that don't have a tier.
 
−
*Powerplant: Sell
 
−
**Sells the [[Power Plant]] component at X: [x] and Y: [y] and automatically refunds a part of the selling price. If the selected slot is empty then nothing will happen. (0, 0) is the bottom left corner of the grid.
 
−
*Tradingpost: Refresh
 
−
**Generates a new set of offers in the [[Trading Post]]. '''Requires a specific upgrade for the [[Trading Post]] later in the game in order to be used!'''
 
−
 
−
*Tradingpost: Trade
 
−
**Trades the offer at position [x] in the list of offers (first offer is at position 0) using [y.0 or if y has a decimal uses that instead] (0.15 = 15%) of the available input resources.
 
−
*Museum: Fill Inventory
 
−
**Sets the Fill Inventory button to the [T/F] state.
 
−
*Museum: Combine
 
−
**Combine [[Power Stones]] with the usual combine rules up to Tier [x] (<1 means no limit).
 
−
*Museum: Transmute
 
−
**Transmute [[Power Stones]]
 
−
*Museum: Buy
 
−
**Buy [[Power Stones|Power Stone(s)]] with element "[Element]"
 
−
*Museum: Buy Market
 
−
**Buy [[Power Stones|Power Stone(s)]] with element "[Element]" up to Tier 1.
 
−
*Museum: Move
 
−
**Move a [[Power Stones|Power Stone]] from [place] in slot [x] to [place]
 
−
*Museum: Delete
 
−
**Delete [[Power Stones|Power Stone]] from Inventory in Slot [x].
 
−
*Museum: Delete All
 
−
**Delete all [[Power Stones]] from Inventory.
 
 
*
 
*
 
*
 
*
Line 134: Line 33:
 
[[File:AI-Script-Editor.png|alt=AI-Script-Editor (Ingame)|none|thumb|362x362px|AI-Script-Editor (In game)]]
 
[[File:AI-Script-Editor.png|alt=AI-Script-Editor (Ingame)|none|thumb|362x362px|AI-Script-Editor (In game)]]
  
−
There is a maximum limit of actions per script, also often called "maximum lines." This is determined by the total amount of RAM installed in all servers. The RAM requirements are <code>7.98<sup>actions-7</sup></code>, <code>7.98<sup>8*conditions-12</sup></code> and <code>7.98<sup>11*impulses-15</sup></code> bytes, rounded up. The largest requirement takes effect - they're not added together.
 
  
−
{| class="wikitable"
+
There is a maximum budget per script. This is determined by the total amount of RAM installed in all servers.
−
!RAM (bytes)!!Actions!!Conditions!!Impulses
+
 
−
|-
+
To get a budget of 10,000 requires fully upgrading the RAM of all 16 servers.
−
|1||7||1||1
 
−
|-
 
−
|8||8||1||1
 
−
|-
 
−
|64||9||1||1
 
−
|-
 
−
|509||10||1||1
 
−
|-
 
−
|4056||11||2||1
 
−
|-
 
−
|32361||12||2||1
 
−
|-
 
−
|2.5823e5||13||2||1
 
−
|-
 
−
|2.0607e6||14||2||2
 
−
|-
 
−
|1.6445e7||15||2||2
 
−
|-
 
−
|1.3123e8||16||2||2
 
−
|-
 
−
|1.0472e9||17||2||2
 
−
|-
 
−
|8.3566e9||18||2||2
 
−
|-
 
−
|6.6686e10||19||3||2
 
−
|-
 
−
|5.3215e11||20||3||2
 
−
|-
 
−
|4.2466e12||21||3||2
 
−
|-
 
−
|3.3888e13||22||3||2
 
−
|-
 
−
|2.7042e14||23||3||2
 
−
|-
 
−
|2.1580e15||24||3||2
 
−
|-
 
−
|1.7221e16||25||3||3
 
−
|}
 
  
−
To get all 25 actions requires fully upgrading the RAM of all 16 servers.
+
==AI Script Language==
  
−
==Data Types==
+
===Data Types===
 
There are various data types that are usable within AI scripts, all of which are incredibly versatile and useful in creating a script as complex or simple as one desires.
 
There are various data types that are usable within AI scripts, all of which are incredibly versatile and useful in creating a script as complex or simple as one desires.
 
{| class="wikitable"
 
{| class="wikitable"
Line 265: Line 125:
 
(The table will be updated as soon as more AI features are available.)
 
(The table will be updated as soon as more AI features are available.)
  
−
==Functions==
+
===Functions===
 
Any line in an AI script (apart from impulses) represents a function.
 
Any line in an AI script (apart from impulses) represents a function.
  
Line 276: Line 136:
  
 
The various inputs to a function are called '''arguments'''. Each argument of a function has a specific datatype and accepts either a constant value or a function with a return value of the same type.
 
The various inputs to a function are called '''arguments'''. Each argument of a function has a specific datatype and accepts either a constant value or a function with a return value of the same type.
 +
 +
===APIs (Application Programming Interfaces) (as of v0.49)===
 +
Function signatures have been slightly modified to conform with a C-like syntax for similarity with other function signatures. The special return type <code>impulse</code> denotes a function is an input (rather than an action), actions which previously did not have a return type now have the <code>void</code> return type and the colon between type and argument name is removed.
 +
{| class="wikitable"
 +
|+Impulses
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Wake Up
 +
|<code>impulse wakeup()</code>
 +
|Triggers whenever the AI switches from inactive to active.
 +
|-
 +
|New Round
 +
|<code>impulse game.newround()</code>
 +
|Triggers whenever a new [[Tower Testing]] round starts.
 +
|-
 +
|Open: <[[Buildings|Building]]>
 +
|<code>impulse open.&lt;building&gt;()</code>
 +
|Triggers whenever the window of the building is being opened (ex: Open: Arcade)
 +
|-
 +
|Close: <[[Buildings|Building]]>
 +
|<code>impulse close.&lt;building&gt;()</code>
 +
|Triggers whenever the window of the building is being closed (ex: Close: Arcade)
 +
|-
 +
|<nowiki>Mouse: <Left|Middle|Right> Up</nowiki>
 +
|<code>impulse mouse.<id>.up()</code>
 +
|<nowiki>Triggers whenever the <left|middle|right> mouse button is being pressed down. (ex: Mouse: Left Down)</nowiki>
 +
|-
 +
|<nowiki>Mouse: <Left|Middle|Right> Down</nowiki>
 +
|<code>impulse mouse.<id>.down()</code>
 +
|<nowiki>Triggers whenever the <left|middle|right> mouse button is being pressed down. (ex: Mouse: Left Down)</nowiki>
 +
|-
 +
|Key: <0-9, A-Z>
 +
|<code>impulse key.#()</code>
 +
|Triggers whenever the 0-9 or A-Z key is being pressed (case-insensitive, not numpad). (ex: Key: 0)
 +
|}
 +
{| class="wikitable"
 +
|+Script Execution Context
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Mouse: <Key>
 +
|<code>bool mouse.<key>.state()</code>
 +
|Returns true if the <key> mouse button is currently being held down.
 +
|-
 +
|Screen: Height
 +
|<code>int height()</code>
 +
|Returns the height of the screen in pixels.
 +
|-
 +
|Screen: Width
 +
|<code>int width()</code>
 +
|Returns the width of the screen in pixels.
 +
|-
 +
|UI: Size
 +
|<code>double ui.size()</code>
 +
|Returns the value of the UI size option from from the options menu as a double ranging from 0.5 (50%) to 1.0 (100%)
 +
|-
 +
|Script: Triggering Impulse
 +
|<code>string impulse()</code>
 +
|Returns the ID of the impulse which triggered this script instance. If the script was triggered by another script then this function will return the name of that script
 +
|-
 +
|Basic: Remaining Budget
 +
|<code>int budget()</code>
 +
|Returns the remaining execution budget of this script during execution.
 +
|-
 +
|Time: Frame
 +
|<code>int time.frame()</code>
 +
|Returns the total number of frames since the start of the game.
 +
|-
 +
|Time: Delta
 +
|<code>double time.delta()</code>
 +
|Returns the total time in seconds between the current frame and the last frame. Pausing or accelerating the game affects this value.
 +
|-
 +
|Time: Scale
 +
|<code>double time.scale()</code>
 +
|Returns the factor at which the game is currently accelerated. (0 if the game is paused, 1 if the game runs at normal speed 2 if the game runs at 2x speed and so on)
 +
|-
 +
|Time: Unscaled Delta
 +
|<code>double time.unscaled()</code>
 +
|Returns the total time in seconds between the current frame and the last frame. This value is neither affected by pausing nor accelerating the game.
 +
|-
 +
|Timestamp: Now
 +
|<code>double now()</code>
 +
|Returns the current local time in ticks representing the time from midnight , January 1st, 0001 until now. (UNIX time)
 +
|-
 +
|Timestamp: UTC Now
 +
|<code>double utcnow()</code>
 +
|Returns the UTC time in ticks representing the time from midnight , January 1st, 0001 until now. (UNIX time)
 +
|}
 +
{| class="wikitable"
 +
|+Execution Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Basic: Goto
 +
|<code>void goto(int line)</code>
 +
|Jumps to line <code>line</code>. The first line in the script equals 1. Entering an invalid line number will result in the value being clamped between the min. and max. boundaries during execution.
 +
|-
 +
|Basic: Goto-If
 +
|<code>void goto(int line, bool condition)</code>
 +
|Jumps to line <code>line</code> in the current script if <code>condition</code> is True. First line equals 1.
 +
|-
 +
|Basic: Click
 +
|<code>void click(vector2 pos)</code>
 +
|Performs a mouse click at following location: <code>pos</code>.
 +
|-
 +
|Basic: Slider
 +
|<code>void slider(vector2 where, double value)</code>
 +
|Sets the slider position <code>where</code> on the screen to <code>value</code> with 0 being the leftmost and 1 being the rightmost end.
 +
|-
 +
|Basic: Scrollrect
 +
|<code>void scrollbar(vector2 where, double horizontal, double vertical)</code>
 +
|Scrolls within a scrollable container at <code>where</code> to <code>horizontal</code> (horizontally) and <code>vertical</code> (vertically) with 0 being the left/lower end and 1 being the right/upper end. Use a negative value to ignore an axis.
 +
|-
 +
|Basic: Wait
 +
|<code>void wait(double value)</code>
 +
|A simple wait function that stops the current script for a total of <code>value</code> seconds.
 +
|-
 +
|Basic: Wait Until
 +
|<code>void waituntil(bool condition)</code>
 +
|Stops the current script until <code>condition</code> becomes True.
 +
|-
 +
|Basic: Wait While
 +
|<code>void waitwhile(bool condition)</code>
 +
|Stops the current script as long as <code>condition</code> is True.
 +
|-
 +
|Basic: Wait Frame
 +
|<code>void waitframe()</code>
 +
|Stops execution of this script for this frame and continues in the next one.
 +
|-
 +
|Basic: Execute
 +
|<code>void execute(string script)</code>
 +
|Executes the first script in the list which is named <code>script</code> without requiring an impulse. Conditions of the script called still have to be fulfilled. Executed scripts are put at the end of the script list, and because of this they (usually) will run their first action in the same frame, since the script list pointer is still on the calling script, earlier in the script list.
 +
|-
 +
|Basic: Execute (Sync)
 +
|<code>void executesync(string script)</code>
 +
|Executes the first script in the list which is named <code>script</code> and waits until the execution is completed. Conditions of the script still have to be fulfilled.
 +
|-
 +
|Basic: Stop
 +
|<code>void stop(string script)</code>
 +
|Stops the execution of all scripts and script instances which are named <code>script</code>. '''Important bug/feature:''' If a script stops ''itself'', the script list pointer is reset to the beginning, effectively giving everything before this script an "extra" cycle. Because scripts that have reached the end aren't cleaned up until the end-of-frame processing, this means that scripts on their last line (or that have jumped to 99) will re-execute their last line, which can cause bugs. This behavior is known as "Turbo Exec," since it can be used to build programs that execute much faster than the typical one-action-per-frame.
 +
|-
 +
|Local: Get <T>
 +
|<code>T local.get(string var)</code>
 +
|Returns the value of the the local variable <code>var</code>.
 +
|-
 +
|Local: Set <T>
 +
|<code>void local.set(string var, T value)</code>
 +
|Creates or changes the the local variable <code>var</code> to contain the value <code>value</code>.
 +
|-
 +
|Local: Unset
 +
|<code>void local.unset(string var)</code>
 +
|Deletes the local variable with the name <code>var</code>.
 +
|-
 +
|Global: Get <T>
 +
|<code>T global.get(string var)</code>
 +
|Returns the value of the the global variable <code>var</code>.
 +
|-
 +
|Global: Set <T>
 +
|<code>void global.set(string var, T value)</code>
 +
|Creates or changes the the global variable <code>var</code> to contain the value <code>value</code>.
 +
|-
 +
|Global: Unset
 +
|<code>void global.unset(string var)</code>
 +
|Deletes the global variable with the name <code>var</code>.
 +
|}
 +
{| class="wikitable"
 +
|+Boolean Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Numerical Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Integer Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Double Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+String Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|String: Contains
 +
|<code>bool contains(string str, string substr)</code>
 +
|Returns true if the string <code>str</code> contains the string <code>substr</code>. (ex: "Catch" Contains "Cat")
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Vector Primitives
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|-
 +
|
 +
|
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Town APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|<code>bool anyopen()</code>
 +
|
 +
|-
 +
|
 +
|<code>bool isopen(string: window)</code>
 +
|Returns true if the [[Buildings]] window is active and visible on the screen. (ex: [[Tower Testing]] is open)
 +
|-
 +
|Town: Open Window
 +
|<code>void show(string building, bool open)</code>
 +
|Opens the <code>building</code> window if <code>open</code>is True, otherwise it will be closed. Opening or closing windows this way does not play the transition animation!
 +
|-
 +
|
 +
|<code>bool isBossFight()</code>
 +
|
 +
|-
 +
|
 +
|<code>bool isTowerTesting()</code>
 +
|
 +
|-
 +
|
 +
|<code>double resource(string currency)</code>
 +
|
 +
|}
 +
{| class="wikitable"
 +
|+Tower Testing APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Game: Is Paused
 +
|<code>bool pause.get()</code>
 +
|Returns true if the game is currently paused during tower testing via the pause button. Outside tower testing this will always return false.
 +
|-
 +
|Game: Set Pause
 +
|<code>void pause.set(bool enable)</code>
 +
|Sets the pause state to <code>enable</code>.
 +
|-
 +
|Game: Pause
 +
|<code>void pause()</code>
 +
|Pauses tower testing via the pause button if possible.
 +
|-
 +
|Game: Unpause
 +
|<code>void unpause()</code>
 +
|Unpauses tower testing via the pause button if possible.
 +
|-
 +
|Software: Is Enabled
 +
|<code>bool software.enabled(string software)</code>
 +
|Returns true if the software with id <code>software</code> has been enabled. Returns false is the software has not been toggled on or has not been researched yet.
 +
|-
 +
|Software: Find ID
 +
|<code>string software.find(string software)</code>
 +
|Returns the correct software ID of the software with the closest match to <code>software</code> (case-insensitive). This function is very slow. Avoid using it in performance critical sections.
 +
|-
 +
|Software: Toggle
 +
|<code>void software.toggle(string software, bool enabled)</code>
 +
|Enables software <code>software</code> if the condition <code>bool condition</code> is true or disables it if the condition is false.
 +
|-
 +
|Game: Number of Enemies
 +
|<code>int enemies()</code>
 +
|Returns the numbers of enemy units which are currently present on the map. Returns 0 if tower testing is not active.
 +
|-
 +
|Game: XP
 +
|<code>double xp()</code>
 +
|Returns the current amount of tower testing experience. Returns 0 if called outside of tower testing.
 +
|-
 +
|Game: Wave Acceleration
 +
|<code>double waveAcceleration()</code>
 +
|Returns the current wave acceleration factor. (You can check the current value inside the stats menu during tower testing).
 +
|-
 +
|Game: Fixed Waves Per Interval
 +
|<code>double fixedWavesPerInterval()</code>
 +
|Returns the current amount of fixed waves per interval as seen in the stats menu during tower testing. Returns 0 if currently not tower testing.
 +
|-
 +
|Game: Wave
 +
|<code>double wave()</code>
 +
|Returns the current wave during tower testing or 0 if tower testing is not active.
 +
|-
 +
|Highscore: Wave
 +
|<code>double highscore.wave(string region, string difficulty</code>
 +
|Returns the wave record of region <code>region</code> on difficulty <code>difficulty</code>.
 +
|-
 +
|Game: Era
 +
|<code>double era()</code>
 +
|Returns the current era during tower testing or 0 if tower testing is not active. Equivalent to <code>wave() / 1e11</code>.
 +
|-
 +
|Highscore: Era
 +
|<code>double highscore.era(string region, string difficulty</code>
 +
|Returns the era record of region <code>region</code> on difficulty <code>difficulty</code>. Equivalent to <code>wave() / 1e11</code>.
 +
|-
 +
|Era: Disable Cost
 +
|<code>double disable.cost(string element)</code>
 +
|Returns the XP cost of the upgrade that disables the era powers of <code>element</code> enemies. Returns -1 outside of tower testing or if the upgrade is not available in the current region.
 +
|-
 +
|Era: Disable Power
 +
|<code>void disable.era(string element)</code>
 +
|Tries to disable the era powers of <code>element</code> enemies by purchasing the according upgrade using xp.
 +
|-
 +
|Era: Upgrade Divider
 +
|<code>void upgrade.era(string divider, int times)</code>
 +
|Attempts to upgrade the era <code>str (damage, health)</code> divider a total of <code>int x</code> times by using xp.
 +
|-
 +
|Game: Infinity
 +
|<code>double infinity()</code>
 +
|Returns the current infinity during tower testing or 0 if tower testing is not active. Equivalent to <code>wave() / 1e22</code> and <code>era() / 1e11</code>.
 +
|-
 +
|Highscore: Infinity
 +
|<code>double highscore.infity(string region, string difficulty</code>
 +
|Returns the infinity record of region <code>region</code> on difficulty <code>difficulty</code>. Equivalent to <code>wave() / 1e22</code> and <code>era() / 1e11</code>.
 +
|-
 +
|Infinity: Secure Module Cost
 +
|<code>double disable.inf.cost()</code>
 +
|Returns the amount of XP required in order to secure/disable a module during infinity phase.
 +
|-
 +
|Infinity: Secure Module
 +
|<code>void disable.inf(string moduleId)</code>
 +
|Attempts to secure the module with id  <code>str id</code> to prevent enemies from mimicking it during the infinity phase.
 +
|-
 +
|Game: Active Module Count
 +
|<code>int active.count()</code>
 +
|Returns the total number of active modules in the currently active blueprint of the tower. Returns 0 outside of tower testing.
 +
|-
 +
|Game: Active Module Index
 +
|<code>int active.index(string moduleId)</code>
 +
|Returns the index of the active module with ID <code>moduleId</code> inside the active skills list. If the module is not inside the list or tower testing is not active then this function will return 0.
 +
|-
 +
|Game: Active Module ID
 +
|<code>string active.id(int index)</code>
 +
|Returns the ID of the active module in slot <code>index</code> in the active modules list whereas 1 refers to the first module in the list. Returns an empty string if the slot index is invalid or tower testing is not active.
 +
|-
 +
|Tower: Is Stunned
 +
|<code>bool stunned()</code>
 +
|Returns true if the tower is stunned and false if the tower is either not stunned or does not exist.
 +
|-
 +
|Tower: Negative Buffs
 +
|<code>int negative()</code>
 +
|Returns the total number of nagative buffs currently present on the tower or 0 if the tower has no negative buffs or does not exist.
 +
|-
 +
|Tower: Health
 +
|<code>double health(bool percent)</code>
 +
|Returns the current health of the tower or 0 if the tower is dead does not exist. Returns the value as a percentage of max health value if <code>percent</code> is true otherwise the absolute value.
 +
|-
 +
|Tower: Max. Health
 +
|<code>double health.max()</code>
 +
|Returns the maximum hitpoints of the tower or 0 if the tower is either dead or does not exist.
 +
|-
 +
|Tower: Health Regeneration
 +
|<code>double health.regen()</code>
 +
|Returns the current health regeneration of the tower or 0 if the tower does not exist.
 +
|-
 +
|Tower: Energy
 +
|<code>double energy(bool percent)</code>
 +
|Returns the current energy of the tower or 0 if the tower does not exist. Returns the value as a percentage of max energy value if <code>percent</code> is true otherwise the absolute value.
 +
|-
 +
|Tower: Max. Energy
 +
|<code>double energy.max()</code>
 +
|Returns the maximum energy of the tower or 0 if the tower is either dead or does not exist.
 +
|-
 +
|Tower: Energy Regeneration
 +
|<code>double energy.regen()</code>
 +
|Returns the current energy regeneration of the tower or 0 if the tower does not exist.
 +
|-
 +
|Tower: Shield
 +
|<code>double shield(bool percent)</code>
 +
|Returns the current shieldpoints of the tower or 0 if the tower is dead or does not exist. Returns the value as a percentage of max shieldpoints value if <code>percent</code> is true otherwise the absolute value.
 +
|-
 +
|Tower: Max. Shield
 +
|<code>double shield.max()</code>
 +
|Returns the maximum shieldpoints of the tower or 0 if the tower is either dead or does not exist.
 +
|-
 +
|Tower: Module Cooldown
 +
|<code>double cooldown(int skill)</code>
 +
|Returns the remaining cooldown of the active module at slot <code>skill</code> in seconds Slot 1 refers to the first module in the active modules list.
 +
|-
 +
|Tower: Attack Range
 +
|<code>double tower.range()</code>
 +
|Returns the tower's current attack range. (Default attack range without any modules or buffs is 18).
 +
|-
 +
|Tower: Use (Instantly)
 +
|<code>void useinstant(int skill)</code>
 +
|Orders the Tower to use the [[Modules]] at slot <code>skill</code> where slot 1 refers to the module at the very top of the skill menu. Entering an invalid slot will do nothing.
 +
|-
 +
|Tower: Use (Position)
 +
|<code>void useposition(int skill, vector2 pos</code>
 +
|Orders the tower to use the module at slot  <code>skill</code> where slot 1 refers to the module at the very top of the skill menu at an offset of <code>pos</code>
 +
|-
 +
|Tower: Restart
 +
|<code>void restart()</code>
 +
|Restarts the current [[Tower Testing]] run. Can only be can only be executing during or at the end of a run that took equal or longer than a second.
 +
|-
 +
|Tower: Exit
 +
|<code>void exit()</code>
 +
|Exits the current Tower Testing run.
 +
|}
 +
{| class="wikitable"
 +
|+Power Plant APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Powerplant: Sell
 +
|
 +
|Sells the [[Power Plant]] component at X: <code>int x</code> and Y: <code>int y</code> and automatically refunds a part of the selling price. If the selected slot is empty then nothing will happen. (0, 0) is the bottom left corner of the grid.
 +
|}
 +
{| class="wikitable"
 +
|+Mine APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Mine: Dig
 +
|
 +
|Digs up the tile at X: <code>int x</code> and Y: <code>int y</code> of the currently selected resource in the [[Mine]] with (0, 0) being the top left corner. Only works if the [[Mine]] window is active!
 +
|-
 +
|Mine: New Layer
 +
|
 +
|Generates a new layer of the currently selected resource in the [[Mine]]. Only works if the [[Mine]] window is active!
 +
|-
 +
|Mine: Open Tab
 +
|
 +
|Opens the mining tab at position <code>int position</code>. Position 1 is the first tab (Orange) and position 12 is the last tab (Black).
 +
|-
 +
|Mine: Delete Cluster
 +
|
 +
|Removes the asteroid cluster at list position <code>int position</code> where 1 represents the first cluster in the list.
 +
|}
 +
{| class="wikitable"
 +
|+Factory APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Factory: Try Craft
 +
|
 +
|Tries to craft <code>str item</code> (Tier <code>int tier</code>) a total of <code>double total</code> times by using items inside the inventory or crafting grid. If that is not possible then no items are being crafted. Only works if the [[Factory]] screen is visible.
 +
|-
 +
|Factory: Try Produce
 +
|
 +
|Tries to put <code>double amount</code> x <code>str item</code> (T<code>int tier</code>) into machine <code>str machine</code>. If too few items are available or the selected machine is currently busy with a different item type then nothing will happen. Ignores the tier if the selected item ID is rubber.
 +
|-
 +
|Factory: Trash
 +
|
 +
|Tries to put <code>double amount</code> x <code>str item</code> (T<code>int tier</code>) into the trash can of the [[Factory]]. If too few items are present in the inventory and the crafting grid of the [[Factory]] then it will still try to remove as many as possible. Ignores the tier for items that don't have a tier.
 +
|-
 +
|Factory: Cancel Machine
 +
|
 +
|Stops production of the [[Factory]] machine with the id <code>str machine</code> and ejects all items back to the inventory if possible.
 +
|}
 +
{| class="wikitable"
 +
|+Arcade APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Arcade: Spin Lucky Wheel
 +
|
 +
|Spins the Lucky Wheel with a wager of <code>double wager</code>.
 +
|-
 +
|Arcade: Jumble New Game
 +
|
 +
|Starts a new game of Jumble with a wager of <code>double wager</code>.
 +
|-
 +
|Arcade: Jumble Stop
 +
|
 +
|Stops the current column.
 +
|-
 +
|Adventure: Move
 +
|
 +
|Moves the player in the direction of <code>vector x,y</code> in Adventure.
 +
|-
 +
|Adventure: Wait
 +
|
 +
|Skips a turn in Adventure.
 +
|-
 +
|Adventure: Place Bomb
 +
|
 +
|Places a Bomb at the Player location in Adventure.
 +
|}
 +
{| class="wikitable"
 +
|+Trading Post APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Tradingpost: Refresh
 +
|
 +
|Generates a new set of offers in the [[Trading Post]]. '''Requires a specific upgrade for the [[Trading Post]] later in the game in order to be used!'''
 +
|-
 +
|Tradingpost: Trade
 +
|
 +
|Trades the offer at position <code>int position</code> in the list of offers (first offer is at position 0) using <code>double percent</code> (0.15 = 15%) of the available input resources.
 +
|}
 +
{| class="wikitable"
 +
|+Museum APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Museum: Buy
 +
|
 +
|Buys a <code>str element</code> Power Stone of tier <code>int tier</code> from the shop or market <code>int amount</code> times.
 +
|-
 +
|Museum: Buy Range
 +
|
 +
|Buys a <code>str element</code> Power Stone between tier <code>int tier</code> and <code>int tier</code> from the shop or market <code>int amount</code> times.
 +
|-
 +
|Museum: Combine
 +
|
 +
|Combine Power Stones with the usual combine rules up to Tier <code>int tier</code> (<1 means no limit).
 +
|-
 +
|Museum: Transmute
 +
|
 +
|Transmute Power Stones currently inside the Cubos Cube.
 +
|-
 +
|Museum: Move
 +
|
 +
|Move a Power Stone from <code>str location</code> in slot <code>int slot</code> to <code>str location</code>.
 +
|-
 +
|Museum: Move Slot
 +
|
 +
|Move a Power Stone from <code>str location</code> slot <code>int slot</code> to <code>str location</code> <code>int slot</code>.
 +
|-
 +
|Museum: Swap
 +
|
 +
|Swap the Power Stones in <code>str location</code> slot <code>int slot</code> and <code>str location</code> <code>int slot</code>.
 +
|-
 +
|Museum: Sell
 +
|
 +
|Sell the Power Stone from <code>str location</code> in slot <code>int slot</code>.
 +
|-
 +
|Museum: Sell All
 +
|
 +
|Sell all Power Stones from <code>str location</code>.
 +
|-
 +
|Museum: Set Preferred Tier
 +
|
 +
|Sets the preferred market tier to <code>int tier</code>.
 +
|-
 +
|Museum: Set Preference
 +
|
 +
|Set the market preference for element <code>str element</code> to <code>bool value</code>.
 +
|-
 +
|Museum: Market Refresh
 +
|
 +
|Refreshes Market Offers
 +
|-
 +
|Museum: Buy Market
 +
|
 +
|Buy the Power Stone from market in slot <code>int slot</code> <code>int amount</code> times.
 +
|-
 +
|Museum: Lock Market Slot
 +
|
 +
|Set the lock state of Market slot <code>int slot</code> to <code>bool value</code>.
 +
|-
 +
|Museum: Rebuy
 +
|
 +
|Rebuy the Power Stone from Trash slot <code>int slot</code>.
 +
|}
 +
{| class="wikitable"
 +
|+Worker APIs
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|
 +
|<code>bool worker.paused(string name)</code>
 +
|
 +
|-
 +
|
 +
|<code>int worker.group(int index)</code>
 +
|
 +
|-
 +
|
 +
|<code>string worker.name(int index)</code>
 +
|
 +
|-
 +
|
 +
|<code>string worker.task(string name)</code>
 +
|
 +
|-
 +
|Workers: Toggle Group
 +
|<code>void worker.toggleGroup(int group)</code>
 +
|Toggles the paused state of all workers in group <code>int group</code>. (Click on the parameter to see which color belongs to which group id.) Colors: White (0), Red (1), Blue (2), Green(3), Yellow (4), Magenta (5)
 +
|-
 +
|Workers: Pause Group
 +
|<code>void worker.pauseGroup(int group, bool paused)</code>
 +
|Sets the paused state of all workers in group <code>int group</code> to <code>bool value</code>. (Click on the parameter to see which color belongs to which group id.)
 +
|-
 +
|Workers: Toggle
 +
|<code>void worker.toggleName(string name)</code>
 +
|Toggles the paused state of all workers with name <code>str name</code>.
 +
|-
 +
|Workers: Pause
 +
|<code>void worker.pauseName(string name, bool paused)</code>
 +
|Sets the paused state of all workers with the name <code>str name</code> to <code>bool value</code>.
 +
|-
 +
|Workers: Assign Group
 +
|<code>void worker.assignGroup(string task, int subtask, int group)</code>
 +
|Assigns the task with id <code>str id</code> and optional parameter <code>int param</code> (0 is the leftmost) to all workers in group <code>int group</code>. (Click on the groups parameter to see which color belongs to which group.)
 +
|-
 +
|Workers: Assign
 +
|<code>void worker.assignName(string task, int subtask, string name)</code>
 +
|Assigns Task with ID <code>str id</code> and optional parameter <code>int param</code> (0 is the leftmost) to all workers with the name <code>str name</code>. [[Workers#Worker_Taskid.27s|TaskIDs]]
 +
|-
 +
|Workers: Set Name
 +
|<code>void worker.setName(int index, string name)</code>
 +
|Sets the name of the worker at index <code>int index</code> to <code>str name</code>.
 +
|-
 +
|Worker: Set Group
 +
|<code>void worker.setGroup(int index, int group)</code>
 +
|Sets the group of the worker at index <code>int index</code> (0 is the first worker) to the group with id <code>int id</code>.
 +
|}
 +
{| class="wikitable"
 +
|+User Interface APIs (requires boots.d0s)
 +
!Name
 +
!Function Signature
 +
!Description
 +
|-
 +
|Canvas: Draw Rect
 +
|<code>void canvas.rect(vector2 pos, vector2 size, string colour</code>
 +
|Draws a rectangle on the drawable canvas at location <code>pos</code> with a size of <code>size</code> and colored in <code>colour</code>. (Accepts #RRGGBB and #RRGGBBAA as inputs for color.)
 +
|-
 +
|Canvas: Clear
 +
|<code>void canvas.clear()</code>
 +
|Clears the drawable canvas instantly.
 +
|-
 +
|Window: Create
 +
|<code>void create(string windowId, string windowType)</code>
 +
|Creates a window with the unique identifier <code>windowId</code> (used to address the new instance) of type <code>windowType</code> (window name inside windows list).
 +
|-
 +
|Window: Set Text
 +
|<code>void text.set(string windowId, string textElementId, string value)</code>
 +
|Sets the content inside the window with the id <code>windowId</code> of the text label with the id <code>textElementId</code> to <code>value</code>.
 +
|-
 +
|Window: Set Sprite
 +
|<code>void sprite.set(string windowId, string elementId, string spriteId)</code>
 +
|Sets the sprite inside the window with the id <code>windowId</code> of the button/image with the id <code>elementId</code> to <code>spriteId</code>.
 +
|-
 +
|Window: Get Visibility
 +
|<code>bool visibility.get(string windowId)</code>
 +
|
 +
|-
 +
|Window: Set Visibility
 +
|<code>void visibility.set(string windowId, bool visible)</code>
 +
|Set the window with id <code>windowId</code> to visible if <code>visible</code> is true. Otherwise it will be hidden.
 +
|-
 +
|Window: Get Child Visibility
 +
|<code>bool child.visibility.get(string windowId, string childElementId)</code>
 +
|
 +
|-
 +
|Window: Set Child Visibility
 +
|<code>void child.visibility.set(string windowId, string childElementId, bool visible)</code>
 +
|Set child of window with id <code>windowId</code> with id <code>childElementId</code> to visible if <code>visible</code> is true. Otherwise window will be hidden.
 +
|-
 +
|Window: Set Position
 +
|<code>void position.set(string windowId, vector2 position)</code>
 +
|Changes the position of the window with id <code>windowId</code> to <code>position</code> based on the anchor of its root element. Per default the anchor is set to the center of the window and 0,0 represents the center of the screen.
 +
|-
 +
|Window: Destroy
 +
|<code>void destroy(string windowId)</code>
 +
|Destroys the window with the unique identifier <code>windowId</code>.
 +
|-
 +
|Window: Destroy All
 +
|<code>void destroy.all()</code>
 +
|Destroys all active windows.
 +
|}
  
 
{{PerfectNavigation}}
 
{{PerfectNavigation}}
  
 
<br />
 
<br />

Latest revision as of 13:21, 9 November 2024

The facility AI (short for "Artificial Intelligence") is a feature of the Headquarters that unlocks upon reaching Military Tier 4 and finishing the associated software. It is an extremely versatile tool that allows the user to automate almost any task in the game.

Compared to workers, AI scripts are far more versatile as they can interact with almost every system in the game and even for systems for which there is no current APIs that the AI could use to interact it can always perform mouse clicks to simulate such behavior. This is currently limited as the AI can only click on in-game UI buttons so things like region artifacts must still be performed manually, additionally the AI cannot perform right or middle mouse clicks. However AI cannot run while the game is closed (or more accurately during the simulated time when opening a save file) or interact with buildings which are not open. Workers can do both of these things, appear before AI (MT1 rather than MT4) and are far simpler to use without community assistance so while AI may have more power to automate the game, neither is a replacement for the other.

To use the AI you must first obtain a script to execute. There are several ways to do this:

  • Create an AI script in the headquarters. For more information on learning how to create scripts, see Using the AI.
  • Obtain import codes for scripts that other players have written. For a list of available scripts, see the discord forum.
  • Use machine learning (a macro system). This is done by pressing F7 while the AI overlay is active.

AI Script Format

An AI script contains three sections that control its behavior:

  • Impulses
  • Conditions
  • Actions

All scripts have a limit of impulses, conditions and actions. Impulses and conditions have a cap of 10, actions a cap pf 50.

Impulses

An Impulse can refer to any button press or event that directly activates an AI script. It is not to be confused with the Basic:Execute command which is not considered an impulse, as it is not a way for a player to directly trigger an AI script, but rather a way of calling the script inside of another AI script much like helper methods in high level programming languages. Each impulse can trigger the AI script, regardless if it has already been triggered. It is possible that a script can trigger multiple times before it has finished execution. In this case multiple instances of this script can run in parallel.

Conditions

A Condition is a requirement that has to be fulfilled in order for the script to start executing. If any condition in the script is false then the script will not be executed when an impulse is triggered by a player action. During the execution the specified conditions have no effect. All conditions are of data Type:Bool, and any expression that returns a bool can be used as a condition

Actions

An Action is something that the AI does when the script becomes active. The Actions are executed one by one, in order from top to bottom. Actions will continue to be executed until either the AI menu is closed, or the script terminates normally. Within one instance of a script, as many actions as the script budget will allow can be executed in one frame. Atomic actions (those with a red symbol) cost 0 budget, all others cost 100. The script is executed in sequence until the budget is reached at which point execution is given to the next script.

AI-Script-Editor (Ingame)
AI-Script-Editor (In game)


There is a maximum budget per script. This is determined by the total amount of RAM installed in all servers.

To get a budget of 10,000 requires fully upgrading the RAM of all 16 servers.

AI Script Language

Data Types

There are various data types that are usable within AI scripts, all of which are incredibly versatile and useful in creating a script as complex or simple as one desires.

Type Description Example Values Default Value Notes
double A integer that allows decimal precision. Can be positive or negative. 3.2, 0.29, -10.2, 7.9999993 0.0 Doubles have a max value of approximately 1.797 × 10308.
int A number that does not allow decimal precision. Can be positive or negative. 20, 69, 420, -1029, 0 0 Ints range from -2147483648 to 2147483647
string An array of characters. Basically a way to format and use text. "meow", "hello", " ", "I am a text", "!BanBudE" "" The quotes in the examples are not included in the actual string value.
bool A binary value that can either be true or false. true, false false
Vector2 A container type that contains two double values called x and y. (-30.0, 0.0), (28.38, 13) (0.0, 0.0)

Some datatypes can be converted to others by using a function. Check the table below to see which datatypes are currently interchangeable.

Source / Target double int string bool Vector2
double - Yes Yes No Partially
int Yes - Yes No No
string Yes Yes - No No
bool No No No - No
Vector2 Partially No No No -

(The table will be updated as soon as more AI features are available.)

Functions

Any line in an AI script (apart from impulses) represents a function.

There are two major types of functions:

  • Without a return value (= Actions)
  • With a return value

Functions without a return value appear as actions in the sidebar of the AI-script editor. In general these functions do something specific but require some sort of input.

The various inputs to a function are called arguments. Each argument of a function has a specific datatype and accepts either a constant value or a function with a return value of the same type.

APIs (Application Programming Interfaces) (as of v0.49)

Function signatures have been slightly modified to conform with a C-like syntax for similarity with other function signatures. The special return type impulse denotes a function is an input (rather than an action), actions which previously did not have a return type now have the void return type and the colon between type and argument name is removed.

Impulses
Name Function Signature Description
Wake Up impulse wakeup() Triggers whenever the AI switches from inactive to active.
New Round impulse game.newround() Triggers whenever a new Tower Testing round starts.
Open: <Building> impulse open.<building>() Triggers whenever the window of the building is being opened (ex: Open: Arcade)
Close: <Building> impulse close.<building>() Triggers whenever the window of the building is being closed (ex: Close: Arcade)
Mouse: <Left|Middle|Right> Up impulse mouse.<id>.up() Triggers whenever the <left|middle|right> mouse button is being pressed down. (ex: Mouse: Left Down)
Mouse: <Left|Middle|Right> Down impulse mouse.<id>.down() Triggers whenever the <left|middle|right> mouse button is being pressed down. (ex: Mouse: Left Down)
Key: <0-9, A-Z> impulse key.#() Triggers whenever the 0-9 or A-Z key is being pressed (case-insensitive, not numpad). (ex: Key: 0)
Script Execution Context
Name Function Signature Description
Mouse: <Key> bool mouse.<key>.state() Returns true if the <key> mouse button is currently being held down.
Screen: Height int height() Returns the height of the screen in pixels.
Screen: Width int width() Returns the width of the screen in pixels.
UI: Size double ui.size() Returns the value of the UI size option from from the options menu as a double ranging from 0.5 (50%) to 1.0 (100%)
Script: Triggering Impulse string impulse() Returns the ID of the impulse which triggered this script instance. If the script was triggered by another script then this function will return the name of that script
Basic: Remaining Budget int budget() Returns the remaining execution budget of this script during execution.
Time: Frame int time.frame() Returns the total number of frames since the start of the game.
Time: Delta double time.delta() Returns the total time in seconds between the current frame and the last frame. Pausing or accelerating the game affects this value.
Time: Scale double time.scale() Returns the factor at which the game is currently accelerated. (0 if the game is paused, 1 if the game runs at normal speed 2 if the game runs at 2x speed and so on)
Time: Unscaled Delta double time.unscaled() Returns the total time in seconds between the current frame and the last frame. This value is neither affected by pausing nor accelerating the game.
Timestamp: Now double now() Returns the current local time in ticks representing the time from midnight , January 1st, 0001 until now. (UNIX time)
Timestamp: UTC Now double utcnow() Returns the UTC time in ticks representing the time from midnight , January 1st, 0001 until now. (UNIX time)
Execution Primitives
Name Function Signature Description
Basic: Goto void goto(int line) Jumps to line line. The first line in the script equals 1. Entering an invalid line number will result in the value being clamped between the min. and max. boundaries during execution.
Basic: Goto-If void goto(int line, bool condition) Jumps to line line in the current script if condition is True. First line equals 1.
Basic: Click void click(vector2 pos) Performs a mouse click at following location: pos.
Basic: Slider void slider(vector2 where, double value) Sets the slider position where on the screen to value with 0 being the leftmost and 1 being the rightmost end.
Basic: Scrollrect void scrollbar(vector2 where, double horizontal, double vertical) Scrolls within a scrollable container at where to horizontal (horizontally) and vertical (vertically) with 0 being the left/lower end and 1 being the right/upper end. Use a negative value to ignore an axis.
Basic: Wait void wait(double value) A simple wait function that stops the current script for a total of value seconds.
Basic: Wait Until void waituntil(bool condition) Stops the current script until condition becomes True.
Basic: Wait While void waitwhile(bool condition) Stops the current script as long as condition is True.
Basic: Wait Frame void waitframe() Stops execution of this script for this frame and continues in the next one.
Basic: Execute void execute(string script) Executes the first script in the list which is named script without requiring an impulse. Conditions of the script called still have to be fulfilled. Executed scripts are put at the end of the script list, and because of this they (usually) will run their first action in the same frame, since the script list pointer is still on the calling script, earlier in the script list.
Basic: Execute (Sync) void executesync(string script) Executes the first script in the list which is named script and waits until the execution is completed. Conditions of the script still have to be fulfilled.
Basic: Stop void stop(string script) Stops the execution of all scripts and script instances which are named script. Important bug/feature: If a script stops itself, the script list pointer is reset to the beginning, effectively giving everything before this script an "extra" cycle. Because scripts that have reached the end aren't cleaned up until the end-of-frame processing, this means that scripts on their last line (or that have jumped to 99) will re-execute their last line, which can cause bugs. This behavior is known as "Turbo Exec," since it can be used to build programs that execute much faster than the typical one-action-per-frame.
Local: Get <T> T local.get(string var) Returns the value of the the local variable var.
Local: Set <T> void local.set(string var, T value) Creates or changes the the local variable var to contain the value value.
Local: Unset void local.unset(string var) Deletes the local variable with the name var.
Global: Get <T> T global.get(string var) Returns the value of the the global variable var.
Global: Set <T> void global.set(string var, T value) Creates or changes the the global variable var to contain the value value.
Global: Unset void global.unset(string var) Deletes the global variable with the name var.
Boolean Primitives
Name Function Signature Description
Numerical Primitives
Name Function Signature Description
Integer Primitives
Name Function Signature Description
Double Primitives
Name Function Signature Description
String Primitives
Name Function Signature Description
String: Contains bool contains(string str, string substr) Returns true if the string str contains the string substr. (ex: "Catch" Contains "Cat")
Vector Primitives
Name Function Signature Description
Town APIs
Name Function Signature Description
bool anyopen()
bool isopen(string: window) Returns true if the Buildings window is active and visible on the screen. (ex: Tower Testing is open)
Town: Open Window void show(string building, bool open) Opens the building window if openis True, otherwise it will be closed. Opening or closing windows this way does not play the transition animation!
bool isBossFight()
bool isTowerTesting()
double resource(string currency)
Tower Testing APIs
Name Function Signature Description
Game: Is Paused bool pause.get() Returns true if the game is currently paused during tower testing via the pause button. Outside tower testing this will always return false.
Game: Set Pause void pause.set(bool enable) Sets the pause state to enable.
Game: Pause void pause() Pauses tower testing via the pause button if possible.
Game: Unpause void unpause() Unpauses tower testing via the pause button if possible.
Software: Is Enabled bool software.enabled(string software) Returns true if the software with id software has been enabled. Returns false is the software has not been toggled on or has not been researched yet.
Software: Find ID string software.find(string software) Returns the correct software ID of the software with the closest match to software (case-insensitive). This function is very slow. Avoid using it in performance critical sections.
Software: Toggle void software.toggle(string software, bool enabled) Enables software software if the condition bool condition is true or disables it if the condition is false.
Game: Number of Enemies int enemies() Returns the numbers of enemy units which are currently present on the map. Returns 0 if tower testing is not active.
Game: XP double xp() Returns the current amount of tower testing experience. Returns 0 if called outside of tower testing.
Game: Wave Acceleration double waveAcceleration() Returns the current wave acceleration factor. (You can check the current value inside the stats menu during tower testing).
Game: Fixed Waves Per Interval double fixedWavesPerInterval() Returns the current amount of fixed waves per interval as seen in the stats menu during tower testing. Returns 0 if currently not tower testing.
Game: Wave double wave() Returns the current wave during tower testing or 0 if tower testing is not active.
Highscore: Wave double highscore.wave(string region, string difficulty Returns the wave record of region region on difficulty difficulty.
Game: Era double era() Returns the current era during tower testing or 0 if tower testing is not active. Equivalent to wave() / 1e11.
Highscore: Era double highscore.era(string region, string difficulty Returns the era record of region region on difficulty difficulty. Equivalent to wave() / 1e11.
Era: Disable Cost double disable.cost(string element) Returns the XP cost of the upgrade that disables the era powers of element enemies. Returns -1 outside of tower testing or if the upgrade is not available in the current region.
Era: Disable Power void disable.era(string element) Tries to disable the era powers of element enemies by purchasing the according upgrade using xp.
Era: Upgrade Divider void upgrade.era(string divider, int times) Attempts to upgrade the era str (damage, health) divider a total of int x times by using xp.
Game: Infinity double infinity() Returns the current infinity during tower testing or 0 if tower testing is not active. Equivalent to wave() / 1e22 and era() / 1e11.
Highscore: Infinity double highscore.infity(string region, string difficulty Returns the infinity record of region region on difficulty difficulty. Equivalent to wave() / 1e22 and era() / 1e11.
Infinity: Secure Module Cost double disable.inf.cost() Returns the amount of XP required in order to secure/disable a module during infinity phase.
Infinity: Secure Module void disable.inf(string moduleId) Attempts to secure the module with id str id to prevent enemies from mimicking it during the infinity phase.
Game: Active Module Count int active.count() Returns the total number of active modules in the currently active blueprint of the tower. Returns 0 outside of tower testing.
Game: Active Module Index int active.index(string moduleId) Returns the index of the active module with ID moduleId inside the active skills list. If the module is not inside the list or tower testing is not active then this function will return 0.
Game: Active Module ID string active.id(int index) Returns the ID of the active module in slot index in the active modules list whereas 1 refers to the first module in the list. Returns an empty string if the slot index is invalid or tower testing is not active.
Tower: Is Stunned bool stunned() Returns true if the tower is stunned and false if the tower is either not stunned or does not exist.
Tower: Negative Buffs int negative() Returns the total number of nagative buffs currently present on the tower or 0 if the tower has no negative buffs or does not exist.
Tower: Health double health(bool percent) Returns the current health of the tower or 0 if the tower is dead does not exist. Returns the value as a percentage of max health value if percent is true otherwise the absolute value.
Tower: Max. Health double health.max() Returns the maximum hitpoints of the tower or 0 if the tower is either dead or does not exist.
Tower: Health Regeneration double health.regen() Returns the current health regeneration of the tower or 0 if the tower does not exist.
Tower: Energy double energy(bool percent) Returns the current energy of the tower or 0 if the tower does not exist. Returns the value as a percentage of max energy value if percent is true otherwise the absolute value.
Tower: Max. Energy double energy.max() Returns the maximum energy of the tower or 0 if the tower is either dead or does not exist.
Tower: Energy Regeneration double energy.regen() Returns the current energy regeneration of the tower or 0 if the tower does not exist.
Tower: Shield double shield(bool percent) Returns the current shieldpoints of the tower or 0 if the tower is dead or does not exist. Returns the value as a percentage of max shieldpoints value if percent is true otherwise the absolute value.
Tower: Max. Shield double shield.max() Returns the maximum shieldpoints of the tower or 0 if the tower is either dead or does not exist.
Tower: Module Cooldown double cooldown(int skill) Returns the remaining cooldown of the active module at slot skill in seconds Slot 1 refers to the first module in the active modules list.
Tower: Attack Range double tower.range() Returns the tower's current attack range. (Default attack range without any modules or buffs is 18).
Tower: Use (Instantly) void useinstant(int skill) Orders the Tower to use the Modules at slot skill where slot 1 refers to the module at the very top of the skill menu. Entering an invalid slot will do nothing.
Tower: Use (Position) void useposition(int skill, vector2 pos Orders the tower to use the module at slot skill where slot 1 refers to the module at the very top of the skill menu at an offset of pos
Tower: Restart void restart() Restarts the current Tower Testing run. Can only be can only be executing during or at the end of a run that took equal or longer than a second.
Tower: Exit void exit() Exits the current Tower Testing run.
Power Plant APIs
Name Function Signature Description
Powerplant: Sell Sells the Power Plant component at X: int x and Y: int y and automatically refunds a part of the selling price. If the selected slot is empty then nothing will happen. (0, 0) is the bottom left corner of the grid.
Mine APIs
Name Function Signature Description
Mine: Dig Digs up the tile at X: int x and Y: int y of the currently selected resource in the Mine with (0, 0) being the top left corner. Only works if the Mine window is active!
Mine: New Layer Generates a new layer of the currently selected resource in the Mine. Only works if the Mine window is active!
Mine: Open Tab Opens the mining tab at position int position. Position 1 is the first tab (Orange) and position 12 is the last tab (Black).
Mine: Delete Cluster Removes the asteroid cluster at list position int position where 1 represents the first cluster in the list.
Factory APIs
Name Function Signature Description
Factory: Try Craft Tries to craft str item (Tier int tier) a total of double total times by using items inside the inventory or crafting grid. If that is not possible then no items are being crafted. Only works if the Factory screen is visible.
Factory: Try Produce Tries to put double amount x str item (Tint tier) into machine str machine. If too few items are available or the selected machine is currently busy with a different item type then nothing will happen. Ignores the tier if the selected item ID is rubber.
Factory: Trash Tries to put double amount x str item (Tint tier) into the trash can of the Factory. If too few items are present in the inventory and the crafting grid of the Factory then it will still try to remove as many as possible. Ignores the tier for items that don't have a tier.
Factory: Cancel Machine Stops production of the Factory machine with the id str machine and ejects all items back to the inventory if possible.
Arcade APIs
Name Function Signature Description
Arcade: Spin Lucky Wheel Spins the Lucky Wheel with a wager of double wager.
Arcade: Jumble New Game Starts a new game of Jumble with a wager of double wager.
Arcade: Jumble Stop Stops the current column.
Adventure: Move Moves the player in the direction of vector x,y in Adventure.
Adventure: Wait Skips a turn in Adventure.
Adventure: Place Bomb Places a Bomb at the Player location in Adventure.
Trading Post APIs
Name Function Signature Description
Tradingpost: Refresh Generates a new set of offers in the Trading Post. Requires a specific upgrade for the Trading Post later in the game in order to be used!
Tradingpost: Trade Trades the offer at position int position in the list of offers (first offer is at position 0) using double percent (0.15 = 15%) of the available input resources.
Museum APIs
Name Function Signature Description
Museum: Buy Buys a str element Power Stone of tier int tier from the shop or market int amount times.
Museum: Buy Range Buys a str element Power Stone between tier int tier and int tier from the shop or market int amount times.
Museum: Combine Combine Power Stones with the usual combine rules up to Tier int tier (<1 means no limit).
Museum: Transmute Transmute Power Stones currently inside the Cubos Cube.
Museum: Move Move a Power Stone from str location in slot int slot to str location.
Museum: Move Slot Move a Power Stone from str location slot int slot to str location int slot.
Museum: Swap Swap the Power Stones in str location slot int slot and str location int slot.
Museum: Sell Sell the Power Stone from str location in slot int slot.
Museum: Sell All Sell all Power Stones from str location.
Museum: Set Preferred Tier Sets the preferred market tier to int tier.
Museum: Set Preference Set the market preference for element str element to bool value.
Museum: Market Refresh Refreshes Market Offers
Museum: Buy Market Buy the Power Stone from market in slot int slot int amount times.
Museum: Lock Market Slot Set the lock state of Market slot int slot to bool value.
Museum: Rebuy Rebuy the Power Stone from Trash slot int slot.
Worker APIs
Name Function Signature Description
bool worker.paused(string name)
int worker.group(int index)
string worker.name(int index)
string worker.task(string name)
Workers: Toggle Group void worker.toggleGroup(int group) Toggles the paused state of all workers in group int group. (Click on the parameter to see which color belongs to which group id.) Colors: White (0), Red (1), Blue (2), Green(3), Yellow (4), Magenta (5)
Workers: Pause Group void worker.pauseGroup(int group, bool paused) Sets the paused state of all workers in group int group to bool value. (Click on the parameter to see which color belongs to which group id.)
Workers: Toggle void worker.toggleName(string name) Toggles the paused state of all workers with name str name.
Workers: Pause void worker.pauseName(string name, bool paused) Sets the paused state of all workers with the name str name to bool value.
Workers: Assign Group void worker.assignGroup(string task, int subtask, int group) Assigns the task with id str id and optional parameter int param (0 is the leftmost) to all workers in group int group. (Click on the groups parameter to see which color belongs to which group.)
Workers: Assign void worker.assignName(string task, int subtask, string name) Assigns Task with ID str id and optional parameter int param (0 is the leftmost) to all workers with the name str name. TaskIDs
Workers: Set Name void worker.setName(int index, string name) Sets the name of the worker at index int index to str name.
Worker: Set Group void worker.setGroup(int index, int group) Sets the group of the worker at index int index (0 is the first worker) to the group with id int id.
User Interface APIs (requires boots.d0s)
Name Function Signature Description
Canvas: Draw Rect void canvas.rect(vector2 pos, vector2 size, string colour Draws a rectangle on the drawable canvas at location pos with a size of size and colored in colour. (Accepts #RRGGBB and #RRGGBBAA as inputs for color.)
Canvas: Clear void canvas.clear() Clears the drawable canvas instantly.
Window: Create void create(string windowId, string windowType) Creates a window with the unique identifier windowId (used to address the new instance) of type windowType (window name inside windows list).
Window: Set Text void text.set(string windowId, string textElementId, string value) Sets the content inside the window with the id windowId of the text label with the id textElementId to value.
Window: Set Sprite void sprite.set(string windowId, string elementId, string spriteId) Sets the sprite inside the window with the id windowId of the button/image with the id elementId to spriteId.
Window: Get Visibility bool visibility.get(string windowId)
Window: Set Visibility void visibility.set(string windowId, bool visible) Set the window with id windowId to visible if visible is true. Otherwise it will be hidden.
Window: Get Child Visibility bool child.visibility.get(string windowId, string childElementId)
Window: Set Child Visibility void child.visibility.set(string windowId, string childElementId, bool visible) Set child of window with id windowId with id childElementId to visible if visible is true. Otherwise window will be hidden.
Window: Set Position void position.set(string windowId, vector2 position) Changes the position of the window with id windowId to position based on the anchor of its root element. Per default the anchor is set to the center of the window and 0,0 represents the center of the screen.
Window: Destroy void destroy(string windowId) Destroys the window with the unique identifier windowId.
Window: Destroy All void destroy.all() Destroys all active windows.


Retrieved from "https://www.perfecttower2.com/wiki/index.php?title=AI&oldid=3568"