# FPI Script/FPI Usage Examples

This module provides more detail on each clause in the FPI language with usage examples.

## Conditions

    The conditions test whether something is true. Each one of these conditions will return TRUE or FALSE. If it returns TRUE, then the next condition in the list of conditions separated by a comma is evaluated. If all conditions evaluate to true, then the actions are carried out.

### General
#### STATE

-usage: STATE=X
    tests whether the variable "STATE" is set to value X. Starting out with the default value of 0, "STATE" is used on every line of an fpi script to control the flow, for instance:
    state=0:state=1
-this line checks if the STATE variable is 0. If it is, we change it to a value of 1
    state=1;state=2
-this line tests whether the STATE variable is 1. If it is, we change it to 2
    state=2:state=1
-when we get to state 2, we go back to state 1. This causes an endless loop that really does nothing. It's just for an example.

#### NEVER

-usage: NEVER
    Is never true. Will never return true and cause anything in the ACTIONS list to be carried out.
    Purpose??

#### ALWAYS

-usage: ALWAYS
    Is always true. Whatever is in the ACTIONS list will be carried out if all other condition statements evaluate to true.
    Purpose??

#### RANDOM

-usage: RANDOM=X
    Creates a random number between 0 and X and evaluates to true if that random number equals 1. This is useful for creating fidgeting in your character entities, for instance. While they are just standing around, you can have them fidget randomly every once in a while, for instance:
    :STATE=0,RANDOM=30:ANIMATE=6
