The FPI scripting language.     (Updated with new commands on 01/24/09)

The FPI scripting language is a simple trigger-based artificial intelligence language used to program objects in games. It consist of a simple if/then syntax and a pre-defined list of conditions and actions.  This tutorial will discuss how the game engine processes fpi script elements and it's progression.

An fpi script is made up of statements and remarks.  The statements start with a colon. Following that is a condition, a test to see if something is true. If there is more than one condition, they are separated by a comma. After all the conditions have been listed, there is another colon. The second colon separates the conditions from the actions. If there is more than one action, they too are separated by a comma.

:condition,second condition:action,second action

Remarks, sometimes called comments, start with a semicolon. For the purpose of this tutorial, we will use the term remarks so that we don't confuse comments with conditions.  Remarks are used to label the script and clarify or document it's use for both the creator and end user.  In many cases, a remark is used to define a segment of a script, such as the header and trigger sections.  The engine ignores remarks when executing the script and they are in no way necessary for it to operate, except for the reason stated above.  We will discuss the importance of remarks again as we dissect a script.

;this is a remark

In the following sample script, you can see the use of Remarks, Conditions and Actions.  The scripts remarks are in gray, the description is in red, and the statements ( conditions and actions ) are in blue.  These colors are for the purpose of identifying the parts of the script in this tutorial only.  Unless you use an editor with syntax highlighting, the scripts text will all be in the same color.  The use of spacing between script lines can also help to define and clarify the script and it's different sections.

Lets begin at the top and work our way down the script.

;Artificial Intelligence Script

This first remark defines the document as being an Artificial Intelligence Script.  As stated earlier, remarks help both the creator and end user to locate, use, and alter the script if necessary.  While this may seem unnecessary in a script such as this, it's value becomes more apparent in larger, more complex scripts with multiple paths and operations.

;Header

The header section is followed by the scripts description ( desc = description )  and may contain additional remarks as required to clarify the scripts purpose, actions or even instructions to the end user.  Simply stated, anything can follow the header remark.  Remember that each new line of a remark must begin with a semi-colon.

desc = Player Proximity Door (Open and Close)

The scripts description is preceded by the abbreviation desc =.  While a description is not necessary for the script to operate, I'm sure you can realize the purpose for this one by now.  Believe me, as you get into more complicated scripts, the reason for all this documentation will become apparent. 

So far we have discussed the basic contents of fpi scripts, the proper way to document them and the reasons to do so. Now its time to get down to the meat of the script.  

;Triggers

The triggers section contains the statements of the script and is made up of conditions and actions.  As earlier discussed, statements start with a colon, followed by a condition.  In order to understand how conditions are tested, it is important to know how values are stored.  Think of a condition as being a container.  Inside the container is a value which can be set at the start of the game, changed during the play of the game, or fixed throughout the game.

Lets break down the first line in the triggers section.

:state=0,plrdistwithin=120:state=4

The first condition we see is "state=0".  State is the container and the value it holds is "0".  As the game begins this is true because the value of "state" is always initialized at "0".  Because "state=0" is true, the engine continues to process the statement. 

Next, the comma tells us that there is another condition to be tested, "plrdistwithin=120".  Remember that "plrdistwithin" is the container and "120" is the value it holds.  If this condition is true ( the player is within 120 units) then the engine continues to process the statement.  If not, ( the player is not within 120 units) then the engine stops processing the statement.  For the sake of this tutorial, let's say that the player is within 120 units and the engine continues to process the statement.

Next, the colon tells the engine that there are no more conditions to be tested and since they all tested positive, or true, it's time to process the actions.  The first action, "state=4" is now processed by the engine.  This means that the value in the container "state" is changed from "0" to "4", or state=4.  As you may have noticed, "state" is used as a condition and an action, allowing the script to progress to another statement and perform more actions.  Since there are no more actions and that is the end of the statement, the engine move on to the next line.

Before we move on, let's look at what just happened in the scripts first statement using layman's terms.  

:state=0,plrdistwithin=120:state=4

The engine processes the statement as follows:

1. The colon tells the engine that a statement is about to be processed
2. The first condition, state=0, is true so the engine continues to process the statement.
3. The next condition, plrdistwithin=120, is true so the engine continues to process the statement.
4. The next colon tells the engine there are no more conditions, and since all were true, it may now begin to process the actions.
5. The first action, state=4, is processed by the engine and the value of state is now 4.

There is an exception to the condition/action format that we see in this script.  What if we wanted the engine to perform an action unconditionally?  In that case, we would start the line with a colon, as usual, and follow it immediately with another colon.  For instance:

::incframe=0

In this case the engine has no conditions to test, and since none are false, moves on to perform the actions.  In all cases, anything that is not false is true and vice-versa.  Again, this is just an example and it does not appear in our sample script, so let's move on.

:state=1:incframe=0

The engine once again begins to process the conditions on this statement, but something different happens here.  The first condition after the colon, "state=1" is not true because the value of "state" was changed to "4" by the previous statement.  Therefore the engine stops processing this statement and moves on to the next without processing any of the statements actions.  The engine continues to check the conditions in each new statement until a condition is met or true.

:state=1:incframe=0
:state=1,frameatend=0:state=2,coloff
:state=2,plrdistfurther=120:state=3,sound=$1,colon
:state=3:decframe=0
:state=3,frameatstart=0:state=0,setframe=0

Therefore, the processing of this script begins once again in the following statement:

:state=4,plrcanbeseen:state=1,setframe=0,sound=$0

