The FPI scripting language.

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

NONE no action

DESTROY destroy entity

SUSPEND disable the entity permanently, and keep it visible

RUNFPIDEFAULT=X run a default FPI script by value X (0-init,1-main,2-end)

RUNFPI=X run another FPI script by name X(ie appear1.fpi)

STATE=X sets the value of the internal variable State to X

MOVEUP=X moves the entity up by X units

MOVEFORE=X moves the entity forward by X units

MOVEBACK=X move the entity back by X units

FREEZE=X stop entity from moving

ROTATEY=X set the entity angle around the Y axis for X degrees

ROTATEIY=X rotate the entity around the Y axis incrementally for X degrees

ROTATETOPLR rotate the entity to face the player

RESETHEAD reset the angle of the head if the entity has one

ROTATEHEAD=X rotate the head of the entity by X degrees

ROTATEHEADRANDOM=X rotate the head of the entity at random by X degrees

FORCEBACK=X apply a force to the entity by a factor of X backwards

FORCEFORE=X apply a force to the entity by a factor of X forwards

FORCELEFT=X apply a force to the entity by a factor of X left

FORCERIGHT=X apply a force to the entity by a factor of X right

FORCEBOUNCE=X apply a force to the entity to cause it to bounce back by X

SPINRATE=X spin the entity around the Y axis at a rate of X

FLOATRATE=X cause the entity to float in the air at a hover rate of X

SETFRAME=X set animation X start frame

INCFRAME=X increment another frame in animation X

DECFRAME=X decrement another frame in animation X

ANIMATE=X automatically play animation X

           In regards to characters provided, there are a number of animations built in which can be played.  The following table provides the Animation number and the start and end frame for each.

ASSOCIATEPLAYER associate this entity with the player (lift)

UNASSOCIATEPLAYER disassociate this entity from the player

PLRMOVEUP=X move the player up by X units

PLRMOVEDOWN=X move the player up by X units

PLRMOVEEAST=X move the player east by X units

PLRMOVEWEST=X move the player west by X units

PLRMOVENORTH=X move the player north by X units

PLRMOVESOUTH=X move the player south by X units

PLRMOVETO=X move the player to a new location described by entity name X

PLRMOVEIFUSED=X if player performs the USE action, move the player as above

ACTIVATEIFUSED=X activate entity described in IFUSED property

ACTIVATEIFUSEDNEAR=X activate entity described in IFUSED and near it

ACTIVATETARGET=X activates the entity previously marked as the target with X

ACTIVATE=X activate this entity using the value X

ACTIVATEALLINZONE=X activate all the entities within the trigger zone with X

PLRADDHEALTH=X adds X points to the players health

SETTARGET sets the internal target for the entity, follows ‘target’ conditions

ROTATETOTARGET rotate the entity to face the target

LOOKATTARGET rotate the head of the entity to face the target

MOVETOTARGET moves to the target

COLLECTTARGET if the target is a collectable, collect the target if close

SETTARGETNAME Specify an entity name to force the entity using the action to target the named entity

CHOOSESTRAFE randomly selects a strafe direction (ie left/right/forward)

STRAFE perform the previously chosen strafe to avoid player shots

PIVOTRANDOM=X randomly pivots around to face another direction by X degrees

LOOKATPLR=X look directly at the player even if the player cannot be seen

SOUND=X plays a sound specified by the X filename. Use $0 to specify soundest

PLRSOUND=X plays a 3d sound at the player's current position, the sound file is specified by=X

LOOPSOUND=X loops a 3D sound specified by the X filename

STOPSOUND stops playing the currently looping sound

ALTTEXTURE=X set the texture used based on X being either zero or one

SETALPHAFADE=X set the alpha value to X which causes entity transparency

INCALPHAFADE=X increment the alpha fade, X being the destination

DECALPHAFADE=X decrement the alpha fade, X being the destination

RUNDECAL=X create a decal from the entity, X being a specific mode 1-6

WAYPOINTSTART instructs the entity to find the closest waypoint

WAYPOINTSTOP stops the entity following waypoints

WAYPOINTREVERSE makes the entity reverse course and go the other way

WAYPOINTNEXT instructs the entity to find the next waypoint

WAYPOINTPREV instructs the entity to find the previous waypoint

WAYPOINTRANDOM instructs the entity choose a random waypoint direction

DROPMARKER drops a marker the entity can later return to

NEXTMARKER instructs the entity to go to the last dropped marker

RESETMARKERS resets all markers dropped by this entity

FOLLOWPLR follows the players trail if one exists

PLAYERTAKE used to add an entity to the players inventory and acquire its assets

PLAYERDROP used to drop an item from the players inventory

SHOOTPLR runs the internal FPI script SHOOT specified in character properties

USEWEAPON fires any weapon held by an entity in the direction of the target

RELOADWEAPON reloads the weapon from the entities stock of infinite ammo

COLOFF deactivate all player collision with this entity

COLON activate all player collision with this entity

ACTIVATE=X sets the activation value of the entity to X

AMBIENCE=X sets the overall ambient light level within the scene to X

AMBIENCERED=X sets the red component of the ambient light to X

AMBIENCEGREEN=X sets the green component of the ambient light to X

AMBIENCEBLUE=X sets the blue component of the ambient light to X

