Gumbo Script 101

Welcome to Gumbo Script 101. We'll be creating and breaking down a basic AI script that will get an NPC through combat.

You can view the complete script here.

Setup
In your current content pack:
 * 1) Create the data/ai directory
 * 2) Make an .ai.txt file so the level editor knows the script exists (e.g. gumbo_test.ai.txt)
 * 3) Open the .ai.txt file in a text editor and enter the following
 * name: "gumbo_test"
 * 1) Make a gumbo.txt file to write the script in. This should match the name indicated in the ai.txt file
 * gumbo_test.ai.txt | gumbo_test.gumbo.txt

Variables
Variables are the first thing found in a gumbo script file. These variables are made up of a type prefix, variable name, and value. {string,VERSION,1} {number,MAX_ATTACKS,1} {number,DEFAULT_LOOPS,3} In the above sample, the Variables are predefined. This means they have predetermined uses so their name and type should not be changed or reused. Here we have set:
 * The version number
 * The maximum number of attacks the AI can use
 * The default amount of times a loop will run with no value.

Decisions
The first thing your AI script is going to run will involve decisions. In this case, it will decide if it has a Minor or Major turn available to it. These functions are intended to RETURN True or False to make that decision.

[DECIDE_MAJOR] IF EVALUATE HAS_MOVETO RETURN true IF EVALUATE HAS_PATROL RETURN true IF IS ENEMY MATCH(alive) RETURN true RETURN false

[DECIDE_MINOR] IF EVALUATE HAS_MOVETO RETURN true IF EVALUATE HAS_PATROL RETURN true RETURN false

Major

 * 1) If the AI has a MoveTo target the function Returns True
 * 2) If the AI has a Patrol path the function Returns True
 * 3) If the AI is aware of an Enemy that is Alive the function Returns True

Minor

 * 1) If the AI has a MoveTo target the function Returns True
 * 2) If the AI has a Patrol path the function Returns True

The major difference between the turns ends up deciding if the AI is currently in combat. This is based upon whether or not it is aware of a living enemy.

Defining Starts
With a decision made the script will proceed to taking its Major or Minor turn. This is where the core loop of your script resides.

Major Start
[MAJOR_START] IF RUN DO_MOVETO ELSEIF RUN ENGAGE ELSEIF RUN SEARCHER ELSEIF RUN DO_PATROL IF IS AP>0 LOOP RETURN The Major Turn here consists of a few different actions. At the start of every turn the AI will step though and check for a MoveTo target, failing that it will attempt to ENGAGE,  SEARCH, or continue its  PATROL. It will loop through these actions until its AP is 0 or it has looped 3 times. At this point the function calls RETURN, ending the function call and the turn is passed to the next AI.

Minor Start
[MINOR_START] IF RUN DO_MOVETO ELSEIF RUN DO_PATROL RETURN

The Minor Start refers to actions the AI can take when it is not yet aware of any enemies. In this case the AI will attempt to move to a destination. If it doesn't have one it will attempt to follow a Patrol Route. The end of the function calls RETURN, which ends the function call.

Combat
Combat in this script has two parts: Engage which runs the combat actions and Can Engage which checks if there are targets.

Can Engage
[CAN_ENGAGE] RETURN ENEMY MATCH(alive, in_sight) This function is called as a part of the @gate parameter of Engage. The function Returns true if an Enemy matches the Alive and In Sight adjectives. If there are no enemies that match these attributes, the function will Return False causing the Engage function to end.

Engage
[ENGAGE] @gate=CAN_ENGAGE IF SELECT ENEMY MATCH(alive, in_sight) MOVE ACTOR_SELECTION in_cover, sweet_range ELSEIF SELECT INVENTORY MATCH(attack) DO ITEM_SELECTION RETURN Once Can Engage has finished running, if it got a list of enemies that were Alive and Insight, Engage will proceed to select an enemy.
 * 1) If the AI can select an Enemy from the list that is Alive and In Sight
 * 2) The AI moves so that it is In Cover and Sweet Range of the selected Enemy
 * 3) If it can select an Inventory item with the attack adjective
 * 4) It uses the selected item on the target.
 * 5) Finally the function calls Return to end

Can Search
[CAN_SEARCH] RETURN ENEMY MATCH(alive) As a part of the @gate parameter of Searcher, this function checks if there is an Enemy that Matches alive and Returns True if one is found.

Searcher
[SEARCHER] @gate=CAN_SEARCH IF SELECT ENEMY MATCH(alive) MOVE ACTOR_SELECTION RETURN


 * 1) If Can Search returns true, the function continues to run.
 * 2) If the AI can Select an Enemy that is alive
 * 3) We move the AI towards that Enemy
 * 4) The ends upon calling Return

Has Move To
[HAS_MOVETO] RETURN SELF MATCH(moveto) Has MoveTo acts as the @gate parameter for Do MoveTo. It checks if the AI has a MoveTo and Returns True or False.

Do Move To
[DO_MOVETO] @gate=HAS_MOVETO MOVE moveto LOOP If Has MoveTo Returns True:
 * 1) The AI moves towards the its MoveTo target
 * 2) The AI loops the function until it no longer has a MoveTo target or has looped 3 times.

Has Patrol
[HAS_PATROL] RETURN SELF MATCH(patrol) Has Patrol acts as the @gate parameter for Do Patrol. It checks if the AI has a Patrol Path and Returns True or False.

Do Patrol
[DO_PATROL] @gate=HAS_PATROL MOVE patrol LOOP If Has Patrol Returns True
 * 1) The AI moves along its Patrol Path
 * 2) The AI loops through this command until it no longer has a path or has looped 3 times.