Using the AI

As powerful as the AI can be, it can be overwhelming at first, and there are many common mistakes that can be very discouraging at first.

Watch this video for one of the easier to access introductions to using the AI

https://youtu.be/JPFxJFaYcc4

First steps

1. Before you can use the AI at all, you need to install the "Facility AI" software in the headquarters, which you receive at military tier 4.
2. To be able to run a script in the AI, the script needs to be enabled. If it is displayed with a strikethrough then it is disabled, to enable it click on the script name, then tick the enabled button on the left, then hit save. The strikethrough should be removed to show that the script is enabled.
3. Before you can run any scripts, the AI needs to be turned on. If you hit F4 (or whatever key you have configured in the control settings for "AI overlay") then the AI overlay will be displayed showing the running scripts on the left and the global variable with their values on the right. If you turn the AI off, all running scripts are stopped and all global variables are cleared - when you turn the AI back on, it will start from a clean slate.
4. To start a script, you need to trigger one of its impulses. If you edit the script, the impulses will be listed at the top of the script with a red flag on the left. If a script doesn't have an impulse, you can't start it directly, though it can be started by another script.
5. Before the script actually starts, any conditions it has must be fulfilled. If the script has no conditions then the script is always allowed to start.

First scripts

To get you started, try importing the script by the code below. All scripts are disabled when they are first imported, this is to allow you to edit the script and see what it is trying to do before you run it, to prevent someone from giving you a malicious script that runs as soon as you turn the AI on.

FXVuaXZlcnNhbF9tb3VzZV9kZWJ1ZwEAAAAGd2FrZXVwAAAAAAMAAAARZ2xvYmFsLmRvdWJsZS5zZXQI
Y29uc3RhbnQEBm1vdXNleBFhcml0aG1ldGljLmRvdWJsZQxkb3VibGUucm91bmQRYXJpdGhtZXRpYy5k
b3VibGURYXJpdGhtZXRpYy5kb3VibGUGdmVjMi54Dm1vdXNlLnBvc2l0aW9uCGNvbnN0YW50BAEvA2ky
ZAxzY3JlZW4ud2lkdGgIY29uc3RhbnQEASoIY29uc3RhbnQDAAAAAABAj0AIY29uc3RhbnQEAS8IY29u
c3RhbnQDAAAAAABAj0ARZ2xvYmFsLmRvdWJsZS5zZXQIY29uc3RhbnQEBm1vdXNleRFhcml0aG1ldGlj
LmRvdWJsZQxkb3VibGUucm91bmQRYXJpdGhtZXRpYy5kb3VibGURYXJpdGhtZXRpYy5kb3VibGUGdmVj
Mi55Dm1vdXNlLnBvc2l0aW9uCGNvbnN0YW50BAEvA2kyZA1zY3JlZW4uaGVpZ2h0CGNvbnN0YW50BAEq
CGNvbnN0YW50AwAAAAAAQI9ACGNvbnN0YW50BAEvCGNvbnN0YW50AwAAAAAAQI9ADGdlbmVyaWMuZ290
bwhjb25zdGFudAIBAAAA

You should have a script called UNIVERSAL_MOUSE_DEBUG, with a WAKE UP impulse. If you start the AI now, you should see the script in the active list on the left, and some global variables on the right. The variables will change whenever you move the mouse cursor, and they describe the cursor's location in the game screen as "relative coordinates". This is a very useful technique when creating scripts that need to click on the screen, because absolute coordinates will change based on the size of the game's window. But the relative coordinates will be the same for everyone, which makes it easier to share scripts.

A second script

Time to make use of everything so far!

Start the AI and determine the relative coordinates for the MILITARY button in the HQ. If you have the cursor at the top-left of the M, it should be about MOUSEX=0.14, MOUSEY=0.76 - roughly speaking, it's a big button so we don't need to be too accurate.

Click the NEW button to a new script and call it anything, say "let's open the military tab". Actually that won't work, because script names can't be that long, just call it "military state". Leave the enabled box ticked then hit save - you should see a new script appear in the list on the right. Click on your new script and hit edit.

You now have a pristine script, and will need to set it up to do what you want. We want to click on a button, so look for BASIC: CLICK in the components list on the left. Click it, and you'll open a dialog to configure the details of the action. Click on the (X: 0, Y: 0) button for another, slightly more confusing dialog. This is how you configure values in AI scripts, and what this dialog looks like will depend on the type of the value you're configuring, but it's always either setting a constant value that doesn't change at the top, or a calculated value that might change below that. The tick simply shows which is currently active - it has to be one or the other, it can never be both.

It might be tempting to simply enter our 0.14 and 0.76 values at the top, because they certainly are constant and don't change... but that will actually click very close to the bottom-left corner of the game screen, which isn't what we want. So click on the calculation drop-down and choose VECTOR2: FROM COORDINATES. There are now two values at the bottom of the dialog that you can fill in. Click the left one!

