Submarine TitansT
ST Aiscript
Description:
CONTENTS
INTRODUCTION
1. OBJECTS OF ST ARTIFICIAL INTELLIGENCE
1.1. Executors and containers
1.2. Arbiter
1.3. Strategist
1.4. Tactician
1.5. Fleet
1.6. AI executors and game units
2. BASIC COMPONENTS OF ST AISCRIPT
2.1. ST AIscript and C programming language
2.2. Compile time and Run time
2.3. Control of compilation process
2.3.1. Comment Symbols
2.3.2. Operator macro.
2.3.3. Operator include.
2.3.4. Conditional operator of Compile time
2.3.5. Operator import.
2.4. Constants of ST AIscript language
2.4.1. Integer constants
2.4.2. String constants
2.4.3. Floating point constants
2.5. Variables of Compile time. Operator ( ) assignment statement
2.6. Expressions, operations, operators and functions
2.6.1 Expression and its interpretation
2.6.2. Arithmetic operations
2.6.3. Bitwise logical operations
2.6.4. Logical operations and operations of relation
2.6.5. Operations of condition
2.6.6. Operations with string data
2.6.7. Operators and functions
2.6.8. Priority of operations of ST AIscript
3. General functions of ST AIscript
3.1. Functions of converting types
3.1.1. _strtoint
3.1.2. _strtodbl
3.1.3. _inttostr
3.1.4. _dbltostr
3.1.5. inttodbl
3.1.6. _floor
3.1.7. _ceil
3.2. String manipulation functions
3.2.1. _strf
3.3. Miscellaneous functions
3.3.1. _averageint
3.3.2. _averagedbl
3.3.3. _isin2D
3.3.4. _isin3D
4. Description of container parameters
4.1. Arbiter
4.1.1. Creation of Arbiter
4.2. Strategist
4.2.1. Creation of Strategist
4.2.2. Main Enemy
4.2.3. General offensive
4.3. Tactician
4.3.1. Creation of Tactician
4.4. Fleet
4.4.1. Creation of Fleet
4.4.2. Description of Fleet effectives
4.4.3. Repair of Fleet objects
4.4.4. Basic Fleet position
4.4.5. Collecting resources
4.4.6. Patrolling
4.4.7. Raid
4.4.8. Zone protection
4.4.9. Participation in General offensive
4.4.10. Helping other Fleets
4.4.11. Building objects
4.4.12. Types of Fleet programs
4.5. String Tables.
4.5.1. Creation of String Table
4.5.2. Adding strings to String Table
5. Events and their parameters
5.1. Events program (Events)
5.2. Structure of an Event and its parameters
5.3. Common Events
5.3.1. Simple Event
5.3.2. Input device Event
5.3.3. Event of briefing's end
5.3.4. Event of the beginning and end of player's Events program
5.4. Events for player's objects
5.5. Events for resource containers
5.6. Events for artifacts
5.7. Events for resource deposits
5.8. Events for mines
5.9. Events for technology research
5.10. Events for fleets
6. Run time variables. Assignment statements
6.1. Local and global Run time variables
6.2. Assignment statements
7. Run Time Functions
7.1. System Run Time Functions
7.1.1. IsEventOn
7.1.2. GetVar
7.1.3. GetGlobVar
7.1.4. GetParInt
7.1.5. GetParStr
7.1.6. GetRnd
7.1.7. GetStrRes
7.1.8. GetMyPlayer
7.2. Time Run Time Functions
7.2.1. GetTime
7.2.2. GetGameTime
7.2.3. GetOwnTime
7.2.4. GetTimerTime
7.3. Missions management Run Time Functions
7.3.1. GetMissDifficulty
7.3.2. GetTeam
7.3.3. IsEnemy
7.3.4. IsPlPresent
7.3.5. IsTeamPresent
7.3.6. IsTeamGame
7.3.7. GetMissCond
7.3.8. GetCurrPl
7.3.9. GetPlCiv
7.3.10 IsShareVis
7.3.11 GetPlName
7.3.12 GetRCLevel
7.3.13. GetGoldLevel
7.3.14. GetStartSetLevel
7.3.15. GetTechStartLevel
7.3.16. GetTechMaxLevel
7.4. Quantity Run Time Functions
7.4.1. GetPlObjT
7.4.2. GetPlObjM
7.4.3. GetPlObjN
7.4.4. GetPlObjLost
7.4.5. GetPlObjKilled
7.4.6. GetPlObjBuilt
7.4.7. GetPlRes
7.4.8. GetRes
7.4.9. GetRCField
7.4.10. GetRCCont
7.4.11. GetVolRCCont
7.4.12. GetArt
7.4.13. GetDest
7.4.14. GetMine
7.4.15. GetPlObjCost
7.5. Search Run Time Functions
7.5.1. IsPlObjExist
7.5.2. IsRCContExist
7.5.3. IsArtExist
7.5.4. IsDestExist
7.5.5. IsMineExist
7.6. Technology Run Time Functions
7.6.2. GetTechDevN
7.6.3. GetTechMaxLev
7.6.4. IsTechDev
7.6.5. IsTechProcessing
7.6.6. IsTechCanDevG
7.6.7. IsTechCanDevN
7.6.8. GetTechCost
7.7. Fleets Run Time Functions
7.7.1. GetFleetNum
7.7.2. GetFleetObjT
7.7.3. GetFleetObjM
7.7.4. GetFleetObjEx
7.7.5. GetFleetBehavior
7.7.6. GetFleetVision
7.7.7. IsFleetCanProduce
7.7.8. GetFleetMassWeaponReady
8. Actions. Operator <if>
8.1. Actions and Run time operators
8.2. Operator <if>
8.3. System Actions
8.3.1. ActLockEvent
8.3.2. ActOnEvent
8.3.3. ActOffEvent
8.3.4. ActSetVar
8.3.5. ActSetGlobVar
8.3.6. ActSetParInt
8.3.6. ActSetParStr
8.4. Timer Actions
8.4.1.ActOnTimer
8.4.2.ActOffTimer
8.4.3.ActTimerOnScreen
8.5. Information Actions
8.5.1. ActStringMess
8.5.2. ActStringInfo
8.5.3. ActOutText
8.5.4. ActOutString
8.5.5. ActPlaySound
8.5.6. ActPlayBriefing
8.6. Visibility Actions
8.6.1. ActOnFOW
8.6.2. ActOffFOW
8.6.3. ActHoleFOW
8.6.4. ActSetScreen
8.6.5. ActSetCamera
8.6.6. ActZoomIn
8.6.7. ActZoomOut
8.6.8. ActZoomSet
8.6.9. ActShowMapAction
8.7. Missions management Actions
8.7.1. ActInitPlRC
8.7.2. ActInitTech
8.7.3. ActInitDisGold
8.7.4. ActCreateStartSet
8.7.5. ActSetPlRC
8.7.6. ActSetDisGold
8.7.7. ActEndMiss
8.7.8. ActNextMiss
8.7.9. ActTotalStatistics
8.7.10. ActEpilogue
8.7.11. ActVideo
8.7.12. ActAddObjective
8.7.13. ActDelObjective
8.7.14. ActClearObjectives
8.7.15. ActAddStrRes
8.7.16. ActDelStrRes
8.7.17. ActClearStrRes
8.7.18. ActSetFriend
8.7.19. ActSetEnemy
8.7.20. ActSetTeam
8.7.21. ActLockInterface
8.7.22. ActUnLockInterface
8.7.23. ActSetShareVis
8.7.24. ActSetSiliconPerCell
. ActSaveMission
8.8. Objects Manipulation Actions
8.8.1. ActSetName
8.8.2. ActCreatePlObj
8.8.3. ActDelPlObjEx
8.8.4. ActDelPlObjS
8.8.5. ActObjSelectT
8.8.6. ActObjSelectM
8.8.7. ActObjSelectN
8.8.8. ActCreateRCCont
8.8.9. ActDelRCCont
8.8.10. ActCreateArt
8.8.11. ActDelArt
8.8.12. ActSetArtText
8.8.13. ActCreateRCField
8.8.14. ActDelRCField
8.8.15. ActSetRCFieldVol
8.8.16. ActCreateDest
8.8.17. ActDelDest
8.8.18. ActSetDestText
8.8.19. ActCreateMine
8.8.20. ActDelMine
8.8.21. ActSetParMine
8.9. Technology Actions
8.9.1. ActTechDevDisable
8.9.2. ActTechDevDisableAll
8.9.3. ActTechDevEnable
8.9.4. ActTechDevEnableAll
8.9.5. ActTechDevRun
8.9.6. ActTechSet
8.9.7. ActTechSetDepend
8.9.8. ActTechSetAll
8.9.9. ActTScenDevRun
8.9.10. ActTScenDevStop
8.9.11. ActBldObj
8.10. Strategist Actions
8.10.1. ActSParMainEnemy
8.10.2. ActSParOffensiveStroke
8.11. Tactician Actions
8.11.1 ActExecTactic
8.12. Fleet Actions
8.12.1. ActCreateFleet
8.12.2. ActDelFleet
8.12.3. ActSelectFleet
8.12.4. ActAddFleet
8.12.5. ActLockFleet
8.12.6. ActUnLockFleet
8.12.7. ActLinkFleet
8.12.8. ActLinkFleet
8.12.9. ActFParPutInStaff
8.12.10. ActFParCleanStaff
8.12.11. ActFParCanChangeStaff
8.12.12. ActFParRepairStaff
8.12.13. ActFParHomePosition
8.12.14. ActFParGatherRC
8.12.15. ActFParPatrol
8.12.16. ActFParSetPatrolPoint
8.12.17. ActFParCleanPatrolPoints
8.12.18. ActFParRaid
8.12.19. ActFParOffensive
8.12.20. ActFParGuardZones
8.12.21. ActFParSetZone
8.12.22. ActFParCleanZones
8.12.23. ActFParHelp
8.12.24. ActFParBuild
8.13. Direct commands to Actions Fleets
8.13.1. ActFCmdMove
8.13.2. ActFCmdAttackT
8.13.3. ActFCmdAttackZ
8.13.4. ActFCmdGuardF
8.13.5. ActFCmdGatherRC
8.13.6. ActFCmdProduction
8.13.7. ActFCmdLoad
8.13.8. ActFCmdUnLoad
8.13.9. ActFCmdCapture
ActFCmdTeleport
8.13.11. ActFCmdMassWeaponHit
9. Run Time errors
10. Command-line compiler of ST Aiscript language
10.1.Adding of AI containers and string tables to mission database
10.1.1. append
10.1.2. close
10.1.3. name
10.1.4. pack
10.1.5. Names of AI containers and string tables.
10.2. Environment variables
10.3. Command-line options
11. Media components
11.1. mfew32.exe utility
11.1.1. Create/open database. Operators 'create' and 'append'.
11.1.2. Source files. Operator 'source'.
11.1.3. Names of records. Operator 'name'.
11.1.4. Additional options. Operators 'pack', 'transp' and 'stretch'.
11.1.5. Command-line options.
11.2. String Tables
11.2.1. Creation of a string table. Operators 'initsar' and 'putsar'
11.2.2. Adding strings to the string table. Operator 'setsar'.
11.3. Prolog and epilogs
11.3.1. Preparation of background image.
11.3.2. Preparation of animations
11.3.3. Preparation of sound files
11.3.4. Creation of a program. Operators 'inittask' and 'puttask'.
11.3.5. Operators 'Time', 'SetColor', 'SetLevel'.
11.3.6. Buttons. Operators 'ShowBut', 'HideBut'.
11.3.7. Switch of difficulty level. Operators 'ShowSwitch' and 'HideSwitch'.
11.3.8. Default set of controls. Operator 'SetDefControl'.
11.3.9. Show Objectives. Operators 'ShowObjectives' and 'HideObjectives'.
11.3.10. Show text. Operators 'ShowTTask' and 'HideTTask'.
11.3.11. Show text in Viewer window. Operators 'ShowTask' and 'HideTask'.
11.3.12. Show text with typing and scrolling. Operators 'ShowATask' and 'HideATask'.
11.3.13. Show animations. Operators 'ShowAni', 'MoveAni', 'ShowAniFrame' and 'HideAni'.
11.3.14. Play sounds. Operator 'StartWave'.
11.4. Briefings
11.4.1. Preparation of TV animations
11.4.2. Creation of briefing program. Operators 'initbriefing' and 'putbriefing'.
11.4.3. Operator 'Time'.
11.4.4. Stop briefing program execution. Operator 'BriefingStop'.
11.4.5. Show text. Operator 'BriefingText'.
11.4.6. Show TV animations. Operator 'BriefingAni'.
11.4.7. Play sounds. Operator 'BriefingWave'.
11.5.
11.6. Video
Appendix A: Constants to define playing sides
Appendix B: Constants to define relation to playing side
Appendix C: Constants to define logo colors of objects
Appendix D: Constants to define civilizations
Appendix E: Constants to define teams
Appendix F: Constants to define types of Fleets
Appendix G: Constants to 19119b18t define types of Fleet behavior
Appendix H: Constants to define groups of types of game objects
Appendix I: Constants to define formations of units
Appendix J: Constants to define character and direction of attack
Appendix K: Constants to define types of artifacts
Appendix L.: Constants to define conditions of game objects
Appendix M: Constants to define changeable properties of Fleet objects
Appendix X: Names of common media components of TASKS.DKD database
INTRODUCTION
The ST AIscript is a language intended mainly to describe the behavior of Submarine Titans AI objects. ST AIscript contains a wide range of functions to affect the course of events in a game session.
These abilities allow:
The organization of different game types by providing game participants with different objectives to accomplish in a game session.
The tracking of victory and defeat conditions for game participants.
The control of players' objects, technology research and resource management.
The control of informational components of the game, such as text and voice messages, briefings, time count, etc.
Many other ways for an AI to react to, alter or constrain events within a game session.
The ST AIscript, in conjunction with the ST Editor, is powerful enough to develop not only individual scenarios for Single and Multiplayer-mode of the game, but entire campaigns. The campaigns for each ST civilization were developed entirely with the ST AIscript. The source code for the ST AIscript programs are included as an example for those who wish to create their own missions or campaigns (add-on).
The ST AIscript is not as complicated as C or Pascal programming languages. Together with the special abilities of the ST Editor, it allows users to create their own scenarios quickly and easily.
1. OBJECTS USED IN ST ARTIFICIAL INTELLIGENCE
1.1 Executors and containers
Executors are game objects that provide information for the execution of AI tasks during a game session. Executors include: Arbiter, Strategist, Tactician and Fleet.
Each of the executors has its own set of characteristics described by the parameters of the executor. Each can also have a Program of Events.
Containers contain the data (code) for executors. They bear the same names as their executors: Arbiter, Strategist, Tactician and Fleet except for one special container that contains data for the Program of Events. This container we will call Events.
What is the difference between Executor and its Container?
We deal with containers all the time when we create a new mission and its AI with the help of the ST Editor. In other words we create, edit and save the data of executors (their containers) into the mission database.
Containers can contain another container:
Arbiter can contain one Events
Strategist can contain one Events and several Tacticians
Tactician can contain several Fleet but no Events
Fleet cannot contain other containers
Hierarchy of containers:
a) Arbiter
|
|- Events (only one)
b) Strategist
|
|- Events (only one)
|
|- Tactician_1
| |
| |- Fleet_1_1
| | ...
| |- Fleet_1_N
| . . .
| . . .
|- Tactician_N
|
|- Fleet_N_1
| ...
|- Fleet_N_N
It should be noted that the Events container does not have its own executor. It is always a part of an Arbiter or Strategist. Hence the code of the events program that contains Events is executed in the game by the same Arbiter or Strategist in which it is included.
Executor
containers are stored in the database for each mission or in a special Strategist database included in the
game. This database contains a collection of Arbiters and Strategists,
which are used in
It should also be noted that the containers of Tactician, Fleet and Events are not stored independently. They are always part of an Arbiter or Strategist.
1.2 Arbiter
This executor has Events, which it executes during a game session. Arbiter is not associated with any side that participates in a game session. Instead it is intended as an overall game manager, creating starting game conditions for each side, watching for the conditions of mission accomplishment, informing human player of met criteria, etc. If Arbiter is present in the database of a mission, it will start at the very beginning of the game. Only one Arbiter can be present in a game session and it cannot be altered during the session.
1.3 Strategist
Strategist is always associated with a playing side and is intended mainly to coordinate the actions of all units on that side as well as solve strategic problems such as:
technology research
collecting and managing of resources
trade
production and management of ammunition
organization of general offensives
Furthermore it contains Events that may be executed from the moment it starts until the moment it stops. If a playing side is controlled by a computer player the Strategist that controls this side is called Opponent. If a playing side is controlled by a human player (one or several) the Strategist is called Assistant.
Opponent is started at the very beginning of the game and works until the game ends. It cannot be stopped during a game session. A mission database can contain several Opponents for a single computer player. In this case users are able to choose between Opponents. If the mission database does not have a single Opponent for a specific computer player, the objects of this player will not function. Different Opponents for the same computer player may be structured as different skill levels or as different strategic alternatives to allow a single scenario to unroll in very different ways.
Assistant is started on the human players' initiative. A human player selects an assistant from the list of those available in the mission database. An Assistant may be stopped and a new one started by the human player at any time during a game session.
NOTE: If
1.4 Tactician
Container Tactician is always included in its Strategist, but it is not started immediately when the Strategist is launched. To start a Tactician, the ActExecTactic command in the program of events needs to be executed. After this command a Tactician-executor will be created based on the data of the Tactician container. Tactician continues to be executed until its Strategist is executed.
As it was mentioned above, Strategist can contain several Tacticians and can start them at different times in different points of the playing field.
Tactician is intended to co-ordinate the interaction between Fleets, connections between Strategist and Fleet and solve tactical problems such as:
initial distribution of game objects between Fleets;
finding the optimal location for a Fleet in the zone of Tactician's force development;
executing Fleets' orders to build objects and submarines for them;
creation of repair base (or recharge base);
organization of interaction between Fleets;
calculation of optimal positioning of gun turrets to protect the zones of a Tacticians force development;
finding optimum locations for mine fields and mine laying.
1.5 Fleet
Container Fleet is always included in its Tactician. Fleet executor is created on the base of its container at the moment of Tacticians start, in which this container is included.
Right after its creation Fleet will be linked to its Tactician. A Fleet linked to Tactician is able to interact with other Fleets linked to that Tactician. The Fleet can replenish its forces in accordance with the vacancies defined within it, get help from other Fleets, repair units, etc. It will obey the orders of the Tactician, if able to fulfil them. For example, to participate in production of objects for other Fleets, help other Fleets, or participate in offensives organized by Tactician or Strategist.
Fleet will be deleted as soon as its Tactician is deleted.
Unlike other executors, Fleet can be created not only on the basis of a Fleet container at the moment of Tacticians start, but also by the ActCreateFleet command in the program of events. In this case Fleet will not be linked to a Tactician and it will act in accordance with its parameters and be controlled by direct commands of the ST AIscript, like: ActFCmdMove ActFCmdAttackZ, etc.
No matter by what method a Fleet is created, it can be linked to a Tactician or separated from it at any time using the Program of Events commands: ActLinkFleet and ActUnLinkFleet
Fleet can also be deleted by the command ActDelFleet at any moment.
Note that Fleet is the most low-level executor of AI. It is Fleet that unites and controls game objects directly. All commands that control unit behavior are given via a Fleet, which in its turn forwards them to the specific units included in it.
1.6 AI executors and game units
Game units (submarines and structures) can be controlled by the game interface or by a Fleet. No other executor can give direct orders to units.
Tactician and Strategist can control units of their playing side only via the Fleet to which the units belong.
How are units included in a Fleet?
Via the so-called procedure of selecting objects. The operators ActObjSelectT, ActObjSelectM and ActObjSelectN execute this procedure. If a Fleet is created outside a Tactician, all selected objects will be included in this Fleet, if they are of a common type (See 4.4). If a Fleet is created by a Tactician, the distribution of selected objects between Fleets will be done by that Tactician in accordance with their needs and priorities. After that a Fleet looks after its own maintenance within defined parameters.
If a playing side is controlled by a human player using Assistant, he is able to delegate his objects to Assistant and regain control via special parts of the game interface.
Deletion of a Fleet does not mean deletion of its game units. When a Fleet is deleted all objects in that Fleet are selected. In effect they lose their commander and, generally, do not take any further actions (except Fleets that deal with collecting resources).
2. BASIC COMPONENTS OF ST AISCRIPT
2.1 ST AIscript and C programming language
If you look at the source code of the ST AIscript you will see some similarity between its syntax and the C programming language. For example, you will see the symbols of arithmetic and logic operations, variables, string operations and even operators similar to C, however this similarity is superficial.
On one hand this simplifies the use of the ST AIscript by those familiar with C, on the other it can lead to mistakes caused by the differences between the languages.
First of all you should note that almost everything written in C (excluding, of course, comments and strings that control pre-processor) is transformed by a compiler into executable code. In other words, alteration of values of variables, calculation of mathematical operations, execution of functions happens (almost always) not at the stage of compilation but while executing the code. The ST AIscript consists of two equally important parts: one is intended for compilation and the other, just like in C, for creation of executable code to be run during the game.
Secondly, the ST AIscript is not a complete programming language hence it does not contain many of the components that even a simplest programming language possesses.
For example, it does have the ability to create new types of variables, new procedures and functions and deal with arrays of variables. This makes the ST AIscript simple and clear for common users who are not sophisticated programmers.
Lastly, note that an application created with a programming language is executed by a certain operational system or virtual machine. For the ST AIscript the game Submarine Titans is the OS or virtual machine. Hence an understanding of the ST AIscript language and its use benefits from a comprehensive knowledge of the game itself.
2.2 Compile time and Run-time
It is very important to differentiate that part of the ST AIscript that acts only during its compilation and the part that is compiled into a code to be executed during the game.
Compile time ST AIscript components are intended for:
a) management of the compilation process;
b) working with data in the process of compilation;
c) creation and description of parameters for containers such as Arbiter, Strategist, Tactician and Fleet.
It needs to be noted that the above 'c' part of the ST AIscript may not be used because the ST Editor allows the creation of those containers automatically without describing them.
RT (run-time) components of the ST AIscript language are intended for describing executable code contained in Events containers. As a rule RT components of the ST AIscript language are met inside description of Events containers, usually inside description of each event. Commonly those components can be inserted in any ST AIscript source code.
2.3. Control of compilation process
2.3.1. Comment Symbols
- simple string comment
- beginning of multistring comment
ending of multistring comment
The rules of using these comment symbols are analogous to the ones in C programming language.
2.3.2. Operator macro
This operator replaces one substring with the other
macro "substr1" "substr2"
where
substr1 - string to be replaced,
substr2 - string that replaces the above string.
After this operator the ST AIscript compiler before compilation will replace all substr1 to substr2.
This operator is used to replace frequently used constructions with shorter equivalents. AISCRIPT.MCR file that contains a big set of replacement macros included in the game simplifies the process of creation of the ST AIscript programs.
Examples:
macro "_actOnEvent(" "ActOnEvent(PLAYER_CURR, AIREL_MYSELF,"
macro "isTechProcessing(" "IsTechProcessing(PLAYER_ME,"
2.3.3. Operator include
This operator inserts files that contain the ST AIscript program source code. It can have one of the following types:
include<file_name>
or
include<[strvar_with_file_path]\file_name>
where
file_name - file name that contains the ST AIscript program,
strvar_with_file_path - string variable name of compile time. Value of this variable is usually a path to the file with source code.
Examples:
include<[_src_path]\AiScript.dfn>
include<[_main_path]\Editor\AiScript.mcr>
NOTE: Before compilation starts the ST AIscript compiler creates some string variables for compile time:
_main_path - contains full path of the folder where ST was installed
_src_path - contains full path of the folder where source code files of the ST AIscript programs are located and ST was installed
_curr_path - contains full path to the currently compiled source file.
2.3.4. Conditional operator of Compile time
This operator includes/excludes parts of the ST AIscript source code.
#if(expr)
<part 1>
#else
<part 2>
#endif
where
expr - constant expression with integer result
NOTE: We will call 'constant' an expression that needs to be calculated in the moment of compilation. Such expression is always an expression that does not include RT elements.
<part 1> and <part 2> - parts of source code.
If the result of expression equals to 0, then the compiler omits <part 1> and processes <part 2>
Example:
#if(!TRUE)
TRUE = 1;
....
....
#endif
The method shown in the example allows avoiding compilation of the same part of source code, which is included in other files several times.
2.3.5. Operator import
This operator imports Arbiter and Strategist containers, i.e. containers that can contain a Program of Events.
#import
<part 1>
#endimport
where
<part 1> - part of source code.
This operator indicates to ST AIscript that the part <part 1> contains components necessary for the RT part of the ST AIscript, i.e. for the Program of Events, and this part of the code <part 1> should be imported together with the Program of Events.
Example
...
#import
// Names
tactic = "WS Main Base";
fbase = "WS Base ";
fbuild = "WS Builder";
fguard0 = "WS Guard 00";
#endimport
...
If some variables of Compile time created outside the Program of Events are present in non-constant expressions intended for the Program of Events, then place that container into the body of the operator #import to import the expressions correctly.
2.4. Constants of ST AIscript language
2.4.1. Integer constants
Integer constants are recorded as decimals, hexadecimals and binaries. They can take any value between -2,147,483,647 and 2,147,483,648.
Examples:
0, 1, 10, 145, 76584360 - decimal;
0xFF, 0xA306, 0xABCDEF00 - hexadecimal;
0b01000001, 0b1100110001010101 - binary.
2.4.2. String constants
String constants are recorded between double quotation marks ("."). They may have an arbitrary length limited by the buffer size of compiler input (1024 byte).
Input of special symbols is preceded by backslash (\).
Special symbols:
\n - end of line,
\" - double quotation marks,
\\ - backslash.
Examples
"WS Main Base" , "The main forces have arrived.\n Well done.",
"c:\\Submarine Titans\\Editor\\WS_Raid_Fleet.flt"
2.4.3. Floating point constants
The distinguishing feature of floating-point constants is the presence of a decimal point 'e' ('E') symbol. Such constants have 7 significant numerals and their absolute value is between 3.4E-38 and 3.4E38.
Examples:
1.E-5, 0.0, 3.1415926, 67.28E18
2.5. Variables of Compile time. Operator ( ) assignment statement
Variables of Compile time are characterized by:
name,
type,
value.
Variable name is an arbitrary sequence of English alphabet letters, numerals and the symbol that is not preceded by a numeral. The length of this sequence should not exceed 64 symbols. Small and capital letters do differ from each other.
Variable type is defined at the moment of the first value assignment with the help of the assignment operator
name_var = expressoin;
where
name_var - variable name,
expressoin - constant or non-constant expression,
- symbol used to separate operators written in one line and indicate the end of expression.
If an expression is constant it will be calculated during its compilation. The received value will have one of the types described in 2.4. and it will be assigned to a variable named from the assignment statement.
If an expression is non-constant the result of its compilation will be executable code for the expression. In this case the variable that's name is to the left of the assignment statement will get a special type - expression. The value of this type of variable will be the executable code for the expression.
Examples:
tactic = "WS Main Base";
x = y + 10;
curr_boats = _getPlObjM(AITRG_BOATALL) + 10;
path = _src_path + "\\AiScript.dfn";
2.6. Expressions, operations, operators and functions
2.6.1. Expression and its interpretation
Expression is a sequence of operands, operations, functions and symbols-separators.
Operands are variables, constants or other expressions.
Symbols-separators are and . Expression can consist of one or more operations and define the execution of a sequence of elementary operations to transform information. The compiler follows a strict order of interpreting an expression. This order can be altered if separate parts of it are between round brackets.
Elementary operation for transforming information is set to be an operation symbol.
More complicated transformations of information are called functions. They are set by their names -reserved words in the ST AIscript language.
2.6.2. Arithmetic operations
Arithmetic operations are:
- addition;
- subtraction;
- change positive value to negative and vice versa;
- multiplication;
- division;
- definition of division remainder
For integer operands all the above mentioned operations are defined. The result of division will be an integer part and the result of the operation will be the remainder.
For floating-point operands all but operations are defined.
Operations of addition, subtraction, multiplication, division and definition have 2 operands and are called binary. Operation of changing value sign has one operand is called unary.
Examples:
x = 5 % 2;
d = -3*0.345;
z = x/3 + y/3.1415;
2.6.3. Bitwise logical operations
ST AIscript supports the following bitwise logical operations:
bitwise AND (&)
bitwise XOR (^)
bitwise OR (|)
bitwise inversion NOT (~)
All bitwise operations are defined for integer operands. Bitwise inversion becomes an unary operation and changes all bits of the operand to opposite ones. All other operations are binary; each bit of the result is defined by the bits of operands in the way shown in the table below:
Operand1 | Operand2 | AND | XOR | OR
-------- ----- ------ -------
0 | 0 | 0 | 0 | 0
0 | 1 | 0 | 1 | 1
1 | 0 | 0 | 1 | 1
1 | 1 | 1 | 0 | 1
Examples
s = 0x53C9; mask = 0x356C;
or = s | mask; // result - 0x77ED
or = s & mask; // result - 0x1148
or = s ^ mask; // result - 0x66A5
or = ~mask; // result - 0xCAA3
2.6.4. Logical operations and operations of relation
Logical operations and operations of relation are used in the formation of logical expressions that have only two integer values:
1 - if logical expression is true,
0 - if logical expression is false.
Logical expressions in the ST AIscript are mostly used in the header of an Event or in 'if' operator.
NOTE: The ST AIscript in fact does not have logic type of data. Operands and result of logical operations have integer values. Operators Event and if consider the result of expression calculation as FALSE if it equals to 0, otherwise it is considered as TRUE. Nevertheless for the user's convenience in the definition file of ST AIscript.DFN two constants are defined that can be used to identify results of logical operations and functions:
FALSE = 0;
TRUE = 1;
ST AIscript supports the following relational operations:
> - more than,
< - less than,
== - equal to,
>= - more than or equal to,
<= - less than or equal to,
= - is not equal to.
Logical operations of ST AIscript:
&& - logical AND
- logical OR
^^ - logical XOR
- logical NOT
NOTE: Logical and relational operations in the ST AIscript work in the same way as in standard C. In the code of logical operation && if the left operand is FALSE the right operand will not be calculated and the total result of the operation will be FALSE. Accordingly if the left operand || is TRUE the right will not be calculated and the total result will be TRUE.
Examples:
bool = (y > 10) && (y < -10);
cond = (time >= 200) || bool;
2.6.5. Conditional Operations
These operations are set by the symbols and and have the following structure:
cond_expression ? TRUE_statment : FALSE_statment
When executing conditional operations, cond_expression is calculated first. If it is true the result of the whole operation will be TRUE_statment and if it is false - FALSE_statment
Example:
a = 4; b=3;
c = a>b ? a*a + b*b : 0; // result - 25
2.6.6. Operations with string data
All relational operations and operations adding strings are defined over string data. Execution of relational operations for string operands is done by comparing their values symbol-by-symbol until the operation reaches the first unequal symbol including 0 that signifies the conclusion of the string.
The result of adding strings is a new string. This is made from the string on the right of the operation sign following the end of the string to the left of the sign.
Examples:
drive = "c:\\";
dir = "Submarine Titans\\Editor\\";
file = "AiScript.dfn";
path = drive + dir + file; // result - "c:\Submarine Titans\Editor\AiScript.dfn"
name = "Transport";
bool = name > "" ; // - TRUE
bool = name == ""; // - FALSE
str1 = "ABCDEF"; str2 = "abcdef"; str3="abcdefg";
bool = str1 < str2 ; // - TRUE
bool = str2 != str2 ; // - TRUE
bool = str3 >= str2 ; // - TRUE
bool = str1 > str3 ; // - FALSE
2.6.7. Operators and functions
Operators and functions in the ST AIscript language have the same syntax construction (except Events operators and the operator if which will be considered later)
name(par1, par2, ...)
where
name - name of operator or function,
par1, par2, ... - parameters which are included into brackets and separated by the separator (,)
The names of operators and functions are reserved case-sensitive words in the ST AIscript language. The ST AIscript offers a variety of operators and functions but does not allow the creation of new ones.
Parameters for operators and functions can be constants, variables and expressions.
Some operators and functions do not have parameters, in this case they are called: name(). The majority of operators and functions have a strictly pre-defined number of parameters, but others can have variable number, for example, functions _strf _averageint _averagedbl
There are also operators and functions that allow for default parameters. This means that when such an operator or function is called some of its parameters can be left undefined to be assigned default values automatically. Parameters can be not defined in strict order only: from right to left. In other words you cannot define parameter 4 if parameter 3 is undefined. Also note that you may not undefine those parameters allowed in the function description. Hereinafter parameters for operators or functions which are allowed to be undefined will be represented between square brackets . For example, in the description of the function:
GetPlObjT(who, who_rel, tobj[, logo, x, y, z, lx, ly, lz])
you can see that parameters logo, x, y, z, lx, ly, lz can be undefined whilst calling this function. This does not mean they will not be used when calculating the function's value. It means that the parameters will be assigned default values when the function is called.
Whilst all operators and functions have the same syntax construction they are intended for different purposes.
Operators are for execute actions based on the values of their parameters. They do not return values. Operators also cannot be used in expressions.
Functions are intended to calculate a result based on the values of their parameters and always returns a value. Functions can be used in expressions.
Operators that execute their actions while compiling the ST AIscript source code we shall call operators of compile time. As a rule such operators are used outside Program of Events and are used to create containers and describe their parameters.
Examples:
...
////////////////////////////////////////
// Creating a fleet container
////////////////////////////////////////
OpenFleet("BO Builder",CIV_BO, AIF_BUILD, 12);
// Staff
PutInStaff(TOBJ_ASSEMBLER , TOBJ_UNDEFINED, TOBJ_UNDEFINED, 10);
PutInStaff(TOBJ_HEAVY_CRUISER, TOBJ_DESTROYER, TOBJ_FIGHTER , 5);
PutInStaff(TOBJ_AVENGER , TOBJ_RAIDER , TOBJ_FIGHTER , 5);
// Param
RepairStaff(AICAN_MYSELF, 20, 0, AISF_HOMEPOSITION+AISF_PAUSE , AITRG_ALL);
CloseFleet();
...
Operators that execute actions during the game we shall call runtime operators.
Examples:
...
////////////////////////////////////////
// Programm of events for SI strategs
////////////////////////////////////////
OpenEvents();
// Execute Tactician
Event(getOwnTime()>1)
;
CloseEvents();
...
Functions that process general information not connected with the course of a ST game session are called General Functions. If the values of all parameters for a general function can be calculated at the moment of calculation the compiler will calculate the value of the function during compilation. If even one parameter for a general function is not calculable (a constant expression), the value of the function is calculated only when the executable code in the Program of Events is executed. See further details in part 3.
Examples:
...
mess = _strf("Mission %s .", end==0 ? "failed" : "completed");
// _strf - common function
actOutString(10, mess);
...
Functions can be calculated during the game to get information about a game session. Such functions are called Run Time Functions.
Expressions containing at least one Run Time Function cannot be constant expressions and must be calculated during the game session. More details on run time functions are in part 6.
Examples:
GetTime();
// get game time
isPlObjExist("Transport"); // get to know if a game object named "Transport" exists
NOTE: The names of all Run Time Functions begin with prefixes Get (get, _get) or Is (is, _is). In macros based on these functions Get and Is are replaced with get and is correspondingly if the functions are used to get info about a side (player) from the Program of Events by which they are called. In macros intended for functions that provide information about the current side, Get and Is are replaced with _get and _is correspondingly.
All macro definitions are included in the file AiScript.mcr supplied with the game.
2.6.8. Priority of operations of ST AIscript
All operations defined by the ST AIscript are ordered by priority. This defines the order of interpretation for expressions and can be altered using round brackets.
If there are several operations with the same priority inside brackets or when brackets are absent in an expression, binary operations are executed in "left-to-right" order and binary - from right to left. Expression between brackets are interpreted by the compiler first. In complex cases the expression "deepest" in round brackets is executed first.
Below is a table with all ST AIscript operations ordered by priority. A dash separates operations with equal priority.
= = = = = = = = = = = = = = = = =
Name | Symbol | Types of operands
= = = = = = = ===|= = |= = = = = = =
Function call | () | depends on function type
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Logical negation | ! | integer
Bitwise logical NOT | ~ | integer
Change of sign (unary minus) | - | integer, floating-point
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Multiplication | * | integer, floating-point
Division | / | integer, floating-point
Remainder of division | % | integer, floating-point
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Addition (addition of strings) | + | integer, floating-point, string
Subtraction | - | integer, floating-point
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Less than | < | integer, floating-point, string
Less than or equal to | <= | integer, floating-point, string
More than | > | integer, floating-point, string
More than or equal to | >= | integer, floating-point, string
Equal to | == | integer, floating-point, string
Not equal to | != | integer, floating-point, string
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Bitwise logical AND | & | integer
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Bitwise excluding XOR | ^ | integer
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Bitwise logical OR | | | integer
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Logical AND | && | integer
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Logical OR | || | integer
Excluding logical XOR | ^^ | integer
-------- ----- ------ -----|----------|----- ----- --------- ----- -------
Operation of condition | ?: | integer
= = = = = = = = = = = = = = = = =
3. General functions of ST AIscript
3.1. Functions of converting types
The ST AIscript supports several data types: integer, floating-point and string. Below are general functions intended to convert data from one of these types into another.
3.1.1. _strpoint
Converts a string to an integer.
_strtoint(str);
Parameters:
str - string to be converted.
Return Value:
The function returns the integer value produced by interpreting the input characters as a number. If the input cannot be converted to a value of the appropriate type, this will return 0. The return value is undefined in any case of overflow.
Remarks:
The string argument for these functions has the form: [whitespace] [sign]digits A whitespace consists of space and/or tab characters, which are ignored. Sign is either plus or minus Digits are one or more decimal digits. The function do not recognize decimal points or exponents.
_strtodbl
Convert strings to a floating-point value
_strtodbl(str);
Parameters:
str - string to be converted,
Return Value:
The function returns the value of the floating-point number, except when the representation would cause an overflow. _strtodbl returns 0 if no conversion can be performed or an overflow occurs.
Remarks:
The function stops reading the string str at the first character it cannot recognize as part of a number.
3.1.3. _inttostr
Convert an integer to a string
_inttostr(val[, radix]);
Parameters:
val - number to be converted,
radix - base of val, must be in the range 2 - 36.
Return Value:
This functions returns a string. There is no error return.
Remarks:
If radix equals 10 and value is negative, the first character of the stored string is the minus sign (-). Default value for radix is 10.
3.1.4. _dbltostr
Converts a floating-point value to a string,
_dbltostr(val, digits);
Parameters:
val - value to be converted,
digits - number of significant digits stored (integer value).
Return Value:
This functions returns a string of digits. There is no error return.
Remarks:
There is no provision for overflow. _dbltostr attempts to produce digits digits in decimal format. If it cannot, it produces digits in exponential format. Trailing zeros may be suppressed in the conversion.
3.1.5. inttodbl
Converts an integer number to a floating-point value
_inttodbl(val);
Parameters:
val - number to be converted,
Return Value:
This functions returns a floating-point value equal of val.
3.1.6. _floor
Calculates the integer floor of a floating-point value.
_floor(val);
Parameters:
val - floating-point value.
Return Value:
The _floor function returns an integer value representing the largest integer that is less than or equal to val. There is no error return.
3.1.7. _ceil
Calculates the integer ceiling of a floating-point value.
_ceil(val);
Parameters:
val - floating-point value
Return Value:
The _ceil function returns an integer value representing the smallest integer that is greater than or equal to val. There is no error return.
3.2. String manipulation functions
The ST AIscript has an operation for adding strings and for comparing strings. Functions for string manipulation are: _strtoint _strtodbl _inttostr and _dbltostr as described above
3.2.1. _strf
Formats and stores a series of characters and values in a result string.
Any arguments are converted and copied to the result string according to the corresponding format specification in the format string.
_strf(str[, ...]);
Parameters:
str - a string that contains the format-control specifications.
In addition to ordinary ASCII characters, a format specification for each argument appears in this string.
Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding format-control specifications in the str parameter.
Return Value:
The function returns a string with the result of processing.
Remarks:
The format-control string contains format specifications that determine the output format for the arguments following the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign . If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, produces a single percent-sign character).
The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the result string according to the format specification.
The second format specification causes the second argument to be converted and copied, and so on.
If there are more arguments than format specifications, the extra arguments are ignored.
If there are not enough arguments for all of the format specifications, the results are undefined.
A format specification has the following form:
%[-][#][0][width][.precision]type
Each field is a single character or a number signifying a particular format option.
The type characters that appear after the last optional format field determine whether the associated argument is interpreted as a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s
The optional fields control other aspects of the formatting. Following are the optional and required fields and their meanings:
= = =
Field | Meaning
= =
| Pad the output with blanks or zeros to the right to fill the field width,
| justifying output to the left. If this field is omitted, the output is
| padded to the left, justifying it to the right.
# | Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase) for integer
| argument, or decimal point for floating-point argument.
0 | Pad the output value with zeros to fill the field width. If this field is
| omitted, the output value is padded with blank spaces.
width | Copy the specified minimum number of characters to the result string. The
| width field is a nonnegative integer. The width specification never causes
| a value to be truncated; if the number of characters in the output value is
| greater than the specified width, or if the width field is not present, all
| characters of the value are printed, subject to the precision specification
.precision | For numbers, copy the specified minimum number of digits to the result
| string. If the number of digits in the argument is less than the specified
| precision, the output value is padded on the left with zeros. The value is
| not truncated when the number of digits exceeds the specified precision. If
| the specified precision is 0 or omitted entirely, or if the period (.)
| appears without a number following it, the precision is set to 1.
| For strings, copy the specified maximum number of characters to the result
| string. For floating-point arguments, copy the specified minimum number of
| digits to the result string after decimal point.
type | Output the corresponding argument as a character, a string, or a number.
| This field can be any of the following values.
| Value |
| d, i | Signed decimal integer.
| u | Unsigned integer.
| x, X | Unsigned hexadecimal integer in lowercase or uppercase.
| s | String.
| f | Signed floating-point by format [-]dddd.dddd
| e, E | Signed floating-point by format [-]d.dddde[+|-]ddd or [-]d.ddddE[+|-]ddd
3.3. Miscellaneous functions.
ST AIscript
3.3.1. _averageint
Calculates the average of an arbitrary number of integer arguments.
_averageint(arg1, arg2, ...);
Parameters:
arg1, arg2 integer arguments
Return Value:
An integer value derived from the integer division of the sum of all the arguments by their total quantity.
3.3.2. _averagedbl
Calculates the average of an arbitrary number of floating-point arguments.
_averagedbl(arg1, arg2, ...);
Parameters:
arg1, arg2, - floating-point arguments
Return Value:
A floating-point value derived from the division of the sum of all arguments by their total quantity.
3.3.3. _isin2D
Checks if point is within rectangle
_isin2D(x,y, x0, y0[, lx, ly]);
Parameters:
x,y - integer coordinates of the point,
x0, y0 - integer coordinates of initial apex,
lx, ly - integer lengths of rectangle sides
Return Value:
The return value is equal TRUE(1), if the point is within the rectangle, otherwise it returns FALSE(0).
Remarks:
lx and ly may be not defined when calling this function. In this case they will return value (1).
Initial apex is the apex from which all sides are directed towards the coordinate axis.
3.3.4._isin3D
Checks if point is within parallelepiped
_isin3D(x,y,z, x0, y0, z0[, lx, ly, lz]);
Parameters:
x, y, z - integer coordinates of the point,
x0, y0, z0 - integer coordinates of initial apex,
lx, ly, lz - integer lengths of parallelepiped sides
Return Value:
The return value is equal TRUE(1), if the point is within the parallelepiped, otherwise it returns FALSE(0).
Remarks:
lx and ly may be not defined when calling this function. In this case they will return value (1).
Initial apex is the apex from which all edges are directed towards the coordinate axis.
Description of container parameters
4.1. Arbiter
Arbiter does not have its own parameters except title and can contain one Program of Events.
4.1.1. Creation of Arbiter
Two operators of compile time OpenArbiter and CloseArbiter are used to create an Arbiter.
OpenArbiter(title[, game_types]);
Parameters:
title - string name of Arbiter. Only the first 63 symbols are significant, the rest are ignored.
game_type - type of provided game
Default: 0x00000001
Remarks:
Operator OpenArbiter creates data for Arbiter for the time of compilation. This data can be changed until the compiler meets the operator CloseArbiter
CloseArbiter();
Parameters:
It does not have any parameters.
Remarks:
It ends compilation of Arbiter.
Example:
...
OpenArbiter("Arbiter Default");
...
CloseArbiter();
...
4.2. Strategist
Strategist has its own behavior that is set by the parameters described below. It can also contain one Program of Events.
4.2.1. Creation of Strategist
Two operators of compile time OpenStrateg and CloseStrateg are used to create a Strategist.
OpenStrateg(title, civ[, short_name, game_types]);
Parameters:
title - string name of Strategist. Only the first 63 symbols are significant, the rest are ignored. This name is used as the name of human player in all types of the game.
civ - civilization of Strategist. The following constants are defined for this parameter:
CIV_BO - for Black Octopi,
CIV_WS - for White Sharks,
CIV_SI - for Silicons.
short_name - short name. Only the first 11 symbols are significant in short name, the rest are ignored. This name is used to select controller for playing side in single and multiplayer games.
game_types - supported game types
Default: 0xFFFFFFFF
Remarks:
Operator OpenStrateg creates data for Strategist for compile time. This data can be changed until the compiler meets the operator CloseStrateg
Civilization of Strategist is defined once and forever and cannot be changed.
CloseStrateg();
Parameters:
It does not have any parameters.
Remarks:
It ends compilation of Strategist.
4.2.2. Main Enemy
Main Enemy is a playing side that will be attacked by Fleets controlled by Strategist in the first turn. The Main Enemy and the ability to change it during the game are set by the operator of compile time MainEnemy
MainEnemy(can, enemy);
Parameters:
can - ability to change the main enemy during the game.
The following constants are used for this parameter:
AICAN_NOT - Strategist cannot replace the main enemy,
AICAN_MYSELF - Strategist can change the main enemy by its own.
enemy - side of enemy player. Constants described in Appendix A are used to describe this parameter.
Remarks:
If PLAYER_ALL is used for enemy then the Main Enemy is considered to be undefined. If also can==AICAN_NOT, then Strategist will not attack unbidden.
4.2.3. General offensive
One of the duties of Strategist is organization of offensive on the main Enemy with all forces able to participate in offensives. The operator of compile time OffensiveStroke sets parameters, which are used by Strategist while organizing an offensive.
OffensiveStroke(can, min_boats, max_boats, balance[, mode]);
Parameters:
can - ability to organize an offensive.
The following constants are used for this parameter:
AICAN_NOT - Strategist does not organize an offensive
AICAN_MYSELF - Strategist organizes an offensive.
min_boats minimum number of submarines necessary to begin an offensive
max_boats - number of submarines when offensive begins independent of the balance of power.
Balance - balance of power, if the value is higher than balance of power an offensive can be started. Balance of power is a quotient of player's power to the power of the Main Enemy, which is measured in percentage points. For example,
100 - powers are equal,
80 - player is weaker than enemy (power is less),
120 - player is stronger than enemy (power is greater)
mode - additional characteristics of offensive. (not used in this version.)
Remarks:
It should be noted that when balance and number of ships are calculated the Strategist only counts subs in fleets available to participate in an offensive. Hence it is not enough to simply set the parameters for Strategist to organize an offensive, you must also set corresponding parameters for its Fleets.
4.3. Tactician
4.3.1. Creation of Tactician
Two compile time operators OpenTactic and CloseTactic are used to create a Tactician.
OpenTactic(title, civ[, prio]);
Parameters:
title - string name of Tactician. Only the first 63 symbols are significant, the rest are ignored.
civ - civilization of Tactician. The following constants are defined for this parameter:
CIV_BO - for Black Octopi,
CIV_WS - for White Sharks,
CIV_SI - for Silicons.
prio - priority. Priority affects the distribution of objects and common resources for the playing side. Priority is set within the range from 0 to 19 (PRIO_TACT-1)
Remarks:
Operator OpenTactic creates data for Tactician for compile time. This data can be changed until the compiler reaches the operator CloseTactic
Civilization of Tactic is defined once and cannot be changed.
CloseTactic();
Parameters:
It does not have any parameters.
Remarks:
Ends compilation of Tactician.
4.4. Fleet
4.4.1. Creation of Fleet
Two compile time operators OpenFleet and CloseFleet are used to create a Fleet.
OpenFleet(title, civ, behav[, prio, logo]);
Parameters:
title - string name of Fleet. Only the first 63 symbols are significant, the rest are ignored.
civ - civilization of Fleet. The following constants are defined for this parameter:
CIV_BO - for Black Octopi,
CIV_WS - for White Sharks,
CIV_SI - for Silicons.
behav - type of Fleet. It defines the main function of the Fleet. Constants described in Appendix F are used for this parameter.
prio - priority. Priority affects the distribution of objects between Fleets and the sequence for executing orders for different Fleets to build required objects.
Priority is set within the range from 0 to 19 (PRIO_FLT-1)
Default: PRIO_FLT/2 (10)
logo - logo color of Fleet objects. Objects produced for the given Fleet will get the defined logo color (if no other logo color is defined in vacancy description of the produced object).
Constants for defining logo colors are described in Appendix C.
Default: LOGO_DEFAULT
Remarks:
Operator OpenFleet creates data for Fleet for compile time. This data can be changed until the compiler reaches the operator CloseFleet
Parameters civ behav prio logo are defined once and cannot be changed.
CloseFleet();
Parameters:
It does not have any parameters.
Remarks:
Ends compilation of Fleet.
4.4.2. Description of Fleet effectives
Each Fleet takes care of replenishing its effectives. For this purpose it orders its Tactician to produce objects based on the vacancies described in Fleet. The operator PutInStaff is used to set one vacancy.
PutInStaff(tobj1[, tobj2, tobj3, prio, x, y, z, logo, name]);
Parameters:
tobj1, tobj2, tobj3 - types of game objects. Constants TOBJ_... are used to indicate the types of players objects. Parameters tobj2 and tobj3 are consequent replacements for tobj1 if there is no technological capability for its production. If replacement is not required, then TOBJ_UNDEFINED is used.
Default: TOBJ_UNDEFINED.
prio - priority. Priority affects the priority of object production and is set within the range 0 to 49 (PRIO_OBJ-1).
Default: PRIO_OBJ/2 (25)
x,y,z - coordinates for building a structure. These parameters are ignored for submarines.
Default:
logo - logo color of produced object, see Appendix C. If the parameter is equal to LOGO_DEFAULT, then the object will be produced with the Fleet logo, see OpenFleet.
Default: LOGO_DEFAULT.
name - object's string proper name (no more than 14 symbols).
Default: no proper name.
Remarks:
1. The priority of an object and the priority of a Fleet are taken into consideration when defining the priority of object production. Priority of Fleet is principal, i.e. a fleet object with higher priority will be produced earlier than a fleet object with lower priority.
2. If the indicated coordinates to build a construction are equal to -1, the Fleet will select the building site itself. If the coordinates are not equal to -1, but are incorrectly set, for example, outside the map or in an unreachable area, the object will be built in the closest possible place to the defined spot.
3. Vacancies defined with the operator PutInStaff are also used to distribute existing objects between Tacticians Fleets using only tobj1 and prio parameters. Priorities for Fleet and Tactician are set in the same way.
4. The sequence of PutInStaff operators, written in arbitrary order, defines all Fleet effectives. Their quantity is unlimited.
A Fleet has the ability to change its effectives, i.e. delete and add vacancies. The operator CanChangeStaff is used for this.
CanChangeStaff(can);
Parameters:
can - ability to change vacancies independently.
If can==AICAN_NOT Fleet is using the vacancies defined when the Fleet was created or added by the operator PutInStaff
If can==AICAN_MYSELF - Fleet can change the list of vacancies by itself or via the requests of Tactician or Strategist.
If can==AICAN_BYORDER - Fleet can change the list of vacancies only via the requests of Tactician or Strategist.
Default: AICAN_NOT
Remarks:
The ability to change the list of Fleet vacancies allows the AI of executors (Fleet, Tactician and Strategist) to set Fleet effectives in accordance with the current situation on the playing field. For example, if a playing side does not have enough oxygen, the Strategist will try to add a vacancy for an object that extracts oxygen to one of its basic fleets, and so on.
4.4.3. Repair of Fleet objects
Fleets of structures and Fleets of submarines which are linked to a Tactician, have the ability to repair their effectives. The operator RepairStaff defines the parameters of this process.
RepairStaff([can, life, min_obj, states, types]);
Parameters:
can - ability to repair objects, see AICAN_... (AICAN_MYSELF)
If can == AICAN_NOT - does not repair its objects.
If can == AICAN_MYSELF - repairs its objects.
If can == AICAN_BYORDER - repairs its objects.
Default: AICAN_NOT
life - life level in percent, if it is less the object will be repaired.
Default:
min_obj - minimum number of objects, which must stay in the Fleet and not go to repair.
Default:
states - Fleet behaviors, in which it can repair objects, see Appendix G.
Default: AISF_HOMEPOSITION
types - types of objects allowed to repair, see Appendix H.
Default: AITRG_ALL
Remarks:
It should be noted that objects, whilst being repaired, are temporarily out of Fleet effectives and cannot fulfil their tasks.
4.4.4. Basic Fleet position
Basic Fleet Position is a point on the map and a manner how fleet objects are positioned round it. To be in the Basic Fleet Position is a background behavior of Fleet.
The operator HomePosition sets parameters of this behavior.
HomePosition([can, x, y, z, mode, time, form_type, form_size, form_dir]);
Parameters:
can - ability to return and change Basic Position.
If can == AICAN_NOT Fleet does not return to its Basic Position.
If can == AICAN_MYSELF Fleet returns to its Basic Position and can change this position by its own or by Tactician's demand.
If can == AICAN_BYORDER Fleet returns to its Basic Position defined in the Fleet description or BY the command ActFParHomePosition and cannot change it.
Default: AICAN_NOT
x, y, z - central point of Basic Position.
Default:
mode - behavior mode at the Basic Position (is not used so far)
Default:
time - time remaining at the Basic Position.
If time==0 - is unlimited
Default:
form_type - formation type, see Appendix I.
Default: FORMATION_DEFAULT
form_size - formation size from FORMATION_MIN_SIZE to FORMATION_MAX_SIZE, see Appendix I.
Default:
form_dir - direction of formation is set in degrees from 0 to 360. Angle is measured from the positive direction of axis X counterclockwise. The axis X coincides with the northeast border of the map. For the convenience of setting direction constants are defined in AiScript.dfn, see Appendix I.
Default:
Remarks:
If the central position point is set incorrectly and can == AICAN_BYORDER, Fleet will be obliged to define the point by its own.
4.4.5. Collecting resources
Collecting resources is a background Fleet behavior. The operator GatherRC sets parameters for this behavior.
GatherRC([can, main_rc, time]);
Parameters:
can - ability to collect resources and change collected resource type.
If can == AICAN_NOT Fleet does not collect resource.
If can == AICAN_MYSELF Fleet collects resource and can change its type by itself or by requests of Strategist or Tactician.
If can == AICAN_BYORDER Fleet collects the resource, which type is set in the Fleet description or by the command ActFParGatherRC and it cannot change.
Default: AICAN_NOT
main_rc - type of principal collected resource
Default: TOBJ_CORIUM
time - time of continuous collecting. If time==0 - is unlimited.
Default:
Remarks:
1. It is not enough to set the parameter can not equal to AICAN_NOT so that Fleet will collect resources. You should also include submarines that are able to collect resources in the Fleet. It is desirable to set Fleet type equal to AIF_RES (See Appendix F).
2. Resources and submarine types for their collection:
-------- ----- ------ ----- ----- --------- ----- -------
Res\Civ | WS | BO | SI
-------- ----- ------ ----- ----- --------- ----- -------
TOBJ_CORIUM | TOBJ_TRANSUB | TOBJ_CARGO_SUB | TOBJ_TRANSPORT
TOBJ_METAL | TOBJ_TRANSUB | TOBJ_CARGO_SUB | none
4.4.6. Patrolling
Patrolling is a background fleet behavior, which consists of sequential Fleet movement between multiple patrol points. Fleet remains for a defined period of time at each patrol points and its subs assume the defined formation. If the patrolling Fleet meets enemy objects they will be attacked.
The operator Patrol sets common parameters for patrolling.
Patrol([can, mode, time]);
Parameters:
can - ability to patrol and change patrol points.
If can == AICAN_NOT Fleet does not patrol.
If can == AICAN_MYSELF Fleet patrols and can change patrol points by itself or on Tactician's demand.
If can == AICAN_BYORDER Fleet patrols the points defined in the Fleet description or via the command ActFParSetPatrolPoint. It cannot change patrol points.
Default: AICAN_NOT
mode - patrolling mode (not used at present)
time - maximum time for patrolling. If time==0 - is unlimited.
Default:
Patrolling points can be added with the operator SetPatrolPoint. The number of patrol points is unlimited.
SetPatrolPoint(x, y, z [,mode, time, form_type, form_size, form_dir]);
Parameters:
x, y, z - patrol point coordinates.
mode - behavior mode at the patrol point (is not used so far)
time - total time of movement to and staying at the point.
Default:
form_type - formation type, see Appendix I.
Default: FORMATION_DEFAULT
form_size - formation size from FORMATION_MIN_SIZE to FORMATION_MAX_SIZE, see Appendix I.
Default:
form_dir - formation direction is set in degrees from 0 to 360. Angle is measured from the positive direction of axis X counterclockwise. The axis X coincides with the northeast border of the map. For the convenience of setting direction constants are defined in AiScript.dfn, see Appendix I.
Default:
Remarks:
1. If coordinates of a patrol point are set incorrectly, that point will be omitted in patrolling.
2. The order of patrol points corresponds to the order of SetPatrolPoint operators in Fleet description. For example, 4 patrol points are set for a Fleet: 1, 2, 3 and 4. The order in which these points will be patrolled will be: 1->2->3->4->3->2->1->2->3->4->...
3. If parameter can equals to AICAN_MYSELF, then the Fleet can add new patrol points and delete them by itself or on Tactician's or Strategist's demands. It will never delete points that were defined in Fleet description.
4. Military subs need to be included in a Fleet to perform this behavior.
4.4.7. Raid
Raid is a behavior, periodically executed by Fleet under certain conditions, which are described with the help of the operator Raid and consists of short-term attacks on the main enemy objects.
Raid([can, targets, boat_start, boat_finish, mode, time, time_out]);
Parameters:
can - ability to raid and select targets.
If can == AICAN_NOT Fleet does not raid.
If can == AICAN_MYSELF Fleet does raid and can change priority targets by itself or Tactician's demand.
If can == AICAN_BYORDER Fleet raids attacking priority targets defined in Fleet description or by the command ActFParRaid .It cannot change the targets.
Default: AICAN_NOT
targets - the highest priority targets. Constants described in Appendix H are used.
Default: AITRG_ALL
boat_start - number of subs necessary to initiate raid.
Default:
boat_finish - number of subs remaining when raid is terminated.
Default:
mode - attack type. Constants described in Appendix J are used.
Default: AIATTACK_HUNT
time - maximum time for each raid. If time==0 - time is unlimited.
Default:
time_out - minimum time between the end of the last raid and beginning of the next one.
Default:
Remarks:
Military subs need to be included in a Fleet to perform this behavior.
4.4.8. Zone protection
Zone protection is a behavior, which consists of attacking enemy objects which have crossed the border of a zone defined by the operator SetZone
It is executed under circumstances described with the help of the parameter GuardZones.
GuardZones([can, targets, boat_start, boat_finish, time]);
Parameters:
can - ability to protect zones and change their list.
If can == AICAN_NOT Fleet does not protect zones.
If can == AICAN_MYSELF Fleet protects zones and can change the list of zones by itself or on a Tactician's or Strategist's request.
If can == AICAN_BYORDER Fleet protects only those zones defined in Fleet description or by the command ActFParSetZone .It cannot change the list of zones.
Default: AICAN_NOT
targets - enemy objects considered as violators of protected zones. Constants described in Appendix H are used to define this parameter.
Default: AITRG_ALL
boat_start - number of subs necessary to attack the violators of protected zones.
Default:
boat_finish - number of subs remaining when zone protection attack should be terminated.
Default:
time - maximum time to spend in any zone protection attack. If time==0 - time is unlimited.
Default: 0
Protected zones can be added with the operator SetZone. The number of zones is unlimited.
SetZone(x, y, z, lx, ly, lz);
Parameters:
x, y, z, lx, ly, lz - zone parallelepiped, where x, y, z - coordinates of initial apex of the parallelepiped, i.e. the apex from which all edges directed as the coordinate axes;
lx, ly, lz - lengths of parallelepiped sides.
Remarks:
1. If a zone is defined incorrectly the Fleet will not guard it.
2. If the parameter can is set equal to AICAN_MYSELF, then the Fleet can add new zones to protect and delete them by itself or on a Tactician's or Strategist's demands. It will never delete zones defined in fleet description.
3. Military subs need to be included in a Fleet to perform this behavior.
4.4.9. Participation in General Offensive
Participation in General offensive is a behavior, which is executed by a Fleet when it receives the order from a Strategist, which organizes a General Offensive. The ability to participate in a General Offensive and the parameters of the participation are set with the operator Offensive
Offensive([can, targets, boat_start, boat_finish, time]);
Parameters:
can - ability to participate in General Offensive.
If can == AICAN_NOT Fleet does not participate in the offensive.
If can == AICAN_MYSELF or AICAN_BYORDER Fleet participates in the offensive.
Default: AICAN_NOT
targets - the highest priority targets in the offensive. Constants described in Appendix H are used for this parameter.
Default: AITRG_ALL
boat_start - number of subs required to start a General Offensive.
Default:
boat_finish - number of subs remaining when the General Offensive participation ends.
Default:
time - maximum time in offensive. If time==0 - time is unlimited.
Default:
4.4.10. Helping other Fleets
Helping other Fleets is a behavior, executed by a Fleet when it receives this order from a Tactician, which coordinates mutual assistance for Fleets. The help consists of attacking the enemy objects attacking another Fleet. The ability to help other Fleet and the parameters of this help are set with the operator Help
Help([can, fleets, boat_start, boat_finish, mode, time]);
Parameters:
can - ability to help other Fleet.
If can == AICAN_NOT Fleet does not help other Fleet.
If can == AICAN_MYSELF or AICAN_BYORDER Fleet helps other Fleet.
Default: AICAN_NOT
fleets - Fleet types, that can be helped, see Appendix F.
Default: AIF_BASE
boat_start - number of subs required to initiate help.
Default:
boat_finish - number of subs remaining when the help ceases..
Default:
mode - attack type. Constants described in Appendix J are used.
Default: AIATTACK_HUNT
time - maximum time spent helping another Fleet. If time==0 - time is unlimited.
Default:
Remarks:
1. Each Fleet can help only one Fleet at a time.
. Military subs need to be included in a Fleet to perform this behavior.
4.4.11. Building objects
Building objects is a behavior, executed by a Fleet when it receives a Tacticians order to build a structure or submarine. The ability to build objects is set with the operator Build
Build([can, group_obj]);
Parameters:
can - the ability to build objects.
If can == AICAN_NOT Fleet does not build objects.
If can == AICAN_MYSELF or AICAN_BYORDER Fleet builds objects.
Default: AICAN_NOT
group_obj - groups of object types, which are allowed to produce by the fleet, see Appendix H.
If group_obj == AITRG_ALL, the fleet is allowed to produce any type of objects.
Default: AITRG_ALL
Remarks:
1. This operator also affects the ability of a Fleet consisting of structures to produce submarines.
2. To execute this behavior you should include subs able to build structures, in submarine Fleet and structures able to produce subs, in structure Fleet.
3. The parameter group_obj does not affect the ability of fleet to produce different types of player's objects, but is intended to concentrate the fleet efforts on the production of the specified groups of object types only.
4.4.12. Types of Fleet programs
Fleet AI executes one of its programs in a concrete moment of time to fulfil set tasks.
According to the type of start, programs divide into:
- background. These are always executed, if allowed. If several background programs are allowed, they are executed alternatively.
- those started due to internal Fleet events.
- those started on a Tactician's or Strategist's request.
- those started via the commands of an Events program.
When any non-background program ends, Fleet starts executing the next background program. The action of replenishing and/or repairing effectives occurs simultaneously with the execution of any other programs in correspondence with set parameters.
Structure objects Fleet (AIF_BASE) are always in the condition AISF_HOMEPOSITION. Nevertheless such Fleet can also replenish and repair effectives and objects.
The table below shows all types of submarine (not structures) Fleet programs from lowest to highest priority. The only exceptions are ActFCmdProduction and ActFCmdMassWeaponHit, which can be executed by a fleet of structures:
= = = = = = = = = = = = = = = = = = =
Programs | Operators to describe abilities | Constant to indicate
= = = = = = = = = = = = = = = = = = =
Background:
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Remaining in | HomePosition, ActFParHomePosition | AISF_HOMEPOSITION
HomePosition | |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Patrol | Patrol, SetPatrolPoint, ActFParPatrol | AISF_PATROL
| ActFParSetPatrolPoint, |
| ActFParCleanPatrolPoints |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Collecting resources| GatherRC, ActFParGatherRC | AISF_GATHERINGRC
= = = = = = = = = = = = = = = = = = =
Started by internal fleet events:
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Raid | Raid, ActFParRaid | AISF_RAID
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Zone protection | GuardZones, SetZone, ActFParGuardZones | AISF_GUARDZONE
| ActFParSetZone, ActFParCleanZones |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
| MineZones, SetMineZone, |
Zone mine-laying | ActFParMineZones, ActFParSetMineZone, | AISF_MINE
| ActFParCleanMineZones |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Picking up Cargo | |
Containers, | Shipping, ActFParShipping | AISF_SHIPPING
paralyzed subs, etc.| |
= = = = = = = = = = = = = = = = = = =
Started on tactician's or strategist's requests:
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Build structure | Build, ActFParBuild | AISF_BUILDINGOBJ
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Help | Help, ActFParHelp | AISF_HELP
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Participate in | Offensive, ActFParOffensive | AISF_ATTACK
General offensive | |
= = = = = = = = = = = = = = = = = = =
Started on tactician's or strategist's requests:
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Go to a point | ActFCmdMove | AISF_MOVE
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Attack zone | ActFCmdAttackZ | AISF_ATTACK
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Attack targets | ActFCmdAttackT | AISF_ATTACK
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Protect other | ActFCmdGuardF | AISF_GUARDFLT
fleet | |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Collect resource | ActFCmdGatherRC | AISF_GATHERINGRC
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Build a submarine | ActFCmdProduction | AISF_BUILDINGOBJ
or structure | |
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Load object | ActFCmdLoad | AISF_SHIPPING
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Unload object | ActFCmdUnLoad | AISF_SHIPPING
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Capture object | ActFCmdCapture | AISF_CAPTURE
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Mine zone | ActFCmdMine | AISF_MINE
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----
Teleport | ActFCmdTeleport | AISF_TELEPORT
-------- ----- ------ -------- ----- ------ ----- ----- --------- ----- -----Attack with weapons | ActFCmdMassWeaponHit | AISF_ATTACK
of mass destruction | | = = = = = = = = = = = = = = = = = = =
4.5. String Tables
String tables are parts of mission media components and are intended to store string constants necessary for informational service of the mission.
Each mission must contain two string tables:
table of common string resources;
table of Objectives strings.
Table of common string resources contains strings intended for prolog, epilog and briefing programs, string messages and names of game units.
Table of Objectives strings contains the list of objectives
4.5.1. Creation of String Table
Two compile time operators are used to create a String Table: OpenStringTable and CloseStringTable
OpenStringTable();
Parameters:
It does not have parameters.
Remarks:
Operator OpenStringTable opens data for String Table for compile time. This data can be changed until the compiler reaches the operator CloseStringTable
CloseStringTable();
Parameters:
It does not have parameters.
Remarks:
It ends compilation of String Table.
4.5.2. Adding strings to String Table
Operator PutString is used to add strings to String Table.
PutString(str);
Parameters:
str - added string.
Remarks:
When strings are added to the String Table, it is important to keep the sequence order of PutString operators because later the access to the string will be available only through its number in the String Table. Strings enumeration in the String Table begin with zero.
5. Events and their parameters
5.1. Events program (Events).
Events Program (Events) is a container with executable code created by the ST AIscript during compilation and executed in the game. This container cannot exist independently - it must be included in the container of one of the executors - Strategist or Arbiter, which execute it during the game.
Two compile time operators OpenEvents and CloseEvents are used to create Events.
OpenEvents([title]);
Parameters:
title - string name of Events. Only the first 63 symbols are significant in the title, the rest are ignored.
Remarks:
1. Operator OpenEvents opens data for Events for compile time. This data can be changed until the compiler reaches the operator CloseEvents
2. Events can be opened only inside the description of containers Strategist or Arbiter.
3. String name of Events - title - can be undefined. In this case Events will receive the name of the container in which it is included.
CloseEvents();
Parameters:
It does not have parameters.
Remarks:
Ends compilation of Events.
5.2. Structure of an Event and its parameters
Events Program consists of a sequence of Events, each of them has the following structure:
NameOfEvent(expr[, Id])
;
where,
NameOfEvent - name (type) of Event.
expr - ST AIscript expression that sets conditions as to when Event occurs.
Id - integer identifier of Event.
Default:
ActProc1, ActProc2, ... - operators, which will be executed when the Event occurs.
Processing each Event consists of calculating the expression expr.
If the result of the calculation is TRUE, then all actions described by run time operators in the Event body (ActProc1, ActProc2, ...), will be executed. After that the Event becomes inactive, if it does not contain operator ActLockEvent(), which prohibits switching it off. If the result is not equal to TRUE, the operators in the Event body will not be executed and the Event remains active till the next processing.
Before processing an Event, i.e. the beginning of calculation of expression expr, integer and string parameters of the Event will be initialized.
The access to integer parameters is realized through pseudo-variables
_PI0, _PI1, ... _PI32 - total 33 parameters.
The access to string parameters is realized through pseudo-variables
_PS0, _PS1, PS2, PS3 - total 4 parameters.
For ALL types of events parameters _PI30, _PI31 and _PI32 will be initialized independently:
_PI30 - game time measured in seconds from the game beginning,
_PI31 - game time measured in atoms from the game beginning,
_PI32 - time measured in seconds from the moment of start of Events Program.
Initialization of other parameters depends on the type of Event and will be described below.
Initialized integer and string parameters can be used as in expression expr as in any other expressions in the Event body. They can also be used in the left part of assignment statement.
Example:
...
OpenEvents();
Event(_PI32>=10, 1)
;
CloseEvents();
...
5.3. Common Events
5.3.1. Simple Event
Simple Event is processed every game second.
Name:
Event
Parameters:
Only common parameters _PI30, _PI31, _PI32 are completed.
Remarks:
If an Events Program contains several Simple Events, they will be processed in the same game second in the order they are described in the Events Program.
5.3.2. Input device Event
This Event is processed when a key or a mouse button is pressed.
Name:
EventInput
Parameters:
_PI0 - input device command number (0...AIINPUT_NUM-1)
5.3.3. Event of briefing's end
This Event is processed when the launched briefing program ends.
Name:
EventBriefing
Parameters:
_PS0 - string name of briefing.
5.3.4. Event of the beginning and end of player's Events program
Such events are:
EventInit - is processed first upon execution of the Events program, which is included into the Strategist of a player. It is always processed before the rest of the events of the Events program.
EventDone - is processed last in the execution of the Events program, which is included into the Strategist of a player. It is always processed after all of the events of the Events program.
Parameters:
_PI0 - players number (PLAYER_0...7)
_PI1 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI2 - players team number, for team play mode only (TEAM_0...7)
_PS0 - string name of Events program
Remarks:
These events are processed only for players Strategist Events program and are not processed for Arbiter Events program.
5.4. Events for player's objects
These Event include:
EventPlObjCreated - processed when players object is created,
EventPlObjKilled - processed when players object is destroyed,
EventPlObjLoaded - processed when players object is loaded,
EventPlObjUnLoaded - processed when players object is unloaded,
EventPlObjCaptured - processed when players object is captured.
EventPlObjAttacked - processed when players object is attacked.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI7 and _PS0 - describe players object, for which one of the following Events occur:
_PI0 - players number (PLAYER_0...7)
_PI1 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI2 - players team number, for team play mode only (TEAM_0...7)
_PI3 - objects type (TOBJ_...)
_PI4 - objects logo (LOGO_0...7)
_PI5, _PI6, _PI7 - x,y,z - objects coordinates,
_PI8 - objects fleet number or ,
_PS0 - objects string name
Additional parameters:
For EventPlObjCreated - can give information about objects producer.
If player-producer is known, then
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
else
_PI10 == PLAYER_ALL
_PI11, PI12 - ARE NOT FILLED IN
If object-producer is known, then
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
else
_PI13 == TOBJ_UNDEFINED
_PI14.._PI18, _PS1 - ARE NOT FILLED IN
For EventPlObjKilled - can give information about objects killer.
If player-killer is known, then
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
else
_PI10 == PLAYER_ALL
_PI11, PI12 - ARE NOT FILLED IN
If object-killer is known, then
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
else
_PI13 == TOBJ_UNDEFINED
_PI14.._PI18, _PS1 - ARE NOT FILLED IN
For EventPlObjAttacked - can give information about what attacked the object.
If the attacking player is known, then
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
else
_PI10 == PLAYER_ALL
_PI11, PI12 - ARE NOT FILLED IN
If the attacking object is known, then
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
else
_PI13 == TOBJ_UNDEFINED
_PI14.._PI18, _PS1 - ARE NOT FILLED IN
For EventPlObjLoaded - describe object, on which the given object is loaded.
For EventPlObjUnLoaded - describe object, which the given object unloads.
For EventPlObjCaptured - describe object, which captured the given object.
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15,_PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
5.5. Events for resource containers
These Events include:
EventRCContCreated -processed when resource container is created,
EventRCContKilled -processed when resource container is destroyed,
EventRCContLoaded -processed when resource container is loaded,
EventRCContUnLoaded -processed when resource container is unloaded,
EventRCContUsed -processed when resource container is used.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI7 - describe resource container, for which one of the following Events occur:
_PI0 - number of player-producer (PLAYER_0...7)
_PI1 - civilization of player-producer (CIV_...)
_PI2 - team number of player-producer, for the team play mode only (TEAM_0...7)
_PI3 - type of resource (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON)
_PI4 - NONE
_PI5, _PI6, _PI7 - x,y,z - coordinates of container
_PI8 - quantity of resource in container
_PS0 - string name of container
Additional parameters:
For EventRCContCreated - can give information about the producer of resource container. It is filled in the same way as for EventPlObjCreated.
For EventRCContKilled - can give information about the killer of resource container. It is filled in the same way as For EventPlObjKilled.
For EventRCContLoaded - describe object, onto which resource container is loaded,
For EventRCContUnLoaded - describe object, from which unloads resource container,
For EventRCContUsed - describe object, which utilizes resource container.
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
5.6. Events for artifacts
Such Events are:
EventArtCreated -processed when artifact is created,
EventArtKilled -processed when artifact is destroyed,
EventArtLoaded -processed when artifact is loaded,
EventArtUnLoaded -processed when artifact is unloaded.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI7 and _PS0 - describe artifact, for which one of the following Events happens:
_PI0 - NONE
_PI1 - civilization-creator of artifact's shell (CIV_WS, CIV_BO or CIV_SI)
_PI2 - NONE
_PI3 - artifact's type (TART_...)
_PI4 - NONE
_PI5, _PI6, _PI7 - x,y,z - coordinates of artifact
_PS0 - string name of artifact
Additional parameters:
For EventArtCreated - can give information about the producer of artifact.
It is filled in the same way as for EventPlObjCreated.
For EventArKilled - can give information about the killer of artifact.
It is filled in the same way as for EventPlObjKilled.
For EventArtLoaded - describe object, on which the given artifact is loaded,
For EventArtUnLoaded - describe object, which unloads the given artifact.
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI160, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
5.7. Events for resource deposits
These Events include:
EventRCFieldCreated -processed when resource deposit is created,
EventRCFieldExhausted -processed when resource deposit is depleted (exhausted),
EventRCFieldEngaged -processed when an extractor (mine, collector) is built on resource deposit,
EventRCFieldFree -processed when an extractor (mine, collector) on resource deposit is destroyed.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI7 - describe resource deposit, for which one of the following Events occur:
_PI0 - NONE
_PI1 - NONE
_PI2 - NONE
_PI3 - type of resource deposit (TOBJ_CORIUM, TOBJ_METAL)
_PI4 - NONE
_PI5, _PI6, _PI7 - x,y,z - coordinates of resource deposit
Additional parameters:
For EventRCFieldEngaged - describe extractor (mine, collector), which is built on resource deposit:
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15, _PI16, _PI17 - x,y,z - objects coordinates
_PI18 - objects fleet number or ,
_PS1 - objects string name
For EventRCFieldCreated, EventRCFieldExhausted, EventRCFieldFree - are not filled in.
5.8. Events for mines
These Events are:
EventMineCreated - processed when mine is created,
EventMineKilled - processed when mine is destroyed.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI7 and _PS0 - describe mine, for which one of the following Events happens:
_PI0 - players number (PLAYER_0...7)
_PI1 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI2 - players team number, for the team play mode only (TEAM_0...7)
_PI3 - mine's type (TOBJ_...)
_PI4 - mine's logo (LOGO_0...7)
_PI5, _PI6, _PI7 - x,y,z - coordinates of mine
_PS0 - string name of mine
Additional parameters:
For EventMineCreated - can give information about the producer of mine.
It is filled in the same way as for EventPlObjCreated.
For EventMineKilled - can give information about the destroyer (victim) of mine.
It is filled in the same way as for EventPlObjKilled.
5.9. Events for technology research
These Events are:
EventTechDevStart - is processed if the research structure has begun to research the technology,
EventTechDevStop - is processed if the research structure has completed the technology research
EventTechAvailable - is processed if technology has become available for research,
EventTechDisable - is processed if technology has become unavailable for research.
Parameters:
Basic parameters:
Basic parameters _PI0 - PI5 - describes player and technology for which an event occurs:
_PI0 - players number (PLAYER_0...7)
_PI1 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI2 - players team number, for the team play mode only (TEAM_0...7)
_PI3 - technology (TTECH_...)
_PI4 - level (TTECH_LEV1...4)
_PI5 - is used only for EventTechDevStop
0 - technology research has been interrupted,
1 - technology research has been completed.
Additional parameters:
For EventTechDevStart and EventTechDevStop - describe research facility:
_PI10 - players number (PLAYER_0...7)
_PI11 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI12 - players team number, for the team play mode only (TEAM_0...7)
_PI13 - objects type (TOBJ_...)
_PI14 - objects logo (LOGO_0...7)
_PI15,_PI16, PI17 - x,y,z - coordinates of object
_PI18 - objects fleet number or ,
_PS1 - objects string name
For EventTechAvailable EventTechDisable - are not used.
Remarks:
These events occur only if changes in technologies happen because of gameplay (research of technology at a research facility, capture of enemy research structure, etc.) and do not occur if changes in technologies happen because of the STAIScript commands or using cheat codes.
5.10. Events for fleets
EventFCmdDone - is processed if fleet has accomplished fulfillment of a direct command (ActFCmd...)
Parameters:
Basic parameters:
Basic parameters _PI0 - PI5 and _PS0 - describe fleet, for which event occurs:
_PI0 - players number (PLAYER_0...7)
_PI1 - players civilization (CIV_WS, CIV_BO or CIV_SI)
_PI2 - players team number, for the team play mode only (TEAM_0...7)
_PI3 - fleet number
_PI4 - ID of direct command
_PS0 - Fleet's string name
Additional parameters:
Are not used.
6. Run time variables. Assignment statements
6.1. Local and global Run time variables
Every launched program has AIVARS_NUM cells of memory to store integer values. These cells are called Local Run Time Variables. The following pseudo-variables are defined in the ST AIscript to access them:
_RT0, _RT1, _RT2, ... - total AIVARS_NUM variables (for each Events program).
Physically these variables are situated in the executor that contains the Events Program; hence they are accessible only when this executor is launched. When this executor is launched all variables are assigned value: 0.
Besides Local Run Time Variables in the game system there are AIVARS_NUM memory cells for placing integer values. These cells are called Global Run Time Variables. The following pseudo-variables are defined in the ST AIscript to access them:
_GL0, _GL1, _GL2, ... - total AIVARS_NUM variables.
Global variables are not connected to an executor. They are accessible from any Events Program from the moment the game session begins until it ends. Moreover, if a game session consists of a sequence of missions, global variables will retain their values when passed from mission to mission. Only at the start of the first mission will all global variables be assigned value: 0.
Local and global variables are Run Time Variables; therefore they can be used only in expressions which set conditions for when an event occurs or in the body of an event. They cannot be used in any other parts of the ST AIscript source code.
6.2. Assignment statements
To assign values to Run Time Variables the ST AIscript has several assignment statements with the following structure:
variable <symbol of assignment statement> expression;
where
variable - local or global Run Time Variable;
<symbol of assignment statement> - symbol of an assignment statement:
- simple assignment,
- addition and assignment,
- subtraction and assignment,
- multiplication and assignment,
- integer division remainder and assignment,
- division remainder and assignment.
expression - expression, for which the calculation result is an integer value.
Assignment statements can only be written inside the body of an event.
Do not confuse compile time assignment statement with run time assignment statement . Statement is intended for assigning integer, string, real values to compile time variables, but statement is intended to assign only integer values to run time variables.
Examples:
...
Event(TRUE, 0)
...
Event(GL0>=DIFF_MEDIUM && _RT10<5 && getPlRes(TOBJ_GOLD)<1000, 10)
...
7. Run Time Functions
Run Time Functions are functions intended to obtain information about a game session. RTF can be calculated only during the game and cannot be calculated at the compilation stage.
7.1. System Run Time Functions
These functions are intended for obtaining information about various elements of the game system.
7.1.1. IsEventOn
Get information as to whether Event is active or not.
IsEventOn(who, Id);
isEventOn(Id);
_isEventOn(Id);
Parameters:
who - number of playing side, for which Events Program is executed, see Appendix A.
Id - identifier of Event in Events Program
Return Value:
If Event is active the returned value equals TRUE(1), otherwise it returns FALSE(0).
Remarks:
If Event with indicated Id is not found, the function returns FALSE. If Events Program has several Events with the indicated Id, the function returns the condition for the first, chosen by the order of description.
7.1.2. GetVar
Get value of Local Run Time Variable.
GetVar(who, n);
getVar(n);
_getVar(n);
Parameters:
who - number of playing side, for which Events Program is executed, see Appendix A.
n - number of variable (0 <= n < AIVARS_NUM).
Return Value:
Returns integer value of variable.
Remarks:
Unlike pseudo-variables type _RTn, this function may get value of a local variable for both it's and any other launched Events Program,.
7.1.3. GetGlobVar
Get value of Global Run Time Variable.
GetGlobVar(n);
Parameters:
n - number of global variable (0 <= n < AIVARS_NUM).
Return Value:
Returns integer value of variable.
Remarks:
This function is analogous to pseudo-variable type _GLn.
7.1.4. GetParInt
Get value of Event's integer parameter.
GetParInt(n);
Parameters:
n - parameter number (0 <= n < AIPARINT_NUM).
Return Value:
Returns value of Event's integer parameter.
Remarks:
This function is analogous to pseudo-variable type _PIn.
7.1.5. GetParStr
Get value of Event's string parameter.
GetParStr(n);
Parameters:
n - parameter number (0 <= n < AIPARSTR_NUM).
Return Value:
Returns value of Event's string parameter.
Remarks:
This function is analogous to pseudo-variable type _PSn.
7.1.6. GetRnd
Get random integer number within the range from min to max.
GetRnd(min, max);
Parameters:
min - minimum value,
max - maximum value.
Return Value:
Returns random integer number x, within the range min <= x <=max.
Remarks:
Parameters min, max can take negative values, but min must be less or equal to max.
7.1.7. GetStrRes
Get a string from String Table.
GetStrRes(n);
Parameters:
n - string number
Return Value:
Returns a string from String Table.
Remarks:
Enumeration of strings in String Table begins with 0.
7.1.8. GetMyPlayer
Get a number of the player, which is the owner of Events program
GetMyPlayer();
Return Value:
For a Strategist it returns one of the values PLAYER_0...PLAYER_7
For arbiter it returns PLAYER_ALL
7.2. Time Run Time Functions
These functions are intended to get the time counted in different elements of the game system.
7.2.1. GetTime
Get game time measured in seconds.
GetTime();
Parameters:
No parameters.
Return Value:
Returns game time measured in seconds.
Remarks:
Game second is approximately equal to standard physical seconds at the normal game speed. At higher and slower game speeds game seconds vary accordingly.
7.2.2. GetGameTime
Get game time measured in atoms.
GetGameTime();
Parameters:
No parameters.
Return Value:
Returns game time measured in atoms.
Remarks:
One game second equals 25 atoms.
7.2.3. GetOwnTime
Get time in game seconds counted from the moment of launch of the executor's Events Program.
GetOwnTime(who);
getOwnTime();
_getOwnTime();
Parameters:
who - playing side number, for which Events Program is executed , see Appendix A.
Return Value:
Returns time in game seconds counted from the moment of launch of executor's Events Program.
Remarks:
Game second is approximately equal to standard physical seconds at the normal game speed. At higher and slower game speeds game seconds vary accordingly.
7.2.4. GetTimerTime
Get timer time.
GetTimerTime(who);
getTimerTime();
_getTimerTime();
Parameters:
who - playing side number, the owner of timer, see Appendix A.
Return Value:
Returns timer time measured in game seconds. It returns if timer is not started for the indicated playing side.
Remarks:
Each playing side has a timer, which may be started to count down by the operator ActOnTimer. The timer for the current player is displayed on the Main Control Panel.
7.3. Missions management Run Time Functions
These functions return data necessary in controlling a mission.
7.3.1. GetMissDifficulty
Get mission's difficulty level.
GetMissDifficulty(who);
Parameters:
No parameters.
Return Value:
Returns one of the following constants:
DIFF_WEAK - easy,
DIFF_MEDIUM - medium,
DIFF_STRONG - strong.
Remarks:
This function is intended only for missions included in campaigns. In all other cases it returns 0.
7.3.2. GetTeam
Get number of the playing side.
GetTeam(who);
getTeam();
_getTeam();
Parameters:
who - number of playing side, see Appendix A.
Return Value:
Returns one of the constants described in Appendix E.
Remarks:
The function is intended for team play mode only. In non-team game mode it returns 0.
7.3.3. IsEnemy
Get information as to if the first playing side is the enemy of the second playing side.
IsEnemy(who, player);
isEnemy(player);
_isEnemy(player);
Parameters:
who - number of the first playing side, see Appendix A.
player - number of the second playing side, see Appendix A.
Return Value:
Returns TRUE, if who is enemy to player, otherwise returns FALSE.
Remarks:
The function is intended both for team play and non-team play modes.
7.3.4. IsPlPresent
Get information as to if the playing side participates in the current game session.
IsPlPresent(who);
isPlPresent();
_isPlPresent();
Parameters:
who - number of the first playing side, see Appendix A.
Return Value:
Returns TRUE, if the playing side who does exist, otherwise returns FALSE.
7.3.5. IsTeamPresent
Get information as to if the team is presented in the game session.
IsTeamPresent(team);
Parameters:
team - team number (see Appendix E.)
Return Value:
Returns TRUE, if the team team has at least one playing side, otherwise returns FALSE.
Remarks:
The function is intended only for team play mode. In case of non-team play mode it returns FALSE.
7.3.6. IsTeamGame
Get information as to if the current game session is a team game.
IsTeamGame();
Return Value:
Returns TRUE, if the session is played in the team play mode, otherwise returns FALSE.
7.3.7. GetMissCond
Get information about the state of mission accomplishment by a playing side.
GetMissCond(who);
getMissCond();
_getMissCond();
Parameters:
who - number of the first playing side, see Appendix A.
Return Value:
Returns one of the following values:
ENDMISS_NONE - mission is being played,,ENDMISS_ACCOMPL - mission has been accomplished,
ENDMISS_FAILED - mission has been lost.
7.3.8. GetCurrPl
Get the playing side value of the current player, i.e. the value of the side, which is controlled with the user's interface on the current computer.
GetCurrPl();
Return Value:
Returns one of the values between PLAYER_0 .. PLAYER_7
7.3.9. GetPlCiv
Get civilization of the player.
GetPlCiv(who);
getPlCiv();
_getPlCiv();
Parameters:
who - number of the first playing side, see Appendix A.
Return Value:
Returns one of the values:
CIV_WS - for White Sharks,
CIV_BO - for Black Octopi,
CIV_SI - for Silicons.
7.3.10 IsShareVis
Define if the ally visibility is set to on.
IsShareVis();
Return Value:
Returns TRUE, if ally visibility is switched on, otherwise returns FALSE.
7.3.11 GetPlName
Get the name of the player who controls the playing side.
GetPlName(who);
getPlName();
_getPlName();
Parameters:
who - number of the first playing side, see Appendix A.
Return Value:
Player's string name.
Remarks:
If several players control the playing side, the function will return the name of the main player.
7.3.12. GetRCLevel
Get the set starting resources level.
GetRCLevel();
Return Value:
One of the following values: LEVEL_LOW, LEVEL_MEDIUM or LEVEL_HIGH;
7.3.13. GetGoldLevel
Get the set gold density level.
GetGoldLevel();
Return Value:
One of the following values: LEVEL_LOW, LEVEL_MEDIUM or LEVEL_HIGH;
7.3.14. GetStartSetLevel
Get the set starting objects set.
GetStartSetLevel();
Return Value:
One of the following values: LEVEL_LOW, LEVEL_MEDIUM or LEVEL_HIGH;
7.3.15. GetTechStartLevel
Get the set starting tech level.
GetTechStartLevel();
Return Value:
One of the following values: LEVEL_LOW, LEVEL_MEDIUM or LEVEL_HIGH;
7.3.16. GetTechMaxLevel
Get the set maximum tech level.
GetTechMaxLevel();
Return Value:
One of the following values: LEVEL_LOW, LEVEL_MEDIUM or LEVEL_HIGH;
7.4. Quantity Run Time Functions
These functions are intended to get the quantity of various types of game objects, resources, statistic data, etc.
7.4.1. GetPlObjT
Get quantity of a set type of player's (s') objects.
GetPlObjT(who, who_rel, tobj[, logo, x, y, z, lx, ly, lz]);
getPlObjT(tobj[, logo, x, y, z, lx, ly, lz]);
_getPlObjT(tobj[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - defines list of players, see Appendix A. and Appendix B.
tobj - type of counted objects, see TOBJ_... constants.
If tobj == TOBJ_UNDEFINED, then objects of any type will be counted.
logo - logo of counted objects, see Appendix A.
If logo == LOGO_UNDEF, objects with any logo will be counted.
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be counted.
If zone is not defined (lx=ly=lz=-1) objects will be counted on the entire map.
Default:
Return Value:
Returns quantity of the set type of objects.
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes, and other objects and terrain features, which are not player objects.
To calculate structures and silicon prototypes separately, you can combine with one of the flags AITAKE_NOEMBRYO or AITAKE_NOOBJ (see Appendix H.)
7.4.2. GetPlObjM
Get number of player objects by groups.
GetPlObjM(who, who_rel, group_obj[, logo ,x, y, z, lx, ly, lz]);
getPlObjM(group_obj[, logo, x, y, z, lx, ly, lz]);
_getPlObjM(group_obj[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
group_obj - groups of types of counted player's objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
logo - logo of counted objects, see Appendix A.
If logo == LOGO_UNDEF, objects with any logo will be counted.
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be counted.
If zone is not defined (lx=ly=lz=-1) objects will be counted on the entire map.
Default:
Return Value:
Returns number of playerobjects by groups.
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects and terrain features are not player objects.
To calculate structures and silicon prototypes separately, you can combine with one of the flags AITAKE_NOEMBRYO or AITAKE_NOOBJ (see Appendix H.)
7.4.3. GetPlObjN
Get number of playerobjects by name
GetPlObjN(who, who_rel, name[, logo ,x, y, z, lx, ly, lz]);
getPlObjN(name[, logo, x, y, z, lx, ly, lz]);
_getPlObjN(name[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
name - proper name of the object (no more than 14 symbols).
If name is empty, objects with any name will be counted.
logo - logo of counted objects, see Appendix A.
If logo == LOGO_UNDEF, objects with any logo will be counted.
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be counted.
If zone is not defined (lx=ly=lz=-1) objects will be counted on the entire map.
Default:
Return Value:
Returns number of playerobjects by name.
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects and terrain features are not player objects.
7.4.4. GetPlObjLost
Get number of objects lost by player(s).
GetPlObjLost(who, who_rel, group_obj);
getPlObjLost(group_obj);
_getPlObjLost(group_obj);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
group_obj - groups of types of counted player's objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Return Value:
Returns number of objects lost by player(s).
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects and terrain features are not player objects.
Player objects lost since the beginning of the current game session are counted.
Silicon prototypes of structures are not counted.
7.4.5. GetPlObjKilled
Get number of objects destroyed by player(s).
GetPlObjKilled(who, who_rel, group_obj);
getPlObjKilled(group_obj);
_getPlObjKilled(group_obj);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
group_obj - groups of types of counted player objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Return Value:
Returns number of objects destroyed by player(s).
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects and terrain features are not player objects.
Destroyed objects are counted from the beginning of the current game session.
Silicon prototypes of structures are not counted.
7.4.6. GetPlObjBuilt
Get number of objects built by player(s).
GetPlObjBuilt(who, who_rel, group_obj);
getPlObjBuilt(group_obj);
_getPlObjBuilt(group_obj);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
group_obj - groups of types of counted player objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Return Value:
Returns number of objects built by player(s).
Remarks:
Player objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects and terrain features are not player objects.
Built objects are counted from the beginning of the current game session.
7.4.7. GetPlRes
Get number of player resources.
GetPlRes(who, who_rel, tres);
getPlRes(tres);
_getPlRes(tres);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
tres - resource type (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_AIR, TOBJ_ENERGY, TOBJ_SILICON)
Return Value:
Returns number of player resources presented in measurement units of the corresponding resource.
Remarks:
If tres==TOBJ_AIR the function returns the residual between the produced and required amount of air. This can be negative.
7.4.8. GetRes
Get number of resources on the map.
GetRes(tres[, x, y, z, lx, ly, lz]);
Parameters:
tres - resource type (TOBJ_WATERGOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON)
x, y, z, lx, ly, lz - zone parallelepiped in which resources will be counted.
If zone is not defined (lx=ly=lz=-1) resources are counted on the entire map.
Default:
Return Value:
For TOBJ_CORIUM or TOBJ_METAL the function returns the sum amount of the corresponding resource in deposits, which are situated within the defined zone on the map.
For TOBJ_WATERGOLD the function returns the amount of gold dissolved in the water on the entire map, there is no need to define a zone.
For TOBJ_SILICON the function returns the amount of silicon in the sea shelf in the defined zone.
To get the amount of energy which can be extracted by the Silicons from metal, the amount of metal must be multiplied by the constant METAL_TO_ENERGY, which is defined in AiScript.dfn.
7.4.9. GetRCField
Get the number of resource deposits on the map.
GetRCField(tres[, x, y, z, lx, ly, lz]);
Parameters:
tres - resource deposit type (TOBJ_CORIUM, TOBJ_METAL)
x, y, z, lx, ly, lz - zone parallelepiped, in which resources will be counted.
If zone is not defined (lx=ly=lz=-1) resources are counted on the entire map.
Default:
Return Value:
Returns the number of resource deposits on the map.
7.4.10. GetRCCont
Get number of containers with player resources.
GetRCCont(who, who_rel, [tres, name, x, y, z, lx, ly, lz]);
getRCCont([tres, name, x, y, z, lx, ly, lz]);
_getRCCont([tres, name, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
tres - resource type in container (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON) or TOBJ_UNDEFINED.
If tres=TOBJ_UNDEFINED, containers with any resource type will be counted.
Default: TOBJ_UNDEFINED
name - proper name of container (no more than 14 symbols) or empty string.
If name is not defined, then containers with any name will be counted.
Default: empty string
x, y, z, lx, ly, lz - zone parallelepiped in which containers will be counted
If zone is not defined (lx=ly=lz=-1) then containers will be counted on the entire map.
Default:
Return Value:
Returns number of containers with player resources.
7.4.11. GetVolRCCont
Get quantity of a resource in player containers.
GetVolRCCont(who, who_rel, [tres, name, x, y, z, lx, ly, lz]);
getVolRCCont([tres, name, x, y, z, lx, ly, lz]);
_getVolRCCont([tres, name, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
tres - resource type in container (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON) or
TOBJ_UNDEFINED.
If tres=TOBJ_UNDEFINED, then containers contents will be totaled regardless of resource types.
Default: TOBJ_UNDEFINED
name - proper name of container (no more than 14 symbols) or empty string.
If name is not defined, then containers with any name will be counted.
Default: empty string
x, y, z, lx, ly, lz - zone parallelepiped in which containers will be counted
If zone is not defined (lx=ly=lz=-1) then containers will be counted on the entire map.
Default:
Return Value:
Returns quantity of a resource in player containers.
7.4.12. GetArt
Get number of artifacts.
GetArt([tart, name, x, y, z, lx, ly, lz]);
Parameters:
tart - artifact type or TART_UNDEFINED, see Appendix K. If tart=TART_UNDEFINED, then artifacts of any type will be counted.
Default: TART_UNDEFINED.
name - proper name of artifact (no more than 14 symbols) or empty string.
If name is not defined, then artifacts with any name will be counted.
Default: empty string
x, y, z, lx, ly, lz - zone parallelepiped in which artifacts will be counted.
If zone is not defined (lx=ly=lz=-1) artifacts will be counted on the entire map.
Default:
Return Value:
Returns number of artifacts.
7.4.13. GetDest
Get number of Destinations on the map.
GetDest([logo, name, x, y, z, lx, ly, lz]);
Parameters:
logo - logo of Destination, see Appendix C.
If logo == LOGO_UNDEF then Destinations with any logo will be counted.
Default: LOGO_UNDEF.
name - proper name of Destination (no more than 14 symbols) or empty string.
If name is not defined, then Destinations with any name will be counted.
Default: empty string
x, y, z, lx, ly, lz - zone parallelepiped in which Destination will be counted.
If zone is not defined (lx=ly=lz=-1) Destination will be counted on the entire map.
Default:
Return Value:
Returns number of Destinations on the map.
7.4.14. GetMine
Get quantity of player mines.
GetMine(who, who_rel[, tmine, logo, name, x, y, z, lx, ly, lz]);
getMine([tmine, logo, name, x, y, z, lx, ly, lz]);
_getMine([tmine, logo, name, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define list of players, see Appendix A. and Appendix B.
tmine - type of mines (TOBJ_MINE_DEPTH, TOBJ_MINE_SNARE, TOBJ_ACOUSTIC_MINE, TOBJ_BEACON) or TOBJ_UNDEFINED. If tmine=TOBJ_UNDEFINED, then any type of player mines will be counted.
Default: TOBJ_UNDEFINED
logo - logo of mine (See Appendix C.) or LOGO_UNDEF.
If logo == LOGO_UNDEF then mines with any logo will be counted.
Default: LOGO_UNDEF.
name - proper name of mine (no more than 14 symbols) or empty string.
If name is not defined, then mines with any name will be counted.
Default: empty string
x, y, z, lx, ly, lz - zone parallelepiped in which mines will be counted.
If zone is not defined (lx=ly=lz=-1) mines will be counted on the entire map.
Default:
Return Value:
Returns quantity of player mines.
7.4.15. GetPlObjCost
Get quantity of a resource necessary to produce a players object.
GetPlObjCost(tres, tobj, civ);
Parameters:
tres - type of resource (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON)
tobj - type of players object, see constants TOBJ_...
civ - original civilization of object (CIV_WS, CIV_BO, CIV_SI)
Return Value:
Returns quantity of a resource necessary to produce a players object or 0 if the defined type of resource is not needed.
Remarks:
If the indicated civ is not the original one for the type of object tobj, the function will return 0 without an error message.
7.5. Search Run Time Function
These functions are intended for searching for various game objects by their unique string names.
7.5.1. IsPlObjExist
Searches for player object.
IsPlObjExist(who, name[, nvar_x, nvar_y, nvar_z, nvar_state]);
isPlObjExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
_isPlObjExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
Parameters:
who - playing side for which the search is conducted, see Appendix A.
name - proper name of the object (no more than 14 symbols). It must not be empty.
nvar_x, nvar_y, nvar_z - numbers of local variables to record the coordinates of the found object or , if the coordinates are not required. Numbers can be indicated within the range from to AIVARS_NUM -1.
Default:
nvar_state - number of local variable to record object's conditions or , if the conditions are not required. (See Appendix L.)
Default: .
Return Value:
Returns TRUE - if object is found, or FALSE, if not.
Remarks:
If object is not found, then the variables to record its coordinates and conditions are not filled in.
The local variables (_RT) of the events program, which calls this function, are used.
If there are several objects of the indicated playing side with the indicated name, then the first created will be found.
7.5.2. IsRCContExist
Searches player containers with resources.
IsRCContExist(who, name[, nvar_x, nvar_y, nvar_z, nvar_state]);
isRCContExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
_isRCContExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
Parameters:
who - playing side for which the search is conducted, see Appendix A.
name - proper name of container (no more than 14 symbols). It must not be empty.
nvar_x, nvar_y, nvar_z - numbers of local variables to record the coordinates of the found container or , if the coordinates are not required. Numbers can be indicated within the range from to AIVARS_NUM -1.
Default:
nvar_state - number of local variable to record container's conditions or , if the conditions are not required. (See Appendix L.)
Default: .
Return Value:
Returns TRUE - if container is found, or FALSE, if not.
Remarks:
If container is not found, then the variables to record its coordinates and conditions are not filled in.
The local variables (_RT) of the events program, which calls this function, are used.
If there are several containers of the indicated playing side with the indicated name, then the first created will be found.
7.5.3. IsArtExist
Searches for an artifact.
IsArtExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
Parameters:
name - proper name of artifact (no more than 14 symbols). It must not be empty.
nvar_x, nvar_y, nvar_z - numbers of local variables to record the coordinates of the found artifact or , if the coordinates are not required. Numbers can be indicated within the range from to AIVARS_NUM -1.
Default:
nvar_state - number of local variable to record artifact's conditions or , if the conditions are not required. (See Appendix L.)
Default: .
Return Value:
Returns TRUE - if artifact is found, or FALSE, if not.
Remarks:
If artifact is not found, then the variables to record its coordinates and conditions are not filled in.
The local variables (_RT) of the events program, which calls this function, are used.
If there are several artifacts of the indicated playing side with the indicated name, then the first created will be found.
7.5.4. IsDestExist
Searches Destination.
IsDestExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
Parameters:
name - proper name of Destination (no more than 14 symbols). It must not be empty.
nvar_x, nvar_y, nvar_z - numbers of local variables to record the coordinates of the found Destination or , if the coordinates are not required. Numbers can be indicated within the range from to AIVARS_NUM -1.
Default:
nvar_state - number of local variable to record Destination's conditions or , if the conditions are not required. (See Appendix L.)
Default: .
Return Value:
Returns TRUE - if Destination is found, or FALSE, if not.
Remarks:
If Destination is not found, then the variables to record its coordinates and conditions are not filled in.
The local variables (_RT) of the events program, which calls this function, are used.
If there are several Destinations of the indicated playing side with the indicated name, then the first created will be found.
7.5.5. IsMineExist
Searches mine of a playing side.
IsMineExist(who, name[, nvar_x, nvar_y, nvar_z, nvar_state]);
isMineExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
_isMineExist(name[, nvar_x, nvar_y, nvar_z, nvar_state]);
Parameters:
who - playing side for which the search is conducted, see Appendix A.
name - proper name of mine (no more than 14 symbols). It must not be empty.
nvar_x, nvar_y, nvar_z - numbers of local variables to record the coordinates of the found mine or , if the coordinates are not required. Numbers can be indicated within the range from to AIVARS_NUM -1.
Default:
nvar_state - number of local variable to record mine's conditions or , if the conditions are not required. (See Appendix L.)
Default: .
Return Value:
Returns TRUE - if mine is found, or FALSE, if not.
Remarks:
If mine is not found, then the variables to record its coordinates and conditions are not filled in.
The local variables (_RT) of the events program, which calls this function, are used.
If there are several mines of the indicated playing side with the indicated name, then the first created will be found.
7.6. Technology Run Time Function
These functions are intended to get information about technology development level of a playing side.
7.6.1. GetTechDevG
Get percentage of already developed technologies to the total number of technologies.
GetTechDevG(who);
getTechDevG();
_getTechDevG();
Parameters:
who - playing side (See Appendix A.)
Return Value:
Returns value within the range from 0 to 100.
7.6.2. GetTechDevN
Get percentage of already developed technologies of a playing side to the number of the technologies allowed to be developed in the given mission.
GetTechDevN(who);
getTechDevN();
_getTechDevN();
Parameters:
who - playing side (See Appendix A.)
Return Value:
Returns value within the range from 0 to 100.
7.6.3. GetTechMaxLev
Get the maximum allowed technology level.
GetTechMaxLev(tech);
Parameters:
tech - technology. TTECH_... constants are used to define technologies.
Return Value:
Returns value equal to one of TTECH_LEV... constants.
7.6.4. IsTechDev
Get information about whether technology is developed to a certain level.
IsTechDev(who, tech[, lev]);
isTechDev(tech[, lev]);
_isTechDev(tech[, lev]);
Parameters:
who - playing side (See Appendix A.)
tech - technology. TTECH_... constants are used to define technologies.
lev - technology developed level (TTECH_LEV... constants)
Default: TTECH_LEV1
Return Value:
Returns TRUE, if the technology tech is developed up to the level lev, or FALSE, if not.
7.6.5. IsTechProcessing
Get information about the technology is being researched at the moment.
IsTechProcessing(who, tech);
isTechProcessing(tech);
_isTechProcessing(tech);
Parameters:
who - playing side (See Appendix A.)
tech - technology. TTECH_... constants are used to define technologies.
Return Value:
Returns TRUE, if the technology (tech) is being researched by a ResLab, TechCenter or Command Hub Module at the current moment in time in the game, or FALSE, if it is not.
7.6.6. IsTechCanDevG
Get information about if the given technology level is allowed to be researched during the game session.
IsTechCanDevG(who, tech[, lev]);
isTechCanDevG(tech[, lev]);
_isTechCanDevG(tech[, lev]);
Parameters:
who - playing side (See Appendix A.)
tech - technology. TTECH_... constants are used to define technologies.
lev - technology level (TTECH_LEV... constants)
Default: TTECH_LEV1
Return Value:
Returns TRUE, if the level lev of the technology tech is available to be researched during the game session, or FALSE, if it is not.
7.6.7. IsTechCanDevN
Get information about if the given technology level is available for research at the current moment in time.
IsTechCanDevN(who, tech[, lev]);
isTechCanDevN(tech[, lev]);
_isTechCanDevN(tech[, lev]);
Parameters:
who - playing side (See Appendix A.)
tech - technology. TTECH_... constants are used to define technologies.
lev - technology level (TTECH_LEV... constants)
Default: TTECH_LEV1
Return Value:
Returns TRUE, if the level lev of the technology tech is available for research at the current moment in time, or FALSE, if it is not.
7.6.8. GetTechCost
Get the quantity of a resource necessary to research a specified technology.
GetTechCost(tech[, lev]);
Parameters:
tech - technology. TTECH_... constants are used to define technologies.
lev - technology level (TTECH_LEV... constants)
Default: TTECH_LEV1
Return Value:
For WS and BO it returns the amount of GOLD, necessary to research the technology.
For SI it returns the amount of ENERGY, necessary to research the technology.
7.7. Fleets Run Time Function
These functions are intended to get information about fleets.
7.7.1. GetFleetNum
Get fleet number by its name.
GetFleetNum(who, flt_name[, tact_name]);
getFleetNum(flt_name[, tact_name]);
_getFleetNum(flt_name[, tact_name]);
Parameters:
who - playing side of the fleet (See Appendix A.)
flt_name - string name of the fleet (See CreateFleet)
tact_name - string name of the tactician, to which the fleet is linked or empty string.
If tacticians name is not defined, then the fleet will be searched for in all of the players launched tacticians and then amongst non-linked fleets.
Default: empty string
Return Value:
Returns fleet number or if the fleet with defined name is not found.
Remarks:
The received fleet number is unique for fleets of the given playing side. It can be saved in a local or global Run time variable and is meant to identify fleets in other functions and operators of the STAIscript.
7.7.2. GetFleetObjT
Get number of objects in the defined type fleet.
GetFleetObjT(who, fleet, tobj[, logo]);
getFleetObjT(fleet, tobj[, logo]);
_getFleetObjT(fleet, tobj[, logo]);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
tobj - type of counted objects (TOBJ_... constants)
logo - logo of counted objects (See Appendix C.) or LOGO_UNDEF.
If logo == LOGO_UNDEF objects with any logo will be counted.
Default: LOGO_UNDEF.
Return Value:
Returns number of objects in the defined type fleet.
7.7.3. GetFleetObjM
Get number of objects in a fleet by groups.
GetFleetObjM(who, fleet[, group_obj, logo]);
getFleetObjM(fleet[, group_obj, logo]);
_getFleetObjM(fleet[, group_obj, logo]);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
group_obj - groups of types of counted player's objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Default: AITRG_ALL
logo - logo of counted objects (See Appendix C.) or LOGO_UNDEF.
If logo == LOGO_UNDEF objects with any logo will be counted.
Default: LOGO_UNDEF.
Return Value:
Returns number of objects in a fleet by groups.
7.7.4. GetFleetObjEx
Get the number of objects in the fleet.
GetFleetObjEx(who, fleet[, group_obj, tobj, logo, name, x, y, z, lx, ly, lz]);
getFleetObjEx(fleet[, group_obj, tobj, logo, name, x, y, z, lx, ly, lz]);
_getFleetObjEx(fleet[, group_obj, tobj, logo, name, x, y, z, lx, ly, lz]);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
group_obj - groups of types of counted player's objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Default: AITRG_ALL
tobj - type of counted objects (See TOBJ_...) or TOBJ_UNDEFINED.
When tobj==TOBJ_UNDEFINED - type is of no importance and objects of any type of fleet will be counted.
Default: TOBJ_UNDEFINED
logo - logo of counted objects (See Appendix C.) or LOGO_UNDEF.
If logo == LOGO_UNDEF objects with any logo will be counted.
Default: LOGO_UNDEF.
name - proper name of counted objects of the fleet (no more than 14 symbols)
If name is not defined, then objects with any name will be counted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be counted.
If zone is not defined (lx=ly=lz=-1), objects are counted on the entire map.
Default:
Remarks:
The following is the list of filters arranged in the descending priority:
- tobj;
- group_obj;
- name;
- logo;
- x, y, z, lx, ly, lz;
Return Value:
Returns the number of objects in the fleet.
7.7.5. GetFleetBehavior
Get the type of executed behavior of fleet.
GetFleetBehavior(who, fleet);
getFleetBehavior(fleet);
_getFleetBehavior(fleet);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
Return Value:
Returns one of the constants described in Appendix G.
7.7.6. GetFleetVision
Get the number of objects, which get into the visibility area of the fleet. The visibility area of the fleet is the alliance of visible areas of each object, which is included into the fleet.
GetFleetVision(who, fleet, player, player_rel[, group_obj, tobj, logo, name]);
getFleetVision(fleet, player, player_rel[, group_obj, tobj, logo, name]);
_getFleetVision(fleet, player, player_rel[, group_obj, tobj, logo, name]);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
player, player_rel - defines the list of playing sides, which objects will be counted (see Appendix A. and Appendix B.)
group_obj - groups of types of counted players objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
Default: AITRG_ALL
tobj - type of counted objects (See TOBJ_...) or TOBJ_UNDEFINED.
When tobj==TOBJ_UNDEFINED - type is of no importance and objects of any type of fleet will be counted.
Default: TOBJ_UNDEFINED
logo - logo of counted objects (See Appendix C.) or LOGO_UNDEF.
If logo == LOGO_UNDEF objects with any logo will be counted.
Default: LOGO_UNDEF.
name - proper name of counted objects of the fleet (no more than 14 symbols)
If name is not defined, then objects with any name will be counted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be counted.
If zone is not defined (lx=ly=lz=-1), objects are counted on the entire map.
Default:
Remarks:
1. The following is the list of filters arranged in the descending priority:
- player, player_rel;
- tobj;
- group_obj;
- name;
- logo;
2. If the fleet does not contain a single object the function will return .
Return Value:
Returns the number of objects, which get into the visibility area of the fleet.
7.7.7. IsFleetCanProduce
Define whether the fleet can produce objects of the defined type.
IsFleetCanProduce(who, fleet, tobj);
isFleetCanProduce(fleet, tobj);
_isFleetCanProduce(fleet, tobj);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
tobj - type of produced object (See Remarks for ActFCmdProduction).
Return Value:
Returns TRUE, if the fleet is able to produce the tobj type of object, or FALSE - if not.
7.7.8. GetFleetMassWeaponReady
Get the number of units of weapons of mass destruction, which are ready to strike the defined point.
GetFleetMassWeaponReady(who, fleet, weapon, x, y, z);
getFleetMassWeaponReady(fleet, weapon, x, y, z);
_getFleetMassWeaponReady(fleet, weapon, x, y, z);
Parameters:
who - playing side of the fleet (See Appendix A.)
fleet - fleet number, received by GetFleetNum function.
weapon - type of weapons of mass destruction (WEAPON_LASER_BOMB, WEAPON_THERMO_NUCLEAR_MISSILE, WEAPON_VACUUM_BOMB, WEAPON_SATELLITE_GAS_LASER
x, y, z - target coordinates.
Return Value:
Returns number of units of weapons of mass destruction, which are ready to strike.
8. Actions. Operator <if>
8.1. Actions and Run time operators
Actions are used for the immediate control of a game session from an Events program. Actions are run time operators of the ST AIscript language. Such operators can be placed inside an event in the Events Program.
For the sake of convenient distinction, names for all actions operators begin with the prefix Act(act, _act). Prefix Act is used for action operators only. In macros Act is changed to act, if the action operator is used to affect the playing side of the Events Program from which it is called. The other group of macros intended for action operators are applied to a so-called current player, the side. They are controlled via the game interface. In such macros Act is changed to _act.
All macro definitions are included in the file AiScript.mcr, supplied with the game.
Example:
...
Event(TRUE, 0)
...
8.2. Operator <if>
Operator if is intended to control the order for executing actions in the body of events. It can be expressed in 2 forms:
Shorter:
if(expression)
;
and complete:
if(expression)
else
;
where,
expression - ST AIscript language expression, where the result must be an integer;
ActProc1, ActProc2, ... - operators, which are executed if the result of the expression equals TRUE;
ActProc3, ActProc4, ... - operators, which are executed if the result of the expression is not equal to TRUE;
Example:
....
Event(_GL50)
else
else
}
}
...
8.3. System Actions
These actions are intended to control the parameters of an Events Program and its elements.
8.3.1. ActLockEvent
Prohibit switching off (switch on) events after it happens.
ActLockEvent([timer]);
Parameters:
timer - time in game seconds, after which the event will be switched on.
If timer > 0 - the event will be switched on in timer seconds.
If timer ==0 - the event will be switched on immediately.
Default:
Remarks:
It affects the event in which it is called. It may be placed anywhere in the event body.
8.3.2. ActOnEvent
Make event(s) active.
ActOnEvent(who, who_rel, Id_Beg[, Id_End]);
actOnEvent(Id_Beg[, Id_End]);
_actOnEvent(Id_Beg[, Id_End]);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
Id_Beg - identifier of the first event.
Id_End - identifier of the last event. If not defined it is equal to Id_Beg.
Default: Id_Beg
Remarks:
All events, whose identifiers are within the range Id_Beg to Id_End inclusively, must be in the Events program of the processed side; otherwise an error message will appear.
8.3.3. ActOffEvent
Make event(s) inactive.
ActOffEvent(who, who_rel, Id_Beg[, Id_End, timer]);
actOffEvent(Id_Beg[, Id_End, timer]);
_actOffEvent(Id_Beg[, Id_End, timer]);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
Id_Beg - identifier of the first event.
Id_End - identifier of the last event.
If it is not defined, then it is equal to Id_Beg.
Default: Id_Beg
timer - time in game seconds, after which the event will be switched off.
When if > 0 - the event will be switched off in timer seconds.
When if ==0 - the event will not be switched on.
Default:
Remarks:
All events, whose identifiers are within the range Id_Beg to Id_End inclusively, must be in the Events program of the processed side; otherwise an error message will appear.
8.3.4. ActSetVar
Set value of local variable (_RT..)
ActSetVar(who, who_rel, n, val);
actSetVar(n, val);
_actSetVar(n, val);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
n - number of local variable (0 <= n < AIVARS_NUM).
val - integer value.
Remarks:
Operator actSetVar(n, val) is equivalent to operator _RTn:=val;
8.3.5. ActSetGlobVar
Set value of global variable (_GL).
ActSetGlobVar(n, val);
Parameters:
n - number of global variable (0 <= n < AIVARS_NUM).
val - integer value.
Remarks:
Operator ActSetGlobVar(n, val) is equivalent to operator _GLn:=val;
8.3.6. ActSetParInt
Set value of integer parameter of event (_PI).
ActSetParInt(n, val);
Parameters:
n - number of integer parameter of the event (0 <= n < AIPARINT_NUM)
val - integer value.
Remarks:
Operator ActSetParInt(n, val) is equivalent to operator _PIn:=val;
8.3.6. ActSetParStr
Set value of string parameter of event (_PS)
ActSetParStr(n, val);
Parameters:
n - number of string parameter of the event (0 <= n < AIPARSTR_NUM))
val - value-string.
Remarks:
Operator ActSetParStr(n, val) is equivalent to operator _PSn:=val;
8.4. Timer Actions
Besides the clock that measures game time each playing side has a timer, which counts down time in seconds. Actions described below are intended to control such timers.
8.4.1.ActOnTimer
Switch timer on.
ActOnTimer(who, who_rel, time);
actOnTimer(time);
_actOnTimer(time);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
time - initial timer time in seconds.
Remarks:
After switching on the timer begins time countdown to zero. Note that when the timer counts down to zero it will not be switched off automatically.
8.4.2.ActOffTimer
Switch timer off.
ActOffTimer(who, who_rel);
actOffTimer();
_actOffTimer();
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
8.4.3.ActTimerOnScreen
Display timer on the playing field.
ActTimerOnScreen(who, who_rel, on_off);
actTimerOnScreen(on_off);
_actTimerOnScreen(on_off);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
on_off - When on_off==TRUE - timer is displayed on the playing field. When on_off==FALSE - timer is not displayed on the playing field.
Remarks:
This action affects only the time of the current player.
8.5. Information Actions
These actions are intended to inform the current player.
8.5.1. ActStringMess
Display string message on the screen console.
ActStringMess(who, who_rel, mess);
actStringMess(mess);
_actStringMess(mess);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
mess - message string.
8.5.2. ActStringInfo
Set information line.
ActStringInfo(who, who_rel, hold_time, color, str);
actStringInfo(hold_time, color, str);
_actStringInfo(hold_time, color, str);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
hold_time - time of holding string on the screen in seconds.
color - color of information string (constants ISTR_BLUE, ISTR_RED).
str - information string.
8.5.3. ActOutText
Display text from string resource on the briefing zone of the screen.
ActOutText(who, who_rel, hold_time, st_beg, st_end);
actOutText(hold_time, st_beg, st_end);
_actOutText(hold_time, st_beg, st_end);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
hold_time - time of holding on the screen in seconds
st_beg, st_end - numbers of the first and the last strings of the string resource.
Remarks:
Each string of the string resource will be formatted as a separate paragraph.
8.5.4. ActOutString
Display text on the briefing zone of the screen.
ActOutString(who, who_rel, hold_time, str);
actOutString(hold_time, str);
_actOutString(hold_time, str);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
hold_time - time of holding on the screen in seconds.
str - string.
8.5.5. ActPlaySound
Play sound.
ActPlaySound(who, who_rel, snd_name);
actPlaySound(who, who_rel, snd_name);
_actPlaySound(who, who_rel, snd_name);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
snd_name - string, which contains the name of the sound.
Remarks:
Sound with indicated name must be kept in the media components part of the base of the current mission or in the sound database of the game TASKS.DKD.
8.5.6. ActPlayBriefing
Play briefing.
ActPlayBriefing(who, who_rel, brf_name);
actPlayBriefing(brf_name);
_actPlayBriefing(brf_name);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
brf_name - string, which contains briefing's name.
Remarks:
Briefing with indicated name must be kept in the briefing part of the base of the current mission.
8.6. Visibility Actions
These actions are intended to control Fog of War (FOW) and camera positions. They can be applied only to the current player.
8.6.1. ActOnFOW
Switch FOW on.
ActOnFOW(who, who_rel);
actOnFOW();
_actOnFOW();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.6.2. ActOffFOW
Switch FOW off.
ActOffFOW(who, who_rel);
actOffFOW();
_actOffFOW();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.6.3. ActHoleFOW
Make a visible area in FOW.
ActHoleFOW(who, who_rel, x, y, z, r, time);
actHoleFOW(x, y, z, r, time);
actHoleFOW(x, y, z, r, time);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
r - radius of the visible area.
time - lifetime in game seconds. When time<0 - the area stays forever.
8.6.4. ActSetScreen
Set screen center in map point.
ActSetScreen(who, who_rel, x, y[, mode]);
actSetScreen(x, y[, mode]);
_actSetScreen(x, y[, mode]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
x, y - coordinates of the point on the map where the center of the screen will be placed (the point at which the camera will be centered)
mode - map scrolling mode (constants SCROLL_FAST, SCROLL_SOFT).
Default: SCROLL_FAST
8.6.5. ActSetCamera
Set a camera view.
ActSetCamera(who, who_rel, camera);
actSetCamera(camera);
_actSetCamera(camera);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
camera - camera's number. The following constants are defined for cameras:
CAM_FRONT - central camera (up is North),
CAM_LEFT - left camera (up is East),
CAM_BACK - back camera (up is South),
CAM_RIGHT - right camera (up is West).
8.6.6. ActZoomIn
Zoom in (enlarge objects).
ActZoomIn(who, who_rel);
actZoomIn();
_actZoomIn();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.6.7. ActZoomOut
Zoom out (diminish objects).
ActZoomOut(who, who_rel);
actZoomOut();
_actZoomOut();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.6.8. ActZoomSet
Set camera's zoom out.
ActZoomSet(who, who_rel, step);
actZoomSet(step);
_actZoomSet(step);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
step - cameras zoom out (constants ZOOM_...)
8.6.9. ActShowMapAction
Show event on the Sonar map.
ActShowMapAction(who, who_rel, type, x, y);
actShowMapAction(type, x, y);
_actShowMapAction(type, x, y);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
type - symbol type on the Sonar map (constants RMAP_..).
x, y - coordinates of symbols output.
8.7. Missions management Actions
8.7.1. ActInitPlRC
Set initial amount of resources for player or players dependent on the resources level at the start of the mission.
ActInitPlRC(who, who_rel, lev);
actInitPlRC(lev);
_actInitPlRC(lev);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
lev - resources level for playing sides in the beginning of the mission. (See constants LEVEL_...). When lev==LEVEL_DEFINED the level, which has been defined when the mission was created in the Scenario Editor or selected in the settings panel before the mission start, is used.
8.7.2. ActInitTech
Set initial and maximum technology development level for player or players.
ActInitTech(who, who_rel, start_lev, max_lev);
actInitTech(start_lev, max_lev);
_actInitTech(start_lev, max_lev);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
start_lev - initial technology level, see constants LEVEL_...
max_lev - maximum technology level, see constants LEVEL_...
Remarks:
For lev==LEVEL_DEFINED level, which has been defined when mission was created in the Scenario Editor or selected in the settings panel before the mission start, is used.
Initial technology level defines what technologies will be available (already developed) for a playing side at the mission start.
Maximum technology level defines what technologies will be available for research and which will not for a playing side during the game.
8.7.3. ActInitDisGold
Set the amount of gold dissolved in the water dependent on the level in the beginning of the mission.
ActInitDisGold(lev);
Parameters:
lev - level of density of gold dissolved in the water, see constants LEVEL_... When lev==LEVEL_DEFINED the level, which has been defined when mission was created in the Scenario Editor or selected in the settings panel before the mission start, is used.
8.7.4. ActCreateStartSet
Create starting set of objects for playing side(s) at the start of the mission.
ActCreateStartSet(who, who_rel, lev[, x, y, z]);
actCreateStartSet(lev[, x, y, z]);
_actCreateStartSet(lev[, x, y, z]);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
lev - type of set, see constants LEVEL_...
When lev==LEVEL_DEFINED the type, which has been defined when mission was created in the Scenario Editor or selected in the settings panel before the mission start, is used.
x, y, z - point of creation of the set of objects.
If it is not defined (or defined incorrectly), a place near the players starting position will be selected.
Default:
8.7.5. ActSetPlRC
Set amount of resources for player or players.
ActSetPlRC(who, who_rel, tobj, method, val);
actSetPlRC(tobj, method, val);
_actSetPlRC(tobj, method, val);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
tobj - resource type (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_AIR, TOBJ_SILICON, TOBJ_ENERGY)
method - method of setting ( - is set, < 0 - is decreased, > 0 - is added)
val - set value.
Remarks:
Each of the resources is measured in its own units of measurement.
For TOBJ_AIR val indicates the quantity of produced air. The constant AIRPRODUCT_PER_STATION indicates how much air a single air-extracting structure is producing. Therefore if we add AIRPRODUCT_PER_STATION to a playing side that will be equivalent to building one more air-extracting structure.
For TOBJ_ENERGY val indicates the amount of energy stored by Silicons. The playing side has a limitation on the amount of stored energy, dependent on the number of Replenish Pods. This can be calculated by the formula:
ENERGY_MIN + ENERGY_PER_POD * num_pod
where
ENERGY_MIN, ENERGY_PER_POD - constants defined in AiScript.dfn,
num_pod - the number of Replenish Pods, which the current playing side has at the given moment of time. You cannot add more than this amount of energy.
8.7.6. ActSetDisGold
Set amount of gold dissolved in the water.
ActSetDisGold(method, val);
Parameters:
method - method of setting ( - is set, < 0 - is decreased, > 0 - is added)
val - set value.
Remarks:
The amount of gold dissolved in the water is measured in gold units. The set amount is distributed evenly across the entire map.
8.7.7. ActEndMiss
End mission.
ActEndMiss(who, who_rel, cond);
actEndMiss(cond);
_actEndMiss(cond);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
cond - condition of mission end. The following constants are defined for this:
ENDMISS_NONE - end mission without result,
ENDMISS_ACCOMPL - mission accomplished,
ENDMISS_FAILED - mission failed.
Remarks:
Affects only the current player.
8.7.8. ActNextMiss
Set the name of the next mission.
ActNextMiss(who, who_rel[, next_miss]);
actNextMiss([next_miss]);
_actNextMiss([next_miss]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
next_miss - file name of the next mission or empty string. Empty string signifies that the current mission is the last in the campaign and there will be no additional missions.
Default: empty string.
Remarks:
Affects only the current player and is valid only for campaigns.
8.7.9. ActTotalStatistics
Display final statistics after mission ends.
ActTotalStatistics(who, who_rel, prio[, score]);
actTotalStatistics(prio[, score]);
_actTotalStatistics(prio[, score]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
prio - priority. Priority is an integer number, which affects the order of displaying final statistics, epilog and video. These components are displayed from highest to lowest priority.
If priority equals final statistics are not displayed.
If score<0, the total amount of scores will be calculated based on the statistic data of the playing side.
Default:
Remarks:
Final statistics display is possible for the current player only, though the total score can be set for any playing side.
8.7.10. ActEpilogue
Displays epilog.
ActEpilogue(who, who_rel, prio, name_prg);
actEpilogue(prio, name_prg);
_acEpilogue(prio, name_prg);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
prio - priority. Priority is an integer number, which affects the order of displaying final statistics, epilog and video. These components are displayed in priority from highest to lowest.
If priority equals epilog is not displayed.
name_prg - name of epilog program
Remarks:
Affects only the current player.
Epilog with indicated name in the epilog part of the base of the current mission.
8.7.11. ActVideo
Display video after mission end.
ActVideo(who, who_rel, prio, name_video[, mode, resolution, color, x, y, lx, ly, mode_rect]);
actVideo(prio, name_video[, mode, resolution, color, x, y, lx, ly]);
_actVideo(prio, name_video[, mode, resolution, color, x, y, lx, ly]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
prio - priority. Priority is an integer number, which affects the order of displaying final statistics, epilog and video. These components are displayed in order from highest to lowest priority.
If priority equals video is not displayed.
name_prg - name of video file.
mode - sets the mode of video playback.
Allowed values:
MODE_NORMAL - play video with its normal size,
MODE_WHOLE - play video stretching it on the whole screen,
MODE_RECT - play video in the defined area of the screen.
Default: MODE_NORMAL
resolution - resolution of the screen that is set before video playback.
Allowed values:
MODE_800x600,
MODE_640x480.
Default: MODE_640x480,
color - the color depth of the graphics screen, which is set before video playback.
Allowed values:
MODE_8BIT,
MODE_16BIT,
MODE_24BIT,
Default: MODE_24BIT
x,y,lx,ly - coordinates of the graphics area of the screen, which are used when mode value equals to MODE_RECT.
Default:
mode_rect - additional settings of video playback in the defined area of the screen.
Allowed values:
MODE_NORMAL - play video with its nornal size,
MODE_WHOLE - play video stretching it on the whole screen.
Default: MODE_NORMAL
Remarks:
Affects only the current player.
8.7.12. ActAddObjective
Add string to Objectives
ActAddObjective(who, who_rel, var, str);
actAddObjective(var, str);
_actAddObjective(var, str);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
var - number of local variable (_RT) to save the index of the added string. It can be set within the range from to AIVARS_NUM-1. Local variables of the Events program, in which the action is executed, are used.
str - string.
Remarks:
Affects only the current player.
8.7.13. ActDelObjective
Delete string from Objectives
ActDelObjective(who, who_rel, num);
actDelObjective(num);
_actDelObjective(num);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
num - index of deleted string.
Remarks:
Affects only the current player.
8.7.14. ActClearObjectives
Delete all strings from Objectives.
ActClearObjectives(who, who_rel);
actClearObjectives();
_actClearObjectives();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
Remarks:
Affects only the current player.
8.7.15. ActAddStrRes
Add string to String Table.
ActAddStrRes(who, who_rel, var, str);
actAddStrRes(var, str);
_actAddStrRes(var, str);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
var - number of local variable (_RT) to save the index of the added string. It can be set within the range from to AIVARS_NUM-1. Local variables of the Events program, in which the action is executed, are used.
str - string.
Remarks:
Affects only the current player.
8.7.16. ActDelStrRes
Delete string from String Table
ActDelStrRes(who, who_rel, num);
actDelStrRes(num);
_actDelStrRes(num);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
num - index of deleted string.
Remarks:
Affects only the current player.
8.7.17. ActClearStrRes
Delete all string from String Table.
ActClearStrRes(who, who_rel);
actClearStrRes();
_actClearStrRes();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
Remarks:
Affects only the current player.
8.7.18. ActSetFriend
Set friendly relationship for one player(s) with another
ActSetFriend(who, who_rel, player);
actSetFriend(player);
_actSetFriend(player);
Parameters:
who, who_rel - define the list of playing sides which offer friendship (See Appendix A. and B.)
player - the playing side to which the friendship is offered. (See Appendix A.)
Remarks:
It is valid only for no-team play mode. Objects of the player(s) who offers friendship do not attack the objects of the player to whom the friendship is offered. But if the latter does not set a friendship relationship back to first, his objects may attack the first player's objects even though they do not return fire.
8.7.19. ActSetEnemy
Set enmity for one player(s) with another.
ActSetEnemy(who, who_rel, player);
actSetEnemy(player);
_actSetEnemy(player);
Parameters:
who, who_rel - define the list of playing sides which set enmity (See Appendix A. and B.)
player - the playing side to which the enmity is set. (See Appendix A.)
Remarks:
It is valid only for no-team play mode.
8.7.20. ActSetTeam
Set team number to player(s).
ActSetTeam(who, who_rel, team);
actSetTeam(team);
_actSetTeam(team);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
team - team number (See Appendix E.)
Remarks:
It is valid for the team play mode only.
8.7.21. ActLockInterface
Disable commands from the game interface (switch interface off).
ActLockInterface(who, who_rel);
actLockInterface();
_actLockInterface();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
Remarks:
Affects only the current player.
8.7.22. ActUnLockInterface
Enable commands from the game interface (switch interface on).
ActUnLockInterface(who, who_rel);
actUnLockInterface();
_actUnLockInterface();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
Remarks:
Affects only the current player.
8.7.23. ActSetShareVis
Switch ally visibility on/off.
ActSetShareVis(on);
Parameters:
on - switch.
If on == TRUE - switch ally visibility on.
If on == FALSE - switch ally visibility off.
8.7.24. ActSetSiliconPerCell
Set amount of silicon in a cell on the bottom of the landscape.
ActSetSiliconPerCell(silicon[, x, y, lx, ly])
Parameters:
silicon - the amount of silicon in the cell.
x, y, lx, ly - zone of bottom of landscape, to which cells the amount silicon will be set
If zone is not defined the amount of silicon will be set on the entire map.
Default:
8.7.25. ActSaveMission
Make mission autosave.
ActSaveMission();
8.8. Objects Manipulation Actions
8.8.1. ActSetName
Set name for the object which is situated at the indicated coordinates.
ActSetName(name, x, y, z[, lev=0]);
Parameters:
name - proper name of the object (no more than 14 symbols)
x, y, z - object's coordinates.
lev - cell level:
lev == 0 - for player's objects, artifacts, containers,
lev == 1 - for mines,
lev == 2 - for Destination.
Remarks:
1. It does not generate an error message if the object is not found at the indicated coordinates.
2. If in the cell lev==0 there are 2 objects (CargoSub or TranSub with cargo), the name will be given to the CargoSub or TranSub.
8.8.2. ActCreatePlObj
Create an object for Player(s).
ActCreatePlObj(who, who_rel, tobj[, x, y, z, logo, name, nflt, life, eff, par0, par1, ...]);
actCreatePlObj(tobj[, x, y, z, logo, name, nflt, life, eff, par0, par1, ...]); _actCreatePlObj(tobj[, x, y, z, logo, name, nflt, life, eff, par0, par1, ...]);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
tobj - type of the created object, see constants TOBJ_...
x, y, z - point of objects creation. If it is not defined (or defined improperly, for example, ), then a place near the player's start position will be chosen.
Default:
logo - color of objects logo (See Appendix C.)
Default: LOGO_UNDEF
name - proper name of the object (no more than 14 symbols). Default: empty string.
nflt - number of fleet.
When nflt>0 - create the object in an already existing fleet.
When nflt=0 - create the object outside of existing fleets and make it selected.
When nflt<0 - create the object outside of existing fleets and do not select it.
Default:
life - life level in percent (0<life<=100).
Default:
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
par0, par1, ... - additional parameters for the created object.
Default:
Remarks:
Additional parameters are used for:
- submarines, which carry resources:
par0 - corium in percentage of full capacity.
par1 - metal in percentage of full capacity.
- structures:
par0 == 1 - begin the process of construction. In this case time and resources will be spent. In general cases this process may be not completed.
par0 == 0 - object will be created immediately without costing time or resources.
8.8.3. ActDelPlObjEx
Delete player(s) objects.
ActDelPlObjEx(who, who_rel[, group_obj, tobj, logo, name, x, y, z, lx, ly, lz, eff]);
actDelPlObjEx([group_obj, tobj, logo, name, x, y, z, lx, ly, lz, eff]); _actDelPlObjEx([group_obj, tobj, logo, name, x, y, z, lx, ly, lz, eff]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
group_obj - groups of types of deleted objects see Appendix H.
If group_obj == AITRG_ALL, then objects of any type will be deleted.
Default: AITRG_ALL
tobj - type of deleted objects (See TOBJ_...) or TOBJ_UNDEFINED.
When tobj==TOBJ_UNDEFINED - type is of no importance and objects of any type will be deleted.
Default: TOBJ_UNDEFINED
logo - logo of deleted objects (See Appendix C.).
When logo==LOGO_UNDEF - objects with any logo are deleted.
Default: LOGO_UNDEF
name - proper name of the object (no more than 14 symbols)
If name is not indicated objects with any name are deleted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped, in which objects will be deleted.
If zone is not defined objects are deleted from the entire map.
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
Remarks:
Priority of filters in descending order:
- tobj
- group_obj
- name
- logo
- x, y, z, lx, ly, lz
8.8.4. ActDelPlObjS
Delete all SELECTED player objects.
ActDelPlObjS(who, who_rel[, eff]);
actDelPlObjS([eff]);
_actDelPlObjS([eff]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
Remarks:
To select playing sides objects, actions ActObjSelectT, ActObjSelectM and ActObjSelectN are used.
8.8.5. ActObjSelectT
Select player objects by their type.
ActObjSelectT(who, who_rel, tobj[, logo, x, y, z, lx, ly, lz]);
actObjSelectT(tobj[, logo, x, y, z, lx, ly, lz]);
_actObjSelectT(tobj[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tobj - type of player objects, see constants TOBJ_...
If tobj == TOBJ_UNDEFINED, then objects of any type will be selected.
logo - logo of selected objects, see Appendix A.
If logo == LOGO_UNDEF, then objects with any logo will be selected.
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped in which objects will be selected.
If zone is not defined (lx=ly=lz=-1) objects will be selected on the entire map.
Default:
Remarks:
Players objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects or terrain features are not players objects.
8.8.6. ActObjSelectM
Select player objects by groups.
ActObjSelectM(who, who_rel, group_obj[, logo ,x, y, z, lx, ly, lz]);
actObjSelectM(group_obj[, logo, x, y, z, lx, ly, lz]);
_actObjSelectM(group_obj[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
group_obj - types of groups of player selected objects, see Appendix H.
If group_obj == AITRG_ALL, objects of any type will be counted.
logo - logo of selected objects, see Appendix A.
If logo == LOGO_UNDEF, then objects with any logo will be selected
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped in which objects will be selected.
If zone is not defined (lx=ly=lz=-1), then objects will be selected on the entire map.
Default:
Remarks:
Players objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects or terrain features are not players objects.
8.8.7. ActObjSelectN
Select player objects by name.
ActObjSelectN(who, who_rel, name[, logo ,x, y, z, lx, ly, lz]);
actObjSelectN(name[, logo, x, y, z, lx, ly, lz]);
_actObjSelectN(name[, logo, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
name - proper name of the object(s) (no more than 14 symbols).
If name is empty, then objects with any name will be counted.
logo - logo of selected objects, see Appendix A.
If logo == LOGO_UNDEF, then objects with any logo will be selected
Default: LOGO_UNDEF.
x, y, z, lx, ly, lz - zone parallelepiped in which objects will be selected.
If zone is not defined (lx=ly=lz=-1) objects will be selected on the entire map.
Default:
Remarks:
Players objects are subs (including cyborgs) and structures. Resource deposits, mines, containers with resources, artifacts, sea animals, silicon prototypes and other objects or terrain features are not players objects.
8.8.8. ActCreateRCCont
Create player container(s) with resources.
ActCreateRCCont(who, who_rel, tres, x, y, z, vol[, name, eff]);
actCreateRCCont(tres, x, y, z, vol[, name, eff]);
_actCreateRCCont(tres, x, y, z, vol[, name, eff]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tres - resource type in the container (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON)
x, y, z - point of creation on the map.
vol - amount of resource in the container.
name - proper name container (no more than 14 symbols) or empty string.
Default: empty string.
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
Remarks:
When a container is created resources for its production are not deducted from the playing side for which it was created.
8.8.9. ActDelRCCont
Delete player container(s) with resources.
ActDelRCCont(who, who_rel[, tres, name, x, y, z, lx, ly, lz, eff]);
actDelRCCont([tres, name, x, y, z, lx, ly, lz, eff]);
_actDelRCCont([tres, name, x, y, z, lx, ly, lz, eff]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tres - resource type in the container or TOBJ_UNDEFINED.
When tres=TOBJ_UNDEFINED, then players containers with any resource will be deleted.
Default: TOBJ_UNDEFINED
name - proper name of container (no more than 14 symbols) or empty string.
If name is not indicated, then containers with any name will be deleted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped in which containers will be deleted.
If zone is not defined containers will be deleted from the entire map.
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
8.8.10. ActCreateArt
Create artifact.
ActCreateArt(tart, shell, x, y, z[, name, text, eff]);
Parameters:
tart - type of artifact (See Appendix K.)
shell - type of shell (CIV_BO, CIV_WS, CIV_SI).
x, y, z - point of creation.
name - proper name of artifact (no more than 14 symbols) or empty string.
Default: empty string.
text - text information about artifact or empty string.
Default: empty string.
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
8.8.11. ActDelArt
Delete artifact(s).
ActDelArt([tart, name, x, y, z, lx, ly, lz, eff]);
Parameters:
tart - type of artifact or TART_UNDEFINED.
When tart=TART_UNDEFINED, then artifacts of any type will be deleted.
Default: TOBJ_UNDEFINED
name - proper name of artifact (no more than 14 symbols) or empty string.
If name is not defined, then artifacts with any name will be deleted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped in which artifacts will be deleted.
If zone is not defined, then artifacts will be deleted from the entire map.
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
8.8.12. ActSetArtText
Set new text information to artifact.
ActSetArtText(name, text);
Parameters:
name - proper name of artifact (no more than 14 symbols).
text - new text information.
Remarks:
If artifact with the name name is not found, error message is not generated.
If there are several artifacts with the name name, then the text information will be given to the first found.
8.8.13. ActCreateRCField
Create a resource deposit.
ActCreateRCField(tobj, x, y, z[, vol, eff]);
Parameters:
tobj - type of created resource deposit (TOBJ_CORIUM, TOBJ_METAL).
x, y, z - point of creation of resource deposit.
vol - volume of resource deposit.
Default:
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
Remarks:
If the point of the resource deposit creation is indicated incorrectly, the Events program executor will try to find the nearest acceptable point. If it cannot find such a point, it will generate an error message.
8.8.14. ActDelRCField
Delete resource deposits.
ActDelRCField([tobj, x, y, z, lx, ly, lz, eff]);
Parameters:
tobj - type of resource deposits to be deleted (TOBJ__UNDEFINED, TOBJ_CORIUM, TOBJ_METAL).
If tobj=TOBJ_UNDEFINED, any resource deposits will be deleted.
Default: TOBJ_UNDEFINED
x, y, z, lx, ly, lz - zone parallelepiped in which resource deposits will be deleted.
If zone is not defined, then artifacts will be deleted from the entire map.
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
8.8.15. ActSetRCFieldVol
Set volume of resource deposit.
ActSetRCFieldVol(method, val[, tobj, x, y, z, lx, ly, lz]);
Parameters:
method - method of setting ( - is set, < 0 - is deducted, > 0 - is added)
val - set value.
tobj - type of processed resource deposits (TOBJ__UNDEFINED, TOBJ_CORIUM, TOBJ_METAL)
If tobj=TOBJ_UNDEFINED, any type of resource deposits will be processed.
Default: TOBJ_UNDEFINED
x, y, z, lx, ly, lz - zone parallelepiped in which resource deposits will be processed
If zone is not defined then resource deposits will be processed on the entire map.
Default:
8.8.16. ActCreateDest
Create Destination.
ActCreateDest(tdst, logo, x, y, z[, name, text, eff]);
Parameters:
tdst - type of Destination (See TDST_...)
logo - logo color of Destination (See Appendix C.)
x, y, z - point of creation of Destination
name - proper name of Destination (no more than 14 symbols) or empty string.
Default: empty string.
text - text information or empty string.
Default: empty string.
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
Remarks:
If point of Destination is set incorrectly, an error messages is generated.
8.8.17. ActDelDest
Delete Destination(s).
ActDelDest([logo, name, x, y, z, lx, ly, lz, eff]);
Parameters:
logo - logo of Destination or LOGO_UNDEF.
If logo == LOGO_UNDEF Destinations with any logo will be deleted.
Default: LOGO_UNDEF.
name - proper name of Destination (no more than 14 symbols) or empty string.
If name is not defined then Destinations with any name will be deleted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped in which Destinations will be deleted.
If zone is not defined, then Destination will be deleted from the entire map.
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
8.8.18. ActSetDestText
Set text information to Destination.
ActSetDestText(name, text);
Parameters:
name - proper name of Destination (no more than 14 symbols)
text - new text information.
Remarks:
If Destination with the name name is not found, an error message is not generated.
If there are several Destinations with the name name, then the new text information will be set only to the first found.
8.8.19. ActCreateMine
Create mine(s).
ActCreateMine(who, who_rel, tobj, x, y, z[, logo, name, eff, par]);
actCreateMine(tobj, x, y, z[, logo, name, eff, par]);
_actCreateMine(tobj, x, y, z[, logo, name, eff, par]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tobj - type of mine (TOBJ_MINE_DEPTH, TOBJ_MINE_SNARE, TOBJ_ACOUSTIC_MINE, TOBJ_BEACON).
x, y, z - point of mines creation.
If the point is indicated incorrectly, then the nearest acceptable point will be chosen.
logo - logo color of mine (See Appendix C.)
Default: LOGO_UNDEF
name - proper name of mine (no more than 14 symbols).
Default: empty string.
par - additional parameters.
Default:
eff - effect in the moment of creation (see VEFF_...)
Default: VEFF_NONE
Remarks:
If TOBJ_ACOUSTIC_MINE par defines the type of targets, see constants EXPL_IF_...
8.8.20. ActDelMine
Delete mine(s).
ActDelMine(who, who_rel[, tmine, logo, name, x, y, z, lx, ly, lz, eff]);
actDelMine([tmine, logo, name, x, y, z, lx, ly, lz, eff]);
_actDelMine([tmine, logo, name, x, y, z, lx, ly, lz, eff]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tmine - type of mines (TOBJ_MINE_DEPTH, TOBJ_MINE_SNARE, TOBJ_ACOUSTIC_MINE, TOBJ_BEACON) or TOBJ_UNDEFINED.
When tmine == TOBJ_UNDEFINED, then player mines of any type will be deleted.
Default: TOBJ_UNDEFINED
logo - logo of mine or LOGO_UNDEF.
If logo == LOGO_UNDEF, then mines with any logo will be deleted.
Default: LOGO_UNDEF
name - proper name of mine (no more than 14 symbols) or empty string.
If name is not defined, then mines with any name will be deleted.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped in which mines will be deleted.
If zone is not defined, then mines will be deleted from the entire map
Default:
eff - effect in the moment of deletion (see VEFF_...)
Default: VEFF_NONE
8.8.21. ActSetParMine
Set parameters to mines.
ActSetParMine(who, who_rel, par[, tmine, logo, name, x, y, z, lx, ly, lz]);
actSetParMine(par[, tmine, logo, name, x, y, z, lx, ly, lz]);
_actSetParMine(par[, tmine, logo, name, x, y, z, lx, ly, lz]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
par - parameters:
For TOBJ_ACOUSTIC_MINE, see constants EXPL_IF_...
For the rest it is not used
tmine - type of mines (TOBJ_MINE_DEPTH, TOBJ_MINE_SNARE, TOBJ_ACOUSTIC_MINE, TOBJ_BEACON) or TOBJ_UNDEFINED.
When tmine=TOBJ_UNDEFINED, parameters will be set to player mines of all types.
Default: TOBJ_UNDEFINED
logo - logo of mine or LOGO_UNDEF.
If logo == LOGO_UNDEF, parameters will be set to mines with any logo.
Default: LOGO_UNDEF
name - proper name of mine (no more than 14 symbols) or empty string.
If name is not defined then parameters will be set to mines with any name.
Default: empty string.
x, y, z, lx, ly, lz - zone parallelepiped in which parameters will be set to mines.
If zone is not defined, then parameters will be set to mines on the entire map.
Default:
8.9. Technology Actions
8.9.1. ActTechDevDisable
Prohibit development of technologies beginning from the level lev of technology tech.
ActTechDevDisable(who, who_rel, tech[, lev]);
actTechDevDisable(tech[, lev]);
_actTechDevDisable(tech[, lev]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tech - technology, see constants TTECH...
lev - level, see constants TTECH_LEV...
Default: TTECH_LEV1
8.9.2. ActTechDevDisableAll
Prohibit development of ALL technologies.
ActTechDevDisableAll(who, who_rel);
actTechDevDisableAll();
_actTechDevDisableAll();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.9.3. ActTechDevEnable
Allow development of technologies beginning from the level lev of technology tech.
ActTechDevEnable(who, who_rel, tech[, lev]);
actTechDevEnable(tech[, lev]);
_actTechDevEnable(tech[, lev]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tech - technology, see constants TTECH...
lev - level, see constants TTECH_LEV...
Default: TTECH_LEV1
8.9.4. ActTechDevEnableAll
Allow development of ALL technologies.
ActTechDevEnableAll(who, who_rel);
actTechDevEnableAll();
_actTechDevEnableAll();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.9.5. ActTechDevRun
Start technology development.
ActTechDevRun(who, who_rel, tech[, lev, prio]);
actTechDevRun(tech[, lev, prio]);
_actTechDevRun(tech[, lev, prio]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tech - technology, see constants TTECH...
lev - level, see constants TTECH_LEV...
Default: TTECH_LEV1
prio - priority . The priority affects the order for processing commands to develop technologies.
Default:
Remarks:
Execution of this action consists of giving the command to the Strategist that will try to develop the technology. Note that the Strategist requires certain conditions, for example, availability of a certain structure, certain amount of resources, certain technology development level, and so on, on which development a particular technology depends.
8.9.6. ActTechSet
Set technology.
ActTechSet(who, who_rel, tech[, lev]);
actTechSet(tech[, lev]);
_actTechSet(tech[, lev]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tech - technology, see constants TTECH...
lev - level, see constants TTECH_LEV...
Default: TTECH_LEV1
Remarks:
The technology is set immediately without requiring any game conditions, resource expenses and development of previous technologies on which it depends
8.9.7. ActTechSetDepend
Set all technologies necessary to develop the given one.
ActTechSetDepend(who, who_rel, tech[, lev, include]);
actTechSetDepend(tech[, lev, include]);
_actTechSetDepend(tech[, lev, include]);
Parameters:
who, who_rel - define the list of playing sides, for which the action will be performed (See Appendix A. and B.)
tech - technology, see constants TTECH...
lev - level, see constants TTECH_LEV...
Default: TTECH_LEV1
include - inclusively(TRUE)/exclusively(FALSE)
Default: FALSE
Remarks:
The technologies are set immediately without requiring any game conditions and without resource expenses.
8.9.8. ActTechSetAll
Set all technologies.
ActTechSetAll(who, who_rel);
actTechSetAll();
_actTechSetAll();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
Remarks:
The technologies are set immediately without requiring any game conditions and without resource expenses.
8.9.9. ActTScenDevRun
Set technology development by scenario.
ActTScenDevRun(who, who_rel, tscen[, prio]);
actTScenDevRun(tscen[, prio]);
_actTScenDevRun(tscen[, prio]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tscen - scenario, see constants TECH_SCENARIO_...
prio - priority (1..100). The priority affects the order for processing commands to develop technologies.
Default:
Remarks:
Execution of this action consists of giving the command to the Strategist that will try to develop the technology. Note that the Strategist requires certain conditions, for example, availability of a certain structure, certain amount of resources, certain technology development level, and so on, on which development a particular technology depends.
8.9.10. ActTScenDevStop
Stop technology development by scenario.
ActTScenDevStop(who, who_rel);
actTScenDevStop();
_actTScenDevStop();
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
8.9.11. ActBldObj
Allow/prohibit building an object.
ActBldObj(who, who_rel, tobj, on);
actBldObj(tobj, on);
_actBldObj(tobj, on);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
tobj - player's type of object, see constants TOBJ_...
on - switch.
When on == TRUE - allow building an object,
When on == FALSE - prohibit building an object.
Remarks:
Setting this event may be altered by game conditions. For example, the prohibition to build objects of a certain type can be aborted after the development of the technology that allows building such objects.
8.10. Strategist Actions
8.10.1. ActSParMainEnemy
Change parameters for setting the main enemy.
ActSParMainEnemy(who, who_rel, can, enemy);
actSParMainEnemy(can, enemy);
_actSParMainEnemy(can, enemy);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
can - ability to change the main enemy during the game. The following constants are used for this parameter:
AICAN_NOT - Strategist cannot change the main enemy,
AICAN_MYSELF - Strategist can change the main enemy by itself.
enemy - side of enemy player. Constants described in Appendix A. are used for this parameter.
Remarks:
Parameters for setting the main enemy are also defined by operator MainEnemy when the Strategist is created.
8.10.2. ActSParOffensiveStroke
Change parameters of Offensive.
ActSParOffensiveStroke(who, who_rel, can, min_boats, max_boats, balance[, mode]);
actSParOffensiveStroke(can, min_boats, max_boats, balance[, mode]);
_actSParOffensiveStroke(can, min_boats, max_boats, balance[, mode]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
can - ability to organize an offensive.
The following constants are used for this parameter:
AICAN_NOT - Strategist does not organize an offensive,
AICAN_MYSELF - Strategist organizes an offensive.
min_boats - minimum number of subs necessary to begin an offensive.
max_boats - number of subs when offensive begins independent of the balance of power.
balance - balance of power, higher than that which the Strategist is allowed to start an offensive.
Balance of power is a quotient of player's power to the power of the Main Enemy, which is measured in percentage points. For example,
100 - powers are equal,
80 - player is weaker than enemy (power is less),
120 - player is stronger than enemy (power is greater)
mode - additional characteristics of offensive. (not used in this version.)
Remarks:
Parameters of offensive are also defined by operator OffensiveStroke when Strategist is created.
8.11. Tactician Actions
8.11.1 ActExecTactic
Execute Tactician.
ActExecTactic(who, who_rel, title[, x, y, z]);
actExecTactic(title[, x, y, z]);
_actExecTactic(title[, x, y, z]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
title - name of executed Tactician.
x, y, z - point of Tactician's start.
If coordinates of the executed Tactician are not indicated (or indicated incorrectly), Strategist will select the point of Tactician's start by itself.
Default:
Remarks:
The launched Tactician takes under its control (distributes between its Fleets) only SELECTED objects. Procedures ActObjSelectT, ActObjSelectM and ActObjSelectN are intended to select objects and can be used before the Tactician's start. It must be noted that if objects are already under other Tacticians' control then after being selected they will remain uncontrolled until the start of another Tactician or a human player (if there is one) takes them under control.
8.12. Fleet Actions
8.12.1. ActCreateFleet
Create Fleet.
ActCreateFleet(who, who_rel, title, civ, behav[, prio, logo, enemy]);
actCreateFleet(title, civ, behav[, prio, logo, enemy]);
_actCreateFleet(title, civ, behav[, prio, logo, enemy]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
title - string name of Fleet. Only the first 63 symbols are significant in title, the rest are ignored.
civ - civilization of the Fleet. The following constants are defined for this parameter:
CIV_BO - for Black Octopi,
CIV_WS - for White Sharks,
CIV_SI - for Silicons.
behav - type of Fleet. It defines the main mission of the Fleet. Constants described in Appendix F are defined for this parameter.
prio - priority. Priority affects the distribution of objects between fleets and on the priority of fleets' orders to produce required objects. Priority is set within the range from 0 to 19 (PRIO_FLT-1).
Default: PRIO_FLT/2 (10).
logo - logo color of fleet objects. Objects produced for the given fleet will get the indicated logo color (if other logo color is not indicated in the vacancy description of produced object).
Constants to define logo colors are described in Appendix C.
Default: LOGO_DEFAULT.
enemy - number of enemy player, see Appendix A. It is used to select targets in attack.
Default: PLAYER_ALL - enemy is not defined.
Remarks:
Parameters civ, behav, prio, logo are defined once and forever and cannot be changed. Parameter enemy can be changed, if fleet is linked to a Tactician.
In the moment of its creation fleet takes selected objects (if they match by type) under its control. If a human player controls the playing side, the fleet will be available for control through the game interface.
8.12.2. ActDelFleet
Delete Fleet.
ActDelFleet(who, who_rel, fleet);
actDelFleet(fleet);
_actDelFleet(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
Remarks:
Fleet objects become selected.
8.12.3. ActSelectFleet
Exclude all objects from Fleet.
ActSelectFleet(who, who_rel, fleet);
actSelectFleet(fleet);
_actSelectFleet(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
Remarks:
Fleet objects become selected.
8.12.4. ActAddFleet
Add selected objects to Fleet.
ActAddFleet(who, who_rel, fleet);
actAddFleet(fleet);
_actAddFleet(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
8.12.5. ActLockFleet
Switch off some properties of fleet objects.
ActLockFleet(who, who_rel, fleet, flags);
actLockFleet(fleet, flags);
_actLockFleet(fleet, flags);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
flags - flags of properties, see Appendix M.
8.12.6. ActUnLockFleet
Switch on some properties of fleet objects.
ActUnLockFleet(who, who_rel, fleet, flags);
actUnLockFleet(fleet, flags);
_actUnLockFleet(fleet, flags);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
flags - flags of properties, see Appendix M.
8.12.7. ActLinkFleet
Add fleet to Tactician.
ActLinkFleet(who, who_rel, fleet, tact_title);
actLinkFleet(fleet, tact_title);
_actLinkFleet(fleet, tact_title);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
tact_title - string name of Tactician (63 significant symbols).
Remarks:
Tactician must be launched (ActExecTactic). If Tactician with the name tact_title is not found, an error message is generated.
8.12.8. ActLinkFleet
Detach fleet from Tactician.
ActUnLinkFleet(who, who_rel, fleet);
actUnLinkFleet(fleet);
_actUnLinkFleet(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
8.12.9. ActFParPutInStaff
Add vacancy.
ActFParPutInStaff(who, who_rel, fleet, tobj1[, tobj2, tobj3, prio, x, y, z, logo, name]);
actFParPutInStaff(fleet, tobj1[, tobj2, tobj3, prio, x, y, z, logo, name]);
_actFParPutInStaff(fleet, tobj1[, tobj2, tobj3, prio, x, y, z, logo, name]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in PutInStaff.
8.12.10. ActFParCleanStaff
Delete all vacancies.
ActFParCleanStaff(who, who_rel, fleet);
actFParCleanStaff(fleet);
actFParCleanStaff(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
8.12.11. ActFParCanChangeStaff
Alter the ability to change vacancies independently.
ActFParCanChangeStaff(who, who_rel, fleet, can);
actFParCanChangeStaff(fleet, can);
_actFParCanChangeStaff(fleet, can);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in CanChangeStaff.
8.12.12. ActFParRepairStaff
Change parameters of fleet objects' repair.
ActFParRepairStaff(who, who_rel, fleet, can[, life, min_obj, states, types]);
actFParRepairStaff(fleet, can[, life, min_obj, states, types]);
_actFParRepairStaff(fleet, can[, life, min_obj, states, types]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in RepairStaff.
8.12.13. ActFParHomePosition
Set basic fleet position.
ActFParHomePosition(who, who_rel, fleet, can[, x, y, z, mode, time, form_type, form_size, form_dir]);
actFParHomePosition(fleet, can[, x, y, z, mode, time, form_type, form_size, form_dir]);
_actFParHomePosition(fleet, can[, x, y, z, mode, time, form_type, form_size, form_dir]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in HomePosition.
8.12.14. ActFParGatherRC
Change parameters for collecting resources.
ActFParGatherRC(who, who_rel, fleet, can[, main_rc, time]);
actFParGatherRC(fleet, can[, main_rc, time]);
_actFParGatherRC(fleet, can[, main_rc, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in GatherRC.
8.12.15. ActFParPatrol
Change parameters for patrolling.
ActFParPatrol(who, who_rel, fleet, can[, mode, time]);
actFParPatrol(fleet, can[, mode, time]);
_actFParPatrol(fleet, can[, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet- fleet number, received by GetFleetNum function.
The rest of the parameters are just like in Patrol.
8.12.16. ActFParSetPatrolPoint
Add a patrol point for a fleet.
ActFParSetPatrolPoint(who, who_rel, fleet, x, y, z[,mode, time, form_type, form_size, form_dir]);
actFParSetPatrolPoint(fleet, x, y, z[, mode, time, form_type, form_size, form_dir]);
_actFParSetPatrolPoint(fleet, x, y, z[, mode, time, form_type, form_size, form_dir]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet- fleet number, received by GetFleetNum function.
The rest of the parameters are just like in SetPatrolPoint.
8.12.17. ActFParCleanPatrolPoints
Delete all patrol points for a fleet.
ActFParCleanPatrolPoints(who, who_rel, fleet);
actFParCleanPatrolPoints(fleet);
_actFParCleanPatrolPoints(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
8.12.18. ActFParRaid
Change parameters for a raid.
ActFParRaid(who, who_rel, fleet, can[, targets, boat_start, boat_finish, mode, time, time_out]);
actFParRaid(fleet, can[, targets, boat_start, boat_finish, mode, time, time_out]);
_actFParRaid(fleet, can[, targets, boat_start, boat_finish, mode, time, time_out]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet- fleet number, received by GetFleetNum function.
The rest of the parameters are just like in Raid.
8.12.19. ActFParOffensive
Change parameters for the participation in an offensive.
ActFParOffensive(who, who_rel, fleet, can[, targets, boat_start, boat_finish, time]);
actFParOffensive(fleet, can[, targets, boat_start, boat_finish, time]);
_actFParOffensive(fleet, can[, targets, boat_start, boat_finish, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in Offensive.
8.12.20. ActFParGuardZones
Change parameters for zone protection.
ActFParGuardZones(who, who_rel, fleet, can[, targets, boat_start, boat_finish, time]);
actFParGuardZones(fleet, can[, targets, boat_start, boat_finish, time]);
_actFParGuardZones(fleet, can[, targets, boat_start, boat_finish, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in GuardZones.
8.12.21. ActFParSetZone
Add a zone to protect to a fleet.
ActFParSetZone(who, who_rel, fleet, x, y, z, lx, ly, lz);
actFParSetZone(fleet, x, y, z, lx, ly, lz);
_actFParSetZone(fleet, x, y, z, lx, ly, lz);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in SetZone.
8.12.22. ActFParCleanZones
Delete all zones to protect from a fleet.
ActFParCleanZones(who, who_rel, fleet);
actFParCleanZones(fleet);
_actFParCleanZones(fleet);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
8.12.23. ActFParHelp
Change parameters for help.
ActFParHelp(who, who_rel, fleet, can[, fleets, boat_start, boat_finish, mode, time]);
actFParHelp(fleet, can[, fleets, boat_start, boat_finish, mode, time]);
_actFParHelp(fleet, can[, fleets, boat_start, boat_finish, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet- fleet number, received by GetFleetNum function.
The rest of the parameters are just like in Help.
8.12.24. ActFParBuild
Change parameters for building objects.
ActFParBuild(who, who_rel, fleet, can[, group_obj]);
actFParBuild(fleet, can[, group_obj]);
_actFParBuild(fleet, can[, group_obj]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
The rest of the parameters are just like in Build.
8.13. Direct commands to Actions Fleets
8.13.1. ActFCmdMove
Command to fleet to move to a point.
ActFCmdMove(who, who_rel, fleet, x, y, z[, mode, time, form_type, form_size, form_dir]);
actFCmdMove(fleet, x, y, z[, mode, time, form_type, form_size, form_dir]);
_actFCmdMove(fleet, x, y, z[, mode, time, form_type, form_size, form_dir]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
x, y, z - destination point.
mode - mode of movement (is not used so far)
time - maximum time before execution.
Default:
form_type - formation type, see Appendix I.
Default: FORMATION_DEFAULT
form_size - formation size from FORMATION_MIN_SIZE to FORMATION_MAX_SIZE, see Appendix I.
Default:
form_dir - Direction of formation is set in degrees from 0 to 360. Angle is measured from the positive direction of axis X counterclockwise. The axis X coincides with the northeast border of the map. For the convenience of setting direction, constants are defined in AiScript.dfn described in Appendix I.
Default:
Remarks:
Is executed by submarine fleet only.
8.13.2. ActFCmdAttackT
Command to fleet to attack targets.
ActFCmdAttackT(who, who_rel, fleet[, enemy, group_obj, tobj, logo, name, boat_finish, mode, time]);
actFCmdAttackT(fleet[, enemy, group_obj, tobj, logo, name, boat_finish, mode, time]);
_actFCmdAttackT(fleet[, enemy, group_obj, tobj, logo, name, boat_finish, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
enemy - number of enemy-player (see Appendix A.)
If enemy==PLAYER_ALL targets defined in fleet are selected.
Default: PLAYER_ALL
group_obj - groups of target types, see Appendix H.
If group_obj == AITRG_ALL, targets of any type are selected.
Default: AITRG_ALL
tobj - type of targets, see constants TOBJ_...
If tobj == TOBJ_UNDEFINED, targets of any type are selected.
Default: TOBJ_UNDEFINED
logo - logo of targets, see Appendix A.
If logo == LOGO_UNDEF, targets with any logo are selected.
Default: LOGO_UNDEF.
name - proper name of target(s) (no more than 14 symbols).
If name is not defined, targets with any name are selected.
Default: empty name
boat_finish - number of subs remaining when attack ends.
Default:
mode - mode and direction of attack (See Appendix J.)
Default: AIATTACK_UNDEF | AIADIR_UNDEF
time - maximum time to attack.
If time==0 - time is unlimited.
Default:
Remarks:
Is executed by a fleet, which contains military submarines
2. If enemy==PLAYER_ALL targets defined in Fleet are selected. If the Fleet is linked to a Tactician then the enemy of the Fleet is set equal to the main enemy of the playing side (see MainEnemy). If the Fleet is not linked to a Tactician, then its main enemy is set when it is created by the operator ActCreateFleet. On the whole if enemy==PLAYER_ALL and the enemy of the Fleet is also equal to PLAYER_ALL, the Fleet will not be able to find a target to attack and the attack will not be executed (an error message is not generated).
8.13.3. ActFCmdAttackZ
Command to fleet to attack zone.
ActFCmdAttackZ(who, who_rel, fleet, x, y, z, lx, ly, lz[, boat_finish, mode, time]);
actFCmdAttackZ(fleet, x, y, z, lx, ly, lz[, boat_finish, mode, time]);
_actFCmdAttackZ(fleet, x, y, z, lx, ly, lz[, boat_finish, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
x, y, z, lx, ly, lz - zone parallelepiped.
boat_finish - number of subs remaining when attack ends.
Default:
mode - mode and direction of the attack (See Appendix J.)
Default: AIATTACK_UNDEF | AIADIR_UNDEF
time - maximum time to attack. If time==0 - time is unlimited.
Default:
Remarks:
Is executed by a fleet, which contains military submarines
8.13.4. ActFCmdGuardF
Command to fleet to protect another fleet.
ActFCmdGuardF(who, who_rel, fleet_guard, fleet_ward[, boat_finish, mode, time]);
actFCmdGuardF(fleet_guard, fleet_ward[, boat_finish, mode, time]);
_actFCmdGuardF(fleet_guard, fleet_ward[, boat_finish, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet_guard - number of guardian fleets received by function GetFleetNum.
fleet_ward - number of the fleet to protect received by function GetFleetNum.
boat_finish - number of subs remaining, when protection ends.
Default:
time - maximum time for protection.
If time==0 - time is unlimited.
Default:
Remarks:
Is executed by a fleet, which contains military submarines
8.13.5. ActFCmdGatherRC
Command to fleet to collect a resource.
ActFCmdGatherRC(who, who_rel, fleet, type_rc[, x, y, z, lx, ly, lz, mode, time]);
actFCmdGatherRC(fleet, type_rc[, x, y, z, lx, ly, lz, mode, time]);
_actCmdFGatherRC(fleet, type_rc[, x, y, z, lx, ly, lz, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - number of the fleet, received by function GetFleetNum.
type_rc - type of collected resource:
For WS and BO - TOBJ_CORIUM, TOBJ_METAL
For SI - TOBJ_CORIUM
x, y, z, lx, ly, lz - zone parallelepiped, in which the resource will be collected from deposits.
If zone is not defined ((lx=ly=lz=-1) then the resource is extracted from all mines on the entire map.
Default:
mode - is not used so far.
Default:
time - maximum time for protection.
If time==0 - time is unlimited.
Default:
Remarks:
Is executed by a fleet, which contains transport submarines
8.13.6. ActFCmdProduction
Command to fleet to produce an object.
ActFCmdProduction(who, who_rel, fleet, tobj[, x, y, z, logo, name, par, mode, time]);
actFCmdProduction(fleet, tobj[, x, y, z, logo, name, par, mode, time]);
_actCmdProduction(fleet, tobj[, x, y, z, logo, name, par, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function
tobj - type of produced object, see TOBJ_... constants
x, y, z - coordinates where the object will be created. If it is not indicated ( ), then a place near the player's starting position will be selected.
Default:
logo - logo color of the object (see Appendix C.)
Default: LOGO_UNDEF
name - proper name of the object (no more than 14 symbols).
Default: empty string.
par - additional parameter
Default:
mode - is not used so far
Default:
time - maximum time of protection. If time==0 - time is unlimited.
Default:
Remarks:
1. Produced can be:
- submarines;
- structures;
- containers with resources (TOBJ_GOLD, TOBJ_CORIUM, TOBJ_METAL, TOBJ_SILICON
- weapons of mass destruction (WEAPON_LASER_BOMB, WEAPON_THERMO_NUCLEAR_MISSILE, WEAPON_VACUUM_BOMB, WEAPON_SATELLITE_GAS_LASER
2. The following conditions are necessary for a fleet to be able to produce an object:
- permission to the fleet to produce objects (see Build and ActFParBuild
- correct fleet type. Submarine fleet can produce a structure (except modules for a Command Hub), and structure fleet can produce all the rest.
- presence of an object-constructor in the fleet, for example, submarines like TOBJ_CONSTRUCTOR, or structures like TOBJ_SUBCENTER
- research of corresponding technologies.
With the help of the IsFleetCanProduce function you can define whether the given fleet is able to produce the given object in general (i.e. in no dependence with temporary difficulties, such as lack of required amount of resources at the moment the command is given).
3. The additional parameter has different meanings for different objects:
- for a submarine or structure - it is the fleet number which the produced object will join,
if par>0 - create for an already existing fleet.
if par==0 - not create for a fleet and make the produced object to be selected.
if par<0 - not create for a fleet and not make the produced object to be selected.
- for container with resources - the quantity of resources.
8.13.7. ActFCmdLoad
Command to fleet to load an object.
ActFCmdLoad(who, who_rel, fleet, x, y, z[, mode, time]);
actFCmdLoad(fleet, x, y, z[, mode, time]);
_actFCmdLoad(fleet, x, y, z[, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - number of the fleet, received by function GetFleetNum
x, y, z - coordinates of loaded object,
mode - is not used so far.
Default:
time - maximum time for executing the command.
When time==0 - time is not limited.
Default:
Remarks:
Is executed by a fleet, which contains transport submarines (TOBJ_REPSUB, TOBJ_REPAIR_PLATFORM or TOBJ_SUPPLIER).
You can load only submarines, artifacts or resource containers.
8.13.8. ActFCmdUnLoad
Command to fleet to unload an object.
ActFCmdUnLoad(who, who_rel, fleet, x, y, z[, mode, time]);
actFCmdUnLoad(fleet, x, y, z[, mode, time]);
_actFCmdUnLoad(fleet, x, y, z[, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - number of the fleet, received by function GetFleetNum
x, y, z coordinates where the object will be unloaded,
mode - If mode == 0 - object is just unloaded and not used, if mode == 1 - a unit, which is able to use the unloaded object, must be at the point of unloading. Such units are:
TOBJ_TRADECENTER - is using resource containers only,
TOBJ_MARKET - is using resource containers only,
TOBJ_ENERGY_CONVERTER - is using resource containers only,
TOBJ_RECYCLOTRON - is using resource containers, submarines and artifacts.
Default:
time - maximum time for executing the command.
When time==0 - time is not limited.
Default:
Remarks:
Is executed by a fleet, which contains transport submarines (TOBJ_REPSUB, TOBJ_REPAIR_PLATFORM or TOBJ_SUPPLIER) and loaded objects.
You can load only submarines, artifacts or resource containers.
8.13.9. ActFCmdCapture
Command to capture enemy object.
ActFCmdCapture(who, who_rel, fleet, x, y, z[, boat_finish, mode, time]);
actFCmdCapture(fleet, x, y, z[, boat_finish, mode, time]);
_actFCmdCapture(fleet, x, y, z[, boat_finish, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - number of the fleet, received by function GetFleetNum
x, y, z coordinates of captured object.
boat_finish number of subs remaining when the command execution is terminated
Default:
mode is not used so far.
Default:
time - maximum time for executing the command.
When time==0 - time is not limited.
Default:
Remarks:
Is executed by a fleet, which contains submarines able to capture enemy objects (TOBJ_MARAUDER, TOBJ_RAIDER or TOBJ_USURPER).
ActFCmdTeleport
Command to fleet to teleport.
ActFCmdTeleport(who, who_rel, fleet, dst_x, dst_y, dst_z[, src_x, src_y, src_z, mode, time]);
actFCmdTeleport(fleet, dst_x, dst_y, dst_z[, src_x, src_y, src_z, mode, time]);
_actFCmdTeleport(fleet, dst_x, dst_y, dst_z[, src_x, src_y, src_z, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - number of the fleet, received by function GetFleetNum
dst_x, dst_y, dst_z the destination point,
src_x, src_y, src_z the point of departure. This is the point in which the object that realizes teleportation (TOBJ_TRANCENTER, TOBJ_TELEPORTER, TOBJ_GATE) must be located. If the point of departure is not defined , then the fleet will teleport from the position in which it was located at the moment the command was given. If the point is defined but the object that realizes the teleportation is not there, the fleet will not teleport (no error message is output).
Default:
mode is not used so far.
Default:
time maximum time for teleportation.
When time==0 - time is not limited.
Default:
Remarks:
1. Is executed by a submarine fleet only.
2. In case of teleportation through a GATE, the destination point coordinates are ignored.
3. In case of teleportation through TRANCENTER or TELEPORTER these objects will be given a new destination point at the moment the command is given.
8.13.11. ActFCmdMassWeaponHit
Command for fleet to attack with a weapon of mass destruction.
ActFCmdMassWeaponHit(who, who_rel, fleet, weapon, x, y, z[, use, mode, time]);
actFCmdMassWeaponHit(fleet, weapon, x, y, z[, use, mode, time]);
_actFCmdMassWeaponHit(fleet, weapon, x, y, z[, use, mode, time]);
Parameters:
who, who_rel - define the list of playing sides for which the action will be performed (See Appendix A. and B.)
fleet - fleet number, received by GetFleetNum function.
weapon - type of weapons of mass destruction (WEAPON_LASER_BOMB, WEAPON_THERMO_NUCLEAR_MISSILE, WEAPON_VACUUM_BOMB, WEAPON_SATELLITE_GAS_LASER
x, y, z - target coordinates.
use - the percentage of use of weapons of mass destruction available to the fleet.
Default:
mode - is not used so far.
Default:
time - maximum time of executing the command. If time==0 - time is unlimited.
Default:
Remarks:
1. It is executed only by a fleet of structures.
2. The quantity of weapons of mass destruction ready to be used can be defined by the GetFleetMassWeaponReady function.
9. Run Time errors
When running executable code there may be situations when an executor is not able to calculate a function, expression or execute an operator. Such kind of situations is called Run Time Error. Processing of all run time errors by an executor consists of the following:
- if an error occurred when calculating an expression that sets a condition for an event occurring, then that event becomes inactive and an error message is generated.
- if an error occurred when executing an operator in the body of an event, the execution of the operator is stopped, an error message is generated and the executor proceeds to execution of the next operator in the body of the event.
An error message is output to the chat area of the screen and AiScript.dbg file. Error message output can be switched on or off via the Configuration program.
10. Command-line compiler of ST Aiscript language
Command-line compiler of the ST Aiscript language (STAiMake.exe) is intended to create AI containers and string tables and add them to the mission database.
Each mission database is created with the STEditor program and must contain:
- a map for the mission,
- list of playing sides and their starting positions.
In addition to that, the mission database can contain:
- AI containers,
- media components including string tables.
All the above mentioned can be created and/or added to the mission database with the help of the STEditor program. The STAiMake.exe program provides an alternative way of compiling and adding AI containers and string tables to the mission database.
10.1. Adding of AI containers and string tables to mission database
Source text files of the ST Aiscript language are regular text files with the following extensions:
*.flt - file to describe fleet:
*.tct - file to describe tactician;
*.stg - file to describe strategist and its events program;
*.arb - file to describe arbiter and its events program;
*.aim - file to describe how AI containers should be added to the mission database.
Self-sufficient AI containers, which are added as records to database, are Strategist and Arbiter only.
Below are described extensions of the ST Aiscript language syntax, which are used in files *.aim to add AI containers and string tables to the mission database.
10.1.1. append
Open database to add data
append(path_missions);
Parameters:
path_missions - path to the file of the mission database.
Remarks:
1. Adding of an AI container or string table to the database occurs at the moment of database closure, if the database has been opened by the operator append by that time.
2. Only one database can be opened at the same time. If by the time of calling the operator append(dbase2) the database dbase1 has been already opened, then the database dbase1 will be closed first and only then dbase2 will be opened.
3. If the file containing the database does not exist, it will be created.
10.1.2. close
Close database.
close();
Parameters:
It has no parameters.
Remarks:
This operator is not necessary. The current database will be closed automatically when the compilation process is over or when another database is opened.
10.1.3. name
Set the law of generating names for records added to the database.
name(root[, width, start]);
Parameters:
root - string root of the name of records;
width - number of figures in the name suffix or 0 if suffix is not necessary;
Default:
start - number of the first suffix
Default:
Remarks:
1. Names of records in databases are case sensitive.
2. If width==0, then all records will be added under one and the same name, i.e. they will consequently overwrite one another.
Examples:
name("RECORDS", 3); // Gives sequence RECORDS000, RECORDS001, RECORDS002, ...
name("Names", 2, 5); // Gives sequence Names05, Names06, Names07, ...
name("Overwrite"); // Gives sequence Overwrite, Overwrite, Overwrite, ...
10.1.4. pack
Pack records.
pack([fl_pack]);
Parameters:
fl_pack - identifier of packing records:
- write records without packing,
- pack records before writing.
10.1.5. Names of AI containers and string tables.
- Arbiter always has the name - "AIBOSS"
- Strategists for playing side N should take names from the sequence set by the operator:
name("STRATEG<N>", 3, 0);
where N - is the number of the playing side.
For example, for playing side 1(green), names of strategists are set with the operator:
name("STRATEG1", 3, 0); // Gives sequence STRATEG1000, STRATEG1001, STRATEG1002...
- Table of common string resources should have the name - "DESCRIPTION"
- Table of Objectives strings should have the name - "OBJECTIVES"
10.2. Environment variables
Before compilation starts the ST AIscript compiler sets the value of some variables that provide info about the environment.
Integer variables:
_env_var0, _env_var1, _env_var2.
Integer values of these variables can be set in the options of compiler's command-line (see. 10.3.). By default they are equal to 0.
The main path of the game:
_main_path
This string variable contains the main directory where the game was installed. If it is not initialized, it is empty. The value of this variable can be re-defined in the options of compiler's command-line (see. 10.3.).
The path to the file of constants and macro definitions:
_inc_path
This string variable contains the directory where the files AiScript.dfn, AiScript.mcr and any other files that contain common information are stored. If it is not installed the string is empty. The value of this variable can be re-defined in the options of compiler's command-line (see. 10.3.).
The path to the database of user's missions:
_maps_path
This string variable contains the directory in which the database of user's missions is stored. If it is not installed the string is empty. The value of this variable can be re-defined in the options of compiler's command-line (see. 10.3.).
The path to the compiled file:
_curr_path
This string variable contains the directory in which the currently compiled file is stored. The value of this variable is not defined in the options of compiler's command-line, but is assigned by the compiler automatically when the next source code file is opened.
10.3. Command-line options
STAiMake <src_file_name> [</D>] [</V<N>=<val>] [/G<_main_path>]
[/I<_inc_path>] [/M<_maps_path>]
Commands:
<src_file_name> - name of the compiled file.
/D - create log file.
</V<N>=<val> - set value of integer variable
<N> - the number of variable ,
<val> - value.
/G<_main_path> - assign value to the variable _main_path,
<_main_path> - the assigned value.
/I<_inc_path> - assign value to the variable _inc_path,
<_inc_path> - the assigned value.
/M<_maps_path> - assign value to the variable _maps_path,
<_maps_path> - the assigned value.
Examples:
STAiMake Add.aim
STAiMake Add.aim /D
STAiMake Add.aim /D /v0=10 "/Gc:\Submarine Titans"
STAiMake Add.aim /v0=1 /v1=3 "/Ic:\Submarine Titans\Editor" "/Mc:\Out\Maps"
11. Media components
Each mission can be decorated with media components such as:
- string tables,
- programs of prolog and epilogs,
- background images for prolog and epilogs,
- animations for prolog and epilogs,
- briefing programs,
- animations for briefings,
- sound files that contains effects and speech
- video files.
String tables as well as programs of prolog and epilogs should be stored in the mission database.
Background images, animations and sound files can be stored either in the mission database or in the common game media database TASKS.DKD. Names of available media components stored in this database are listed in Appendix X.
Sound files, which are used in briefing programs, can be stored from the common game sounds database SOUNDS.DKD.
Video files are not included into game databases and are always stored in separate files in the \Video - directory.
The majority of the components listed above can be created and/or added to a mission database with the help of the STEditor program. In this chapter we describe an alternative method of adding media components to databases with the help of the utility mfew32.exe
11.1. mfew32.exe utility
The utility mfew32.exe is intended to create game databases and adding various components to them. The strategy of the creation of a database and adding records to it is described in a special language (MFEW Script), syntax elements of which are described below.
The source files of MFEW Script - are regular text files with the following recommended extensions:
*.smf - main source file from which the processing has started;
*.imf - include files with text written in the MFEW Script language.
11.1.1. Create/open database. Operators 'create' and 'append'.
The Mission database can be opened for adding and created by the following operators:
create(path_missions);
append(path_missions);
Parameters:
path_missions - path to the mission database file.
Remarks:
1. create always creates a new database. If the database with the name path_missions already exists, it will be deleted.
2. append opens an already existing database for adding new data. If the file path_missions does not exist, it will then be created.
3. Only one database can be opened at the same time. If by the moment of append(dbase2) or create(dbase2) operator call dbase1 has been already opened, then the database dbase1 will be closed first and only then dbase2 will be opened or created.
11.1.2. Source files. Operator 'source'.
Graphics and sound data are added from the corresponding source files.
The utility mfew32.exe can read graphics data from the graphics file formats: BMP, GIF, PCX and JPG. Since Submarine Titans is using 8-bit graphics, it is desirable that all graphics source files should be prepared in 8-bit format (except JPG).
Sound data can be added from .WAV files that contain sound in the formats:
- PCM 11-44 kHz, 8-16 bit, Stereo (Mono);
- Microsoft ADPCM 11-44 kHz, 2-4 bit, Stereo (Mono).
For short sound effects we recommend that you use the PCM 22 kHz, 16 bit, Mono format and for music, voice or background sound effects with a longer playback time - Microsoft ADPCM 22 kHz, 4 bit, Stereo.
To set the sequence of names of source file the following operator is used:
source(scr_path[, width, start]);
Parameters:
root - the full path (including name and extension) of source files;
width - the number of figures in the file suffix, or if suffix is not necessary;
Default:
start - number of the first suffix.
Default:
Remarks:
When width is not equal to suffix is added only to the file name, file's extension remains unchanged.
Examples:
source("d:\\WSBkg.gif", 2); // Gives sequence c:\WSBkg00.gif, c:\WSBkg01.gif, ...
source("Speech.wav", 2, 5); // Gives sequence Speech005, Speech006, ...
11.1.3. Names of records. Operator 'name'.
Set the law of generating names for records added to the database.
name(root[, width, start]);
Parameters:
root - string root of records name;
width - number of figures in the name's suffix or 0, if suffix is not required;
Default:
start - the number of the first suffix.
Default:
Remarks:
1. Records names in the database are case sensitive.
2. If width==0, then all records will be added with the same name, i.e. they will consequently overwrite each other.
Examples:
name("RECORDS", 3); // Gives sequence RECORDS000, RECORDS001, RECORDS002, ...
name("Names", 2, 5);// Gives sequence Names05, Names06, Names07, ...
name("Overwrite"); // Gives sequence Overwrite, Overwrite, Overwrite, ...
11.1.4. Additional options. Operators 'pack', 'transp' and 'stretch'.
There is an option of packing records before adding them to the database. This increases the time of database creation and reading data from it but reduces its size.
pack([fl_pack]);
Parameters:
fl_pack - identifier of packing records:
- write records without packing them,
- pack records before writing them to the database.
Default:
Animation sequences require setting the number of the transparent color. The following operator is used for this purpose:
transp([void_color]);
Parameters:
void_color - the number (index in the array of RGB components of the palette) of the transparent color.
Default:
The following operator is used to change the size of graphics matrices:
stretch([nx,ny]);
Parameters:
nx - double-byte co-efficient of changing the horizontal size, which sets as a common fraction, where the enumerator is the high byte and the denominator is the low byte.
Default: 0x0101
ny - double-byte co-efficient of changing the vertical size, which sets as a common fraction, where the enumerator is the high byte and the denominator is the low byte.
Default: 0x0101
11.1.5. Command-line options.
mfew32.exe <src_file_name> [</D[dblog_name]>] [</L[srclog_name]>]
Commands:
<src_file_name> - name of the MFEW Script file.
</D[dblog_name]> - create file with reports about added records, where dblog_name is the optional name of the report file. If the name is not defined, then the database file name with the .LGM extension will be used.
</L[srclog_name]> - create report file, which contains the list of the source files, where srclog_name is the optional name of the report file. If the name is not defined, then the database file name with the .LGS extension will be used.
11.2. String Tables
String tables are intended to store string constants, which are necessary for informational service of a mission.
Each mission must have two string tables:
- table of common string resources;
- table of Objectives strings.
A table of common string resources contains strings intended for prolog, epilog and briefing programs, string messages and names of game units. It should be named as "DESCRIPTION".
A table of Objectives strings contains a list of objectives. It should be named as "OBJECTIVES".
11.2.1. Creation of a string table. Operators 'initsar' and 'putsar'
The two operators of the MFEW Script language initsar and putsar are used to create a string table.
initsar([beg,incr]);
Parameters:
beg - initial number of strings in the table,
Default:
incr - number of strings which are added to the table when it is overflown,
Default:
Remarks:
The operator initsar opens a string table for adding new strings until the operator putsar is met.
putsar();
Parameters:
It has no parameters.
Remarks:
It closes the string table and writes it to the opened mission database
11.2.2. Adding strings to string table. Operator 'setsar'.
The operator setsar is used to add strings into a string table:
setsar(str);
Parameters:
str - added string.
Remarks:
The sequence order of the setsar operators is important when adding new strings to a string table, because later on the access to a string will only be available by its index number in the table. The enumeration of strings in a string table begins with .
11.3. Prolog and epilogs
Each campaign mission or Add-ons can be preceded with a prolog and ended with one of few epilogs. Prolog and epilogs are described by programs in the MFEW Script language and are using graphics and sound data when they are executed.
Prolog and epilog programs should be placed directly in the mission database. The prolog should be added to the database under the name "TASKPLAY", epilogs can be added to the database under any other names, which are defined by the mission developer. The MFEW Script tolls, which are intended for writing prologs, epilogs and adding graphics and sound data to databases, are described below.
11.3.1. Preparation of background image.
Background image is a graphics matrix with the size of 800x600 and the color depth 8-bit, which is displayed on the screen from the very beginning till the end of prolog or epilog execution. Besides the image, background image also contains a palette, which is set for the time of execution of prolog or epilog program.
Since the decoration elements of prolog and epilog screens are imaged with strictly defined clusters, background image palette have the following restrictions:
= = = = = = = = = = = = = = = =
N | Palette clusters | Purpose
= = = = = = = = = = = = = = = =
1 | 0-21, 246-255 | System (do not change!)
-------- ----- ------ -------- ----- ------ ----------
2 | 22-25 | Bright spectrum of the first color of decoration
-------- ----- ------ -------- ----- ------ ----------
3 | 26-41 | Dark spectrum of the first color of decoration
-------- ----- ------ -------- ----- ------ ----------
4 | 42-45 | Bright spectrum of the second color of decoration
-------- ----- ------ -------- ----- ------ ----------
5 | 46-61 | Dark spectrum of the second color of decoration
-------- ----- ------ -------- ----- ------ ----------
6 | 62-245 | User defined
= = = = = = = = = = = = = = = =
The color range 1 contains system color and should not be changed.
Color ranges 2 - 5 can be changed, but only in such a way that they will remain as spectrums for 2 colors in which all decoration elements of prolog and epilogs are drawn.
The last (the 6th) color range can contain arbitrary colors, defined by the user.
You can find the examples of files, which contain background images, in the directory ...\Editor\Tasks\Examples:
task_bo.gif ,
task_ws.gif ,
task_si.gif .
The following two overloaded operators are used to add background images to a mission database:
putdib([num]);
putdib(x,y,lx,ly[,num]);
Parameters:
num - number of added images,
Default:
x,y,lx,ly - rectangular zone in the source graphics file that will be added as an image.
Remarks:
1. The first operator adds the whole image that the source file contains. The second operator adds only the rectangular clip (x,y,lx,ly) of this image.
2. The names of records placed in the database and the names of the graphics source files are taken from the sequences determined by the operators name and source (see 11.1.2. and 11.1.3.)
Example:
...
source(path_task+"task_ws.gif");
name("DEFAULT_WS");
putdib(1); // Whole image will be added from file task_ws.gif
...
11.3.2. Preparation of animations
Animation for prolog and epilogs is a sequence of 8-bit color pictures-frames, where size is no bigger than 800x600 pixels. Animations can be played at any time of a prolog or an epilog execution and at any part of the screen. The transparent color (pixels of that color are not displayed on the screen) is set for each animation.
It should be noted that when animations are displayed they are using the palette determined by the background image, hence the background picture and all animations displayed over it should be prepared in one palette.
The following set of the MFEW Script language operators is used for creating and adding animation sequences to a mission database:
initribb - open a sequence,
setribb - add frames,
putribb - write the sequence in the database.
Open animation sequence.
initribb(type);
Parameters:
type - type of graphics matrices used as the frames.
_M_SPR type is used for prolog and epilog animations.
Remarks:
The animation sequence will be opened for adding new frames until the operator putribb is met.
Adding of new frames to an animation sequence can be realized by any of the overloaded operators:
setribb([num]);
Parameters:
num - number of added frames
Default:
Remarks:
It adds the whole image of the source graphics file as one frame of an animation sequence.
A new graphics source file, which name is determined by the operator source (see 11.1.2.), is taken for every new frame.
setribb(x,y,lx,ly[,num]);
Parameters:
x,y,lx,ly - rectangular zone in the source graphics file that will be added as a new animation sequence frame.
num - number of added frames.
Default:
Remarks:
It adds the rectangular clip (x,y,lx,ly) of the source file image.
A new graphics source file, whose name is determined by the operator source (see 11.1.2.), is taken for every new frame.
setribb(num,x0,y0,lx,ly,dx,dy,nx[,nx1]);
Parameters:
num - total number of added frames;
x0,y0 - co-ordinates of the top left corner of the first frame in the graphics source file;
lx,ly - frame size in pixels;
dx,dy - horizontal and vertical gapping between frames in the graphics source file;
nx - number of frames in the "frames string" graphics source file;
nx1 - number of frames in the first incomplete "frames string" graphics source file;
Default: nx
Remarks:
It adds frames from ONE source image file, in which frames of the same size (lx,ly) are placed in "frames strings" in nx frames in each string. All strings are strictly one under another, i.e. they have the same coordinate y0. The first string cannot be complete - it may not have a few of the first frames. The gapping between frames in a string should be equal to dx and the gapping between strings should be equal to dy.
You can find the examples of files, which contain frame sequences, in the directory ...\Editor\Tasks\Examples:
ws_anim1.gif ,
ws_anim2.gif ,
ws_anim3.gif ,
ws_anim4.gif ,
ws_anim5.gif ,
ws_anim6.gif .
Write an animation sequences to a database.
putribb();
Parameters:
It has no parameters.
Remarks:
It closes an animation sequence and writes it to a database. The name for the record is taken from the sequence, which is determined by the operator name (see 11.1.3.).
Example:
...
// it extracts an animation from one graphic file
source(path_task+"si_anim1.gif");
initribb(_M_SPR);
setribb(20, 1, 1, 118, 118, 1, 1, 10);
putribb();
// it extracts an animation from two graphic files
source(path_task+"si_anim4.gif");
initribb(_M_SPR);
setribb(18, 1, 1, 383, 150, 1, 1, 3);
source(path_task+"si_anim5.gif");
setribb(2, 1, 1, 383, 150, 1, 1, 2);
putribb();
...
11.3.3. Preparation of sound files
Each prolog and epilog program can be decorated with the following two types of sound fragments:
- looped background sound (only one). It is launched in the beginning of the program start and constantly sounds till its end.
- sounds fragments, which are launched by events in the program. They sound till their natural end.
Sound fragments, which are contained in the game media base TASKS.DKD (their names are listed in Appendix X), and original sound fragments, which can be added to a mission database, can be used in prolog and epilog programs. The following operator is used for this purpose:
putwav(num, mode);
Parameters:
num - number of added sound fragments;
mode - format of the sound fragment. For prologs and epilogs it should be equal to _MF_PCM
Remarks:
The names for sound fragments, which are placed in the database, and the names of the sound source files are taken from the sequences determined by the operators name and source (see 11.1.2. and 11.1.3.)
11.3.4. Creation of a program. Operators 'inittask' and 'puttask'.
Open prolog/epilog program.
inittask(bkg_name, snd_name);
Parameters:
bkg_name - background image name (see 11.3.1.)
snd_name - background looped sound name (see 11.3.3.)
Remarks:
The program will be opened for adding new commands until the operator puttask is met.
Close prolog/epilog program.
puttask();
Parameters:
It has no parameters.
Remarks:
It closes the prolog/epilog program and writes it to the database. The name for the record is taken from the sequence, which is determined by the operator name (see 11.1.3.).
11.3.5. Operators 'Time', 'SetColor', 'SetLevel'.
Set the time of executing program command.
Time(time);
Parameters:
time - the moment of time, which is counted in the 1/30th fractions of a second from the moment of the program start.
Remarks:
Sets the moment of time when all program commands, which follow the operator Time, will be executed until another operator Time, which will set a new moment of time, is met.
The extent of the whole program is determined by the operator Time with the biggest value of the parameter time
Set colors for decoration elements.
SetColor([fnt, glass, border, ctrl]);
Parameters:
fnt - color of symbols;
Default:
glass - color of semi-transparent background;
Default:
border - color of edging;
Default:
ctrl - color of control elements;
Default:
Remarks:
Two sets of colors are reserved in the palette for displaying decoration elements (see 11.3.1.):
- corresponds to the first set,
- corresponds to the second set,
The operator SetColor defines colors of all decoration elements, which will be displayed after it in the program until the next SetColor operator is met.
Set the level of input.
SetLevel([lev]);
Parameters:
lev - the level of input (it should be equal or bigger than ).
Default:
Remarks:
Animations, controls, windows, text, etc., which are displayed in the process of program execution, can overlap one another. The operator SetLevel sets the level for all displayed components, which will be shown after it until the next SetLevel operator is met.
The highest (closest to the monitor surface) level is set with the value , the next level is , then , etc..... up to .
11.3.6. Buttons. Operators 'ShowBut', 'HideBut'.
In the process of the prolog/epilog program execution a few types of buttons can be output on the screen. The user can use them to control the process of execution of the program.
The button is output on the screen by the operator:
ShowBut(type, x, y, lx, ly);
Parameters:
type - button type. The supported types are:
TBTYPE_MENU - return to the main menu (only for prolog),
TBTYPE_BACK - return to the previous menu (only for prolog),
TBTYPE_START - start the game from prolog or go to the next mission in epilog,
TBTYPE_REPLAY - restart prolog/epilog program.
x,y,lx,ly - place and size of the button. The buttons should not be less than 145x40 pixels.
Remarks:
Besides the buttons output on the screen, the <Esc> key is always active and allows to interrupt the program execution and set the screen of prolog/epilog to the condition it will normally be set to after execution of the program.
Hide a button from the screen.
HideBut(type);
Parameters:
type - button type.
Remarks:
Each button type can exist on the screen only as a single button; hence it is enough just to indicate the type of the button to locate it precisely.
11.3.7. Switch of difficulty level. Operators 'ShowSwitch' and 'HideSwitch'.
To allow user select difficulty levels, use the following special switch:
ShowSwitch(x1, y1, x2, y2[, x3, y3]);
Parameters:
x1, y1 - coordinates of output of the item <AI Weak>,
x2, y2 - coordinates of output of the item <AI Medium>,
x3, y3 - coordinates of output of the item <AI Strong>,
Default: item is not displayed
Remarks:
1. The difficulty level switch is not accessible in epilogs.
2. Note that this switch defines only the value of the variable, which contains the difficulty level that can be used by the arbiter or strategists, whose programs should determine the mission difficulty level.
Hide the difficulty level switch:
HideSwitch();
Parameters:
It has no parameters.
11.3.8. Default set of controls. Operator 'SetDefControl'.
There is an option of using the default set of controls: buttons and difficulty level switches.
SetDefControl();
Parameters:
It has no parameters.
Remarks:
The default set of controls consists of buttons: TBTYPE_MENU, TBTYPE_BACK, TBTYPE_START and the switch of three difficulty levels.
11.3.9. Show Objectives. Operators 'ShowObjectives' and 'HideObjectives'.
The list of Objectives can be displayed in a special window that contains special controls, which allows to view the whole list.
The following operator is used for that purpose:
ShowObjectives(x, y, lx, ly);
Parameters:
x,y,lx,ly - location and the size of the window with the Objectives list.
Remarks:
The list of Objectives is not available in epilogs.
Hide Objectives from the screen.
HideObjectives();
Parameters:
It has no parameters.
11.3.10. Show text. Operators 'ShowTTask' and 'HideTTask'.
There are a few ways of showing strings from a table of common string resources. The simplest way is to show quickly a string in a window with semi-transparent background or without it. This can be realized with the operator:
ShowTTask(id, x, y, lx, ly, from, nstr[, fl_glass, dx, dy]);
Parameters:
id - identifier of a simple text. It is selected by the user;
x,y - the left top corner of the output window;
lx, ly - the size of the output window in pixels;
from - must be always equal to ;
nstr - the number of the output string in the table of common string resources;
fl_glass - identifier of semi-transparent background output:
- do not display
- display
Default:
dx, dy - widths of horizontal and vertical interspace between the text and the output window edges.
Default:
Remarks:
1. Note that in this case the output window will not have any controls and if the text does not fit in the window, users will not be able to read the whole text.
2. You can display several samples of simple text on the screen simultaneously. Assign each of them a unique id to differentiate between them.
Hide a simple text from the screen.
HideTTask(id);
Parameters:
id - identifier of a simple text
Remarks:
The window with a simple text will not be hidden immediately; it may take a while but no more than 0.5 second.
11.3.11. Show text in Viewer window. Operators 'ShowTask' and 'HideTask'.
Big text that consists of several strings can be displayed in a special window (viewer), which contains the controls necessary to view the whole text.
The following operator is used for that purpose:
ShowTask(x, y, lx, ly[, beg_str, num]);
Parameters:
x,y,lx,ly - location and the size of the viewer window;
beg_str - number of the first displayed string in the table of common string resource;
Default:
num - number of strings or . If num= -1 then all strings beginning from the string beg_str till the end of the table are displayed.
Default:
Remarks:
1. Only one viewer can exist at the same time.
2. The operator allows displaying of strings only with consequent numbers. You should keep this in mind when preparing tables of common string resources.
Hide viewer with text from the screen.
HideTask();
Parameters:
It has no parameters.
11.3.12. Show text with typing and scrolling. Operators 'ShowATask' and 'HideATask'.
There is also the option of displaying text symbol by symbol (typing). The text (one string of the common string resource) will be displayed symbol by symbol in a window with a semi-transparent background (or without it). If the area for text display is smaller than the displayed text, then the text will wrap up string by string giving space for the next string.
Show text with typing and wrapping.
ShowATask(id, x, y, lx, ly, from, nstr[, fl_glass, dx, dy, snd]);
Parameters:
id - text identifier. It is selected by the user.
x,y - the left top corner of the output window,
lx, ly - the size of the output window in pixels;
from - must be always equal to ;
nstr - the number of the output string in the table of common string resources;
fl_glass - identifier of semi-transparent background output:
- do not display
- display
Default:
dx, dy - widths of horizontal and vertical interspace between the text and the output window edges.
Default:
snd - identifier of typing sound:
- sound off,
- sound on.
Default:
Remarks:
1. The output window in this case does not have any controls and after the text output, if the text was wrapped up, the user will not be able to view the whole text.
2. It is possible to display several texts with typing simultaneously. To differentiate between them you should assign a unique id to each of them.
Hide text with typing.
HideATask(id);
Parameters:
id - text identifier.
Remarks:
The window with text will not be hidden immediately; it may take a while but no more than 0.5 second.
11.3.13. Show animations. Operators 'ShowAni', 'MoveAni', 'ShowAniFrame' and 'HideAni'.
Animation sequences described in 11.3.2. can be displayed in one of the following ways.
Display animation sequence at a point of the screen:
ShowAni(id, name, x, y, time_frame[, loop]);
Parameters:
id - animation identifier. It is selected by the user.
name - string with record name containing graphics data for the animation sequence (see 11.3.2.)
x, y - point of animation display on the screen.
time_frame - display time of one animation frame in 1/30 fractions of a second ,
loop - loop identifier:
- do not loop,
- loop.
Default:
Display animation sequence moving it along a line:
MoveAni(id, name, xs, ys, xf, yf, time_frame, time[, loop]);
Parameters:
id - animation identifier. It is selected by the user.
name - string with record name containing graphics data for the animation sequence (see 11.3.2.)
xs,ys - point of animation start,
xf,yf - point of animation finish,
time_frame - display time of one animation frame in 1/30 fractions of a second,
time - time of animation movement in 1/30 fractions of a second,
loop - loop identifier:
- do not loop,
- loop.
Default:
Show one frame from animation sequence:
ShowAniFrame(id, name, x, y[, frame]);
Parameters:
id - animation identifier. It is selected by the user.
name - string with record name containing graphics data for the animation sequence (see 11.3.2.)
x, y - point of animation display on the screen.
frame - enumeration number of the frame (the enumeration begins with )
Default:
Remarks:
1. If the animation is not looped, then in the end the last frame will remain displayed.
2. All coordinates are superposed with the top left corner of the animation.
3. It is possible to display several animations on the screen simultaneously. To differentiate between them you should assign a unique id to each of them.
Hide animation.
HideAni(id);
Parameters:
id - animation identifier.
11.3.14. Play sounds. Operator 'StartWave'.
Sound fragment described in 11.3.3. can be played back with the help of the operator:
StartWave(name);
Parameters:
name - string with record name containing data of the sound fragment.
Remarks:
A sound launched by this operator cannot be looped or stopped till its natural end.
11.4. Briefings
A mission can contain an arbitrary number of briefings, which can be played back by a special command of the ST AIScript language (see 8.5.6.).
Briefings are described by programs in the MFEW Script language and are using graphics and sound data when played back. Briefing programs should be placed directly in the mission database.
Briefings are always played back during the game in a special panel that appears at the moment of briefing start, over the main panel. Briefing panel consists of two parts: one is to display TV animation, the other to display text information from the main string resource of the mission.
The tools of the MFEW Script language intended to write briefing programs and adding sound and graphics data for them into mission databases are described below.
11.4.1. Preparation of TV animations
Animation for a briefing is a specially prepared sequence of frames, which imitate a TV image.
Each frame of such animation sequence should have the size 76x56 pixels and 8-bit color depth. Since briefing animations are displayed in the process of the game they should be prepared in the game palette.
The operators of the MFEW Script language intended for creating and adding of TV animations to mission databases are described in 11.3.2.
You can find the examples of files, which contain TV animations, in the directory ...\Editor\Tasks\Examples:
ws_face1.gif ,
ws_face2.gif .
Those file can be used as the sources of the game palette.
11.4.2. Creation of briefing program. Operators 'initbriefing' and 'putbriefing'.
Open briefing program.
initbriefing();
Parameters:
It has no parameters.
Remarks:
The program will be open for adding new commands until the operator putbriefing is met.
Close briefing program.
putbriefing();
Parameters:
It has no parameters.
Remarks:
Closes the briefing program and writes it to the database. The name for the record is taken from the sequence determined by the operator name (see 11.1.3.).
11.4.3. Operator 'Time'.
Set time for executing program commands.
Time(time);
Parameters:
time - the moment of time, which is counted from the beginning of the game in atoms of game time.
Remarks:
1. Sets the moment of time when all briefing commands, which follow the operator Time, will be executed until a new Time operator is met, which will set a new moment of time.
2. Note that the game time depends on the game speed, which is defined by the user. At the normal game speed one atom of game time is equal to 1/25 fraction of a second.
11.4.4. Stop briefing program execution. Operator 'BriefingStop'.
Stop executing briefing program and hide the briefing panel.
BriefingStop();
Parameters:
It has no parameters.
Remarks:
If the briefing program does not contain a single BriefingStop operator, the briefing panel will remain onscreen till the end of the game session or till the start of a new briefing program.
11.4.5. Show text. Operator 'BriefingText'.
The following operator is used to show text (strings from a table of common string resource) in the briefing panel:
BriefingText(beg_str, num_str[, flTyping, flSound]);
Parameters:
beg_str - number of the first output string in the table of common string resource,
num_str - number of strings,
flTyping - identifier of symbol-by-symbol text output (with typing)
- immediate text output,
- text output with typing;
Default:
flSound - identifier of typing sound:
- sound off,
- sound on.
Default:
Remarks:
1. Note that in case of immediate text output (flTyping==0) the output window will not have any controls and if the output text does not fit in the window the user will not be able to read the whole text.
2. The operator allows to output only strings with consequent numbers. You should take this into consideration when you prepare tables of common string resource.
11.4.6. Show TV animations. Operator 'BriefingAni'.
The following operator is used to show TV animations in the briefing panel:
BriefingAni(tobj, civ[, name_ani]);
Parameters:
tobj, civ - game unit type and its native civilization;
name_ani - string with the record name, which contains graphics data for the TV animation (see 11.4.1.).
Default: empty string
Remarks:
1. If the name of the TV animation name_ani is not empty, then the animation with that name will be displayed and the parameters: tobj and civ are ignored. The graphics data of the animation with the indicated name will be searched first in the mission database and then, if it is not found there, in the common media base of the game TASKS.DKD. The names of available TV animations, stored in this database, are listed in Appendix X. If the name of animation is an empty string, then the TV animation of the unit defined with the parameters: tobj and civ will be displayed. Constants for these parameters are defined in the file MFDEF_T.IMF, which is supplied with the game.
2. Animation is always looped.
11.4.7. Play sounds. Operator 'BriefingWave'.
The following operator is used to play sounds when the briefing program is executed:
BriefingWave(id_wav[, name_wav]);
Parameters:
id_wav - sound identifier in the game sounds database;
name_wav - string with the record name, which contains sound data (see 11.3.3.).
Default: empty string
Remarks:
With this operator sound fragments can be played from the three sources:
- game sounds database SOUNDS.DKD,
- common game media base TASKS.DKD,
- original mission database.
If the name name_wav is not empty then the sound with the indicated name will be played and the parameter id_wav will be ignored. The sound with the indicated name will be searched first in the mission database and then, if it is not found there, in the common media base of the game TASKS.DKD. The names of available sounds, stored in this database, are listed in Appendix X.
If the name of the sound is an empty string, then the sound from the game sounds database defined with the parameters: id_wav will be played. Constants for sound identifiers are defined in the file MFDEF_T.IMF, which is supplied with the game.
11.5. Mission Name
Each mission has its own string name, which will be displayed in the users interface display windows or when selecting the mission file.
Mission name can be defined with the operator:
putaobj(name);
Parameters:
name - string name of mission (64 symbols);
Remarks:
Database record that contains mission name should always be added with the name "TITLE_MISSION".
Example:
...
name("TITLE_MISSION"); putaobj("INTERCEPTION");
...
11.6. Video
Each campaign mission or Add-ons can be preceded with a video fragment. Video fragments for campaign missions are stored in the directory ...\Video, and the fragments for Add-on missions in corresponding subdirectories of that directory.
When you prepare a video fragment note that your video will be displayed in the video mode 640x480x24. Microsoft DirectX Media 6.0 decoders are used to unpack video files. To get info about compatible formats of video files, see the Microsoft DirectX Media 6.0 documentation.
= = = = = = = = = = = = = = = = ===
Appendix A: Constants to define playing sides
Up to 8 playing sides can participate in a Submarine Titans game session. Each of the sides has its different basic logo color.
The following constants are defined to indicate the playing sides in ST AIscript:
PLAYER_0 - basic color - dark blue
PLAYER_1 - basic color - green
PLAYER_2 - basic color - yellow
PLAYER_3 - basic color - red
PLAYER_4 - basic color - violet
PLAYER_5 - basic color - blue
PLAYER_6 - basic color - orange
PLAYER_7 - basic color - beige
Additional constants to indicate playing sides:
PLAYER_CURR - defines the side of the current player, i.e. the side, which on a given computer is controlled with the game interface. Concrete side is defined during execution.
Remarks:
Note that in a multiplayer game each computer will have a different current player from the others.
PLAYER_ME - defines side for which the executor will be launched. Concrete side is defined during execution.
Remarks:
Arbiter is not associated with any playing side, hence PLAYER_ME must not be used in Arbiter operators.
PLAYER_ALL - as a rule defines all playing sides.
Appendix B: Constants to define relation to playing side
These constants define one or several playing sides, which are in a set relation to the given one. As a rule in ST AIscript operators they are used in conjunction with constants as described in Appendix A (except PLAYER_ALL).
AIREL_MYSELF - the given side;
AIREL_ENEMYS - all sides that the given sides considers as enemies;
AIREL_MYTEAM - all sides that the given sides does not consider as enemies, including the given one;
AIREL_FRIENDS - all sides that the given sides does not consider as enemies, excluding the given one.
AIREL_UNION all sides which are in mutual alliance with the given side including the given side.
AIREL_ALLIES all sides which are in mutual alliance with the given side excluding the given side.
AIREL_NOTALLY - all sides which are not in mutual alliance with the given side.
Examples:
1. ...
GetPlObjM(PLAYER_CURR, AIREL_MYTEAM, ...);
...
In this example the function GetPlObjM will calculate objects of all sides, which are not considered as enemies to the side of the current player, including the current player.
2. ...
ActTechDevDisable(PLAYER_ME, AIREL_MYSELF,...);
...
Operator ActTechDevDisable works only for the side for which the strategist containing this operator is launched.
3. ...
GetPlObjBuilt(PLAYER_ALL, AIREL_MYSELF, ...);
...
Function GetPlObjBuilt returns the number of built objects by all playing sides. In this case the second parameter that sets relation is ignored.
Appendix C: Constants to define logo colors of objects
Each playing side uses a basic color for all of its objects, see Appendix A. However, game objects of any particular side can be different from the basic color.
Constants to set object's logo color directly:
LOGO_0 - dark blue,
LOGO_1 - green,
LOGO_2 - yellow,
LOGO_3 - red,
LOGO_4 - violet,
LOGO_5 - blue,
LOGO_6 - orange,
LOGO_7 - beige.
Additional constants to set object's logo colors:
LOGO_DEFAULT - sets color that corresponds the basic color of the side to which the object belongs.
LOGO_UNDEF - indefinite logo color. It is used to indicate that the logo color is unimportant.
Examples:
1.
....
ActCreatePlObj(PLAYER_0, AIREL_MYSELF, TOBJ_SENTINEL, -1, -1, -1, LOGO_DEFAULT);
...
Operator ActCreatePlObj will create object with dark blue logo.
2.
...
ActDelPlObjEx(PLAYER_CURR, AIREL_MYSELF, AITRG_ALL, TOBJ_UNDEFINED, LOGO_UNDEF);
...
Operator ActDelPlObjEx will delete all objects for the current player independent of their logo color.
Appendix D: Constants to define civilizations
CIV_UNDEF - civilization is not defined,
CIV_WS - White Sharks,
CIV_BO - Black Octopi,
CIV_SI - Silicons.
Appendix E: Constants to define teams
In team-play game each of the playing sides is a member of the team. The following constants are used to define teams:
TEAM_A - team A
TEAM_B - team B
TEAM_C - team C
TEAM_D - team D
TEAM_E - team E
TEAM_F - team F
TEAM_G - team G
TEAM_H - team H
Appendix F: Constants to define types of Fleets
One of the most important fleet characteristics is fleet type. Fleet type indicates what basic tactical tasks it can fulfil. The following constants are used to define fleet types in the ST AIscript:
AIF_NONE - type is not defined (auxiliary).
AIF_BASE - structure fleet. It is intended to control structures. It consists only of structures.
It cannot contain submarines.
AIF_RES - resource transporting fleet. It should contain units able to transport resources.
It cannot contain structures.
AIF_BUILD - structure building fleet. It should contain objects, which are able to build structures.
It cannot contain structures.
AIF_CARRIER - Fleet-carrier. It is intended to carry subs, resource containers and artifacts. Such fleet should consist of units able to carry other objects.
It cannot contain structures.
AIF_MILITARY - fleet to fulfil general military tasks.
It cannot contain structures.
AIF_SPEC - fleet to fulfil special military tasks. It must contain military subs with non-standard arming.
It cannot contain structures.
AIF_MINER - fleet to set mines
It must contain units, which can set mines.
It cannot contain structures.
AIF_CAPTOR - fleet to capture enemy structures
It must contain units, which are able to capture enemy structures.
It cannot contain structures.
AIF_CYBER - fleet of cyborgs
It must contain cyborgs.
It cannot contain structures.
AIF_SUPPLY - combination of AIF_RES, AIF_BUILD and AIF_CARRIER
AIF_ARMED - combination of AIF_MILITARY, AIF_SPEC, AIF_MINER, AIF_CAPTOR and AIF_CYBER
AISF_ALL - any type
Division of fleets into types is used not to differentiate their behavior, but to distribute game units between fleets more accurately. In other words, a structure building fleet can fulfil all military tasks if it has military submarines and a military fleet can build structures if it has at least one unit able to build structures.
Appendix G: Constants to 19119b18t define types of Fleet behavior
To fulfil the set tasks, fleet can execute several behaviors. The following constants are used to define fleet behaviors in the ST AIscript:
AISF_NONE - do nothing,
AISF_HOMEPOSITION - stay in basic position,
AISF_GATHERINGRC - collect resources,
AISF_BUILDINGOBJ - build object,
AISF_PATROL - patrol,
AISF_MOVE - move to a point,
AISF_GUARD - protect other fleet,
AISF_ATTACK - attack enemy,
AISF_PAUSE - state of military pause,
AISF_ALL - any behavior.
Appendix H: Constants to define groups of types of game objects
Game units of different types are united into groups (categories) according to their main purpose. The following constants are used to define such groups in the ST AIscript:
AITRG_NONE - empty group,
AITRG_TLODEFENSECOMMON - guns with conventional ammo,
AITRG_TLODEFENSESPEC - guns with special ammo,
AITRG_TLOPROTECTIVE - defensive structures,
AITRG_TLOPRODUCTIVE - production structures,
AITRG_TLOSUPPLY - supply structures,
AITRG_TLORCCONVERT - structures that convert resources,
AITRG_TLORCEXTRACT - resource extracting structures,
AITRG_TLOHIGHTECH - hi-tech structures,
AITRG_TLOINTELLIGENCE - information structures,
AITRG_TLODEFENSE - guns with any ammo,
AITRG_TLORC - structures that extract or convert resources,
AITRG_TLOALL - any structure,
AITRG_BOATMILITARYCOMMON - submarines with conventional ammo,
AITRG_BOATMILITARYSPEC - submarines with special ammo,
AITRG_BOATRCEXTRACT - submarines extracting and transporting resources,
AITRG_BOATCONSTRUCT - submarines -constructors,
AITRG_BOATSUPPLY - submarines, whose function is to support other subs and structures,
AITRG_BOATHIGHTECH - submarines with hi-tech abilities,
AITRG_BOATCYBERS - cyborgs,
AITRG_BOATINTELLIGENCE - submarines that provide information-based support,
AITRG_BOATMILITARY - submarines with any ammo
AITRG_BOATARMED - submarines with any ammo, high-tech ability or cyborgs
AITRG_BOATCIVIL - submarines extracting and transporting resources, for constructing structures or those whose function is to support other subs and structures
AITRG_BOATALL - any submarine,
AITRG_ALL - any unit.
These constants are defined the way that allows combining them to create new groups. The ST AIscript bitwise logical operations are used for this purpose.
Definition file AiScript.dfn contains copious information for each civilization about what groups contain which types of game units.
Appendix I: Constants to define formations of units
Types of formations:
FORMATION_DEFAULT - undefined formation
FORMATION_LINE - "line" formation
FORMATION_WALL - "wall" formation
FORMATION_CIRCLE - "circle" formation
FORMATION_SCIRCLE_UP - "convex bow" formation
FORMATION_SCIRCLE_DOWN - "concave bow" formation
Size of formation is set:
from FORMATION_MIN_SIZE - minimum size of formation,
to FORMATION_MAX_SIZE - maximum size of formation.
Direction of formation is set in degrees from 0 to 360. Angle is measured from the positive direction of axis X counterclockwise. The axis X coincides with the northeast border of the map. For the convenience of setting direction constants are defined in AiScript.dfn, which correlate formation direction with geographical directions:
FORMATION_DIR_N - north
FORMATION_DIR_NNW - north-north-west
FORMATION_DIR_NW - north-west
FORMATION_DIR_NWW - north-west-west
FORMATION_DIR_W - west
FORMATION_DIR_SWW - south-west-west
FORMATION_DIR_SW - south-west
FORMATION_DIR_SSW - south-south-west
FORMATION_DIR_S - south
FORMATION_DIR_SSE - south-south-east
FORMATION_DIR_SE - south-east
FORMATION_DIR_SEE - south-east-east
FORMATION_DIR_E - east
FORMATION_DIR_NEE - north-east-east
FORMATION_DIR_NE - north-east
FORMATION_DIR_NNE - north-north-east
Appendix J: Constants to define character and direction of attack
Attack type is defined with the following constants:
AIATTACK_UNDEF - undefined.
AIATTACK_HUNT - "hunt" type of attack. In such type of attack, attacking objects will aspire to destroy selected targets at any cost, not returning fire against other enemy objects. The attacking objects "fix" targets and try to pursue them using the shortest approach path (as a rule, work around are not taken). This type of attack is effective when the task is to inflict maximum damage to selected objects. Note that the attacking side may suffer greater losses from enemy defensive structures.
AIATTACK_GLADE - "glade" type of attack. In such type of attack, attacking objects destroys all enemy objects on their way to the selected target. The fleet can work around approaching targets from flanks or from the rear. This type of attack is effective in inflicting maximum damage to the enemy, the attacking objects do not expose themselves to enemy defensive structures' fire, but destroy them. The attacking fleet may not reach the selected target due to the loss of all subs enroute.
Direction of attack, work around:
AIADIR_UNDEF - direction of attack is undefined.
AIADIR_STRAIGHT - attack by the shortest approach.
AIADIR_LEFT - attack by working around from the left flank.
AIADIR_RIGHT - attack by working around from the right flank.
AIADIR_BACK - attack by working around from the rear. This value can be selected in combination with AIADIR_LEFT and AIADIR_RIGHT, which will indicate from which side they work around to strike from the rear.
Constants AIATTACK_.. and AIADIR_.. can be combined with the help of the ST AIscript bitwise logical operations.
For example,
AIATTACK_GLADE | AIADIR_LEFT | AIADIR_BACK
Appendix K: Constants to define types of artifacts
The following constants define artifact types:
TART_UNDEFINED - type is not defined,
TART_XBOX - "black" box,
TART_MICROFILM - microfilm
TART_DATA_DISK - data disk
TART_GOLD_DISK - gold disk
TART_BLUE_DISK - blue disk
TART_OPTICAL_DISPERSER - optical disperser
TART_NUCLEAR_ROCKET - thermo-nuclear rocket
TART_NON_LINEAR_PHOTON_CONCENTRATOR - non-linear photon concentrator
TART_GASEOUS_CORRELATIVE_REACTOR - gaseous correlative reactor
TART_THERMONUCLEAR_ENERGETIC_MODULE - thermo-nuclear energetic module
TART_ION_PLASMIC_ACCUMULATOR - ion plasmic accumulator
TART_STEALTH_GENERATOR - stealth generator
TART_PLASMIC_TURBOCOMPRESSOR - plasmic turbo compressor
TART_HIGH_LEVEL_GASEOUS_CONCENTRATOR - high level gaseous concentrator
TART_STEALTH_DISPERSING_BLOCK - stealth dispersing block
TART_CORIUM_296 - Corium 296
TART_ION_OPTICAL_ACCUMULATOR - ion optical accumulator
TART_POLARIZED_HIGH_TEMPERATURE_EMITTER - polarized high temperature emitter
TART_CAPSULE_WITH_SILICON_GENE_PROTOTYPE -capsule with silicon gene prototype
TART_EPI46_SAMPLE - sample EPI 46
TART_SHT17_SAMPLE - sample SHT 17
Appendix L: Constants to define conditions of game objects
Game objects can exist in certain defined conditions. The following constants are used to define these conditions:
TOBJSTATE_BOARDED - object is loaded on another object,
TOBJSTATE_ENGAGED - object is occupied by another object,
TOBJSTATE_REPAIRING - object is under repair (BO, WS) or is being recharged (SI),
TOBJSTATE_PARALYSED - object is paralyzed,
TOBJSTATE_CAPTURING - objects are under capturing attack,
TOBJSTATE_LOADING - loading/unloading resources,
TOBJSTATE_MOBILED - structure on the move,
TOBJSTATE_ON - if there is a generator it is switched on,
TOBJSTATE_PRODUCING - object is producing something,
TOBJSTATE_READY - object is ready to use (launchers).
Constants TOBJSTATE_.. can be combined with the help of the ST AIscript bitwise logical operations.
Appendix M: Constants to define changeable properties of Fleet objects
Some properties of game objects can be switched off (and then switched on) by Events Program. The following constants are used to define these properties in ST:
LOCKOBJ_DARK - object does not 'open' the Fog of War,
LOCKOBJ_ACTIVITY - does not set activity on (does not select) the object,
LOCKOBJ_INTERF - object's interface becomes inactive,
LOCKOBJ_AISELECT - object cannot be selected,
LOCKOBJ_TARGET - object cannot be selected as a target,
LOCKOBJ_ALL - all above mentioned properties.
Constants LOCKOBJ_.. can be combined with the help of the ST AIscript bitwise logical operations.
Appendix X: Names of common media components of TASKS.DKD database
Background images:
"DEFAULT_WS",
"DEFAULT_BO",
"DEFAULT_SI".
Background images with embedded animation:
"DEFAULT_WS_ANIMATED",
"DEFAULT_BO_ANIMATED",
"DEFAULT_SI_ANIMATED".
Background images for animated characters:
"FACE1_WS",
"FACE1_BO",
"FACE1_SI".
Animations for the first WS character:
"FACE1_WS_START" - character's appearance on the monitor,
"FACE1_WS_FINISH" - character's disappearance,
"FACE1_WS_SPEAK" - character's speech,
"FACE1_WS_SILENT" - character's silence.
Remarks:
All animations should be displayed over the background image "FACE1_WS" in the coordinates x=600, y=64.
Animations for the first BO character:
"FACE1_BO_START" - character's appearance on the monitor,
"FACE1_BO_FINISH" - character's disappearance,
"FACE1_BO_SPEAK" - character's speech,
"FACE1_BO_SILENT" - character's silence.
Remarks:
All animations should be displayed over the background image "FACE1_BO" in the coordinates x=32, y=72.
Animations for the first SI character:
"FACE1_SI_START" - character's appearance on the monitor,
"FACE1_SI_FINISH" - character's disappearance,
"FACE1_SI_SPEAK" - character's speech,
"FACE1_SI_SILENT" - character's silence.
Remarks:
All animations should be displayed over the background image "FACE1_SI" in the coordinates x= y=
! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !!!
All animations should be prepared in task.dkd with indicated names.
! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !!!
TV animations:
"WSFACE1",
"WSFACE2",
"BOFACE1",
"BOFACE2",
"SIFACE1".
Copyright © 2000 Ellipse Studios. All Rights Reserved. Submarine Titans is a Trademark of Ellipse Studios. No part of this documentation can be reproduced, electronically or in any other form without the express written consent of Ellipse Studios. Developed and created by Ellipse Studios.
|
