FPI Script

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 conditional statements and commands.

condition,[second condition(optional)]:action,[second action(optional)]

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 you are familiar with other programming languages, this is similar to an IF THEN conditional statement.

if(CONDITION) { ACTION }

Translates to:

:CONDITION: ACTION

There is also comments to help you organize a script, comments start with a semicolon e.g.

FPI Script Tutorial Part 1

FPI script can be used for a number of operations including object behaviour and Artificial intelligence scripts. A more detailed description of each clause and examples can be found in FPI Usage Examples

Object behaviour

This is one of the most common uses for FPI script. The script below shows a simple hurt zone script that will take away 5 hp from the player every time he enters the hurt zone.

Artificial intelligence script

desc

state0,plriswithin=zone,plraddhealth=-5

Notice the "state0 command at the start of the code. States are like building blocks - "state0 is always the first state in a passage of code. It is the main foundation. The other lines of code are all called from the "state0" command.

Artificial behaviour

Artificial behaviour tells the NPCs or the player how to behave. Everything (apart from the main animation) is built upon AI scripts. As with the object behaviour script,the code ALWAYS has to start with ";Artificial intelligence script" command. Without this,your code will not function. Another variation is the "desc" command.

"taken from the object behaviour script"

Artificial intelligence script

desc

AI Script

Artificial intelligence script

desc () = follow and shoot

Notice the command after the desc. The "follow and shoot" tells the character what action to take. Enough said.

In part 2 is shall explain further about the rotateplr command,and how to put it to good use.

Conditions list

ACTIVATED=X is true when the activation value of the entity equals X
ALPHAFADEEQUAL=X is true when the alpha value equals X
ALWAYS is always true
ANIMATIONOVER=X is true when animation X is complete
ANYFURTHER=X is true when no within X quarter tiles
ANYWITHIN=X is true when any other entity moves within X quarter tiles
ASSOCIATED=X is true when entity has been associated with player (lift)
ENTITYWITHINZONE is true when an entity is within the trigger zone
FRAMEATEND=X is true when animation X is at an end
FRAMEATSTART=X is true when animation X is at the beginning
FRAMEBEYOND=X Y is true when animation X is beyond frame Y
FRAMEWITHIN=X Y is true when animation X is within frame Y
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
HEALTH=X is true when health equals X
HEALTHLESS=X is true when the health is less than X
IFWEAPON=X is true when the weapon being used by entity is ready and X is one
LOSETARGET=X is true when the entity has got stuck after X attempts
NEARACTIVATABLE=X is true when entity is being near activated
NEVER is never true
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
PLRALIVE=X is true when player is alive and X is one
PLRCANBESEEN is true when player can be seen
PLRCANNOTBESEEN is true when player cannot be seen
PLRDISTFURTHER=X is true when player is further than X units
PLRDISTWITHIN=X is true when player is within X units
PLRELEVFURTHER=X is true when player cannot be seen X degrees vertical
PLRELEVWITHIN=X is true when player can be seen within X degrees vertical
PLRHASKEY=X is true when player has pressed the key denoted by the value X
PLRHIGHER=X is true when player is X units higher than entity
PLRINGUNSIGHT=X is true when an entity has the player is gun sights
PLRUSINGACTION=X is true when player performs the USE action
PLRWITHINZONE is true when player is within the trigger zone
QUANTITY=X is true when quantity is equal to X
RANDOM=X is true when a random value between 0 and X is equal to one
RAYCAST=X Y is true when the raycast hits something in front from X to Y units
RAYCASTBACK=X is true when the raycast hits something back from X to Y units
RAYCASTUP=X is true when the raycast hits something above from X to Y units
REACHTARGET=X is true when the entity has reached its target
SHOTDAMAGE=X is true when damage taken exceeds the value X
SPEED=X is true when speed is equal to X
STATE=X is true when the value stored in the FPI script is equal to X

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

WAYPOINTSTATE=X is true when the waypoint state value equals X
State 0 means the entity has not yet started following waypoints
State 1 means the entity is looking for the nearest waypoint marker to start from
State 2 means the entity is following a waypoint line to its current waypoint marker
State 3 means the entity has reached the waypoint marker and needs to decide what to do
State 4 means the entity has reached the waypoint marker and it splits off in more than one other direction
State 5 means the entity has reached the very end of the current waypoint structure and requires a decision to be made

Note: A state of 999 means the entity has been placed in zero-waypoint mode where the entity simply ignores waypoints.