You're now configuring a double value, which is just a number. We want to calculate where 0.14 falls in the current screen size, so we need arithmetic. Click on the checkbox next to the dropdown (simply selecting arithmetic in the dropdown doesn't work because it's already selected so it doesn't fire a change event) to show a new set of values to configure. Lots of layers, it's kind of like Inception but less pretty.

Click on the left value and finally enter our relative X coordinate of 0.14, then click the tick to go back to the arithmetic level. Click on the middle value... now we're configuring a string, check out the dropdown list to see what kind of functions we have available now. But we actually want a constant, replace + with * for multiplication. Click the tick again. Finally click on the right value.

To convert 0.14 into an absolute coordinate so we can actually click it, we need to multiply it by the width of the game window. But... how? There are some interesting calculations available in the double list, but none of them obviously have anything to do with the screen size. For now, choose CONVERT: INT. This means that even though we're using a value in a double context, we're actually going to give it a value that's just an integer - it will never have a fractional component (there's nothing after the decimal place). Edit this value and you can see that SCREEN: WIDTH is one of the available calculations. Even better, it doesn't have any values of its own! Hit that tick button until we're back to the VECTOR2 calculation.

Repeat the steps above for the second value here (the Y value) so it's calculating 0.76 * DOUBLE(SCREEN.HEIGHT). Then you can keep hitting the tick button until you close all of the dialogs.

Et voila, we have a script that will click on a predictable part of the screen no matter what size of window the game is playing in! But we still have work to do to run it. Most importantly, we need an impulse. Click the IMPULSE component right at the top of the list, and choose one of the KEY impulses. For the sake of tutorial, I'm going to assume you chose KEY: 1.

Finally, we want to add a condition. It doesn't really make much sense to click a button that's found in the HQ building unless we're actually in the HQ building... in the worst case it might click on something bad like a delete button or something that spends resources that you've been painfully saving. Click the TOWN: WINDOW OPEN condition which is made just for this situation.

This is a string context, but the game knows you want a building name so it isn't going to make you play "guess the noun" and punish you for mis-spelling the building name. Go ahead and choose HEADQUARTERS from the list and save your condition. We now have a script with one impulse, one condition and one action. Perfectly balanced, as all things should be.

Time to test it! Click the cross at the top-right of the script editor, double-check that your script is indeed enabled, then turn on the AI overlay and hit 1. If the computer gods are smiling on us, you're now looking at the military tier screen! Just to be sure, swap over to the workshop and try hitting 1 again. It's likely that nothing happens, but if you're curious and like poking at things, edit your script and delete the condition by hitting the red X on the right of that line. Now when you go back to the workshop and hit 1 it will open up the module blueprint screen. The condition worked!

Let's recap. Now you know how to:

1. Create a script from scratch, with an impulse, condition and action.
2. Convert between absolute and relative coordinates so you can create shareable scripts.
3. You've seen the calculations available for vector, double, int and string values. Check out the bool (boolean) calculations when you need to.
4. How to combine impulses and conditions. This can be a very useful technique so you can reuse the same impulse in different buildings. There aren't many impulses available so this can help them stretch further.

If anything didn't work or didn't make sense above, please come to the discord and ask for help.

Going further

If you want to try writing your own scripts from scratch, a good place to start is the mine because it lends itself well to writing a small script and trying it, then building up more and more functionality around it:

1. Create a script that digs a cell.
2. Add a loop so the script digs all the cells. What about opening a new layer first?
3. Add another loop so you mine all the layers for one type of shard.
4. Try clicking on the mine tabs so you can mine multiple types of shards.
5. Can you make it faster? Can two dig scripts work together to dig all the cells twice as fast? Does it scale further?

If you get stuck, try looking at someone else's mining script and see if you can figure out how they solved the same problems. Or ask in discord for some advice.

AI mechanics, and AI limitations

As all-powerful as the AI can seem, happily the singularity is not yet upon us, and the AI has some (sometimes severe) constraints. Notably...

1. There's a hard limit of 100 active scripts at a time. If another script is started when at the limit, the AI will shut itself down to protect the rest of the game.
2. If an action is made for a particular building, the action will do nothing unless that building screen is currently open.
3. When the AI is on, each active script will execute one action per game tick, in the order that the scripts were started (same as the order in the list of active scripts). We can often take advantage of this determinism to ensure that multiple scripts running at the same time cooperate rather than interfere with each other.
4. If multiple scripts are started by the same impulse, they will be put in the active script list in the order that the scripts were created - the same relative order as the script sources in the facility AI list.
5. When you use one of the execute commands to start a script from another script, the child script will be added to the end of the active script list, and will execute its first instruction in the current game tick.
6. Integer values are limited in the range of +/-2,147,483,647. If you need larger values than that then you will need to use a double value.