e.g.
BrianEnteredView
HandAxe
HandCrowBar
HandGunColtRevolver
HandHybrid
HandDeepOneClaw
HandKnife
HandLeadPipe
HandNightStick
ShotgunDoubleBarrelled
ShotgunSawnOff
Note that some weapons can be used in either ranged or melee mode, such as shotguns. The choice of which mode to use is made automatically, and is dependent on the amount of ammo in the weapon and the range to the target.
Note that any time-consuming commands (ones which either suspend the virtual machine or are marked as time-consuming) will automatically end the safe block, regardless of the positioning of the EndSafeBlock function. The reason for this is simple - if for example a Wait command is issued within a safe block, the game cannot pause and stop rendering until the safe block is finished. Instead it automatically ends the safe block. In these cases (which are often scripting bugs) an OutputDebugString will be issued with details of the possible bug, but the game will continue running. Note that in certain cases it will be the intention of the scripter to end a safe block with a time-consuming command, such as MoveToPosition.
-0.5 rounds to -1, -0.49 rounds to 0.
An example is :
In the calling script :
RunScript("MyScript", 0.5, "Tree", 4);
In the new script :
String MyString;
MyString = GetArg();
MoveToPosition return codes are :
0 - Path blocked
1 - Movement successful
Modes are currently :
0 - Script controlled mode (even when no scripts running)
1 - Attack mode
2 - Search mode
2 - if the lookee is not in view but is in view memory
1 - if the lookee is in view
0 - if he is not in view or view memory
Note that initially a simple pick test is performed, not taking into account distance, and not taking into account the view cone. This will return 1 if no geometry is in between the two characters. If this failed, the in view table is queried to see whether the looker has a memory of seeing the lookee. This will return 2 if the lookee is still in view memory, or 0 if the lookee is not in view memory.
This means that results can sometimes be confusing when the lookee is outside the vision range of the looker. A character may thus be in view using the pick test (1) but not in view memory because it is outside the vision range.
The teams are :
0 - Undefined (environment)
1 - Player
2 - Friendlies (to the player)
3 - Enemies (to the player)
Sometimes a MoveToPosition command will fail to reach the destination. You can use the GetLastReturned script command to find the result of a MoveToPosition command.
Note the actual physical speed can be set up in the Data/AI/AI_SpeedSettings.ini file. The file describes the speed to be used for different movements by each animator type ( e.g. hybrid, human). The first line is the number of animator types to be described, which is followed by a section for each animator type. The format of the file is as follows :
NUM_TYPES 3
ID 0
WALK 1.0
RUN 2.5
CRAWL 0.75
WOUNDED_WALK 0.8
BACK_FAST 1.0
BACK_SLOW 1.0
STRAFE_FAST 2.0
STRAFE_SLOW 1.0
ID 1
etc. (for 3 types)
0 = Don't loop
1 = Loop
2 = Default
0 = Don't loop
1 = Loop
2 = Default
0 - AI resumes control after precanned, and character is back in physics mode (a passive anim will be played automatically)
1 - Character remains in precanned mode after the precanned animation so more precanned animations can be played straight after
2 - Character remains in precanned mode in order to play a non-looping precan, but then the original precan is returned to (assuming it was a loop). Eg. guy is fiddling underneath a car in a loop, but then is interupted to fetch a spanner, but then continues original loop
3 - Character does NOTHING after the precan eg. you want him to just lie dead
2 - if the player is not in view but is in view memory
1 - if the player is in view
0 - if he is not in view or view memory
Note that the last argument to this command must always be the total number of arguments used. Thus when no optional arguments are passed, the number of arguments will be two. With one optional argument the number of arguments will be three, and so on.
e.g.
RunGameScriptEx("MyScript.hfs", 2);
RunGameScriptEx("MyScript.hfs", "Spam", 3); // passes the string Spam to the script
In MyScript.hfs :
String MyString;
MyString = GetArg();
Print(MyString);
*VM_PrintString* Spam
Parameters
ScriptName : The name of the script to be run.
NumberOfArgs : The total number of arguments (including non-optional) in the call. This would be 2 with no optional arguments.
1) Gamescripts do not run on (and are not associated with) any particular character.
2) Gamescripts do not have priorities.. when a gamescript is run, it will always be executed, regardless of what else is happening in the game.
3) Because gamescripts are not associated with characters, certain AI script commands are not available from gamescript.
This command is one of a special few in the scripting language which can take a variable number of arguments. The first two arguments are always the script name to run and the priority, however any number of optional arguments (of any type) can be added after these two, which will be passed to the script which has been run. The script can retrieve these arguments (in order) using the command GetArg().
Note that the last argument to this command must always be the total number of arguments issued. Thus when no optional arguments are passed the number of arguments will be three. With one optional argument the arguments will be four, and so on.
e.g.
RunScript("MyScript.hfs", 0.5, 3);
RunScript("MyScript.hfs", 0.5, "Spam", 4); // passes the string Spam to the script
In MyScript.hfs :
String MyString;
MyString = GetArg();
Print(MyString);
*VM_PrintString* Spam
Parameters
ScriptName : The name of the script to be run.
Priority : The priority of the script to be run.
NumberOfArgs : The total number of arguments (including non-optional) in the call. This would be 3 with no optional arguments.
e.g.
Character Barry;
Barry = GetCharacterByName("Barry");
RunScriptEx(Barry, "MyScript.hfs", 0.5, "Spam", 5); // passes the string Spam to the script
Parameters
Character : The character to run the script
ScriptName : The name of the script to be run.
Priority : The priority of the script to be run.
NumberOfArgs : The total number of arguments (including non-optional) in the call. This would be 4 with no optional arguments.
Note that problems may occur if a character is told to search a zone outside the range allowed by its current SetZone and ExcludeZone settings.
e.g.
Character Bob;
Bob = GetCharacterByName("Bob");
SendEventEx(Bob, "Spotted", 20.0, 4)
This sends an event Spotted to Bob, and in his event response script 20.0 can be removed from the stack using the command GetArg() :
BobSpotted.hfs :
Print("Ive been spotted!");
Float fMyVar;
fMyVar = GetArg();
Print(fMyVar);
This would print :
Ive been spotted!
20.0
0 - Not alert
1 - Alert
2 - Auto mode
Every time the animator is told to stand or crouch, it checks the alert status to decide whether to use an aiming pose, or a passive pose. Auto mode allows the game to automatically manage the alertness ... a character will be more alert if it has recently seen the player. The other modes allow the scripter precise control over alertness. Remember that it is necessary to call a PlayAnim to stand or crouch after this command in order to see any instantaneous effects.
e.g.
SetDebug(Me, 0, ""); // turns off my npc info
SetDebug(Me, 1, ""); // turns on my npc info
SetDebug(Me, 2, "Hello"); // sets my npc info user string to Hello.
Note that setting a user string just prints the string in the debug window for a character. This can be very useful when debugging (as opposed to a Print) in order to track what stage an npc is at through your scripts.
N.B. D_EnableDebugger must be set to 1 for the npc info windows to show up.
Some events are hard coded into the game to occur in certain circumstances, and the script writer can hijack these to key their own custom responses :
PlayerEnteredView
This event is created whenever the player enters the view of a character, and it is not already in view memory (characters remember that they have seen the player for a certain amount of time (the LostTrackOfTime, see SetStatus) after they have left their view).
LostTrackOfPlayer
This event is created when the main player has been out of view of an npc for a specific, user-definable time (LostTrackOfTime, see SetStatus). This is usually used automatically for purposes such as switching monsters from attack to search mode.
Entered NiRoom01
Exited NiRoom01
These two events respectively are created on entering and on leaving every NiRoom, and can be used easily to trigger AI actions when entering and leaving locations.
Death
This event is created when a character dies (health reaches zero). Note however that if an event response is set for Death, the script writer is responsible for actually deleting the character, which they should do by using the command Kill(Me); at the end of the Death script (see Kill command).
HeardSound
This event is generated on npcs any time a sound is heard and they make a response by looking at the sound.
ShotByPlayer
This event is generated on an AI character when it is shot by the player. In addition the amount of damage (as a float) is passed to the event response script and can be retrieved using the GetArg command.
Some events are hard coded into the game to occur in certain circumstances, and the script writer can hijack these to key their own custom responses :
PlayerEnteredView
This event is created whenever the player enters the view of a character, and it is not already in view memory (characters remember that they have seen the player for a certain amount of time (the LostTrackOfTime, see SetStatus) after they have left their view).
LostTrackOfPlayer
This event is created when the main player has been out of view of an npc for a specific, user-definable time (LostTrackOfTime, see SetStatus). This is usually used automatically for purposes such as switching monsters from attack to search mode.
Entered NiRoom01
Exited NiRoom01
These two events respectively are created on entering and on leaving every NiRoom, and can be used easily to trigger AI actions when entering and leaving locations.
Death
This event is created when a character dies (health reaches zero). Note however that if an event response is set for Death, the script writer is responsible for actually deleting the character, which they should do by using the command Kill(Me); at the end of the Death script (see Kill command).
Quickstatus values
Health (0.0 - ~100.0)
LosingTrackTime (seconds)(defaults to 10 seconds)
Friendly (0.0 or 1.0)
Accuracy (0.0 to 1.0)
Intelligence (0.0 to 1.0)
Courage (0.0 to 1.0)
VisionRange (in cm)
Sniping (0.0 to 1.0)
Glancing (0.0 to 1.0) (never to very frequently, sliding scale)
DodgeTime (minimum dodge time in seconds) (defaults to 3.0)
UnloadModelOnDelete (0.0 or 1.0)
SoundSensitivity (0.0 to 1.0)
Hittable (0.0 or 1.0) (determines whether a character can be hit, defaults to 1.0)
Body Areas (setting these causes the animator to play injured walks etc)
HeadHealth (0.0 to 1.0)
TorsoHealth (0.0 to 1.0)
LeftArmHealth (0.0 to 1.0)
RightArmHealth (0.0 to 1.0)
LeftLegHealth (0.0 to 1.0)
RightLegHealth (0.0 to 1.0)
Quickstatus values
Name (used with the command GetCharacterByName to reference characters after their creation)
WoundingSound (filename string)
DyingSound (filename string)
WoundingSoundSet (one of HybridStage1Wounded, DeepOneWounded or HumanWounded)
Explanation : Scripters can determine the sound set used for wounding sounds by using the WoundedSoundSet quickstatus value (these sets are determined in the sounds dcf). If more precise control is needed, and for particular situations, scripters can control which sound is made by using either the WoundingSound quickstatus or DyingSound, along with the filename of the sound they want to use.
Note that script names contain a path (e.g. Jailbreak/MyScript.hfs) except for the special hard coded tasks :
HC_Attack (caused by the commands Attack or Search or Snipe)
HC_Hide (cause by the command Hide)