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"
```
4. 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

## Searching

### 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

## Moving Around

### 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.