AI Scripting Guide by Wok

Welcome to my article about AI Scripting. If you want to know what AI scripting is, or how to do it, you've come to the right place! This guide will teach you the basic principles of creating AI scripts, and some more advanced techniques to improve your abilities. This guide was made with the intent of teaching people how to make AI for scenaio design purposes, but hopefully everybody will be able to make use of it! Happy scripting!

Table Of Contents:

Part 1 - The Technology
Defining AI
How this relates to the game
Your first script

Part 2 - Basic Functions
Rules
Facts
Fact List
Actions
Action List

Part 3 - Scenario Design Effects
Creating Taunt Effects
Random Numbers

Comments/Suggestions

Part 1 - The Technology

Defining AI:

Before I get underway with my guide, you'll probably want to know what the topic at hand is all about. What is AI scripting all about?

Well, AI stands for Artificial Intelligence, which basically means methods that a computer uses to simulate thought. It tells it how to make decisions based on your interactions, and what to do in certain situations. Almost every time you make your computer do something, it is using AI.

What form does it take?

The AI that we will be dealing with in this guide is merely a set of instructions, typed into a text editor, and used in certain ways to create effects. That's all you will need to create AI, a text editor (I recommend NotePad if you are using Windows).

Don't worry if you didn't quite take all that in just yet. AI is a tricky subject. Here's what we have learned so far:

  • AI is the method a computer uses to simulate thought.
  • It is created in a text editor.

How This Relates To The Game:

Well, at least you know what AI is now. It is used differently

with all things, and you'll probably we itching to find out what it can be made to do in-game.

In Star Wars: Galactic Battlegrounds, you can create custom AI scripts or edit existing scripts to edit how the computer plays in-game, i.e. its stategy. The computer has a default AI script built into it that tells it how to play, but creating your own script will change that. Do you want the computer to rush faster? Do you want it to be more agressive? AI scripting can make that happen. It can also be used in conjunction with the scenario editor, and interact with triggers to create powerful effects in-game. AI for SWGB is a ver powerful tool :).

What you should understand by now:

  • AI is the method a computer uses to simulate though.
  • It is created in a text editor.
  • In SWGB, it tells the computer how to play the game.
  • It can be used to create scenario designing effects.

Your First Script:

It's time to learn how you put these scripts into the game, so you're all set for when you can create them yourself. It's actually quite simple to put a created script into effect in the game, but it's a step that many beginners stumble over for some reason :{

Right, to get a script into the game, you need a script ;). You won't understand this yet, it's just to show you an example of a custom script in a game. First, open up NotePad (I always use it, but if you don't have it for some reason, a simple, easy to use text editor is the best). Then, copy/paste the following into your new document:


(defrule
            (food-amount > 0)
            =>
            (chat-local-to-self "My first AI script")
)

That is the script we will use for now. I'll explain what it means later.

Right, now you have your script, you need to save it. However, AI scripts cannot just be saved as regular text files. You can try it, but it won't work! We need to save it as a .per file.

What is a .per file?

For the game to understand the script, it needs to be a .per file. If it isn't, the computer will skip over it and won't think it's a script.

How do you make it into a .per file?

That is easy. When you save your notepad file, save it as myfirstai.per, and set the file type to "all files." Of course it doesn't have to be myfirsai.per, it can be immobile.per, agressive.per, bigbuttocks.per, or absolutely anything you choose, as long as it is something with .per on the end. The name you give it now will be its name in the game. For now, save it as myfirstai.per.

Where do I save it to?

You save your .per file into your SWGB/Game/AI folder. If you don't save it there, it won't work :).

What next?

You've got your .per file and saved it to the right directory, but there's one more step that you need to take before the computer will recognise the AI script in-game. This step, however, is much easier. Open up NotePad and create a new document. Then, without typing anything, save it as myfirstai.ai. If you saved your .per file under a different name to myfirstai, then just save the .ai file under the same name as that, instead. They must have the same name apart from the .ai and .per endings. Save the .ai file to the same directory as you did the .per file (SWGB/Game/AI). The .ai file doesn't at all affect the script, it just tells the computer that there should be a script called samenameasdotaifile.per in the AI folder.

If you have follwed these steps correctly, your new AI will be all ready for you to use. To test it, run SWGB. Go to the screen where you configure your random map settings, and for Player 1, under name, set it to myfirstai. Then, start a random map, with any settings. Upon entering the game, you should constantly receive chat messages saying "My first AI Script." If you do, it worked. If you get an error message, or it doesn't give you chat messages, then you've done something wrong. Go back and double check all of the instructions I gave you.

Summary of what you now know:

  • AI is the method a computer uses to simulate though.
  • It is created in a text editor.
  • In SWGB, it tells the computer how to play the game.
  • It can be used to create scenario designing effects.
  • To make your script work, you need to save a .per and a .ai file to your Game/AI folder [*]You test your script by choosing it in the "Player Name" option in the random map settings.