FOG=X sets the fog mode within the scene when X is one

FOGRED=X sets the red component of the fog to X

FOGGREEN=X sets the green component of the fog to X

FOGBLUE=X sets the blue component of the fog to X

SKY=X sets the skybox to the sky model specified by X filename

SKYSCROLL=X sets the sky scroll texture to the file specified by X filename

BACKDROP=X loads and pastes the screen backdrop using X filename

MUSIC=X loads and plays the WAV using X filename

MUSICVOLUME=X sets the music volume in the range of 80-100

LIGHTON=X lighton

LIGHTOFF=X lightoff

LIGHTRED=X lightred

LIGHTGREEN=X lightgreen

LIGHTBLUE=X lightblue

LIGHTRANGE=X lightrange

HUDRESET=X call this to reset the HUD creation system

HUDX=X sets the X position percentage of where you want your HUD item to be

HUDY=X sets the Y position percentage of where you want your HUD item to be

HUDZ=X sets the Z position percentage of where you want your HUD item to be

HUDSIZEX=X sets the X size of your HUD item 90

HUDSIZEY=X sets the Y size of your HUD item

HUDSIZEZ=X sets the X size of your HUD item

HUDRED=X sets the red component of your HUD item

HUDGREEN=X sets the green component of your HUD item

HUDBLUE=X sets the blue component of your HUD item

HUDIMAGE=X sets the image filename of your HUD item

HUDFONT=X sets the font name of your HUD item

HUDSIZE=X sets the font size of your HUD item

HUDTEXT=X sets the text that will be used in place of no image of the HUD item

HUDTYPE=X set the HUD type (1-lives,2-health,3-weapon)

HUDHIDE=X set X to the name of the HUD item to hide it

HUDSHOW=X set X to the name of the HUD item to reveal it

HUDUNSHOW=X set X to the name of the HUD item to un-hide it

HUDNAME=X set the name of the HUD item you are creating

HUDANIM=X set the filename X of the animation sequence (exclude #.TGA)

HUDMAKE=X when all HUD items set, use this action to finally create the HUD

NEWGAME=X trigger the running of a new game (typically from title page)

LOADGAME=X trigger the loading of a saved game

SAVEGAME=X trigger the saving of a current game

CONTINUEGAME=X continue game action issued to move onto the next page

QUITGAME=X trigger the current game to quit back to the title page

PAUSEGAME=X trigger the game to pause, and typically enter the game menu

RESUMEGAME=X trigger the game to resume, after previously being paused

TIMERSTART reset the FPI script timer to zero, allowing timing to take place 

FLOORLOGIC=X if X is one, entity never leaves its Y position

INCSTATE=X increments the state variable by X

RUNFORE makes the entity move forward at a run

ADVFRAME=X advances the animation by X percent

SHAPEDECAL=X changes the decal mode to X for the entity

TRIGGERFORCE=X applies a force to the entity by a magnitude of X

SOUNDSCALE=X changes the 3D sound scale by percentage X

HUDIMAGEFINE=X loads the image for the HUD using high quality

HUDFADEOUT causes the HUD item to fade from the screen

HOSTGAME triggers a multiplayer game to be HOSTED

JOINGAME triggers a multiplayer game to be JOINED

REPEATGAME triggers a multiplayer game to repeat play

NOGRAVITY Switches off gravity for physics entity

ACTIVEALLINZONE Activates everything within entity zone

SPAWNON Switches on entity’s ability to spawn

SPAWNOFF Switcjes off entities ability to spawn

VIDEO=X Plays an animation file full screen once

RAISEFACTOR=X where X is the number of units to raise an entity

HEADSHOT=X where 0 is immune and any other value equals headshot height

HEADSHOTDAMAGE=X sets the headshot damage to X health points

NOROTATE=X If X is NOT zero then this will prevent the entity from rotating and lock it in position

STOPSOUND Will stop any looping sound currently being played by the entity. (Does not work for MUSIC)

PLRFREEZE=X freezes the player for X milliseconds

MUSICOVERRIDE=X replaces in-game music in real time

GLOBALVAR=X set the current global variable index to write/read from to X

LOCALVAR=X set the current local variable index to wrire/read from to X

SETVAR=X -et the value of the current variable to X

INCVAR=X increases the value of the current variable by X

DECVAR=X decreases the value of the current variable by X

VAREQUAL=X returns true if the current variable equals X

VARNOTEQUAL=X returns true if the current variable does not equal X

VARGREATER=X returns true if the current variable is greater than X

VARLESS=X returns true if the current variable is less than X

NEWJUMPHEIGHT=X change the default jump height of the player to X (default 50)

LIGHTINTENSITY=X change the intensity of a dynamic light to new percentage

RAISEFACTOR=X allows model to be raised by X to correct model alignments

PLRSETHEALTH=X sets players health to the value of X

PLRSUBHEALTH=X subtracts from players health by the value of X

ADDHEALTH=X increases entities health by the value of X

SUBHEALTH=X decrease entities health value by the value of X

SETHEALTH=X sets entities health to the value of X

PLRDISABLE=X freezes player and disables all controls for X milliseconds

Cliquez ici pour voir cette page sur le site original http://download.fpsfree.com/n79q24t66ks8/scripts/fpi_script.htm