Since "state=4" is true, the engine continues to process the next condition in the statement, "plrcanbeseen". If that condition is met, or true, then the progression continues.  If this condition is not true (the player can not be seen) then the engine stops processing the statement, and the value of "state" remains "4". The engine continues to loop through the statements, stopping at "State=4" to see if "plrcanbeseen" is true yet.  If and when that condition is met, the progression will continue.

You may have wondered why the value of "state" was changed from "0" to "4" when there are clearly states 1, 2, and 3 in-between.  The first action in this statement provides the answer.  The value of "state" is now changed to "1", and when the player can be seen (plrcanbeseen=true), progression will continue on the "state=1" statement.  The "state=4" action created a loop, if you will, that told the engine to continue checking the condition "plrcanbeseen" and not to move on until it were true.

So the engine continues to the next statement and so on.  When it reaches the end, it begins processing once again at the beginning, and so loops until destroyed, instructed to stop or the game ends.

The script ends with a remark telling you that you have reached the end.  More remarks may follow the "End of Script" remark if desired, always remembering to start each line with a semi-colon.

;End of Script

Knowing how the engine processes a script is a good first step in learning to understand and create fpi scripts for your games.  The best way to learn is to study existing scripts.   Follow the progression in your head and see what the script is doing to achieve it's end results.  And remember, practice make perfect.

Included is a list of conditions, action, animations and key codes to use in your scripts.  Happy game making.  

xplosys.

Conditions list

These are the condition words, which will perform actions if all are true:

NEVER is never true

ALWAYS is always true

STATE=X is true when it's value stored in the current FPI script is equal to X

RANDOM=X is true when a random value between 0 and X is equal to one

HEALTH=X is true when health equals X

HEALTHLESS=X is true when the health is less than X

QUANTITY=X is true when quantity is equal to X

SPEED=X is true when speed is equal to X

PLAYERASSOCIATED is true when entity has been associated with player (lift)

PLRDISTWITHIN=X is true when player is within X units

PLRDISTFURTHER=X is true when player is further than X units

PLRALIVE=X is true when player is alive and X is one

PLRHIGHER=X is true when player is X units higher than entity

PLRELEVWITHIN=X is true when player can be seen within X degrees vertical

PLRELEVFURTHER=X is true when player cannot be seen X degrees vertical

ANYWITHIN=X is true when any other entity moves within X quarter tiles

ANYFURTHER=X is true when no within X quarter tiles

PLRCANBESEEN=X returns TRUE, if the player can be seen by the entity, where =X will provide additional vertical angle of sight data. If no =X is used, the default value is =22

PLRCANNOTBESEEN is true when player cannot be seen

PLRHASKEY=X is true when player has pressed the key denoted by the value X

PLRUSINGACTION=X is true when player performs the USE action

SHOTDAMAGE=X is true when damage taken exceeds the value X

IFWEAPON=X is true when the weapon being used by entity is ready and X is one

ACTIVATED=X is true when the activation value of the entity equals X

PLRWITHINZONE is true when player is within the trigger zone

ENTITYWITHINZONE is true when an entity is within the trigger zone

PLRINGUNSIGHT=X is true when an entity has the player is gun sights

NEARACTIVATABLE=X is true when entity is being near activated

NEWWEAPONCANBESEEN=X is true when the entity can see a better weapon

NOISEHEARD=X is true when the entity hears a broadcast noise from scene

RAYCAST=X Y is true when the raycast hits something in front from X to Y units

RAYCASTUP=X is true when the raycast hits something above from X to Y units

RAYCASTBACK=X is true when the raycast hits something back from X to Y units

FRAMEATEND=X is true when animation X is at an end

FRAMEATSTART=X is true when animation X is at the beginning

FRAMEWITHIN=X Y is true when animation X is within frame Y

FRAMEBEYOND=X Y is true when animation X is beyond frame Y

ANIMATIONOVER=X is true when animation X is complete

ALPHAFADEEQUAL=X is true when the alpha value equals X

REACHTARGET=X is true when the entity has reached its target

LOSETARGET=X is true when the entity has got stuck after X attempts

HEADANGLEGREATER=X is true when the angle of the head is greater than X

HEADANGLELESS=X is true when the angle of the head is less than X

WAYPOINTSTATE=X is true when the waypoint state value equals X

IFMARKER=X is true when there is a marker previously dropped by entity in scene

IFPLRTRAIL=X is true when there is a trail left by the player in existence

HUDSELECTIONMADE=X is true when the user has clicked HUD button X

TIMERGREATER=X is true when the internal FPI timer exceeds X in milliseconds

ESCAPEKEYPRESSED=X is true when the Escape Key has been pressed

PLRHEALTHLESS=X is true when the players health falls below X

PLRHEALTHGREATER=X is true when the players health is greater than X

ANYWITHIN=X is true when any entity is closer than X to it

ANYFURTHER=X is true when any entity is further than X from it

CANTAKE is true if the entity can be collected by player

ANYWITHINZONE is true when any entity is within its zone

NORAYCASTUP=X Y is true when no collision upwards X to Y

HUDEDITDONE=X is true when ‘editable’ HUD item X is used

HUDHAVENAME is true when no player-name has been entered

LEVELEQUAL=X where X is level

LEVELNOTEQUAL=X where X is level

SCANCODEKEYPRESSED=X is true when X=the key code of a pressed key   ***Added by V1.03

 

	Example: SCANCODEKEYPRESSED=15 is true when the TAB key is pressed

Actions list