Part 2 - Basic Functions

So, now you know what an AI script is, and how to install a custom script, but you don't know how to write them yet :p. This part of the tutorial will teach you just that - how to write AI scripts.

Rules:

Let's start by defining a rule. An AI script is made up of many rules that tell the computer how to make decisions. They basically state: "If [a fact] is true, perform [an action]." For those of you with programming experience, that is a simple if-then statement.

Here is how a rule is layed out:

(defrule               ; This always starts a rule
            (fact)       ; A valid fact goes here
            =>           ; Signifies the end of the fact(s), and the start 
of the action(s)
            (action)   ; A valid action goes here. If the fact above is 
true, the action will take place.
)

Of course, this isn't a valid rule, as where it says fact and action, you must replace the text with valid facts and actions (I'll go over those later). This is just to show you how a rule is set out. The (defrule always starts a rule, the => signifies the end of the fact and the beginning of the action(s), and the ) shows the end of a rule. Remember, if the fact is true, the condition takes place! Drum that into your mind now, and you won't go far wrong. Everything behind the semi-colon (;) is a comment, and will be ignored by the computer. You can type whatever you like after a comment, and you won't get errors. You don't have to have them, but they are convenient.

Now let's look at a valid rule. We'll use the one you used in your first script earlier:

(defrule
            (food-amount > 0)
            =>
            (chat-local-to-self "My first AI script")
)

For now, I'll tell you that the fact, (food-amount > 0) means (If you have more than 0 food), and that the action, (chat-local-to-self "My first AI script") means (Send a chat to myself saying "My first AI script")

Now, try and guess what this rule does. Highlight the below text to check your answer.

If you have more than 0 food (the fact), you will recieve a chat message from yourself saying "My first AI script" (action)..

Did you get it right? Good :).

Well, an AI script is made up of almost all rules, so you're not far off being able to write your own scripts :). Now we just need to learn how to write facts and actions.

Summary so far for this chapter:

  • Rules are the basis of an AI script
  • They state that if a fact is true, then an action is performed.
  • They always start with (defrule, end with ), and have a => in the middle.

Facts:

You know what facts are and how they fit into a rule, you just need to learn how to write them.

Facts are generally layed out like so: ([game stat] [rel-op] [value])

The game stat is something in the game which can be recorded and has a value. For example, food-amount, or civilian-population. As a general rule, all game stats have a dash (-) for spaces. There is a list of all available game stats below.

The rel-op (standing for Relative-Operator) is the method used to compare the game stat with the value. These are the rel-ops:

== (equal to)
!= (not equal to)
>(greater than)
< (less than)
<= (less than or equal to)
>= (greater than or equal to)

Examples:


([game stat] == [value]) ; Is true if the game stat is equal to the value.
([game stat] != [value]) ; Is true if the game stat is not equal to the 
value.
([game stat] > [value]) ; Is true if the game stat is greater than the 
value.

etc...

The value could be anything fitting to the game stat. For example, the game stat food-amount would have a value of any number. The game stat current-age would have a value of tech-level-1, tech-level-2, tech-level-3, or tech-level-4. Just use whatever applies. In most cases, it is a number.

So, here are some examples of complete, valid facts:


(food-amount > 0)
(current-age != tech-level-1)
(civilian-population == 40)
(civ-selected GUNGANS) ;note - has no rel-op

Of course, there are some facts which are exceptions to the [game stat][rel-op][value] rule. For example, (cheats-enabled) needs no rel-op or value. The fact (can-build) has no rel-op but has a value of a building. For example, (can-build BLDG-PREFAB). There are also the facts True and False. The True fact is always true, and the False fact is always false (duh :)). Rules can also have more than one fact. It would be set out like this:


(defrule
            (fact 1)
            (fact 2)
            =>
            (action)
)

If you have more than one fact in a rule, all facts must be true before the action takes place.

Summary of chapter so far:

  • Rules are the basis of an AI script
  • They state that if a fact is true, then an action is performed.
  • They always start with (defrule, end with ), and have a => in the middle.
  • Facts usually have 3 parameters: a game stat, a rel-op, and a value.

Fact List:

Right, now you know how to create facts, here's a list of different facts you can use:


true
false
attack-soldier-count    
attack-warboat-count    
building-available  
building-count    
building-count-total    
building-type-count     
building-type-count-total     
can-afford-building 
can-afford-complete-wall  
can-afford-research 
can-afford-unit 
can-build 
can-build-gate  
can-build-gate-with-escrow  
can-build-wall   
can-build-wall-with-escrow  
can-build-with-escrow 
can-buy-commodity 
can-research	
can-research-with-escrow 
can-sell-commodity 
can-spy
can-spy-with-escrow
can-train 
can-train-with-escrow 
cc-players-building-count      
cc-players-building-type-count       