ANYFURTHER=X is true when any entity is further than X from it
ANYWITHIN=X is true when any entity is closer than X to it
ANYWITHINZONE is true when any entity is within its zone
CANTAKE is true if the entity can be collected by player
ESCAPEKEYPRESSED=X is true when the Escape Key has been pressed
HUDEDITDONE=X is true when ‘editable’ HUD item X is used
HUDHAVENAME is true when no player-name has been entered
HUDSELECTIONMADE=X is true when the user has clicked HUD button 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
NORAYCASTUP=X Y is true when no collision upwards X to Y
PLRHEALTHGREATER=X is true when the players health is greater than X
PLRHEALTHLESS=X is true when the players health falls below X
SCANCODEKEYPRESSED=X is true when X=the key code of a pressed key. For example: SCANCODEKEYPRESSED=5 is true when the TAB key is pressed
TIMERGREATER=X is true when the internal FPI timer exceeds X in milliseconds

Actions list

ANIMATE=X automatically play animation X
DECFRAME=X decrement another frame in animation X
DESTROY destroy entity
FLOATRATE=X cause the entity to float in the air at a hover rate of X
FORCEBACK=X apply a force to the entity by a factor of X backwards
FORCEBOUNCE=X apply a force to the entity to cause it to bounce back by X
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
FREEZE=X stop entity from moving
INCFRAME=X increment another frame in animation X
MOVEBACK=X move the entity back by X units
MOVEFORE=X moves the entity forward by X units
MOVEUP=X moves the entity up by X units
NONE no action
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
ROTATEIY=X rotate the entity around the Y axis incrementally for X degrees
ROTATETOPLR rotate the entity to face the player
ROTATEY=X set the entity angle around the Y axis for X degrees
RUNFPI=X run another FPI script by name X(i.e., appear1.fpi)
RUNFPIDEFAULT=X run a default FPI script by value X (0-init,1-main,2-end)
SETFRAME=X set animation X start frame
SPINRATE=X spin the entity around the Y axis at a rate of X
STATE=X sets the value of the internal variable State to X
SUSPEND disable the entity permanently, and keep it visible

In regards to characters provided, there are a number of animations built in which can be played.

0 = Spawn
1 = Idle
2 = Move Slow
3 = Strafe Left
4 = Strafe Right
5 = Move Fast
6 = Reload Weapon (or Toss)
10 = Climb
11 = Impact Front
12 = Bounce Front
13 = Get Up Front
14 = Impact Back
15 = Bounce Back
16 = Get Up Back
17 = Impact Left
18 = Bounce Left
20 = Impact Right
21 = Bounce Right
31 = Crouched Idle
32 = Crouched Move Slow (same)
33 = Crouched Strafe Left (same)
34 = Crouched Strafe Right (same)
35 = Crouched Move Fast (same)
36 = Crouched Reload Weapon (or toss)
40 = Freeform Idle
41 = Freeform Move
50 = Weapon Spawn
51 = Weapon Idle
52 = Weapon Move Slow
53 = Weapon Strafe Left
54 = Weapon Strafe Right
55 = Weapon Move Fast
56 = Weapon Reload Weapon (or Toss)
57 = Weapon NEW Climb
61 = Weapon Impact Front
62 = Weapon Bounce Front
63 = Weapon Get Up Front
64 = Weapon Impact Back
65 = Weapon Bounce Back
66 = Weapon Get Up Back
67 = Weapon Impact Left
68 = Weapon Bounce Left
70 = Weapon Impact Right
71 = Weapon Bounce Right
81 = Weapon Crouched Idle
82 = Weapon Crouched Move Slow (same)
83 = Weapon Crouched Strafe Left (same)
84 = Weapon Crouched Strafe Right (same)
85 = Weapon Crouched Move Fast (same)
86 = Weapon Crouched Reload Weapon (or toss)
90 = Weapon Freeform Idle
91 = Weapon Freeform Move

