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

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

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