cc-players-unit-count      
cc-players-unit-type-count        
cheats-enabled
civ-selected  
civilian-population    
commodity-buying-price      
commodity-selling-price      
current-age   
current-age-time   
current-score   
death-match-game
defend-soldier-count   
defend-warboat-count   
difficulty   
doctrine 
dropsite-min-distance     
enemy-buildings-in-town
enemy-captured-relics
escrow-amount      
event-detected   
food-amount   
game-time    
goal  
nova-amount    
housing-headroom    
idle-farm-count    
map-size 
map-type 
military-population    
player-computer 
player-human 
player-in-game  
player-number  
player-resigned 
player-valid  
players-building-count      
players-building-type-count       
players-civ   
players-civilian-population     
players-current-age    
players-current-age-time    
players-military-population     
players-population     
players-score    
players-stance   
players-tribute     
players-tribute-memory     
players-unit-count      
players-unit-type-count        
population    
population-cap    
population-headroom    
random-number    
regicide-game
research-available  
research-completed  
resource-found  
shared-goal  
sheep-and-forage-too-far
soldier-count    
stance-toward  
starting-age  
starting-resources  
metal-amount    
strategic-number      
taunt-detected  
timer-triggered 
town-under-attack
unit-available 
unit-count    
unit-count-total    
unit-type-count     
unit-type-count-total     
victory-condition  
wall-completed-percentage     
wall-invisible-percentage     
warboat-count    
carbon-amount    

Actions:

We're almost there ;)

Actions are simpler than facts - there's no 3 part layout. It's generally just something simple like (build BLGD-PREFAB).

You can also have more than 1 action. All of them will fire, one after the other, the moment the fact(s) are true.

Remember that first script you wrote? This one:


(defrule
            (food-amount > 0)
            =>
            (chat-local-to-self "My first AI script")
)

Well, when you tested it in-game, the chat message should have repeated itself over and over again - even though there was only one action. This is because the actions loop. Basically, that means that the actions keep on taking place again and again the whole time the fact is true. This will happen in all rules, but there is a way to stop it. There is an action called (disable-self), which will mean that the actions in the rule never fire, even while the facts are true. Now, when the computer makes a rule pass (something the computer does many times a second where it looks at all the rules in the AI and carries out all the actions that it should, in order), it will see that the facts are true (if they are ;)), and carry out the actions. It will carry out the first action, and then it will get to the second action, (disable-self). This will disable the rule, so that even if the facts remain true, the actions will not be carried out again. For example, this rule will repeat over and over while the facts are true:


(defrule
            (food-amount > 0)
            =>
            (chat-local-to-self "My first AI script")
)

But this rule will not. If the facts become true, the actions will happen once, and then disable:


(defrule
            (food-amount > 0)
            =>
            (chat-local-to-self "My first AI script")
            (disable-self)
)