3DSOUND=X plays a 3D sound specified by the X filename. Use $0 for soundest
ACTIVATE=X activate this entity using the value X
ACTIVATE=X sets the activation value of the entity to X
ACTIVATEALLINZONE=X activate all the entities within the trigger zone with X
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
ACTIVEALLINZONE Activates everything within entity zone
ADVFRAME=X advances the animation by X percent
ALTTEXTURE=X set the texture used based on X being either zero or one
AMBIENCE=X sets the overall ambient light level within the scene to X
AMBIENCEBLUE=X sets the blue component of the ambient light to X
AMBIENCEGREEN=X sets the green component of the ambient light to X
AMBIENCERED=X sets the red component of the ambient light to X
BACKDROP=X loads and pastes the screen backdrop using X filename
CHOOSESTRAFE randomly selects a strafe direction (i.e. left/right/forward)
COLLECTTARGET if the target is a collectable, collect the target if close
COLOFF deactivate all player collision with this entity
COLON activate all player collision with this entity
CONTINUEGAME=X continue game action issued to move onto the next page
DECALPHAFADE=X decrement the alpha fade, X being the destination
DROPMARKER drops a marker the entity can later return to
FLOORLOGIC=X if X is one, entity never leaves its Y position
FOG=X sets the fog mode within the scene when X is one
FOGBLUE=X sets the blue component of the fog to X
FOGGREEN=X sets the green component of the fog to X
FOGRED=X sets the red component of the fog to X
FOLLOWPLR follows the players trail if one exists
HOSTGAME triggers a multiplayer game to be HOSTED
HUDANIM=X set the filename X of the animation sequence (exclude #.TGA)
HUDBLUE=X sets the blue component of your HUD item
HUDFADEOUT causes the HUD item to fade from the screen
HUDFONT=X sets the font name of your HUD item
HUDGREEN=X sets the green component of your HUD item
HUDHIDE=X set X to the name of the HUD item to hide it
HUDIMAGE=X sets the image filename of your HUD item
HUDIMAGEFINE=X loads the image for the HUD using high quality
HUDMAKE=X when all HUD items set, use this action to finally create the HUD
HUDNAME=X set the name of the HUD item you are creating
HUDRED=X sets the red component of your HUD item
HUDRESET=X call this to reset the HUD creation system
HUDSHOW=X set X to the name of the HUD item to reveal it
HUDSIZE=X sets the font size of your HUD item
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
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)
HUDUNSHOW=X set X to the name of the HUD item to un-hide it
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
INCALPHAFADE=X increment the alpha fade, X being the destination
INCSTATE=X increments the state variable by X
JOINGAME triggers a multiplayer game to be JOINED
LIGHTBLUE=X lightblue
LIGHTGREEN=X lightgreen
LIGHTOFF=X lightoff
LIGHTON=X lighton
LIGHTRANGE=X lightrange
LIGHTRED=X lightred
LOADGAME=X trigger the loading of a saved game
LOOKATPLR=X look directly at the player even if the player cannot be seen
LOOKATTARGET rotate the head of the entity to face the target
LOOPSOUND=X loops a 3D sound specified by the X filename.
MOVETOTARGET moves to the target
MUSIC=X loads and plays the WAV using X filename
MUSICVOLUME=X sets the music volume in the range of 0-100
NEWGAME=X trigger the running of a new game (typically from title page)
NEXTMARKER instructs the entity to go to the last dropped marker
NOGRAVITY Switches off gravity for physics entity
PAUSEGAME=X trigger the game to pause, and typically enter the game menu
PIVOTRANDOM=X randomly pivots around to face another direction by X degrees
PLRADDHEALTH=X adds X points to the players health
PLRASS=X associate this entity with the player (lift)
PLRDROP used to drop an item from the players inventory
PLRMOVEDOWN=X move the player up by X units
PLRMOVEEAST=X move the player east by X units
PLRMOVEIFUSED=X if player performs the USE action, move the player as above
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
PLRMOVEUP=X move the player up by X units
PLRMOVEWEST=X move the player west by X units
PLRNOASS=X disassociate this entity from the player
PLRTAKE used to add an entity to the players inventory and acquire its assets
QUITGAME=X trigger the current game to quit back to the title page
RELOADWEAPON reloads the weapon from the entities stock of infinite ammo
REPEATGAME triggers a multiplayer game to repeat play
RESETMARKERS resets all markers dropped by this entity
RESUMEGAME=X trigger the game to resume, after previously being paused
ROTATETOTARGET rotate the entity to face the target
RUNDECAL=X create a decal from the entity, X being a specific mode 1-6
RUNFORE makes the entity move forward at a run
SAVEGAME=X trigger the saving of a current game
SETALPHAFADE=X set the alpha value to X which causes entity transparency
SETTARGET sets the internal target for the entity, follows ‘target’ conditions
SHAPEDECAL=X changes the decal mode to X for the entity
SHOOTPLR runs the internal FPI script SHOOT specified in character properties
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
SOUND=X plays a sound specified by the X filename. Use $0 to specify soundest
SOUNDSCALE=X changes the 3D sound scale by percentage X
SPAWNOFF Switches off entities ability to spawn
SPAWNON Switches on entity’s ability to spawn
STRAFE perform the previously chosen strafe to avoid player shots
TIMERSTART reset the FPI script timer to zero, allowing timing to take place
TRIGGERFORCE=X applies a force to the entity by a magnitude of X
USEWEAPON fires any weapon half by an entity in the direction of the target
VIDEO Plays an animation file full screen once
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
WAYPOINTREVERSE makes the entity reverse course and go the other way
WAYPOINTSTART instructs the entity to find the closest waypoint
WAYPOINTSTOP stops the entity following waypoints