kas_reference_v2
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
Copyright © 1998 Relic Entertainment Inc.
All rights reserved
\
Updated 1999/07/22
Introduction to BNF Grammar Notation 7
Mission Objectives and Termination 14
\
\
\
\
\
\
In practice, there will typically be one script file per mission in the game.
KAS defines and controls three types of objects: Missions, finite state machines (FSMs), and States. These objects are arranged in a strict hierarchy. The top level defines the mission. Within the mission, you may define any number of finite state machines. And within each finite state machine (FSM) definition, you may define any number of states.
\
A complete script file defines one mission with all its possible associated FSMs and their states.
An instance of a mission object gets created as soon as the mission begins. For example, a mission will begin in a single player game as soon as a player drops out of a hyperspace jump.
\
When a mission begins (and only when a mission begins), its initialize section will be executed.
\
The watch section of a mission is then continuously executed until the mission ends. (In practice, this is isn’t actually continuous – doing so would really hog the CPU. But by giving the watch section a slice of CPU time at regular, short intervals, the script designer can safely pretend that it is being executed continuously -- the watch section time slices are scheduled in a way so that no events in gameplay will be “missed”.)
The FSMCreate function assigns control of a team to an FSM. Teams are defined in the mission layout file. FSMs are defined in the mission KAS file. The FSMCreate function is the only link between the two. Until you execute an FSMCreate function, that FSM definition in the script will lie dormant.
\
Upon executing the FSMCreate function, a unique instance of that FSM definition is created and the team (or whatever is left of it) remains under control of that FSM until control is explicitly given back to the regular game AI with the FSMDestroy function. So if you never execute an FSMDestroy function, even if all units of a team are destroyed, the “ghost” of the team can still reincarnate itself and build its numbers back up with unit requests if the appropriate watches are in the FSM.
\
Like a mission, only when an FSM is created will its initialize section be executed. Unlike a mission, an FSM definition may be have many instances of it running if you choose to control several teams with the same FSM definition. Each time an additional instance of an FSM is created, the initialize section for the new FSM is executed. By convention, an FSM’s initialize section contains (among other things) a JUMP to the initial state.
\
Also like a mission, the watch section of an FSM is continuously executed until the FSM instance is destroyed. Of course the FSMDestroy function only destroys one instance of an FSM, so if there are other multiple instances of the same FSM, the watch sections of all remaining instances will keep executing.
While under control of an FSM, a team must exist in exactly one state at any point in time. Once they are in that state, the team’s behaves in a particular way until they jump from that state to another one. The conditions for jumping to another state are well defined, and usually in the watch section of a state. That’s how finite state machines work.
\
Similar to a mission or FSM, a state’s initialize section will be executed once upon entering that state. However, because a typical day in the life of an FSM involves transitioning from state to state to state and then maybe back to a previous state, it’s possible that a state’s initialize section could be execute many times. Keep this in mind when designing states and their watch and initialize sections.
\
And just like a mission or FSM, the watch section of a state is continuously executed until that state is left.
\
Transitions to other states are made with the JUMP keyword. By convention, an FSM’s initialize section contains (among other things) a jump to the initial state. Then the watch section of each state allows transitions to other states. Also by convention, watch sections usually do not execute anything but JUMPs.
\
This diagram illustrates what a very simple mission and a few of its FSMs and states might look like.
\
FSMCreate
\
\
FSM
FSM
\
State
State
State
State
FSM
\
State
Watch
\
Initialize
\
Watch
\
Initialize
\
Watch
\
Initialize
\
I.
\
W.
\
I.
\
W.
\
I.
\
W.
\
I.
\
W.
\
I.
\
W.
\
State
I.
\
W.
\
State
I.
\
W.
\
\
\
\
\
Watch
\
\
\
\
Initialize
\
\
\
start of mission
\
\
\
\
\
\
\
\
\
\
\
\
\
end of mission
\
\
\
\
\
\
\
\
The unlabelled arrows within the FSM represent JUMPs.
BNF notation is a common means of describing a technical language compactly and non-ambiguously. Pay close attention to the details like “{“ vs. “[“ vs. “<” vs. “(“.
\
<abc> means abc is a component name
::= means “is defined as”
ABC represents the literal string ABC
“,” represents the literal comma (no quotes)
[<abc>] represents one optional <abc> (ie, zero or one instance of <abc>)
represents zero or more instances of <abc> (no limit)
(<abc> | <def>) represents either an instance of <abc> or one of <def>
<mission_defn> ::= [<localization>]
[<initialize_section>]
[<watch_section>]
\
<localization > ::= LOCALIZATION
ENDL
\
<lstring_defn> ::= LSTRING “_” <identifier>
<quoted_string>
<quoted_string>
<quoted_string>
<fsm_defn> ::= FSM <fsm_id>
[STATES <state_id> “;”]
[<initialize_section>]
[<watch_section>]
(ENDFSM | ENDF) [<fsm_id>]
\
<fsm_id> ::= <identifier>
\
<state_defn> ::= STATE <state_id>
[<initialize_section>]
[<watch_section>]
(ENDSTATE | ENDS) [<state_id>]
\
<state_id> ::= <identifier>
\
<initialize_section> ::= (INITIALIZE | INIT)
(ENDINITIALIZE | ENDINIT | ENDI)
\
<initialize_section> ::= (INITIALIZE | INIT)
(ENDINITIALIZE | ENDINIT | ENDI)
\
<statement> ::= ( <expression> “;”
| JUMP <state_name> “;”
| <if_statement> )
\
<if_statement> ::= IF “(“ <expression> “)”
{ (ELSEIF | ELSIF) “(“ <expression> “)”
}
[ ELSE
]
ENDIF
\
<expression> ::= ( <expression> “+” <expression>
| <expression> “-“ <expression>
| <expression> “*” <expression>
| <expression> “/” <expression>
| <expression> AND <expression>
| <expression> OR <expression>
| <expression> “<” <expression>
| <expression> “<=” <expression>
| <expression> “=” <expression>
| <expression> “>=” <expression>
| <expression> “>” <expression>
| <expression> “<>” <expression>
| “-“ <expression>
| NOT <expression>
| “(“ <expression> “)”
| <number>
| <function_call>
| TRUE
| FALSE )
\
<function_call> ::= <function_name> “(“ {<parameter> {“,” <parameter>}} “)”
\
<function_name> ::= see the Functions section
\
<parameter> ::= ( <expression>
| <quoted_string>
| LSTRING “_” <identifier>
| TEAM “_” <identifier>
| SHIPS “_” <identifier>
| TEAMSHIPS “_” <identifier>
| THISTEAM
| THISTEAMSHIPS
| THISTEAMSPOINT
| SHIPSPOINT “_” <identifier>
| TEAMSPOINT ”_” <identifier>
| VOLUMEPOINT “_” <identifier>
| POINT “_” <identifier>
| PATH “_” <identifier>
| VOLUME “_” <identifier> )
\
<quoted_string> ::= ‘ “ ‘ <identifier> ‘ “ ‘
\
<identifier> ::= <letter>
\
<letter> ::= ( “a” | “b” | “c” | … | “z” | “A” | “B” | “C” | … | “Z” )
\
<number> ::= [“-“] <digit>
\
<digit> ::= ( “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” )
Comments may be entered anywhere in a script with the “//” prefix. The rest of the line will then be ignored.
This feature is not yet implemented. It is somewhat difficult to get the parser to do this, but moreover, it could create really nasty dependency bugs with the project make process. If not done carefully, the make could fail to recompile included script files when they change and thus not incorporate the changes into the game EXE. This would be a really ugly bug – half the time, you wouldn’t even notice it was screwing up. So until I can find a way around this risk, I think the level designers should make do without it.
\
The #include keyword can be used on any line, but will typically be used in a “master” script for a mission so each FSM definition may be kept in its own file to keep things manageable.
\
For example:
\
//
// Homeworld single-player Mission01.kas
//
\
#include “Harvester.kas”
#include “LeftPatrol.kas”
#include “RightPatrol.kas”
\
INIT
FSMCreate(LeftPatrol, Team_PatrolA);
FSMCreate(LeftPatrol, Team_PatrolB);
FSMCreate(RightPatrol, Team_PatrolC);
FSMCreate(Harvester, Team_Collectors);
ENDINIT
\
WATCH
ShipsClear(Ships_Penetrators);
IF (FindShipsInside(Volume_Win, Ships_Penetrators))
MissionCompleted( );
ENDIF
ENDWATCH
Optionally, you may use C-style notation in KAS for certain things,
-
logical operators (&& and ||)
-
logical unary negation (!)
-
comparison operators (== and !=)
\
Timers are referenced by symbolic name strings. These names are scoped. That is, if you create a timer in an FSM or an FSM’s state, it will only be visible within that FSM. If you create a timer in the mission Init or Watch sections, it will be visible to the entire mission, in all FSMs and states. You can always force a timer to be globally available to the whole mission by creating and subsequently referring to it with a G_ prefix on the name. For example: TimerCreate(“G_Meltdown”);.
TimerCreate (name : string);
Create a named timer. Typically, you’ll want to set it and start it at some point, also.
TimerSet (name : string, duration : integer);
Sets the timer to a number of seconds. You still need to start it.
TimerStart (name : string);
Starts the timer counting down. When it hits zero TimerExpired() will return True.
TimerCreateSetStart (name : string, duration : integer);
In one operation, this creates, sets, and starts a timer (since the three operations will commonly be done together.)
TimerStop (name : string);
Stops the timer. This is a pause function, really. It can be restarted.
TimerRemaining (name : string) : integer;
Returns the number of seconds remaining on the timer (whether it has been started or not). If the timer has expired, this returns zero.
TimerExpired (name : string) : integer;
Returns True if the timer has hit zero.
Note: This will continue to return True until the timer is reset or destroyed.
TimerExpiredDestroy (name : string) : integer;
Returns True if the timer has hit zero. If True, the timer will also be destroyed for you (so subsequent calls will be False).
TimerDestroy (name : string);
Removes a timer from existence. It’s not necessary, but it’s a good idea to do this when you’re done using a timer or at the end of a mission.
These are integer variables. They are referenced by symbolic name strings. These names are scoped. That is, if you create a variable in an FSM or an FSM’s state, it will only be visible within that FSM. If you create a variable in the mission Init or Watch sections, it will be visible to the entire mission, in all FSMs and states. You can always force a variable to be globally available to the whole mission by creating and subsequently referring to it with a G_ prefix on the name. For example: VarCreate(“G_AttackCount”);.
VarCreate (name : string);
Create a named variable.
VarSet (name : string, value : integer);
Set the value of a variable.
VarCreateSet (name : string, value : integer);
Create a named variable and set its value.
VarInc (name : string);
Increment a variable’s value by 1.
VarDec (name : string);
Decrement a variable’s value by 1.
VarGet (name : string) : integer;
Return a variable’s value.
VarDestroy (name : string);
Remove a variable from existence. It’s not necessary, but it’s a good idea to do this when you’re done using a variable for good or at the end of a mission.
Textual messages can be sent from team to team. Each team has an incoming message queue that can hold quite a few messages. Old ones will be thrown out, though.
There is a special keyword called TEAM_MsgSender that can be used to reference the team that sent the message you last checked (with a successful call to MsgReceived(), below). This could be used to dispatch support, for example, to those requesting it.
MsgSend (team : team, msg : string);
Send another team a message.
MsgSendAll (msg : string);
Send all teams a message.
MsgReceived (msg : string) : integer;
Returns True if the given message string is waiting in the incoming message queue for the team. The strings must match exactly. If True, the message is removed from the queue.
Attack (targets : ships);
Simple attack.
ShipsAttack (targets : ships, attackers : ships);
Attacks “targets” with “attackers”. Useful if you want a portion of a team, or multiple teams, to attack a target.
AttackSpecial (targets : ships);
Executes a special attack on the ships. The attacking team must have and support a special attack, or this will do nothing. Salvaging a ship is an example of a special attack.
AttackFlank (targets : ships);
The team will attack the target from a right angle to it.
AttackHarass ();
The team will automatically determine a target to harass (unarmed ships, lightly armed support ships, etc.). It then moves to the target and attacks it.
MoveAttack (targets ; ships);
The team attacks the targets then circles around them. Use only with teams consisting of capital ships.
AttackMothership ();
Self explanatory.
Kamikaze (targets : ships);
Kamikazes team into targets. Brutal. Currently only works with strikecraft.
KamikazeEveryone (targets : ships);
Kamikazes every team into targets. Even more brutal. Currently only works with strikecraft.
TargetDrop ( );
The team using this function must be comprised of salvage/capture ships (or equivalent). This instructs all team members to drop anything they may have been clamped onto.
A team’s formation can be changed at any time. Subsequent moves will use the last formation setting.
FormationDelta ();
FormationBroad ();
FormationDelta3D ();
FormationClaw ();
FormationWall ();
FormationSphere ();
\
FormationCustom (ships : ships);
Locks the ships into a custom formation. Note that they have to use ShipsMoveTo in order to move together in formation.
MoveTo (destination : vector);
Move to the given point. Once in motion, the team can be given other orders to override the destination.
ShipsMoveTo (ships : ships, destination : vector);
Works exactly like MoveTo, except that it moves a group of ships rather than the team.
Intercept (targets : ships);
Moves a team towards the targets.
UnderAttack (attackers : ships) : integer;
If the team is currently or fairly recently under attack, this will give you a list of the attacking ships. Returns the number of ships attacking (zero, if the team is not under attack).
UnderAttackElsewhere (otherTeam : team, attackers : ships) : integer;
This works just like UnderAttack(), but this function is able to magically tell you if some other team is currently or fairly recently under attack. Some would consider this cheating, but the same functionality could be accomplished with some message passing and/or variables, so this just makes it cleaner.
Guard (ships : ships);
Guards the given ships.
GuardMothership ();
As above, applied to the mothership.
Patrol ();
The team automatically determines a series of points to patrol (key defendable ships, etc.). It then patrols them as a path in PatrolPath().
PatrolPath (path : path);
The team patrols a path, as defined in the mission layout editor. This path may have been defined as open or closed (looping).
PathNextPoint () : integer;
Returns the point number (1..numPoints) of the next point on the path the team is patrolling. If the team has finished a path, 0 is returned. If the team is not patrolling the path, or if the team has 0 ships, then –1 is returned.
Print (string : string);
Write a line to the temporary, scrolling area on the user’s screen. Useful for end-user information and/or debugging.
Log (string : string);
Write a line to the log window and/or file. Useful for debuggin.
LogInteger (string : string, integer : integer);
Write a line consisting of text and an integer parameter to the log window and/or file. Wherever you want the integer in the string, place a “%d”, without the quotes. Useful for debuggin.
For example: LogInteger(“TeamHealthAverage is %d”, TeamHealthAverage());
Popup (string : string);
Pop up a box with the given text in it. It will remain visible for an amount of time roughly proportional to how much text is being displayed. The string will be word-wrapped. You may imbed newline characters “\n” in the string to force line breaks.
PopupInteger (string : string, integer : integer);
Pop up a box with the given text and an integer parameter in it. Wherever you want the integer in the string, place a “%d”, without the quotes. The string will be word-wrapped. You may imbed newline characters “\n” in the string to force line breaks.
For example: PopupInteger(“Harvest %d RUs and then get the hell out of dodge.”, VarGet(“RUsToGet”));
ObjectiveCreate (label : string, briefText : string, fullText : string);
Add an objective for the mission. The label is for internal use. The briefText string is what will be displayed (in one short line) at the bottom of the screen in the fleet intelligence GUI. The fullText string gives details of the objective. The fullText string will be word-wrapped. You may imbed newline “\n” characters in the fullText string to force line breaks. When all objectives are completed, the mission is complete.
ObjectiveCreateSecondary (label : string, briefText : string, fullText : string);
Adds a secondary objective for the mission. The difference between a primary objective and a secondary objective is that a secondary objective has a 2. In front of it in the list window (primary objectives have a 1 in front of them). Otherwise this function behaves as ObjectiveCreate().
ObjectiveSet (label : string, status : integer);
Set the status of a mission objective to complete (= True) or incomplete (= False). When all objectives are completed, the mission is complete.
ObjectivesShowAll ();
Show the user all the current mission objectives.
ObjectiveGet (label : string) : integer;
Returns True if the given objective has been completed, False otherwise.
ObjectivesGetAll () : integer;
Returns True if all objectives for the mission have been completed, False otherwise.
ObjectiveDestroy (label : string);
Remove an objective for the mission.
ObjectivesDestroyAll ();
Remove all objective for the mission.
MissionCompleted ();
Call this manually when the success criteria for a mission are satisfied. This will wrap up the misison and handle any GUI-related actions, NISs, warps to the next mission, etc. If you rely solely on the objective functions in this section, you won’t need to call this.
MissionFailed ();
Call this when the failure criteria for a mission are satisfied. This will wrap up the mission and handle any GUI-related actions.
These functions allow run-time adding and removing of “pingable” objects in the sensors manager. This could be useful for introducing and tracking mission objectives, for example.
PingAddShips (ships : ships, label : string)
This will show a “ping” for the specified group of ships in the Sensors Manager.
PingAddSingleShip (ships : ships, label : string);
This will show a “ping” for a ship in the sensors manager.
PingAddPoint (vector : vector, label : string);
This will show a “ping” for the given point in the sensors manager.
PingRemove (label : string);
Remove a previously added ping.
Any functions that have parameters of type “ships” use temporary variables like these. You refer to them with names after a Ships_ prefix. For example, you might use Ships_Penetrators as a variable to store the list of ships returned by the FindShipsInside() function. This variable can then be inspected, modified, cleared, counted, or passed on to other functions (for attacking, etc.) Unlike integer variables or timers, these ship lists do not need to be explicitly created. The first reference to a new list of ships will implicitly create it. It’s probably a good idea to call ShipsClear() before you use a list of ships for the first time, just to be safe.
ShipsClear (ships : ships);
Remove all ships from the list.
ShipsCount (ships : ships);
Return how many ships are in the list.
ShipsCountType (ships : ships, shipType : string);
Return how many ships of the given type are in the list. Ask a programmer for the correct spelling of ship type strings.
ShipsAdd (shipsA : ships, shipsB : ships);
Adds the ships from B to A. In other words, shipsB won’t change, and shipsA will possibly grow. Return how many ships are in the list.
ShipsRemove (shipsA : ships, shipsB : ships);
Removes the ships in B from A. In other words, shipsB won’t change, and shipsA will possibly get smaller. Return how many ships are in the list.
FindSelectedShips(Ships : ships) : integer;
Returns the ships that the player has selected. Also returns the number of ships the player has selected.
SelectedShipsInFormation (formation : integer) : integer;
Returns TRUE if allof the player’s selected ships are in the specified formation. Formation names can be found in src/game/formationdefs.h
ShipsInFormation (Ships : ships, formation : integer) : integer;
Returns TRUE if anyof the ships are in the specified formation. Formation names can be found in src/game/formationdefs.h. As an added bonus to make Erin super happy, if you pass –1 as the formation, the function returns TRUE if any of the ships are in any formation.
These functions allow you to filter or create subsets of ships lists.
The format is this: you specify a newShips list and an originalShips list. All ships in the originalShips list which satisfy the criteria will be added to the newShips list. (If newShips is the same as originalShips, essentially, you will be removing ships from the list which do not satisfy the criteria.) Some of the functions require additional parameter(s) for their selection criteria. In all cases, the value returned is the resulting number of ships in the newShips list.
ShipsSelectEnemy (newShips : ships, originalShips : ships) : integer;
ShipsSelectFriendly (newShips : ships, originalShips : ships) : integer;
ShipsSelectClass (newShips : ships, originalShips : ships, shipClass : string) : integer;
ShipsSelectType (newShips : ships, originalShips : ships, shipType : string) : integer;
ShipsSelectCapital (newShips : ships, originalShips : ships) : integer;
ShipsSelectNonCapital (newShips : ships, originalShips : ships) : integer;
ShipsSelectNotDocked (newShips : ships, originalShips : ships) : integer;
Selects ships which are not docked. This could be useful to eliminating ships inside carriers from being targeted, for example.
ShipsSelectDamaged (newShips : ships, originalShips : ships, maxHealthPercent : integer) : integer;
Selects ships which have a specified maximum level of health. This could be useful for singling out the weaklings of a group.
ShipsSelectMoving (newShips : ships, originalShips : ships) : integer;
Selects ships which are moving. This could be useful for singling out groups of ships heading towards a target, rather than stationary guards.
ShipsSelectIndex (newShips : ships, originalShips : ships, Index : integer) : integer
Puts a single ship in the newShips shiplist determined by “Index”. For example, calling SelectShipsIndex with Index set to 0 will put the first ship in the originalShips shiplist and put it in the newShips shiplist. If Index is larger than the number of ships in originalShips, the function returns FALSE. If a new ship is added to newShips, the function returns TRUE.
ShipsSelectNearby (newShips : ships, originalShips : ships, location : vector, distance : integer) : integer
Fills newShips with ships in originalShips that are distance away from location. More efficient than FindShipsNearby* routines if the fleets in the mission are spread out.
ShipsSelectSpecial (newShips : ships, originalShips : ships, SpecialFlag : integer) : integer,
Selects ships which follow the criteria indicated by the SpecialFlag:
Below is a list of SpecialFlag values:
1 – selects salcapcorvettes in originalShips returning to the
mothership with stripped technology
2 – selects any ship in originalShips that is disabled (i.e. captured)
3 – selects armed ships in originalShips
4 – selects any ship that has defected.
\
ShipsSetNonRetaliation (Ships : ships)
Sets up the ships in the ship list so that they do not autoretaliate against nearby enemy ships.
ShipsSetRetaliation (Ships : ships)
Undoes “ShipsSetNonRetaliation”.
ShipsOrder (Ships : ships) : integer
Returns the order of the ships:
#define COMMAND_NULL 0
#define COMMAND_MOVE 1
#define COMMAND_ATTACK 2
#define COMMAND_DOCK 3
#define COMMAND_LAUNCHSHIP 4
#define COMMAND_COLLECTRESOURCE 5
#define COMMAND_BUILDINGSHIP 6
#define COMMAND_SPECIAL 7
#define COMMAND_HALT 8
#define COMMAND_MILITARYPARADE 9
ShipsOrderAttributes (Ships : ships)
Returns attributes of the ships:
#define COMMAND_IS_FORMATION 1
#define COMMAND_IS_PROTECTING 2
#define COMMAND_IS_PASSIVEATTACKING 4
#define COMMAND_IS_HOLDINGPATTERN 8
#define COMMAND_IS_ATTACKINGANDMOVING 16
Falko’s Note: I think that the above definitions could possibly exist
more than once – i.e. if ShipsOrderAttributes returns 5, then the ships
are in formation and passive attacking (1 + 4). I’m not sure how that
will be useful in KAS.
FindShipsInside (volume : volume, ships : ships) : integer;
Find any ships (enemy or friendly) in the given volume. Set the ships list to be these ships. Return the size of this list. If you’re planning to attack ships in a given volume, it can be useful to follow this function up with a call to FindEnemiesNearby() with the same ships list. Or use the FindEnemiesInside() function.
FindEnemiesNearby (ships : ships, radius : integer) : integer;
Given a list of ships, this will find all enemy ships within the given radius of these ships. This will be the new list of ships. This returns the size of the new list. Note that the “ships” list is replaced by the new list.
FindEnemiesNearTeam (ships : ships, radius : integer) : integer;
Finds all enemy ships within the given radius of this team, making a ships list of these enemies. Returns the size of this list.
FindEnemiesInside (volume : volume, ships : ships, neighborRadius : integer) : integer;
Calls FindShipsInside() and then follows it up with FindEnemiesNearby(), since these two functions get combined frequently.
FindFriendlyShipsOfType (ships : ships, shipType : string) : integer;
Finds all friendly ships of the given type. Returns the number of said ships. Ask a programmer for the correct spelling of ship type strings.
FindEnemyShipsOfType (ships : ships, shipType : string) : integer;
Finds all enemy ships of the given type. Returns the number of said ships. Ask a programmer for the correct spelling of ship type strings.
FindFriendlyShipsOfClass (ships : ships, shipClass : string) : integer;
Finds all friendly ships of the given class. Returns the number of said ships. Ask a programmer for the correct spelling of ship class strings.
FindEnemyShipsOfClass (ships : ships, shipClass : string) : integer;
Finds all enemy ships of the given class. Returns the number of said ships. Ask a programmer for the correct spelling of ship class strings.
FindShipsNearPoint (ships : ships, point : vector, radius : integer) : integer
Finds all ships within radius of a certain point. Returns the number of said ships.
PointInside (volume : volume, point : vector) : integer;
Returns True if the given point is inside the given volume. Returns False otherwise.
Nearby (location : vector, distance : integer) : integer;
Returns True if any ship of the team is within the given distance of the given location. Returns False otherwise.
FindDistance (location1 : vector, location2 : vector) : integer
Returns the distance between two points.
TeamAttributesSet (value : integer);
Sets the attributes of a team to value. These attributes are magic numbers that are added together and are defined in attributes.h
TeamAttributesBitSet(value : integer);
Logically sets all bits of the attributes of a team as given by value. These attributes are magic numbers that are added together and are defined in attributes.h
TeamAttributesBitClear(value : integer);
Logically clears all bits from the attributes of a team as given by value. These attributes are magic numbers that are added together and are defined in attributes.h
TeamMemberHandle(Index : integer) : integer;
Returns the ShipPtr value of the specified team member. This value may then be used by the game to identify a ship. Returns 0 if the Index is out of range. Valid ranges are 0 to (n-1) where n is the number of members of the team.
TeamHealthAverage () : integer;
Returns the average health (%) of the team members.
TeamHealthLowest () : integer;
Returns the lowest health (%) of the team members.
TeamHealthSet (percentHealth : integer);
Sets the health (%) of all team members.
TeamFuelSet (percentFuel : integer);
Sets the fuel (%) of all team members.
TeamFuelAverage () : integer;
Returns the average fuel level (%) of the team members.
TeamFuelLowest () : integer;
Returns the lowest fuel level (%) of the team members.
TeamVelocityMaxSet (velocity : integer);
Sets the maximum velocity of all team members. Clear this maximum with TeamVelocityMaxClear().
TeamVelocityMaxClear ();
Clears any maximum velocity for team members that may have been previously set with TeamVelocityMaxSet().
ShipsVelocityMaxSet (velocity : integer);
Sets the maximum velocity of specified ships. Clear this maximum with ShipsVelocityMaxClear().
ShipsVelocityMaxClear ();
Clears any maximum velocity for ships that may have been previously set with ShipsVelocityMaxSet().
ShipsDamageModifierSet (ships : ships, damageModifier : integer);
Sets the DamageModifier of specified ships. Clear this maximum with ShipsDamageModifierClear ().
ShipsDamageModifierClear(ships : ships);
Clears any DamageModifier for ships that may have been previously set with ShipsDamageModifierSet ().
TeamCount () : integer;
Returns the numbers of ships in the team.
TeamCountOriginal () : integer;
Returns the number of ships this team was originally blessed with (in the mission layout definition).
NewShipsAdded (); integer;
Returns the number of new ships that have been added to the team since the last time NewShipsAdded() was called. Note that NewShipsAdded() does not return the ships that were added to the team initially (this number can be gotten using TeamCountOriginal()).
TeamDocking () : integer;
Returns True if the team is currently in a docking maneuver. Returns False otherwise. The team is considered to be “docking” from the moment the Dock() order is given, to the moment that the last ship of the team has completed docking and cleared the support ship. Note that if a ship is told to permanently dock with a ship (e.g. with DockStay) then it is considered only to be docking up to the point it either flys inside the ship or latches onto it.
TeamDockedReadyForLaunch () : integer;
Returns True if the team has docked with a ship with the DockStay() or DockInstant() command, and is in a state where it is ready for launch with the Launch() command.
NOTE: This will only come true when all the ships are fully repaired and refuelled. Yay Gaz.
TeamFinishedLaunching () : integer;
Returns True if the team has finished launching (from the Launch() command).
ThisTeamIs (team : team) : integer;
Returns True if the current team is the specified team. Returns False otherwise. This is useful when several teams are controlled by a single FSM definition, but you need to break out some team-specific behavior.
Skill levels are numeric. These functions allow for tuning the relative difficulties of each mission and each team within each mission.
TeamSkillSet (skillLevel : integer);
TeamSkillGet () : integer;
MissionSkillSet (skillLevel : integer);
MissionSkillGet () : integer;
RequestShips (shipType : string, numShips : integer);
Request new ships to be assigned to this team. If the requested ships are not readily available, they will be built. In any case, the team will wait for these ships to arrive before executing further orders. Ask a programmer for the correct spelling of ship type strings.
RequestShipsOriginal (percentOriginal : integer);
Request that new ships of the original type assigned to the team (according to the mission layout definition) be assigned again. The number of these ships requested is expressed as a percentage of the original size of the team (so 50 would request half as many as it started with and 200 would request twice as many). The team will wait for these ships to arrive before executing further orders.
Reinforce (team : team);
The team will move close to the team it is to reinforce. When it is in position, it will transfer control of its ships to the other team and those transferred ships will be given the same orders as the team receiving the reinforcements.
Note: This function makes use of the team’s current tactics setting, so you may wish to set tactics explicitly before calling this function.
ReinforceTeamWithShips (teamtoreinforce : team, shipstoadd : ships );
Same as above function Reinforce, except you explicitly say the team you want to reinforce, and the ships you want to add to it.
TeamGiveToAI ();
This function hands the team’s ships over to full AI control. You will be left with an empty shell of a team. However, the state machine is still happy to run with no ships, so after giving up a team’s ships you can still watch for some condition to be satisfied and eventually request that ships be reassigned to this team.
TeamSwitchPlayerOwner ();
This function switches the player that controls this team’s ships. If the ships on this team were KAS ships, they become human ships. If they were human ships, they become KAS ships.
ShipsSwitchPlayerOwner (Ships : ships);
Same as above function TeamSwitchPlayerOwner except it accepts a list of ships to switch.
TeamMakeCrazy (makecrazy : integer);
If TRUE is passed in, this function makes the team crazy (e.g. the ships spin around and can’t do anything). If FALSE is passed in, this function sanifies the ships (they stop being crazy).
\
\
SpecialToggle ();
Toggle the special function of the current team’s ship(s) on and off. For example, use this for Gravwell and Cloak Generators.
BuildingTeam (team : team)
All subsequent ship request calls get built from this team. Should be a build capable team (Carrier or Mothership).
Dock (team : team);
This command is obsolete. Use DockSupportWith instead.
DockSupport ();
Dock for general support (refuel/repair). See TeamDocking() attribute also.
DockSupportWith (team : team);
Dock for general support with the given team. See TeamDocking() attribute also.
DockStay (team : team);
Dock with the given team, and stay there until explicitly told to launch. Also see TeamDocking() and TeamDockedReadyForLaunch() attributes.
DockInstant (team : team);
Dock instantly with the given team, and stay there until explicitly told to launch. DockInstant is the same as DockStay, except it “magically” docks in zero time. Also see TeamDocking() and TeamDockedReadyForLaunch() attributes.
ShipsDockSupportWith (Ships : ships , withShips : ships);
Dock for general support with the given ship. Simply a more flexible version of DockSupportWith.
ShipsDockStay (Ships : ships , withShips : ships);
Dock with the given ship and stay there until explicitly told to launch. Simply a more flexible version of DockStay.
Launch ();
Tells the current team to launch. This command should only be used after a DockStay or DockInstant and only if you know that they have actually docked and are ready for launch. Check the TeamDockedReadyForLaunch attribute to be sure that they are ready to accept a launch command.
Stop ();
This stops any team orders that are currently executing (any ship-based orders like moves, attacks, etc.) and removes any that might be queued up for future execution (like moving from point to point in a path, for example).
Harvest ();
Tells team to harvest. Note: team should consist of Resource Collectors.
ForceCombatStatus (ships : ships, flag : integer)
When “flag” is TRUE, forces the selection of ships into combat status. Healing is slowed down to combat rate, and a red combat ping shows up in the sensors manager where the ships are located. Setting the flag to FALSE turns off forced combat status for the selection of ships.
TeamHyperspaceOut ();
Hyperspaces the team out of the level.
TeamHyperspaceIn (location : vector);
Hyperspaces the team into the level at the location indicated.
TeamHyperspaceInNear (location : vector, distance : integer)
Hyperspaces the team into the level at a “distance”
SetSwarmTargets (targets : ships);
P2 specific code. Sets the ships in the targets list as the recommended targets for the next Swarmer teams.
SwarmMoveTo (targets : ships);
P2 specific code. Bundles the swarm team together (pod and swarmer) and moves them towards the target.
Sets the team’s tactics for subsequent commands. Some commands use this setting. Some commands ignore it. The ones that do use it are documented here. You can set this as often as you like.
TacticsAggressive ();
TacticsNeutral ();
TacticsEvasive ();
Hyperspace gates are implemented by adding AIPoints named GATE<name>.
\
GateMoveToNearest();
Moves the current team to the nearest gate.
\
GateShipsOutNearest (ships : ships) : integer;
Hyperspaces the ships out of the nearest Hyperspace Gate if the ships are within a certain distance of that Hyperspace Gate. Returns TRUE when the hyperspace out has occurred.
\
GateShipsOut (ships : ships, gate : vector);
Hyperspaces the ships out of the specified gate (i.e. the ships will now be in the Hyperspace ether).
GateShipsIn (ships : ships, gate : vector);
Hyperspaces the ships into the specified gate (i.e. the ships will now return to normal space).
\
GateDestroy (gate : vector);
Destroys the specified gate.
SaveLevel (LevelNum: integer, LevelName: string);
Saves the level. Should be in the init portion of a state. Note that only the watch portion of the state that contains the SaveLevel function will be executed when the level is reloaded.
Random (lowestNum : integer, highestNum : integer) : integer;
Returns a pseudo-random integer number between lowestNum and highestNum, inclusive.
RUsGet (player : integer) : integer;
Returns how many RUs the given player has. 0 = human, 1 = first computer player.
RUsSet (player : integer, RUs : integer);
Sets how many RUs the given player has. 0 = human, 1 = first computer player.
GetWorldResources() : integer;
Returns how many resources are in the world at that time.
RUsEnemyCollected () : integer;
Returns the amount of resource units collected by the player (human) since the start of this mission.
NISRunning () : integer;
Returns True if an NIS is currently running, False otherwise.
BuildControl (on : integer);
If “on” is True, the computer player will build ships according to regular AI. If it is False, the computer player will not build ships.
ShipsDamage (ships : ships, points : integer);
Inflict an amount of damage to all ships in the list. This might be useful for distributing radiation or blast damage.
RenderedShips (ships : ships, LOD : integer) : integer;
Returns True if any ships in the given ship list have been rendered at the given level of detail, False otherwise. If you pass in an empty ship list, it returns False.
For examle, you can check on a team by passing in TEAMSHIPS_ , or you can check on arbitrary ships in the universe by selecting and filtering (see the Ship List Variables section) and then passing the resulting SHIPS_ variable.
This would typically be used to tell if the gamer has seen a given ship or ships. This check will work with any ships, derelicts, or other objects like asteroids that are being treated like ships.
This does not tell you that ships are currently being rendered, just that they have been rendered.
ResetShipRenderFlags (ships : ships)
Resets the rendering flags in ships so that the Rendered Ships routine can be used to see if the ships have been rendered after the call of this function.
RenderedDerelictType (Derelict : string, LOD : integer) : integer
Just like rendered ships, but does not take in a shiplist, but rather takes in a type of derelict.
ResetDerelictRenderFlags(DerelictType : string)
Just like for ships, clears out the rendered flags.
RotateDerelictType (Derelict : string, Xrotation : integer, Yrotation : integer, Zrotation : integer, Variation : integer);
Rotates all derelicts in the level of type “Derelict” around the X-axis, Y-axis and Z-axis determined by the parameters Xrotation, Yrotation and Zrotation. Variation adds a random variation to the spin of each individual derelict to keep multiple derelicts of the same type to have identical rotations. Rotation speeds of 10 are slow, 100 – 300 are medium and 1000 are fast.
RaceOfHuman ( ) : integer;
Returns the race the human is playing. Race 1 returns 0. Race 2 returns
- The human can't play pirates or traders, so don't worry about getting any other values returned.
OpenSensors (flag : integer);
Forces open the sensors manager. If “flag” is set to TRUE, the sensors manager opens as a generic Fleet Intelligence screen (zoom out distance equal to the last zoom out distance used). If “flag” is set to a larger number, the value dictates how far the camera zooms out in the Fleet Intelligence screen. Note that “flag” should be larger than the smZoomMin value set for that level. I’m not sure what will happen with lower numbers.
CloseSensors (flag : integer);
Forces the sensors manager closed.
SensorsIsOpen (flag : integer) : integer
Returns the status of the sensors manager.
If flag == 1, Returns TRUE if the Fleet Intel window is open.
If flag == 0, Returns TRUE if the player is in the Sensors Manager due
to normal gameplay.
SensorsWeirdness (flag : integer);
Setting flag to TRUE, Sensors Manager malfunction is turned on. FALSE turns off the Sensors Manager malfunction.
HideShips(ships : ships);
Hides a group of ships. This is useful for spawning mid-level NIS’s.
UnhideShips(ships : ships);
Unhides a group of ships. Should be pared with HideShips().\
DisablePlayer (toggle : boolean);
If toggle is TRUE, the player’s commands are disabled. If toggle is FALSE, the player’s commands are reenabled.
\
Computer player features that can be enabled or disabled are found in Game/AIFeatures.h. This file must be included (#include “AIFeatures.h”) for the type and feature definitions to work.
\
DisableAIFeature (feature : integer, type : integer);
Disables the feature in the computer player.
\
EnableAIFeature (feature : integer, type : integer);
Enables the features in the computer player.
\
DisableAllAIFeatures ();
Disables all features in the computer player.
\
EnableAllAIFeatures ();
Enables all features in the computer player.
\
These functions control the technology which is offered to and bestowed upon the player. These will likely be used in conjunction with traders and also establishing the technology research tree (dependencies, etc.)
\
TechSetResearch (techName : string);
Allow player to research a technology, starting in the current mission (it does not have to be re-asserted in subsequent missions, unless you plan to warp directly to one.)
TechSetPurchase (techName : string);
Allow player to purchase a technology (when available), starting in the current mission (it does not have to be re-asserted in subsequent missions, unless you plan to warp directly to one.)
TechSet (techName : string);
Gives the player a technology to use. (This does not have to be re-asserted in subsequent missions, unless you plan to warp directly to one.)
TechSetCost (techName : string, cost : integer);
Sets the price of a technology for when the player buys technology from the Traders
TechGetResearch (techName : string) : integer;
Returns True if a player is allowed to research the given technology right now, False otherwise.
TechGetPurchase (techName : string) : integer;
Returns True if a player is allowed to purchase the given technology right now, False otherwise.
TechGet (techName : string) : integer;
Returns True if a player is currently has use of a given technology, False otherwise.
TechIsResearching ( ) : integer;
Returns True if a player is currently researching (anything), False otherwise.
TraderGUIDisplay ( );
Displays the Trader GUI.
TraderGUIIsDisplayed ( ) : integer;
Returns True if the Trader GUI is currently displayed, False otherwise.
TraderGUIPriceScaleSet (scalePercent : integer);
Scales the technology prices from their base. (eg. 100 = normal, 50 = half, 200 = double, etc.)
TraderGUIPriceScaleGet ( ) : integer;
Returns the technology price scale currently in effect. (Set this with TraderGUIPriceScaleSet.)
TraderGUIDialogSet (dialogNum : integer, dialogText : string);
Sets the text used in various parts of the Trader GUI. Please ask a programmer for the magic values to use for the dialogNum parameter.
0: DialogWelcome
1: DialogFirstClick - first click on a technology
2: DialogCantAffordThat - player doesn't have enough RUs. (The tech is also displayed in red.)
3: DialogCantAffordAnything - player is out of money
4: DialogPurchaseMade - thanks, would you like to supersize that?
5: DialogNothingForSale - traders have nothing to offer player
\
TraderGUIDisable (disable : integer);
Disables or enables the player or script from displaying the Trader GUI. Pass with True to disable the GUI, False to enable the GUI.
You can find the numbered parameters required for these audio routines in a document somewhere.
\
SoundEvent (event : integer);
Plays a sound event.
SoundEventShips (ships : ships, event : integer);
Plays a sound event associated with a given ship or ships.
SpeechEvent (event : integer, variable : integer);
Plays a speech event.
SpeechEventShips (ships : ships, event : integer);
Plays a speech event associated with a given ship or ships.
ToggleActor (Actor : integer, on : integer);
By setting on to FALSE, the voice actor defined in Actor is turned off. The Actor flags are defined in SpeechEvents.h.
MusicPlay (trackNum : integer);
Plays a music track or ambient loop.
MusicStop (fadeTime : integer);
Stops playing whatever music or ambient track is currently playing. Specify fadeTime in seconds.
TutSaveLesson(LessonNum : integer, LessonName : string);
Saves the current state of the tutorial as “Lesson (LessonNum) - (LessonName)” where LessonNum and LessonName are the respective function arguments and the parenthesis are omitted from the filename. This saved game also includes the name of the previous lesson, so that hitting the “Back” button repeatedly will traverse the entire lesson list in reverse.
BuilderRestrictShipTypes(shipTypes : string);
Disables the selection of the specified ship types from within the Build Manager. Multiple ships may be passed in as a comma-delimited string with no spaces.
BuilderUnrestrictShipTypes(shipTypes : string);
Re-enables the selection of specific ship types from within the build manager.
BuilderRestrictAll();
Disables the selection of all ships from within the build manager. Users will not be able to select any ships from the ship list. Note that build restrictions are cumulative, so calling BuilderRestrictAll() followed by BuilderUnrestrictShipTypes(“ResourceCollector,Probe”) will allow the user to select only resource collectors and probes.
BuilderRestrictNone();
Enables the selection of all ships from within the build manager.
BuildManagerShipTypeInBatchQueue(shipType : string) : integer;
Returns the number of ships of the specified type in the Build Manager current batch. The current batch of ships are those that the user has selected, but has not yet committed to building.
BuildManagerShipTypeInBuildQueue(shipType : string) : integer;
Returns the number of ships in specified type in the Build Manager construction queue.
BuildManagerShipTypeSelected(shipType: string) : integer;
Returns TRUE if the shiptype is selected in the build manager
CameraGetAngleDeg() : integer;
Returns the current camera rotation (east – west) angle in degrees as an integer from 0 to 359.
CameraGetDeclinationDeg() : integer;
Returns the current camera declination (north – south) angle in degrees as an integer from –90 to 90.
CameraGetDistance() : integer;
Returns the distance from the camera to the camera target as an integer.
SelectNumSelected() : integer;
Returns the number of currently selected ships.
SelectIsSelectionShipType(index : integer, shipType : string) : integer;
Returns 1 if ship number “index” in the current selection is of the given ship type, or 0 if not.
SelectContainsShipTypes(shipTypes : string);
Returns 1 if any of the ships types in “shiptTypes” are currently selected.
TutSetPointerTargetXY(name : string, pointerX : integer, pointerY : integer);
Sets a destination point in screen coordinates for a line drawn from the text display box. When the tutorial text is shown, a line will be drawn from the text to this position on screen. Note that all tutorial highlighting functions must be called after a call to TutShowText(), and that calling TutHideText() also disables the tutorial highlighting functions. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetXYRight(name : string, pointerX : integer, pointerY : integer);
Sets a destination point in screen coordinates for a line drawn from the text display box. Retains relative positioning to the right of the screen at higher resolutions (i.e. to point at something that is at the top right of the screen). When the tutorial text is shown, a line will be drawn from the text to this position on screen. Note that all tutorial highlighting functions must be called after a call to TutShowText(), and that calling TutHideText() also disables the tutorial highlighting functions. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetXYBottomRight(name : string, pointerX : integer, pointerY : integer);
Sets a destination point in screen coordinates for a line drawn from the text display box. Retains relative positioning to the botoom right of the screen at higher resolutions (i.e. to point at something that is at the bottom right of the screen) When the tutorial text is shown, a line will be drawn from the text to this position on screen. Note that all tutorial highlighting functions must be called after a call to TutShowText(), and that calling TutHideText() also disables the tutorial highlighting functions. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetXYTaskbar(name : string, pointerX : integer, pointerY : integer);
Sets a destination point in screen coordinates for a line drawn from the text display box. Used when pointing at Front End elements that stretch across the bottom of the screen. When the tutorial text is shown, a line will be drawn from the text to this position on screen. Note that all tutorial highlighting functions must be called after a call to TutShowText(), and that calling TutHideText() also disables the tutorial highlighting functions. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetXYFE(name : string, pointerX : integer, pointerY : integer);
Sets a destination point in screen coordinates for a line drawn from the text display box. Used in full screen Front End screens. When the tutorial text is shown, a line will be drawn from the text to this position on screen. Note that all tutorial highlighting functions must be called after a call to TutShowText(), and that calling TutHideText() also disables the tutorial highlighting functions. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetShip(name : string, ships : ships);
Sets the highlight target to track the specified ship. The first ship in the ship list will be circled and indicated by a line drawn from the tutorial text. If the ship is destroyed while the highlight is active, the highlight will disappear. Note that ships outside of the camera view will not be indicated until they come into view. To ensure that a ship is in view, use the TutCameraFocus() and TutCameraFocusCancel() commands. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetShipSelection(name : string, ships : ships);
Same as for the previous function, except that it will track the whole group rather than just the first ship in the selection.
TutSetPointerTargetShipHealth(name : string, ships : ships);
Sets the highlight target to track the specified ships health bar. The health / status bar of the first ship in the ship list will be highlighted by a rectangle and indicated by a line drawn from the tutorial text. If the ship is destroyed while the highlight is active, the highlight will disappear. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetShipGroup(name : string, ships : ships);
Sets the highlight target to track the specified ships group number indicator. The group number of the first ship in the ship list will be highlighted by a rectangle and indicated by a line drawn from the tutorial text. If the ship is destroyed while the highlight is active, the highlight will disappear. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetFERegion(name : string, atomName : string);
Draws a pulsing box around a front end region whose atom name matches the argument. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetRect(name : string, x0 : integer, y0 : integer, x1 : integer, y1 : integer);
Draws a pulsing box at x0,y0 to x1,y1. The name parameter is the name of the pointer to set. If there are to be multiple pointers, this name must be unique. Pointers of the same name will be overwritten.
TutSetPointerTargetAIVolume(name : string, volume : volume);
Draws a pulsing box at x0, y0 to the specified AISphere. The line will terminate in a circle around the volume’s screen position. The circle will be the size of the volume as specified in MissionMan, but will have a minimum size. Pointers of the same name will be overwritten.
TutRemovePointer(name : string);
Removes a pointer with the specified unique name.
TutRemoveAllPointers(name : string);
Removes all pointers, regardless of name.
TutSetTextDisplayBox(name : string, posX : integer, posY : integer, width : integer, height : integer);
Sets the position and size of the box in which text will be displayed on screen. The height of the box may be grown to accommodate strings which are too large for the given dimensions.
TutShowText(text : string);
Displays the string in the current text display box. The string will be displayed until hidden with TutHideText() or replaced by another call to TutShowText().
TutHideText();
Hides the text display box, and any tutorial highlight being displayed.
TutShowNextButton();
Displays a “Next >” button directly beneath the currently displayed text box. This must be called after the call to TutShowText() in order for it to correctly align to the bottom of the text box.
TutHideNextButton();
Hides the displayed next button.
TutShowBackButton();
Displays a “<Back” button directly beneath the currently displayed text box. This must be called after the call to TutShowText() in order for it to correctly aligh to the bottom of the text box. Clicking this button causes the tutorial to automatically return to the beginning of the lesson. Note that the button string will soon be changed to “<Restart Lesson”.
TutHideBackButton();
Hides the displayed back button.
TutShowPrevButton();
Shows a “<Previous Lesson” button directly beneath the currently displayed text box. Clicking this button causes the tutorial to automatically return to the previous lesson. This button is hidden by the TutHideBackButton() call.
TutNextButtonClicked() : integer;
Returns 1 if the user has clicked the Next button since the last time this function was called, or 0 if not.
TutShowImages(images : string);
Displays a list of iconic images used to denote keystrokes or mouse actions. The string passed in is a comma delimited text string of image names to be displayed, in order from right to left. These images will be displayed until hidden with TutHideImages() or replaced by another call to TutShowImages().
TutHideImages();
Hides the images previously displayed with TutShowImages().
TutDisableFlags(flags : string);
Disables the game functionality indicated by the flags contained in the argument. Multiple flags may be passed in as a comma-delimited string containing no spaces. Valid flags are as follows :
GameRunning : Stops time in the Homeworld universe.
BuildManager : Disables the Build Manager.
SensorsManager : Disables the Sensors Manager.
ResearchManager : Disables the Research Manager.
PauseGame, Dock, Launch, Move, MoveIssue, Attack, Harvest, CancelCommand, Scuttle, Retire: Disables the named player action.
ClickSelect, BandSelect, : Disables selections of the named type.
CancelSelect : Disables the ability to click empty space to cancel a selection. Note that if the ClickSelect or BandSelect flags are enabled, the user will still be able to select a different ship.
Special : Disables the “special” actions.
BuildBuildShips, BuildPauseJobs, BuildCancelJobs, BuildClose : Disables the corresponding buttons in the Build Manager.
SensorsClose : Disables closing of the sensors manager.
ContextMenus : Disables right-click menus for ships.
ContextFormDelta, ContextFormBroad, ContextFormX, ContextFormClaw, ContextFormWall, ContextFormSphere, ContextFormCustom : Disables named right-click menu formation.
Evasive, Neutral, Agressive: Disables named tactic for ships.
TaskbarOpen,TaskbarClose : Disables the corresponding TaskBar action.
ResearchSelectTech : Disables all selections within the technology list of the Research Manager.
ResearchSelectLab : Disables selection of labs in the Research Manager.
ResearchResearch, ResearchClearLab, ResearchClose : Disables the corresponding button in the Research Manager.
Focus, FocusCancel : Disables the corresponding camera command.
LaunchSelectShips, LaunchLaunch, LaunchLaunchAll, LaunchClose: Disables the corresponding buttons in the Build Manager.
\
TutEnableFlags(flags : string);
Enables game functionality indicated by the flags argument. Multiple flags may be passed in as a comma-delimited string, with no spaces.
TutEnableEverything();
Enables all game flags.
TutDisableEverything();
Disables all game flags.
TutResetGameMessageQueue();
Clears the message queue used by the tutorial system to receive messages about the status of game play. The message queue should be cleared before beginning a watch state which looks for game messages.
TutGameSentMessage(messages : string) : integer;
Returns 1 if the game sent the tutorial system any of the messages named since the last call to TutGameSentMessage() or TutResetGameMessageQueue(), whichever was more recent. Game messages indicate actions performed by the user, keys pressed, front-end buttons pressed, and more. If a user clicks a button in the front end, the atom name of that button is sent as a game message. The list of additional game messages and what they mean is as follows :
Mouse messages indicate the currently displayed cursor type, and are sent whenever the cursor changes. They are Mouse_NormalMouse, Mouse_RotateCamera, Mouse_ZoomCamera, Mouse_AddShips, Mouse_FocusNoSelect, Mouse_Movement, Mouse_BandBoxAttack, Mouse_ForceAttack, Mouse_Guard, Mouse_SpecialAttack, Mouse_SpecialOpActivate, Mouse_SpecialOpDeactivate, Mouse_Gui, Mouse_Resource, Mouse_Derelict, Mouse_Docking, Mouse_SmallDocking, Mouse_EnemyShip, and Mouse_AlliedShip
Game_Move : the user has entered move mode. (pieplate is active)
Game_MoveIssued: a move command was issued.
Game_MoveQuit : the user has quit move mode.
Game_MoveZ : the user has switched to moving in Z. (pieplate changing height)
Game_MoveXY : the user has switched to moving in X and Y. (pieplate normal)
Game_SensorsClose: the user has closed the sensors manager.
Game_ScuttleRequest : The user has made the request to scuttle a ship.
Game_ScuttleConfirm : The user confirmed the request to scuttle a ship.
Game_BandBoxFocus : The user has performed a band box focus.
Game_BandBoxAttack : The user has performed a band box attack.
Game_BandBoxForceAttack : The user has performed a band box forced attack.
Game_BandBoxSpecial : The user has performed a band box special command.
Game_BandBoxGuard : The user has performed a band box guard command.
Game_ClickSelectGroup: A single click has selected an entire group.
Game_ClickFocus : The user has performed a single click focus.
Game_ClickAttack : The user has performed a single click attack.
Game_ClickSpecial : The user has performed a single click special command.
Game_ClickGuard : The user has performed a single click guard command.
Game_ClickHarvest : The user has performed a single click harvest command.
Game_ClickAttack : The user has performed a single click attack command.
Game_DoubleClickSpecial : The user has performed a double click special command.
Game_DoubleClickGuard : The user has performed a double click guard command.
Game_DoubleClickHarvest : The user has performed a double click harvest command.
Game_DoubleClickAttack : The user has performed a double click attack command.
Game_DoubleClickBuild : The user entered the build manager with a double click.
Game_DoubleClickSensors : The user entered the sensors manager with a double click.
Game_DoubleClickResearch : The user entered the research manager with a double click.
Game_DoubleClickDock : The user initiated a dock action by double clicking.
Game_InfoOverlayShiftSelect : The user released the shift key after selecting ships on the information overlay.
Game_InfoOverlaySelect : The user single click selected ships from the information overlay.
Game_PlayerHarvesterDone : A harvester belonging to the current player has stopped harvesting because there are no more resources.
Game_NonPlayerHarvesterDone : A harvester not belonging to the current player has stopped harvesting because there are no more resources.
KB_Special ; The user pressed the Z key.
KB_FocusMothership : The user pressed the HOME key, or ALT-M keys.
KB_GroupAssign : The user pressed CTRL and a number key.
KB_GroupSelect : The user pressed a number key.
KB_GroupSelectFocus : The user double clicked a number key.
KB_GroupFocus : The user pressed ALT and a number key.
KB_GroupAddSelect : The user pressed SHIFT and a number key.
KB_Sensors : The user hit the SPACE bar.
KB_SelectCancel : The user hit ESC.
KB_FormationNext : The user hit the TAB key.
KB_FormationPrevious : The user hit SHIFT TAB.
KB_Build : The user hit the B key.
KB_CancelFocus : The user hit the C key.
KB_Dock : The user hit the D key.
KB_SelectEveryone : The user hit the E key.
KB_Focus : The user hit the F key.
KB_Harvest : The user hit the H key.
KB_Launch : The user hit the L key.
KB_TacticsPrevious : The user hit the left square bracket.
KB_TacticsNext : The user hit the right square bracket.
KB_Move : The user hit the M key.
KB_Pause : The user hit the P key.
KB_Research : The user hit the R key.
KB_Scuttle : The user hit the S key.
KB_Retire : The user hit the I key.
KB_TacticalDisplayOn : The user hit CAPS-LOCK and it is now on.
KB_TacticalDisplayOff : The user hit CAPS-LOCK and it is now off.
KB_FleetView : The user hit CTRL-F1.
KB_Kamikaze : The user hit K.
KB_TacticsEvasive : The user hit F2.
KB_TacticsNeutral : The user hit F3.
KB_TacticsAggressive : The user hit F4.
KB_FocusLast : The user hit ENTER.
KB_SelectNone : The user hit SHIFT tilde (~).
KB_GroupDelete : The user hit CTRL tilde (~).
KB_Undo : The user hit tilde.
RM_LabSelect0 to RM_LabSelect5 : The user clicked on a specified lab in the Research Manager.
RM_TechSelect_TechName : The user clicked on a technology in the Research Manager. Note that “TechName” will be replaced with the name of the specified technology.
KB_Formation_FormationName : The user hit a function key from F5 to
F11. Note that “FormationName” will be replaced with the specific
formation name.
Game_Formation_FormationName : The game placed the selected ships into
the named formation. Note that this message is sent after the game has
actually initiated the formation change.
Game_TaskbarOn: The taskbar interface is on the screen.
Game_TaskbarOff: The taskbar interface is off the screen.
Game_TechnologyReturned: A SalvageCapture Corvette has stripped technology from a derelict and has docked with the technology.
\
TutContextMenuDisplayedForShipType(shipType : string) : integer;
Returns 1 if a context menu has been displayed for a ship of type shipType since the last call to TutResetContextMenuShipTypeTest().
TutResetContextMenuShipTypeTest();
Clears the previous state of the Context Menu test variable. This function should be called before entering a watch state in which TutContextMenuDisplayedForShipType() is used.
TutRedrawEverything();
Forces a redraw of a front-end screen. If tutorial elements are present on top of a front end screen, this function must be called in the init of each state which executes while the front end screen is active.
TutCameraFocus(ships : ships);
Focuses the camera on the ships in the ship list. Note that the “Focus” flag must be enabled for this to work.
TutCameraFocusFar (ships : ships);
Focuses the camera a certain distance away from the ships.
TutCameraFocusDerelictType(Derelict : string);
Focuses the camera on the derelict type specified in “Derelict”. Note that the “Focus” flag must be enabled for this to work. Ask your favorite programmer for proper spelling of the Derelict types.
TutCameraFocusCancel();
Cancels the previous camera focus. Note that the “CancelFocus” flag must be enabled for this to work.
TutCameraFocusedOnShipType(shipType : string) : integer;
Returns the number of ships of the specified type that are in the current focus. Multiple ship types can be specified as a comma delimited string containing no spaces.
TutShipsInView(ships : ships) : integer;
Returns the number of ships in the ship list that the player can see.
TutShipsTactics(ships: ships) integer;
Returns the tactic type of the ships in the list. 0 = Evasive, 1 = Neutral, 2 = Aggressive.
TutPieDistance() : integer;
Returns the destination distance of the pie plate mechanism.
TutPieHeight() : integer;
Returns the destination height of the pie plate mechanism.
TutSetTextDisplayBoxToSubtitleRegion () : integer;
Clips pointers to the subtitle region.
TutForceUnpaused ();
Forces the game to unpause
SpawnEffect(ship : ships, effectName : string, parameter : integer)
Spawns the specified effect for each of the specified ships. Passes to the effect the size of the ship and the integer parameter.
wideScreenIn(frames : integer);
Causes the NIS-style letterbox bars to appear over the course of the specified number of milliseconds. Letterbox bars should not be visible when this is called.
wideScreenOut(frames : integer);
Causes the NIS-style letterbox bars to disappear over the course of the specified number of milliseconds. Letterbox bars should be visible when this is called.
SubtitleSimulate(actor : integer, milliseconds : integer, speech : string)
Simulate a subtitle as would normally be initiated from the speech engine. String will be automatically word wrap and scroll as needed to fit in the appropriate subtitle region in the amount of time specified. Please see separate document on subtitling for more details.
#define STA_FleetCommand 0
#define STA_AllShips0 1
#define STA_AllShips2 2
#define STA_AllShips3 3
#define STA_FleetIntel 4
#define STA_Traders 5
#define STA_Pirates2 6
#define STA_AllEnemyShips 7
#define STA_Ambassador 8
#define STA_Defector 9
\
LocationCard(milliseconds : integer, location :string)
Create a location card string for a specified number of milliseconds. This is actually a regular subtitle in a special subtitle region and as such, it can me manipulated like a regular subtitle.
PauseUniverse();
Pauses the universe. No ships will move or do anything.
UnpauseUniverse();
Unpauses the universe. Ships will resume doing their thing.
PauseOtherKAS();
Pauses global watches and FSM’s other than the one that calls this function. Also pauses all timers not local to the FSM calling this function.
UnpauseOtherKAS();
Just the opposite; resumes all previously paused timers and KAS watches.
IntelEventEnded() : integer
Returns the following:
FALSE – the intel event hasn’t ended
TRUE – the intel event ended naturally
2 – the intel event ended because a player skipped it.
Note that IF “(IntelEventEnded())” will be true if IntelEventEnded()
returns any non-FALSE response.
Quite useful for the fleet intel GUI. This only return TRUE once, that is to say if it is called immediately after returning TRUE, the result will be FALSE.
IntelEventNotEnded();
This function should be called in the init of any FSM that will call IntelEventEnded(). This ensures that it will not erroneously return TRUE the first time it is polled. Also, it would be wise to call this if a Fleet Intel FSM transitions from it’s idle state.
ForceIntelEventEnded ();
This function ensures that the next call to IntelEventEnded will be TRUE. This is useful if you want the FSM to fall through several states when calling IntelEventEnded.
This listing was last updated 1999/07/2216. You can always receive the most current summary of the functions available in your version of KAS by entering KAS2C –f at a command prompt. This will give you a listing of all available functions and the names and types of each of their parameters.
\
If you prefer C-style prototypes, enter KAS2C –fc.
\
Avoid hard-coding strings at the point where they are used in the game. Instead, place all your quoted string definitions in the Localization Section (see Grammar). Then you can reference the string later in the code with the LSTRING_xxxx notation.
\
Keeping strings centralized like this makes finding and changing displayed text easier and makes localization way easier.
\
Here’s an example:
\
LOCALIZATION
LSTRING_Intro
"Fleet Intelligence is now online. Blah blah blah."
"Le Intelligence de la Fleet est onlinez. Et du chocolat pour moi, hein?"
"Actung! Der Fleet Intelligence ist onlinendammen. Schnell, schnell!"
LSTRING_ObjHarvest
"Harvest 800 RUs"
"Arvest 800 har-yooz, s'il vous plait"
"Harvesten der 800 RUs"
LSTRING_ObjResearchShip
"Build a Research Ship"
"Fait le Ship de la Research, s'il vous plait"
"Builden der Researchen Shippen"
ENDL
\
Then, later in the code, you'd reference these strings like this:
\
Popup(LSTRING_Intro);
\
So at run-time, the game will use whatever language the user wants. It can change on-the-fly, mid-game.
G_PlayNis
To play an NIS through the KAS, you set a special variable. For example, in mission two, VarCreateSet("G_PlayNis", 2) plays NIS02.
\
G_PlayNislet
To play an NISlet through the KAS, set this special variable. The lowest digit of the number (in decimal) is the insert number (0 = A, 1 = B, 2 = C) and the second digit is the mission number. So, to play Mission 6 insert B, use VarCreateSet("G_PlayNislet", 61).
G_NisXComplete
You can watch for an NIS to complete by watching the “G_NisXComplete” variable. (Where X is an integer.) For example, once you’ve started to play NIS03, you can test VarGet(“G_Nis3Complete”). It will return the 3 if NIS03 has finished playing. Don’t start watching this variable until you’ve starting the NIS playing, though.
G_NisletXComplete
You can watch for this variable to tell when an NISlet has ended. The number X is the same as the one passed to VarCreateSet() to start the NISlet, and is the number returned by it if the NISlet has finished. Don’t start watching this variable until the NISlet has started.
G_NisCentreDerelict
Creating this variable will center the NIS around the derelict type specified as the value of this variable. Derelict types are defined in “shipdefs.h”.
You can watch the following variables in reference to salvage operations. These will return True/False.
\
G_SalvageTS
Set to True when the salvage corvette deposits a target in the mothership/carrier.
G_SalvageCryoTray
TRUE when a cryo tray has successfully been captured and deposited in the mothership/carrier.
G_SalvageFrigate
TRUE when a frigate has been successfully captured and deposited in the mothership/carrier.
G_DawgHasBone
Set to True when the Junk Yard Dawg latches onto a target
G_SalvageTD
Set to True when the salvage corvette has latched onto its target and the target is disabled. The key is that it occurs after the target is disabled, so it may require numerous corvettes.
G_TechRemoved
Set to the percentage of technology that has been stripped while a salvage covette is salvaging a derelict that has been placed with its attributes flag set to 1 (plus other attributes). A value of 100 indicates that the technology has been successfully removed.
G_RenderMainScreen
Set to TRUE when the main game screen is being rendered. FALSE when GUIs are up (BuildManager, ResearchManager, etc.)
KAS Language Reference Guide CONFIDENTIAL Page 35