One last thing to note - every rule needs an action (it's pretty pointless without them ;)). For testing purposes, the action (do-nothing) exists.

I think that just about covers everything to do with actions. Here's a list of ones to choose from:

Action List:


do-nothing
acknowledge-event   
acknowledge-taunt   
attack-now
build  
build-forward  
build-gate  
build-wall   
buy-commodity  
cc-add-resource  
chat-local 
chat-local-using-id 
chat-local-using-range  
chat-local-to-self 
chat-to-all 
chat-to-all-using-id 
chat-to-all-using-range  
chat-to-allies 
chat-to-allies-using-id 
chat-to-allies-using-range  
chat-to-enemies 
chat-to-enemies-using-id 
chat-to-enemies-using-range  
chat-to-player  
chat-to-player-using-id  
chat-to-player-using-range   

chat-trace  
clear-tribute-memory   
delete-building  
delete-unit  
disable-self
disable-timer  
enable-timer  
enable-wall-placement  
generate-random-number 
log 
log-trace  
release-escrow  
research  
research  
resign
sell-commodity  
set-difficulty-parameter  
set-doctrine 
set-escrow-percentage    
set-goal  
set-shared-goal  
set-signal 
set-stance  
set-strategic-number   
spy
taunt  
taunt-using-range    
train 
tribute-to-player     

Input / Output Actions
chat-local
chat-local-using-id
chat-local-using-range
chat-local-to-self
chat-to-all
chat-to-all-using-id
chat-to-all-using-range
chat-to-allies
chat-to-allies-using-id
chat-to-allies-using-range
chat-to-enemies
chat-to-enemies-using-id
chat-to-enemies-using-range
chat-to-player
chat-to-player-using-id
chat-to-player-using-range
chat-trace
log
log-trace
taunt
taunt-using-range
Rule Control Actions
disable-self
Event Actions
     acknowledge-event
acknowledge-taunt
disable-timer
enable-timer
set-signal
Commodity Trade Actions
buy-commodity
sell-commodity
Tribute Actions
clear-tribute-memory
tribute-to-player
Escrow Actions
release-escrow
set-escrow-percentage
Regicide Actions
spy
Cheating Actions
cc-add-resource
Other Actions
do-nothing
attack-now
build
build-forward
build-gate
build-wall
delete-building
delete-unit
enable-wall-placement
generate-random-number
research
resign
set-difficulty-parameter
set-doctrine
set-goal
set-shared-goal
set-stance
set-strategic-number
train

Summary Of Part 2:

  • Rules are the basis of an AI script
  • They state that if a fact is true, then an action is performed.
  • They always start with (defrule, end with ), and have a => in the middle.
  • Facts usually have 3 parameters: a game stat, a rel-op, and a value.
  • There is a list of different facts and actions to choose from.
Part 3 - Scenario Design Effects

Now you are capable of creating your own AI scripts. Now I'm going to teach you how to use them in conjunction with triggers to create some nifty effects in your scenarios.

What can you do with AI that you cannot do with triggers?

The concept of AI is similar to the concept of triggers (not what they are used for, but how they work). However, they vary in a few ways. There are two game stats that can be measured by AI, and not triggers, that can make neat scenario tricks. Taunts and Random Numbers.

Taunt Tricks:

The taunt trick was first used for SWGB in The Phantom Menace, by Tevious. It basically allowed a trigger effect to fire when a taunt was typed into the chat box.

Since Taunts cannot be regustered by triggers, it must be done with AI. You use the fact (taunt-detected [value]), to tribute some resources to a computer player. The resources can be measured with triggers, so can be used in a condition, which sets off an effect.

You use this AI script to tribute resources:

)
(defrule
(taunt-detected 1 1)
=>
(acknowledge-taunt 1 1)
(cc-add-resource nova 1)
)

The red number is the number of the player sending the taunt. It will almost always be player 1. The yellow text is the number of the taunt you want to use. In this case, it is number 1 ("I got it!") The purple text is the resource that will be tributed when you type the taunt. It doesn't matter too much because there are four equal options to choose from. The green number is the amount that of the resource that will be tributed.

Then, save your AI as taunt.per, inside your Game/AI directory. Then create a blank document and save it as taunt.ai, inside the same folder. Inside the scenario builder, you need to set up triggers. You need to make a trigger system so that when the player receives the resource you specified in the AI, it does a desired effect (It could be to heal a character, for example). Then, it tributes the resource back to GAIA, so you can use the effect again.

Random Numbers:

Ever wanted to make a completely random effect in your scenario? Well now you can :). Many methods of simulating this have been attempted, but the most fool-proof way is through the use of AI. Luckily, the AI for this game has a (set-random-number) action :).

Start by pasting the following into NotePad:

(defrule
            (true)
            =>
            (set-random-number 4)   ;This code generates a random number 
between 1 and 4 at the beginning of the scenario
            (disable-self)
)

(defrule
            (random-number == 1)    ;This code tributes 1 food if the random 
number equals 1
            =>
            (cc-add-resource food 1)
            (disable-self)
)

(defrule
            (random-number == 2)    ;This code tributes 1 carbon if the 
random number equals 2
            =>
            (cc-add-resource carbon 1)
            (disable-self)
)

(defrule
            (random-number == 3)    ;This code tributes 1 nova if the random 
number equals 3
            =>
            (cc-add-resource nova 1)
            (disable-self)
)

(defrule
            (random-number == 4)    ;This code tributes 1 ores if the random 
number equals 4. Note == In AI ore is called Metal.
            =>
            (cc-add-resource metal 1)
            (disable-self)
)

Save the file into your Game/AI folder as random.per, then create a blank text document. Save it into the same directory as random.ai.

Then whenever you start a game and somebody has this AI, a random number will be set. If it is 1, 1 Food will be tributed to the player. If it is 2, 1 Carbon will be tributed to the player. If it is 3, 1 Nova will be tributed to the player, and if it is 4, 1 Ore will be tributed to the player. You can use this in combination with triggers to make a nice effect, like a random character or a random hitpoint increase.

Comments/Suggestions:

Thankyou for reading my AI tutorial. If you have any questions related to my tutorial or to AI scritping, then please ask me via this thread and I will try my best to answer. If I have lots of questions, I may start a small FAQ.

I have also undoubtably made errors in spelling, so if you spot any, please point them out ;).

Anyway, I hope you now feel a lot more informed about the ways of AI scripting, and I hope to see some AI based projects from you soon :)



Contact the author, Wok at walk_the_wok@hotmail.com.