-this line checks to see if the state is zero (if the entity has been recently initialized or had its STATE variable set to 0 by another script or by another line in this script. Then, it creates a random number from 0 to 30. If that random number is 1 (1/30 of the time), then the animation listed will run, which, in this case, is number 6, which shows the character re-loading his or her weapon.
    Correct??

### Entity condition
#### HEALTH

-usage: HEALTH=X
    Returns true if the HEALTH value of the entity equals the number X.
    :HEALTH=20:

#### HEALTHLESS

-usage: HEALTHLESS=X
    Returns true if the HEALTH value of the entity is less than the number X.

#### QUANTITY

-usage: QUANTITY=X
    Returns true if the quantity (OF WHAT??? Maybe number in level?) is equal to X.

#### SPEED

-usage: SPEED=X
    Returns true if the speed of the entity equals the number X.

### ASSOCIATED=

-usage: ASSOCIATED=X
    Returns true if the entity has been associated with the player. Used with lifts.
    (And what can the X value be? ASSOCIATED=1 return true with it IS associated and ASSOCIATED=0 true when it isn't?)

### Reference to player
#### PLRDISTWITHIN

-usage: PLRDISTWITHIN=X
    Returns true if the player is within X units from the entity. The units are measured in (100 'units' is equal to one segment size)

#### PLRDISTFURTHER

-usage: PLRFURTHER=X
    Returns true if the player is NOT within X units from the entity. The units are measured in (100 'units' is equal to one segment size)

#### PLRALIVE

-usage: PLRALIVE=X
    If X is 1, returns true if the player is alive. If X is NOT 1, returns true if the player is dead.

#### PLRHIGHER

-usage: PLRHIGHER=X
    Returns true if the player is X units higher than the entity.

#### PLRELEVWITHIN

-usage: PLRELEVWITHIN=X
    Returns true when the player can be seen within X degrees vertical

#### PLRELEVFURTHER

-usage: PLRELEVFURTHER=X
    Returns true when the player can NOT be seen within X degrees vertical

#### PLRCANBESEEN

-usage: PLRCANBESEEN
    Returns true when the player can be seen.
    NOTE: The player can be seen when he is within the view cone angle of the entities eyes (front position).

#### PLRCANNOTBESEEN

-usage: PLRCANNOTBESEEN
    Returns true when the player can NOT be seen.
    NOTE: The player can be seen when he is within the view cone angle of the entities eyes (front position).

#### PLRHASKEY

-usage: PLRHASKEY
    Returns true when player has a key (entity) to un-lock another entity
    such as, a door or a latch.

#### PLRUSINGACTION

-usage: PLRUSINGACTION=X
    Returns true when the player performs the USE action.
    (X should be either 1=true, or 0=false)

#### PLRWITHINZONE

-usage: PLRWITHINZONE
    Returns true when player is within the trigger zone. Used only with trigger zones.

#### PLRINGUNSIGHT

-usage: PLRINGUNSIGHT=X
    Returns true when the entity (if it is carrying a weapon) has the player in gun sights.

### References to other objects
#### ANYWITHIN

-usage: ANYWITHIN=X
    Returns true when ANY other entity is within X quarter tiles

#### ANYFURTHER

-usage: ANYFURTHER
    Returns true when NO other entity is within X quarter tiles

#### ENTITYWITHINZONE

-usage: ENTITYWITHINZONE
    Returns true when an entity is within a trigger zone.

#### SHOTDAMAGE

-usage: SHOTDAMAGE=X
    Returns true when damage taken exceeds the value of X. This can be used, for instance, to throw and enemy back if he is shot by a very powerful weapon.

#### IFWEAPON

-usage: IFWEAPON=X
    If X=1, returns true when the weapon being used by entity is ready. If X=0, Returns true when the weapon being used by the entity is NOT ready.

#### ACTIVATED

-usage: ACTIVATED=X
    Returns true when the activation value of the entity equals X
(More info about activated???)

#### NEARACTIVATABLE

-usage: NEARACTIVATABLE=X
    Returns true when the entity is being near activated.
(What does that mean???)

#### NEWWEAPONCANBESEEN

-usage: NEWWEAPONCANBESEEN=X
    Returns true when entity can see a better weapon. (if X=1?)

#### NOISEHEARD

-usage: NOISEHEARD=X
    Returns true when the entity hears a broadcase noise from scene.
(What is a broadcast noise? Is any SFX sound a broadcast noise?)

### Object Detection
#### RAYCAST

-usage: RAYCAST = X Y
    Returns true when the raycast hits something in front from X to Y units.
(uhh, what's a raycast?)
    raycast is when a line in 3d space(a ray) is drawn from one location to another. In this instance, the coder could evaluate if a point in space is actually visible from the first location.

#### RAYCASTUP

-usage: RAYCASTUP=X
    Returns true when the raycast hits something above from X to Y units.

#### RAYCASTBACK

-usage: RAYCASTBACK=X
    Returns true when the raycast hits something back from X to Y units.

### Animation
#### FRAMEATEND

-usage: FRAMEATEND=X
    Returns true when animation labelled by X is at its end.

#### FRAMEATSTART

-usage: FRAMEATSTART=X
    Returns true when animation labeled by X is at its beginning,

#### FRAMWITHIN

-usage: FRAMWITHIN=X Y
    Returns true when animation labelled by X is within frame Y

#### FRAMEBEYOND

-usage: FRAMEBEYOND=X Y
    Returns true when animation labelled by X is beyond frame Y

#### ANIMATIONOVER

-usage: ANIMATIONOVER=X
    Returns true when animation labelled by X is complete.

#### ALPHAFADEEQUAL

-usage: ALPHAFADEEQUAL=X
    Returns true when the alpha value = X

#### REACHTARGET

-usage: REACHTARGET=X
    Returns true when the entity has reached it's target (if X=1?)

#### LOSETARGET

-usage: LOSETARGET=X
    Returns true when the entity has got stuck after X attempts.

#### HEADANGLEGREATER

-usage: HEADANGLEGREATER=X
    Returns true when the angle of the entity's head is greater than X

#### HEADANGLELESS

-usage: HEADANGLELESS=X
    Returns true when the angle of the entity's head is less than X

#### WAYPOINTSTATE

-usage: WAYPOINTSTATE=X
    Returns true when the waypoint 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 maker.
    State 3 means the entity has reached the waypoint maker and it splits off in more than one other direction.
    State 4 means the entity has reached the waypoint maker 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.
    A state of 999 means the eneity has been placed in zero-waypoint mode where the entity simply ignores waypoints.

#### IFMARKER

-usage: IFMARKER=X
    Returns true when there is a marker previously dropped by entity in scene.

#### IFPLRTRAIL

-usage: IFPLRTRAIL=X
    Returns true when there is a trail left by player in existence

#### TIMERGREATER

-usage: TIMERGREATER=X
    Returns true when the internal FPI timer exceeds X in milliseconds

#### ESCAPEKEYPRESSED

-usage: ESCAPEKEYPRESSED=X
    Returns true when the escape key has been pressed.

## Actions
### GENERAL
#### NONE

-usage: NONE
    No action

#### DESTROY

-usage: DESTROY
    destroy entity

#### SUSPEND

-usage: SUSPEND
    disable the entity permanently, and keep it visible. This is used for leaving corpses or one-way switches. You could also use it to permanently open a door.

### SCRIPTS
#### RUNFPIDEFAULT

-usage: RUNFPIDEFAULT=X
    Run the default FPI script. If X=0, the fpi script listed under "init" in the entity's properties is run. If X=1, the "main" fpi script is run, and if X=2, the "destroy" fpi script is run.

#### RUNFPI

-usage: RUNFPI=X
    run another fpi script by name. For instance:
    : STATE=1:RUNFPI=runaway.fpi

### MOVEMENT
#### MOVEUP

-usage: MOVEUP=X
    Moves the entity up by X units.

#### MOVEFORE

-usage: MOVEFORE=X
    Moves the entity forward by X units.

#### MOVEBACK

-usage: MOVEBACK=X
    Moves the entity back by X units.

#### FREEZE

-usage: FREEZE=X
    stop entity from moving.
X being the number of milliseconds.

#### ROTATEY

-usage: ROTATEY=X
    Rotates the entity on its "Y" axis TO X degrees

#### ROTATEIY

-usage: ROTATEIY=X
    Rotates the entity on its "Y" axis BY X degrees

#### ROTATEY

-usage: ROTATEY=X
    Rotates the entity on it's "Y" axis by X units

#### SETTARGET

-usage: SETTARGET
    Sets the internal target for the entity. Follows "target" conditions.