                     BATTLECRUISER 3000AD GAME BUILDER SYSTEM
                     ========================================

Last updated : 12/28/99

===============================================================================
                                TABLE OF CONTENTS
===============================================================================

1.0  INTRODUCTION
1.1   - Scripting concepts
1.2   - AI Discussion
1.3   - AG Discussion
1.4   - Race/Caste Discussion
1.5   - Importing/Creating world entities
1.6   - Restrictions in GBS 'lite'
2.0  GAME WORLD CREATION
3.0  SCRIPTING CONCEPTS
3.1   - The GBS Parser
3.2   - Layout & Syntax
3.3   - Object Identifiers
3.4   - Logical Layout & Organization
3.5   - Read Only: System Files
3.6   - Creating A MISCON Description File
3.7   - Filename Convention
3.8   - GBS File Types
3.9   - Planning & Creating Scripts
3.10  - Easy Steps For Creating Scripts
3.11  - Distributing Scripts
3.12  - Script Development Tips
4.0  THE SCRIPT & OBJECT PARSER
4.1   - Script Blocks Explained
4.2   - Parsing A Script
4.3   - Parsing An Object
4.4   - Universal Time Format
5.0  SCRIPT BLOCKS EXPLAINED
5.1   - [ACM]
5.2   - [DYNAMIC]
5.3   - [AI]
5.4   - [EVENT]
5.5   - [SETS]
5.6   - [MACRO]
5.7   - [REGION]
5.8   - [CLASS]
5.9   - [COMMS]
6.0  START/STOP 'nav' commands
      - @date|time|inactive
      - NEAR <objectA> <distance> <objectB>
      - IN <region>
      - ORBIT <object> <distance> <speed> [roll angle] [pitch angle]
      - ESCORT <object> <distance> <position>
6.1  START/STOP 'action' commands
      - CRUISE <object>
      - DOCK <object> [time]
      - FLEE
      - HYPERJUMP <region>
      - INTERCEPT <object>
      - JUMP <object>
      - ORBIT <object> <distance> <speed> [roll angle] [pitch angle]
7.0  SYSTEM EVENT TRIGGERS
      - !ARRIVED <region>
      - !CREATED <object>
      - !DAMAGED <object>,<amount>
      - !DESTROYED <victim>,[attacker]
      - !DETECT <race|caste|object>,[<...>]
      - !DISABLED <object>
      - !DOCKED <object>
      - !EXIST <object>
      - !NOEXIST <object>
      - !REACH <object>
      - !REGION_SECURE <region>
      - !STARTUP
      - !UNDER_ATTACK [object]
7.1  SYSTEM EVENT ACTIONS
      - ACM_NEXT
      - ACM_OFF <caste>
      - ACM_SKIP_ENABLE <on|off>
      - ACTIVATE <object>
      - ADD_MEDAL <0..7>,<num>
      - ADD_STORE <object>,<qty>,<itm_num>,...
      - ATTACK <object>
      - AUTOGEN <on/off> [region]
      - BROADCAST <"message">
      - CAP [region]
      - CAPTURE <object>
      - CLEAR_GUEST <id>,[officer,"message","sfx"]
      - CLEAR_INTRUDER <id>,[officer,"message","sfx"]
      - CLEAR_PRISONER <id>,[officer,"message","sfx"]
      - CLOAK <on|off|ai> [object]
      - CLOAKING <on|off|ai> [object]
      - COURTMARTIAL <on|off>
      - CREATE <num>, [set_member...]
      - CREATE_GUEST <id>,"name",<loc>,[officer,"message","sfx"]
      - CREATE_HOSTILE <race>,<caste>,<class>,<num>,[id]
      - CREATE_INTRUDER <id>,<loc>,[officer,"message","sfx"]
      - CREATE_PRISONER <id>,<loc>,[officer,"message","sfx"]
      - CRUISE <object>
      - DAMAGE_SYSTEM <ship>,<system>,<amount>
      - DEACTIVATE <object>
      - DEFEND <object>
      - DEL_STORE <object>,<qty>,<itm_num>,...
      - DESTROY <object>,<time>,<mode>
      - DOCK <object> [time]
      - EMIT_SOS <on|off|ai> [object]
      - EP_ADD [amount]
      - EP_DEC [amount]
      - ESCORT <object> [on|off]
      - FLAG1..9 <on|off> <object>
      - FLEE [region]
      - FLEETRTB [platform]
      - HALT <on|off|ai> [object]
      - HYPERJUMP <region>
      - IF/IFNOT/THEN/ELSE/ENDIF/RETURN
         HERE <object>, HERE <BC|PLAYER>, ACM <id>, EXIST <object>
         DESTROYED <object>, DOCKED <object>, EMIT_SOS <object>, CLOAK <object>
         DISABLED <object>, FLAG1..9 <object>, <object> IN <region>,
         <object> ESCORT, <object> TOWED, <object1> TOW <object2>
         <object> CONTAINS <item>, <object> TAKEOVER <race> <caste>
         <object> UNDER_ATTACK, <object> DAMAGED <amount>, CMA, EPGE <amount>
         RANK <0..4>
      - IGNORE <on|off>
      - INVINCIBLE <on|off> [object]
      - JETTISON_STORE <object>
      - JUMP <object>
      - LAUNCH [caste],<object|class>,<num>,<orders>
         LAY,SWEEP,TOW,CAP,SAD,SEAD,SAR,PATROl,ESCORT,ATTACK,DEFEND,DOCK
         JUMP,HYPERJUMP,FLEE,RECOVER
      - LAUNCHES <on|off|ai> [object]
      - LAY [region] [object_type]
      - MOD_ALLIANCE <raceA>,<raceB>,<value>
      - MOVE_ALL_STORE <objectA>,<objectB>
      - MOVE_STORE <objectA>,<objectB>,<qty>,<itm_num>,...
      - ORBIT <object> <distance>,<speed>,[roll],[pitch]
      - PATROL [region]
      - PATROLZ <object>, <regionA,<regionB>,...
      - PTEAUTOGENOBJ <region>,<class>,<map_num>,<num>,<x>,<y>
      - PTEDESTROYPLANET <planet>
      - REBUILD <object>
      - RECOVER <object>
      - REENABLE <time>
      - RESET_UNDER_ATTACK <object>
      - RESUPPLY <time> <objectA> <objectB> [crew,fuel,repair,weapons
                 ships,items_set,stores|all]
      - RTB [platform]
      - SAD [region]
      - SAR [region] [object_type]
      - SAY [officer],"message",[<"sfx">]
      - SEAD [region]
      - SET_CAREER <caste>
      - SET_RANK <0..4>
      - SIGNAL <event> [time]
      - SLAVE [on|off] <object>
      - SWEEP [region] [object_type]
      - TOW <object to tow> [deliver action] [destination] [final action]
      - WEAPONS <on|off|ai> [object]
      - VIOLATION_ADD [amount]
      - VIOLATION_DEC [amount]
      - XC_INIT
      - XC_REARM <0..9>
8.0  RESERVED SCRIPTING ID KEYWORDS
      - General Purpose
          THIS, THIS_REGION,IT,DISABLED,SOS_EMIT,LEADER,PLATFORM,TARGET,
          ANYTHING
      - Player's crafts
          PLAYER, BC, IC, SC, ATV
      - Player's personnel
          OFFICER, PILOT, MARINE, SENGINEER, FENGINEER, GUEST, PRISONER,
          INTRUDER, MEDIC
      - Interstellar objects
          FLUXFIELD, WORMHOLE, JUMPPOINT, HAZARD, PLANET, MOON
      - Object classes
          CARGOPOD, ODS, LAUNCHPAD, FIGHTER, CRUISER, CARRIER, TRANSPORT,
          SHUTTLE, CRAFT, NAVAL, STRATEGIC, TACTICAL, INTERSTELLAR,
          SPECIAL, LFCRAFT, BASE, PLANT, STRUCTURE, BUILDING, CITY, FACTORY,
          STARBASE, STARSTATION, RADAR, MARINE, TROOPS, PERSONNEL, SAM, SAL,
          VEHICLE, COLLATERAL, MISC, PROBE, SATELLITE
      - Artifacts
          HSD, ENM, ORB, TAS, KMR, TCD, PAD, RANDOM, RDECODER, JAC
9.0  ALIEN NATIONS/CASTES
      - Alien Castes
        Military, EarthCOM, Police, Marine, Raider, Insurgent, Assassin
        Mercenary, Criminal, Explorer, Colonist, Scientist, Diplomat, Trader
        Paramedic, Worker, Commercial, Journalist, Tourist, Hacker, SEngineer
        FEngineer, Hazard, Aggressive, Harmless, Anycaste
      - Alien Nations
        Terran, Syrion, Kandorian, Empirian, Vesperon, Droidan, Falkerie,
        Mandorian, Gammulan, Zelon, Valkerie, Credian, Galaxian (hidden)
      - Alien nation alliances (default)
10.0 PLAYER SHIP SPECIFICATIONS
      - Ship personnel
      - Ship locations
      - Ship systems
11.0 WORLD DATABASE
      - List of space/planet regions    (see NAVCHART.PDF)
      - List of space region jump links (see NAVLINKS.PDF)

12.0 OBJECT DATABASE
      - List of scripting objects       (see OBJECTS.TXT)
      - Object AI parameters
13.0 A SAMPLE SCRIPT
      - A complete script showing several techniques (see BC3K9800.SCR)
13.1 TRADING ITEMS DATABASE
      - List of valid trading items that can be used as object 'stores'
14.0 CREATING NEW GAME OBJECTS
      - Steps for creating 3D objects
      - Object AI parameters (embedded & scripted)
      - Importing 3DStudio or MAX object models
      - Using TED to embed object characteristics
      - Using CV3D to convert .ASC models to .3D format
      - Using PREPARE to parse object models
      - How to use new objects in BC3K
      - How to view new objects using BC3K
15.0 REPLACING GAME SOUNDFX AND MUSIC

1.0  INTRODUCTION

     BATTLECRUISER 3000AD v2.0 ships with the 'lite' version of the GAME BUILDER
     SYSTEM. It is not officially supported by 3000AD nor Interplay. This file
     will help you get an understanding of the system and how it works. You MUST
     read this file in it's entirety or you won't get anywhere.

     Where necessary, I will indicate features in the full development version
     of the GBS that are not available in this 'lite' version. For example, the
     ability to create new space and planetary regions. Feel free to experiment
     but if you try anything not documented here or attempt to alter the system
     files in shape or form, not only will you be breaching copyrights, you will
     also invalidate your runtime environment. You deserve the results of the
     outcome in any case.

     Any email or phone attempts for tech support will be ignored. You can talk
     to others in the community via the COMMLINK forum of the website. If I can,
     I will pitch in from time to time. For the price you paid for this game,
     don't expect too much by way of support for the GBS. Releasing the GBS was
     a decision I made in order to allow hardcore BC3K fans to extend the life
     of the game as they wait patiently for the sequel, BATTLECRUISER 3020AD, to
     be released in 1999.

1.1  SCRIPTING CONCEPTS

     Writing a mission script for BC3K is a very simple process once you know
     what you are doing. Things to bear in mind are:

     (a) know the world layout. The only way you are going to get a clear
     understanding is to print out the maps of the galactic regions. You will
     also need to print out the navigation links because you will need these in
     order to reference objects starting points in the region

     (b) know the alien nation relationships. For this, you would need to read
     the manual. A lack of understanding in this area can and will lead to
     scripts that are illogical and which will fall through. For instance, the
     Terrans are hostile toward the Gammulans especially the 'military' castes.
     So if you script two ships of this race/caste in the same region,
     regardless of what your script does, a combat situation will ensue (c) you
     also need to print out the list of objects (stations, ships etc), the
     trading database, the medals distribution etc.

     Using the GBS, you can create single missions or a collection of missions
     making up a scenario. You can also create scenarios with branching or
     linear storylines. There is no limit to the number of missions that you can
     create nor the number of missions that a scenario can contain. The longer
     the script, the longer it will take to parse and interpret.

     You also need to think logically. This is not your everyday run of the mill
     system. The GBS allows you to do very powerful things within the game
     world. You can alter the world itself (which is not covered or allowed in
     this 'lite' version of the GBS), the objects in it etc. There is no GUI
     here. You will be using a text editor to script the mission and then use a
     tool to parse and play it.

     All objects in the game are either DYNAMIC or STATIC. The former are
     objects that can move, make decisions, respond to external AI instructions
     etc. Examples would be a starstation or ship. These are called 'actors'.
     The latter are objects that cannot move nor respond to external AI
     instructions. Examples would be planets or jump anomalies.

1.2  AI DISCUSSION

     AI entities have internal AI logic that CANNOT be altered in any shape or
     form. It is highly sophisticated and explanation is beyond the scope of
     this document. The entire game world is interpreted and run by a highly
     classified and technologically advanced AI engine augmented by a very
     powerful Neural Net hybrid. This combination allows the entire game world
     (all 75 planets, 145 moons and 91 space regions) to be updated and
     processed in real time. The system is highly optimized and fast for what it
     does. In the Xtreme Carnage environment, you will notice that it is faster
     than ACM by a factor of 5 or so. This is because it has only 5 regions to
     update and with very few AI entities active at any one time.

     In profiling the engines, the AI processing time eclipses all others,
     including the renderer and sound engines in all tests carried out. This is
     one of the primary reasons why, even with a powerful 3Dfx card, combat
     engagements that exceed 10 ships or more in regions with planets, can grind
     even the minimum required P166 Pentium computer to very low framerates. To
     reduce processing requirements, regions you are not located in or which you
     don't have units or scripted entities in, are not updated unless something
     that requires realtime processing, is introduced. For instance, the
     station, ODS and other entities in the Mars space region are processed
     within the loop but not updated frequently. As soon as you fly there, send
     an interceptor, shuttle or probe there, processing starts to update in
     realtime. Also scripted entities created in mission scripts entering a
     region, will also activate it. You are already beginning to see how quickly
     you can bog down the system is you jump to, say, 10 hostile regions,
     activate all of them, and cause multi-ship skirmishes etc. In testing, I
     have found that a P233 Pentium runs the game quite well with all regions
     activated and with minimum activity. There is no way around this issue. It
     is the nature of the design. In order to create a game world that is
     self-sustaining, runs with or without your involvement, operates in
     realtime etc, you need this sort of technology. All games currently in the
     market concentrate on single, small, compact regions. This results in very
     fast processing but don't give you the experience of being in a vast world.
     Not to mention the fact that their definition of 'AI' is a term used very
     loosely.

     Though you can script an actor to do certain things, if your logic is
     flawed or will cause an internal conflict with the actor's goals, it will
     override your script instruction. Examples: You cannot script a Gammulan
     ship to fly escort for a Terran ship. Sure, it will tell you to shove your
     order and then proceed to engage the Terran ship. You cannot tell a cargo
     pod to fly from point A to point B because (a) it does not have engines and
     (b) it does not know 'how' to fly. You cannot tell GALCOM HQ to fly from
     point A to point B because it is in a fixed orbit around the planet Earth.
     You cannot tell a ship to dock with an asteroid because only carriers,
     stations and planetary starbases are valid docking platforms. There are a
     myriad of examples but as your scripts fail, you will come to experience
     all of them.

1.3  AUTO-GENERATION DISCUSSION

     The AI also creates entities on the fly when an if necessary. These
     entities are used to populate the world and keep it interesting. They are
     generated and introduced to the world using a high level script that only
     indicates the type of actor to create and where. Once created, the
     entities rely on their internal default AI logic for processing. These
     entities are called Auto-Generated entities or AG for short. AG entities
     can include ships in space or planets and of varying nations and castes
     depending on the script created to generate them. For instance a Terran
     Military ship created in Gammulan space will immediately engage any hostile
     Gammulan ship it finds there. A raider ship created in a region with
     diplomats will engage them etc.

     To further ease the processing requirements of the game, AG entities use
     sub-space to travel from region to region. In the game, you use either real
     or hyper-space. Using sub-space allows the AG actor to travel to it's
     target region using sub-space without activating the regions it passes
     through. For example, an AG actor moving from Earth region (Sol) to
     Nevuela region (Alpha Centauri), using real or hyper-space, will activate 4
     regions (the entire flight route. Please check the GALAXY.PCX file for a
     map). A ship moving from Alpha Cygni to Vega Eridani, will activate about
     90% of the game world! Using sub-space, the actor will appear in it's
     target region and only activate it's originating and target regions. This
     is why, up to v1.08B of BC3K, you are unable to follow actors that have
     initiated a FLEE instruction in an attempt to get home. Once they jump,
     they are removed from the game world. In v2.0, by popular demand, this is
     no longer the case. All actors will seek a friendly or neutral (to their
     race or caste) carrier, station or planet to fly to when they are
     performing a FLEE or RTB instruction. The first actor encountered is used.
     This means that you can now follow an actor all the way home...where his
     friends will be waiting for you. During the trip, you and the actor would
     have activated all regions that are traversed. In scripts, you can script
     actors to travel from place to place using real-space (JUMP) or sub-space
     (HYPERJUMP). In the former, a route is plotted and the actor will traverse
     all regions to get to it's destination. In the latter, the ship will simply
     appear in the target region without plotting or flying a route. The
     navigation system allows AI actors to plot routes that are 32 links wide.
     This was done in order to reduce the processing required for the AI actors.
     So, if you script a ship to go from LV-103 (Alpha Cygni) to Alteris (Vega
     Eridani), it won't make it because the route exceeds 32 route links.

     When writing scripts, you have the power to turn Auto-Generation on/off for
     the entire world or in a specific region. This means that if you have a
     script taking place in the Earth region and you don't want an AG actor
     mucking it up, you would de-activate AG for the Earth region for the
     duration of the script. AG actors can and while cause your scripts to have
     results that you are not prepared for. This can be a good and bad thing.

     GOOD in the sense that people playing the same mission will get different
     results each time. Not only as a result of the internal decision logic of
     the actors in the world and your script, but also by the AG actors
     introduced to the world while your script is running.

     BAD in the sense that the desired resolution of your script will most
     likely fail unless you have spent time to create instructions (in the
     script) that will take AG entities into account (if you leave AG active).
     For example, you may script a diplomat transport ship to fly from Earth
     region to Mars and deliver a cargo pod containing objects etc. While in
     transit, if the AG system generates a wing of raiders, there is a chance
     that the diplomat ship will be destroyed and never make it. If there is
     another AI actor waiting in Mars for the diplomat ship to arrive, it will
     be waiting for a long time if the diplomat is destroyed. In this instance,
     you can either disable AG in all regions from Earth to Mars, (2) use a
     script instruction (IGNORE) so that all actors ignore the diplomat actor
     and not regard it as a valid target, (3) give the diplomat a huge escort,
     which in itself can lead to a firefight in which the diplomat may get
     destroyed anyway or (4) use a script instruction (INVINCIBLE) to prevent
     the diplomat from being destroyed. These are decisions that you will have
     to make depending on the type of script you are writing.

     Though it is always a good thing to actually create an object or launch it
     from a station in a distance region and send it to the target region,
     thereby allowing it to be intercepted and create some interesting
     variations, you have to take into account the fact that it may not make it
     to the destination scripted. Also, if it cannot resolve a suitable AI
     action, it will initiate (regardless of your script) an RTB or FLEE order
     implicitly. For example you can drop an object in a region to do the PATROL
     order. If it doesn't find any threats at the end of it's pattern, it's
     going to do an RTB. If it's damaged to a certain degree, based on the AI
     skill factor (AG entities have a random skill), it will do an RTB. In both
     cases, if it was launched from a platform (station, carrier, planet), it
     will 'attempt' to return there. If the platform is no longer existent
     (station, carrier), it will seek another as previously discussed.

1.4  RACE AND CASTE DISCUSSION

     There are twelve 'known' races in the game world and 22 castes (see
     CASTES.PDF and BCALIENS.PDF).

     The AI engines directly affect the race and caste relations. Though the
     world is initialized with a default alliance matrix (see OBJECTS.TXT), you
     can override this in your script. However, you only have a high level
     access and *not* a low level one. For instance, though the Gammulans are
     hostile to the Terrans by default, using a script command (MOD_ALLIANCE),
     you can make them friendly. They can organize cookouts or go to powerball
     games together. However, a Terran raider is going to attack a Gammulan
     diplomat regardless of what the race relation is, leaving it up to the
     decision makers to sort it out. The castes themselves interact with each
     other based on their internal AI goals. A TERRAN MILITARY ship is going to
     ignore a GAMMULAN DIPLOMAT but will attack a GAMMULAN MILITARY ship. A
     TERRAN EARTHCOM ship is going to attack a TERRAN INSURGENT ship. A TERRAN
     POLICE unit is going to attack a GAMMULAN RAIDER regardless of the race
     relationship. It gets more complex at lower levels but we don't need to
     bother with that right now. These relationships are what make it possible
     for the world to continue operating regardless of what you are doing. A
     station that is scheduled to launch a patrol (or invasion) into a hostile
     region only needs to send the units (actors) to the region and their
     internal AI will take over. No additional work is involved. Even when
     scripting, to create a skirmish, all you have to do is introduce a unit to
     the region and that's it. You can script a GAMMULAN MILITARY ship to appear
     in the Earth region and GALCOM HQ will immediately launch a fighter wing to
     take it out. If the ship is within range, it will also launch missiles or
     activate it's turret firing system. You don't have to send any script
     instructions to GALCOM HQ or the ship in question. If the ship is a
     carrier, then it too will launch it's own fighters to engage the fighters
     launched at it. If a scripted ship lays mines in Earth region and GALCOM HQ
     detects the mines, it will launch a wing of fighters with MINESWEEP order
     to remove them.

     An understanding of the race/caste relation is vital to the integrity of
     the scripts. Using the powerful option of actually altering these
     relations, you can alter and tip the balance of power at a galactic scale.
     You may for instance, via a campaign consisting of several scripted
     missions and scenarios, create a diplomatic situation between one race and
     another, leading all the way up to outright hostility based on the outcome
     and resolution of the scripted missions. For instance you could script an
     ship to deliver an object to another ship somewhere. If the object is not
     delivered, you can then alter the relationship slightly between the two
     races etc.

1.5  IMPORTING/CREATING WORLD ENTITIES

     All objects in the game world, including the planets, are 3D entities that
     are created in a high level 3D program developed specifically for the BC3K
     environment. Before you start thinking of creating and importing your own
     objects, learn how to use the system first. There is a section at
     the end of this file which shows you how to do it.

     Importing or replacing a 3D world entity involves the following steps

     1. Creating the 3D entity in TED, the GBS object modeller or creating a
        3Dstudio or MAX object, exporting it to an ascii (.ASC) file and finally
        converting the ascii file and textures to the required GBS format

     2. Using TED to jam required entity vectors into the object. These include
        explosion animations, weapons etc

     3. Including entries in the GBS system files for the new entity

     4. Using PREPARE to parse the entity

     5. Copying the entity to the BC3K runtime environment and running BC3K. You
        would have to use your entity in a mission script in order to see it in
        the game.

1.6  RESTRICTIONS IN GBS 'lite'

     The 'lite' version of the GBS, has the following restrictions

     1. You will not be able to create scripts for planetary regions. You can
        only script for space regions.

     2. You will not be able to alter the default game world by creating new
        space or planetary regions.

     3. You will be able to create new objects but you won't be able to use
        them in the game. I thought about this long and hard before deciding not
        to allow it. Perhaps if I see good objects cropping up in the community,
        I may show how to actually use them in the game.

     4. You will not be able to alter the flight dynamics and attributes of 3D
        entities. Though these files are part of the distribution, by altering
        them, you risk invalidating your BC3K runtime environment. You've been
        warned. If you tinker with the system files, then you are only going to
        cause yourself aggravation.

     5. You will not be able to alter the runtime or low level AI or
        interpretation of default AI actor processing other than giving
        explicit instructions via a mission script.

     6. The [COMMS] block is not supported

     7. The [REGIONS] block is not supported

     Other restrictions may apply. If you try it and it does not work, add it
     to the list of restrictions.

2.0  GAME WORLD CREATION

     SPACE

     A space region is a 3D file created in TED. It is then parsed using PREPARE
     and imported into the game. It can contain an infinite number of regions
     linked using jump points, wormholes and fluxfields. It also contains the
     planets and moons in the region. An entry for the region is then added to
     the STATICS.SCR file which is used to identify the region when the 3D file
     is parsed. Once BC3K is loaded, the defined space regions are interpreted,
     the actors introduced and you are all set.

     All jump anomalies (jump points, wormhole, fluxfield) are also 3D entities
     and must be included in the regions. Since they are bi-directional, they
     must appear in all regions that are accessed to/from. For instance, in the
     Earth region, there is a jump point leading to Mars and vice versa. In the
     EARTHz.3D* file describing the Earth space region, there is a jump point
     with the name JMP-01. There is also an identical one in Mars with the same
     name. The same applies to wormholes. Fluxfields can have more than one
     entry/access point. If you enter the jump point in Mars you will end up in
     Earth region and vice versa. These 'links' must also be included in the
     region system script defining them or they will not be interpreted at
     runtime. This means that flying into an undefined jump point will result in
     a crash because it will be treated as a regular 3D entity.

     The engine interpreting and rendering the space world is called the Space
     Traversal Engine or STE.

     You can load the EARTHZ.3D file located in the REGIONS folder in TED and
     take a look at. In the 'lite' version of the GBS, the Earth and Centris
     space regions are included just so that you can see how it's done. Make
     sure you go into the UNITS menu and switch to 'terrain mode toggle' before
     loading the file or the scaling will be wrong. You do not need this mode
     for view normal objects.

     * Space regions have a trailing z character in their names so that they are
       different from planetary regions. For instance, the planet Earth is
       called EARTH.3D and the space region is EARTHz.3D. BC3K filenames are
       restricted to 8.3 characters, therefore regions with long names are
       abbreviated. For example, the file for the Polaris-1 region is called
       POLAR1z.3D

     PLANETARY

     A planetary region is a more sophisticated environment using other tools
     not included in the GBS. Though the 3D space region contains space and
     planetary regions, they are only placeholders which indicate their
     existence and location within the region. The characteristics of the planet
     or moon being created, the textures used for the surface, the palette etc,
     are all entered into a text file that is also read and interpreted at
     runtime. The surface is based on height map generation technology. There
     are over 100 base height maps distributed among the 75 planets and 145
     moons in the BC3K world. Interesting planets and moons are created with a
     variety of palettes and textures. Some planets even have a variety of
     climate zones ranging from arctic to temperate. Earth has artic, moderate,
     hot and desert climate zones which can be traversed if you fly north or
     south, for an extended period. Though planetary regions are populated using
     a runtime AI system, a tool called MAPEDIT is used to create game specific
     regions called Mission Zones. These can contain objects that are required
     to persist during the course of the game. Think of mzones as cities. On
     planets in the game, mzones are used to create cities, bases and other
     interesting areas. These are then manually positioned at the desired
     location on the planet using MAPEDIT. You can also use MAPEDIT to
     autogenerate mzones for any of the heightmaps on a planet. You can then
     add/remove them to your hearts content. Since BC3K employs a very advanced
     system which allows objects to be rebuilt (if they have AI parameters that
     allow them to), you can pretty much level an mzone and return several hours
     or days later to find that everything has been rebuilt.

     Once you have included a planet or moon in a 3D space region and included
     entries for it in the configuration file, you can fly into the planet and
     the system will auto-generate the height map data, creating the topology
     for the planet. You will then encounter any mzones created as well as
     actors introduced by the system or pre-defined mission script.

     The engine interpreting and rendering the space world is called the
     Planetary Traversal Engine or PTE.

     Once you have created the desired space and planetary regions, you can then
     use a high level script to define the default world entities and their
     locations. These can be stations, asteroid fields, orbital defense systems
     etc.

     The MAPEDIT tool is not included in the 'lite' version of the GBS because
     you are not allowed to alter nor create new planetary regions.

     REFERENCING GAME WORLD ENTITIES

     Once you have created an actor/entity for the world, you have to be able to
     reference it in a script. Here are some examples. You will need to know
     this information as you progress to the scripting section.

     The scripting system also gives you access to the player's own objects for
     reference purposes only. However, they will not respond to script commands.
     So, don't go scripting a player's interceptor to attack a target. Though
     you can script the player's personnel to say things and respond to scripted
     world action, you can't give them any specific orders such as in the case
     of asking the Chief Engineer to slap his Systems Engineers around for
     drinking on the job.

     OBJECT - The GALCOM HQ station is an object placed in the Earthz region.
              The filename is GALCOMHQ.3DC*

              * 3D objects have a .3D extension. Once parsed by PREPARE and all
                AI and other instructions 'jammed' into the file, the resulting
                encrypted file has a .3DC extension. This is the file that is
                then used by the game engine and which must be used in scripts.

     REGION - The Earth space region is called EARTHz.3D and the planet is
              EARTH.3DC. The trailing z character indicates a space region. All
              regions are listed in the REGIONS.TXT file.

     LINK   - A link in the Earth region, such as the Mars jump point, is called
              Earthz^jmp-01. The ^ character tells the interpreter that the link
              you are interested in, is the one in the Earth region and not the
              one in the Mars region which would be Mars^jmp-01. Since the links
              are identical because they are used to link the regions, the
              parser and interpreter need to know which one you are referencing.
              This is the referencing convention that must be used in scripts.

              If you look in the NAVLINK.PDF file, you will see all the links*
              for the regions. So if you wanted to script a ship starting in the
              Earth region, you can see that you have 9 links to choose from.
              You can also use an object in the region, other than a jump
              anomaly link, for a reference object. In the Earth region, you
              have the galcomhq station, an ODS, a planet and an asteroid field.
              You are advised to stick to using STATIC entities because they
              cannot be destroyed. If you reference an object in a script that
              is likely to be destroyed, your script will fail.

              * Jupiter, Neptune, Saturn & Uranus are broken up into smaller
                compact regions due to the number of moons they contain. The
                main region (Jupiter, Neptune, Saturn, Uranus) contains a jump
                point to the smaller regions. There are no links between smaller
                regions. This means that you cannot fly from JUPIT1Z to JUPIT2Z
                without first flying to Jupiter. The jump point link names for
                these small regions are not listed in NAVLINK.PDF but they are
                in REGIONS.TXT

3.0  SCRIPTING CONCEPTS

     To write a script, you need a plain ascii text editor such as Notepad. If
     you don't know what a text editor is, or you are trying to decide if
     Microsoft Word is a plain ascii text editor, you should stop reading now.

     I use and highly recommend TextPad, a shareware text editor available for
     download at www.textpad.com.

     Whatever editor you use, make sure that you have word wrap turned OFF.

3.1  THE GBS PARSER

     The scripting system is a high level interpreted language that is executed
     at runtime. Think of it as a DLL. The PREPARE parser takes the script,
     parses it (like a language compiler such as C++), checks for errors and
     produces a binary file that the interpreter built into the BC3K engine,
     uses at runtime. The parser has no knowledge of how illogical or
     inconclusive your scripts are. It doesn't care either. So, just because the
     script parses OK, does not mean that all is well and good. You should be
     able to read your script and tell if it's logical or not. Then, once its in
     the game, you have to pray that some AG actor is not going to render your
     script pointless (as previously discussed). During the parsing of a script,
     the parser will halt at any errors it finds and provide a line number that
     the error occured on.

     All scripts must be created from the folder in which the parser resides.

     The last line of EVERY script file MUST have the $ character. This is used
     to signal and end of file condition.

3.2  LAYOUT AND SYNTAX

     When writing a script, use indentations as well as a combination of CAPS
     and lowercase so that the logic jumps out at you. When nesting IF blocks,
     indent them so that, again, they are readable. Here is a script segment
     that illustrates this. Notice the indentation and the use of CAPS and
     lowercase syntax. As you become an expert (yeah, right), you will be able
     to look at a script block and immediately notice the logic and/or errors.

     The parser is not case sensitive so 'START' is the same as 'start', 'IF' is
     the same as 'if' and so on. If you create a script that is hard to read,
     you won't be able to make sense of it, nor will the person you are sending
     it off to.

     Though the maximum line length is 128 characters, if you have a line of
     script that exceeds the screen display, i.e., line 79, it will be hard to
     read and understand. All script commands MUST be on their own line. There
     is no line continuation.

     SAMPLE SCRIPT EXCERPT:

     [dynamic]
     vesperon diplomat,,f3,mrt15.3dc,DIPLOMAT3
     [ai]
     .f3,100,100,100,100,100,100,0
     start 120000 near canaanz^jmp-33 2000 jmp-32
     stop
     events 101
     !startup
        jump majorisz^wrm-23
        broadcast "DIPLOMAT3 LAUNCHED"
     !under_attack this
        broadcast "We are under attack!"
        reset_under_attack this
     !destroyed this
        say TO,"Vesperon diplomat3 has been destroyed"
     !arrived majorisz
        IF EXIST majoris_s THEN
         broadcast "Executing docking approach to station Majoris"
         dock majoris_s
        ELSE
         broadcast "Station Majoris not operational, returning to Eridani"
         IF EXIST eridani THEN
          dock eridani
         ELSE
          flee
         ENDIF
        ENDIF
     !docked majoris_s
         say CMO,"Vesperon diplomat3 has docked at station Majoris"
     endevents

3.3  OBJECT IDENTIFIERS

     Use descriptive names for all object identifiers. When you are writing a
     script, avoid id abbreviations such as 'f3' used above unless you are an
     expert and can keep track of this stuff without scrolling the page. If you
     are scripting multiple ships, then names like enemy_ship1, friendly_ship2
     are more descriptive than e1 and f1. The max id length is 128 characters.
     If you are creating wings, you can then use friendly_wing1 etc.

     NOTE: You *CANNOT* use duplicate identifier names in the same script, even
     if you are breaking them up. Therefore, 'enemy1' can only be used once. If
     you have, for instance, two files that are joined together using #include,
     this rule also applies because all the files are parsed as one file.

3.4  LOGICAL LAYOUT & ORGANIZATION

     Use comment lines # to separate scripted entities. This also improves
     readability. When possible, include comments in areas where there is no
     clear indication as to what is happening.

     Augmented blocks such as [sets] and [event] should always be at the end of
     the file. This also improves readability.

     If you are writing a campaign, break it up into smaller script files and
     then use the #include directive to connect them. For instance, you may have
     a 20 mission scenario and you can break it into 4 files each with 5
     missions and name them sensibly. In this example, we assume that the
     'master' script is called BC3K0200.SCR and that each of the other files
     each contain their own mission blocks.

     NOTE: The #include directive MUST be on column 1 of the line!

     You would have BC3K0200.SCR, TOD201.SCR, TOD202.SCR, TOD203.SCR and
     from within BC3K0200.SCR (usually after the comment) you would include
     the smaller files. You can use any filename convention you like.
     The parser will first parse all the included files and then move into the
     current file and parse them. This also means that you can also #include
     files at the END of the master file. This would be the case if the first
     file, BC3K0200.SCR contains 5 missions and the subsequent files contain 5
     each in sequence. Of course the master file doesn't have to contain any
     scripts at all. It can simply contain the description of the scenario
     script and lines which include the missions themselves.

     #
     # The BC3K0200.SCR master file will include 3 other smaller script files
     #
     #include tod201.scr
     #include tod202.scr
     #include tod203.scr
     #

     As your scripts get larger, they will become more and more difficult to
     read. By grouping object entities and blocks together, you will be able to
     read and understand them more clearly. In example1, all the objects are
     identified at the beginning of the script. In example2, they are identified
     when and where needed. This probably won't make sense until you start
     scripting four or more entities in a script.

     Example1

          [dynamic]
          vesperon diplomat,,f3,mrt15.3dc,DIPLOMAT3
          vesperon diplomat,,f4,mrt15.3dc,DIPLOMAT4
          [ai]
          .f3,100,100,100,100,100,100,0
          start near canaanz^jmp-33 2000 jmp-32
          stop
          events
          !startup
             broadcast "DIPLOMAT3 LAUNCHED"
          endevents
          #
          .f4,100,100,100,100,100,100,0
          start near canaanz^jmp-33 5000 jmp-32
          stop
          events
          !startup
             broadcast "DIPLOMAT4 LAUNCHED"
          endevents

     Example2

          #
          # Vesperon diplomat is travelling to Majoris/Alpha Majora
          # where it will meet up with another Vesperon diplomat
          #
          [dynamic]
          vesperon diplomat,,f3,mrt15.3dc,DIPLOMAT3
          [ai]
          .f3,100,100,100,100,100,100,0
          start near canaanz^jmp-33 2000 jmp-32
          stop
          events
          !startup
             jump majorisz^wrm-23
             broadcast "DIPLOMAT3 LAUNCHED"
          !detect f4
             broadcast "DIPLOMAT4 detected on radar!"
          endevents
          #
          # The ship will patrol Majoris until diplomat3 arrives
          #
          [dynamic]
          vesperon diplomat,,f4,mrt15.3dc,DIPLOMAT4
          [ai]
          .f4,100,100,100,100,100,100,0
          start near canaanz^jmp-33 5000 jmp-32
          stop
          events
          !startup
             jump majorisz^wrm-23
             broadcast "DIPLOMAT4 LAUNCHED"
          !arrived majorisz
             patrol majorisz
             broadcast "DIPLOMAT4 starting patrol pattern"
          !detect f3
             broadcast "Hey guys, about time!"
          endevents
          #

3.5  READ ONLY SYSTEM FILES

     All your master scripts MUST contain the system files that the world needs
     to run. You should ensure that the following block is in your master file
     after the description. You do NOT need to put these in files that you have
     broken up into smaller parts. ONLY the master file needs this. See the
     sample BC3K9800.SCR file. In the example above, this block of text would
     only be in the BC3K0200.SCR file and not the smaller TOD20x.SCR files. It
     is preceeded by your scenario description and followed by your #include
     directives if you are including other smaller script files (see above)

     #include glob_rg.scr
     [dynamic]
     #include glob_dyn.scr
     #
     [ai]
     #include glob_ai.scr
     #include glob_ag.scr
     #

3.6  CREATING A MISCON DESCRIPTION FILE

     MISCON description files are also ascii text files that have a .DES
     extension. These are used to describe the basic premise of the scenario
     created. This is the file that is displayed when the user selects a
     scenario in MISCON.

     Each line should be no more than 65 characters wide and each page should
     not exceed 30 lines or the display will overflow into the graphics area.

     Like .MIS files, the .DES description file must be copied over to the
     SCRIPTS folder where it can be accessed by MISCON at runtime.

3.7  FILENAME CONVENTIONS

     The GBS adheres to strict scenario naming conventions. There are three
     system script names that are reserved for use internally. They are
     BC3K0000.SCR, BC3K0100.SCR and BC3K9900.SCR. Unless you want to invalidate
     and corrupt your BC3K runtime environment, do not create scripts with these
     names. You can use BC3K0200.SCR up to BC3K9800.SCR. If you don't understand
     the numbering scheme, let me make it simple. You can start from
     BC3K0200.SCR all the way to BC3K0900.SCR and the next would be BC3K1000.SCR
     all the way up to BC3K9900.SCR. Missions scripts MUST have the .SCR
     extension.

3.8  GBS FILE TYPES EXPLAINED

     You will be working with the following file types, so I may as well explain
     them briefly.

     1. BC3Kxxxx.SCR

        When you parse a .SCR script file, the resulting file is the binary
        version with a .MIS extension. This is the file that BC3K runs.

     2. BC3Kxxxx.DES

        When you create a .DES description file, it is displayed, as is, when
        MISCON starts. The system checks for scenarios in the resource files
        and the SCRIPTS sub-folder and will display those that it finds. It will
        use the most recent file if a file exists in that folder and in the
        resource files. If you create a mission with no description file, it
        will not show up in MISCON and therefore cannot be played.

     3. BC3Kxxxx.TXT / BC3Kxxxx.DAT

        BC3K has multi-language support built in but was never used. The parser
        was also updated to support this system. Therefore, when you write a
        script, all strings scripted using the SAY and BROADCAST commands, are
        stored in a .TXT text file. Each time you build a script, you should
        run the parser with the 'phrases' parameter. This creates a .TXT file
        and a .DAT file. The former contains the actual strings and the latter
        contains the parsed version that the BC3K interpreter uses.

     4. .3DC (object/world)

        Object files have a .3D extension and are in a proprietary format. When
        a 3D object or region is parsed, the resulting file has a .3DC extension
        and must also be copied to the SCRIPTS folder. Unless you are creating
        your own objects, you don't need to bother with this. All the default
        objects are in resource files.

     5. GLOB_DYN.SCR, GLOB_AG.SCR, GLOB_AI.SCR, GLOB_RG.SCR, STATICS.SCR,
        OBJECTS.SCR, OBJCLASS.SCR, NAVDATA.SCR

        There are several system files that you MUST not be altered in any shape
        or form. These files are used by the parser to set up internal
        variables. If these files are altered, not only will your play world be
        invalidated, the parser won't even parse your script. You have been
        warned.

3.9  PLANNING AND CREATING SCRIPTS

     Unless you are just experimenting or modifying the sample script to your
     heart's content, there will come a time when you are going to lose it and
     attempt to create the best mission script you have ever seen. I sure hope
     you have a lot of hair left on your head. Start small, think small and
     progress. The GBS is a very powerful system and you are going to get
     carried away long before you even get your first script to run. Be patient.

     To design, write and run a good script (no script is perfect), you have to

     1.  Think about what you want to achieve in the script.

     2.  Look at the maps and figure out where it is going to take place.

     3.  Make a note of any hostile forces operating in the regions that the
         script takes place in. Such as the Insurgent station in Sygan.

     4.  Make a note of the current race/caste relations. Make a note of what
         kind of objects you are going to be using in the script.

     5.  Think up a descriptive short scenario briefing for display in MISCON
         where you get to choose the script you are about to run.

     6.  Think up short and descriptive mission orders that are going to be
         displayed in the COMMLINK computer when the particular scenario
         starts.

3.10 EASY STEPS FOR CREATING/PLAYING A MISSION SCRIPT

     1. Create the mission script in text editor and give it a name based on
        the convention already discussed in the form BC3Kxxxx.SCR

     2. Create the MISCON description file and give it a name based on the
        convention already discussed in the form BC3Kxxxx.DES

     3. Parse the script using PREPARE in the form, 'PREPARE BC3Kxxxx.SCR'

     4. Generate the strings file i.e 'PREPARE PHRASES BC3Kxxxx.SCR'

     5. Copy the parsed script file, the description file and the language
        data file, to the SCRIPTS sub-folder in your BC3K runtime environment.
        i.e. BC3Kxxxx.MIS, BC3Kxxxx.DES, BC3Kxxxx.DAT

     6. Run BC3K, select the scenario from the list in MISCON and play it!

        Once you start BC3K, the description file, will be displayed in MISCON.
        Select it and launch to run your script. You should then proceed to the
        area where your script takes place and watch it in action.

        TIP: Since a new script will ALWAYS start you off at GALCOM HQ, you can
        monitor different regions where your script is taking place by first
        giving yourself the HSD artifact. You can do this by simply putting it
        in a cargo pod, via a script and collecting the pod when you launch.
        You can then warp to any space region using your BC

        In debug mode (testers version only), you can also view any region from
        tacOPS using the menu underneath PRB-10 without the HSD.

3.11 DISTRIBUTING SCRIPTS

     To share scripts with your friends, send them the entire script set. A
     script set consists of the .SCR, .DAT, .TXT and .DES files. All they have
     to do is put the files in their SCRIPTS folder and run the game. Of course,
     since they have the source (.SCR file), they can make any modifications
     they wish, to the script and build their own variance.

     WARNING: There WILL be set name conflicts for instance if you send someone
     a BC3K0200 set and they already have their own or one from another source.
     The user will simply have to rename all the files to a vacant 'slot' on his
     system. So for instance if you send them the BC3K0200 set and they already
     have one, but have the BC3K0500 'slot' free, all they would have to do is
     rename all the files. For example 'ren BC3K0200*.* BC3K0500*.*' will do the
     trick. Of course they can overwrite any script set that they no longer wish
     to keep.

     Foreign language speakers can edit the .DES and .TXT files to match their
     language. All text displayed in MISCON and COMMLINK (generated by the
     script) will be in the foreign language. Once the .TXT file is translated
     from English to, say, German, the script .SCR source must then be parsed in
     order to generate a German version of the .DAT file.

     Finally, when writing scripts, you MUST include a comment block (you can
     cut and paste the excerpt below) at the top of the main file. This block
     will contain a brief description about the script. For more information
     about what its about, they can always read the .DES file.

     #
     # SCRIPT        Script file name, ie BC3K0200
     # NAME          Author's name
     #               list multiple authors on separate lines
     # EMAIL         email address
     # WEB           Website URL
     # DATE          Date of creation
     # NEW OBJECTS   Y | N (this will always be N, unless you have new objects
     # NEW WORLD     Y | N (this will always be N)
     # NEW SOUNDS    Y | N (this will always be N unless you have new soundfx)
     # VERSION       The version of the PREPARE parser used. This is displayed
     #               when the parser starts.
     #
     # SCENARIO      Brief description of the scenario.
     #               Use multiple lines if necessary.
     #

3.12 SCRIPT DEVELOPMENT TIPS

     Since you will be working from WIN95 or WIN98 DOS box, you can make use of
     multi-tasking and reduce stress. You cannot write five lines of a two
     thousand line scenario and expect to run it right away. Unless of course
     you are testing. You have to finish the script, parse it, run it in BC3K
     and then note any inconsistencies. If the script parses, then it will run,
     all you will be looking for are flaws in the logic (as previously)
     discussed.

     You should open your text editor as normal and create the script from
     there. Open up another windowed DOS session (with a minimum of 8MB of
     memory available in the shortcut properties) and log to the folder
     containing the parser and your script. Once you have finished writing the
     script, even if it is five lines, you simply minimize the editor and run
     the parser from the DOS window. You will then be able to catch any errors,
     hit the enter key to return to the DOS prompt (allowing PREPARE to close
     the file), make a note of the line and error type, then switch to the
     editor and correct the error.

4.0  THE SCRIPT AND OBJECT PARSER

     The PREPARE parser is used to parse an ascii script file into a format that
     can be read by the interpreter. It can also parse .3D objects and jam
     relevant AI instructions into them for use by the game engine.

     When a script is parsed, each block is access and parsed one at a time. If
     an #include directive is encountered, the file is loaded and parsed.
     Processing then continues in the original file. Prepare does multi-passes
     in order to resolve forward references. This means that an object can be
     scripted to reference an object that is probably not even in scope at the
     time of interpretation.

     Blocks can be arranged in any order but for clarity, you must follow the
     convention and be consistent. If you script the [ai] block for an actor
     and then it is followed by instructions that are only valid in a [dynamic]
     block, an error will occur. You must ensure that your script line is in
     context with the block being parsed. This is why, in the previous section,
     you were advised to let each actor have it's own [dynamic] and [ai] block.
     The [sets] and [event] blocks should be last in the file. If you put event
     identifiers in a [sets] block and vice versa, an error will occur.

     PREPARE expects all files to be terminated with the $ character. This tells
     it that an end of file has been reached.

     All blocks MUST be on column 1 of the line. This also applies to the files
     included with the #include directive.

     When an error is encountered, PREPARE will terminate with an explanation
     and possibly a line number containing the error. If the line is correct
     then you must check that the command is in context with the relevant block.
     A typical mistake would be to be putting [ai] block commands in [dynamic]
     blocks etc.

4.1  SCRIPTING BLOCKS

     Each game script can contain definitions for objects, regions and even
     AI processing information for those objects and regions. A script is
     divided into separate blocks which determine how each actor/entity is
     handled.

     There are system and mission scripts with the only difference being that
     mission scripts actually contain orders and goals for the entities created.

     Mission scripts can include system scripts which contain definitions for
     the game universe itself.

     Each script command MUST be on its own line. There is NO continuation
     character for script lines. So if you have word wrap turned on in your
     editor and it causes a lengthy command, ie "broadcast", to wrap to the
     second line, the PREPARE parser will choke. In general, you should always
     have wordwrap turned OFF in your editor but remember to adhere to the
     maximum line limit for script commands and the [ACM] scenario description
     block (see below).

     Script blocks in GBS 'lite' are :

     [dynamic]     - definitions for dynamic entities
     [ai]          - goal related instructions for defined entities
     [event]       - scripted events identifiers
     [macro]       - macro definitions for entities and commands
     [sets]        - defines sets of entities
     [acm]         - ACM orders and definitions block
     [region]      - Region specific definitions*
     [comms]       - Two way communications block*

     *not supported in GBS 'lite'

4.2  PARSING A SCRIPT

     Once you have written a script...

     (a) Parse it to produce a valid binary file used by the interpreter

     i.e. 'prepare <filename.scr>' (no quotes!). This creates FILENAME.MIS,

     (b) Create a new strings definition file if you created new strings

     i.e. 'prepare phrases <filename.scr>'. This creates FILENAME.TXT and
     FILENAME.DAT.

4.3  PARSING AN OBJECT

     Not available in GBS 'lite'

4.4  UNIVERSAL TIME FORMAT

     There is a universal time format that can be used in [acm] and [event]
     blocks.

     <minutes> eg 10 = 10 minutes, or
     <hours>:<minutes> eg 1:30 = 1 hour and 30 mins = 90 minutes, or
     <days>:<hours>:<minutes> eg 1:4:10 = 1 day 4 hours 10 mins = 1690 minutes

     The parser will not allow certain dubious times, for example

     180 minutes (3 hours) can be specified as follows:

     180      <--- ok
     0:0:180  <--- ok
     3:0      <--- ok
     0:3:0    <--- ok

     2:60     <--- invalid
     1:120    <--- invalid

     Similar restrictions apply to hours (must be < 24) if days are specified.

     For convenience, days can be specified as:

     4:: <-- 4 days

     Times of zero are not allowed.

5.0  SCRIPT BLOCKS EXPLAINED

     LEGEND

     < >       indicates a mandatory field
     [ ]       indicates an optional field
     < >,< >,  indicates a collection of mandatory fields
     [< >,< >] indicates a collection of optional fields

5.1  [ACM]

     This is usually the first block in a script. It defines the scenario region
     and also displays the mission instruction to the player. You can have as
     many [ACM] blocks as you like with varying duration. Each block will define
     a new mission.

     The maximum character length for the ACM block is 65. So, you should turn
     on wordwrap at line 64 and end all lines with hard breaks. There is no word
     wrapping when this block is displayed in COMMLINK at runtime. If you fail
     to do this, then the mission description displayed in COMMLINK will not be
     formatted properly.

     SYNTAX

     [acm]
     <orders description>
     :<acm_id>,<theatre>,<setup_event>,<begin_event>,<resolve_event>,<acm_tick>
      <time1>,<time2>,<time3>

     <orders description>

     Text describing the ACM scenario. Must not exceed 65 characters per line.
     There is no restriction on the number of lines because this is displayed in
     COMMLINK. You are advised to keep it short as possible but enough to
     clearly explain the goals of the mission. You CANNOT have a blank line
     within this field. If you want to insert a blank line in order to make the
     description readable, put a period (.) in column 1 of the line.

     The next line, preceed by a colon character, is the ACM definition line
     which consists of 9 parameters. ALL parameters MUST be provided and the
     entire definition MUST be on one line. So, if you have word-wrap turned on,
     turn it off or this line will wrap at the predefined column setting for
     your editor.

     <acm_id>

     This is an identifier for the current mission within the scenario. It can
     be any positive non-zero value. Example, mission 1 in TOD 1 containing
     several missions can be identified as 101, 102, 103...etc

     This id is also used in the events/endevents block in order to restrict
     processing for the particular ACM scenario only. If you fail to use this
     id, then ALL events will be fired within ALL [acm] blocks instead of just
     the current one. See SECTION 5.4 [EVENT] for more on this.

     The ACM id can be used in an IF/IFNOT statement as well in order to test if
     the condition is true/false for the current ACM scenario.

       IF ACM 101 <command>

     meaning: if the current ACM scenario is 101 do <command>

     <theatre>

     is where the mission scenario starts, it must be a valid region name. This
     is where the player has to go for the ACM events (see below) to be fired.

     <events>

     setup_event   : signalled just before the time1 timer is started
     begin_event   : signalled just before the time2 timer is started
     resolve_event : signalled after time2 has expired

     These are 'one off' events equivalent to user defined events specified in
     an [event] block. They can be signalled using the signal keyword just like
     other user defined events if necessary. An error is issued if the event
     names are already defined or are keywords. These can be any string name you
     choose but try to use short and descriptive event names that are easy to
     remember.

     You can use these events anywhere in your script within an events/endevents
     block.

     The 'setup_event' is rarely used.

     In principle, you ALWAYS want to use the 'begin_event' in your scripts so
     that all actors pertaining to this scenario are activated when the CURRENT
     scenario starts.

     The 'resolve_event' is very important because it signals the end of the
     scenario. You can use it to determine what happens when the scenario is
     finished. You can then do normal cleanup using this event. An example would
     be to send an RTB order to all surviving ships etc.

     <acm_tick>

     is an event called every 5 seconds & used to terminate/control scenario
     using above conditional statements. A 'tick event' may be placed in any
     object, but the usual use would be to place the event in a persistent
     object which lasts for the duration of the ACM scenario. You can also use
     this tick in an event/endevents block for checking events every 5 seconds.

     EVENT TIMERS

     <time1>:The max arrival time, the time allowed for the player to reach
             the theatre before the scenario starts, if the player
             doesn't get there in time the scenario will begin without him after
             this time has elapsed. If the player reaches the theatre in this
             time, the scenario will begin as soon as he arrives.

     <time2>:Scenario time, the time the player is allowed to resolve the
             scenario before it is resolved for him. The scenario will always
             take this amount of time even if the player has suceeded in
             destroying the bad guys etc. The player cannot request new orders
             until this time has elapsed.

     <time3>:Scenario interval time, this is the max time the player can lick
             his wounds between scenarios before he will get new orders from
             Galcomhq. During this time, the player can "request new orders"
             This terminates this interval delay and starts the next scenario.

     The 'time2' variable is vital because, in conjunction with the
     'resolve_event', it determines when the scenario ends. Sometimes, you won't
     know how long a scenario will take. You should estimate how long you think
     it would take and then add 15 minutes to this time. Even if there is excess
     time left over and the player is idle, you can always use an 'event' to
     trigger the next mission using the 'resolve_event' event timer. For
     example, if you estimated that the player would take 15 minutes to destroy
     a target and he finishes in 5, you can use an event trigger (perhaps in the
     object he is sent to destroy) and a combination of the 'acm_next' command
     to start the next mission without having him wait around for 10 minutes
     plus whatever 'time3' is set to.

     NOTE: * Normally, you would use minutes in an [acm] block for simplicity.
           * Refer to SECTION 4.4 for notes on the universal time format

     USING COMMENTS

     Comment lines (lines starting with #) are skipped. Orders text lines cannot
     be blank since these are eaten by the parser, to specify a blank line (for
     spacing the orders neatly), place a . (period) at the start of the line.
     The entire line will be replaced by a blank line ("").

     Multiple acm blocks are allowed, but for safety, each must be a complete
     mission scenario (orders text and :params) otherwise an "acm definition is
     incomplete" error is issued. This message will appear if there is spurious
     text after a :params line.

     ACM TRIGGERED ALERT CONDITIONS

     Condition is YELLOW until player arrives at theatre or timeout
     Condition is RED while scenario is in progress

     NOTE: The internal low level alert condition, i.e, the CAS and SAS alerts,
     takes precedence over the ACM alert condition.

     Fresh orders can be requested by the player using ALT-CTRL-C if this
     enabled with the 'acm_script_enable' command.

     In debug mode, current ACM number,state and date of next event is
     displayed above the SCRIPT line. ACM state is

        0 = No ACM,    (only when no ACM script)
        1 = ARRIVAL    (until player arrives)
        2 = INPROGRESS (duration of scenario)
        3 = RESOLVED   (until new orders requested/received)

     The first mission is issued one minute after the game starts for the first
     time.

     EXAMPLE

     [acm]
     CAMPAIGN.................TEST TOD1
     THEATRE OF OPS...........EARTH/SOL
     MISSION CLASS............LONG RANGE TOW/DELIVER TEST
     .
     A diplomat ship is starting in the Canaan region.
     .
     You have 5 mins to get to the area before the scenario starts.
     This scenario will run for 30 mins before it is auto-resolved.
     You have 15 mins downtime to the next mission.
     .
     :101,earthz,setup_tod1,begin_tod1,resolve_tod1,tod1tick,5,30,15
     #

5.2  [DYNAMIC]

     -- OBJECT DYNAMIC DEFINITION --

     SYNTAX:

     [dynamic]
     <race>,<caste>,[<skill>],<id>,[<file|class>],[<CVD name>]

       <race>

       The race is mandatory and can be any valid race, ie

       TERRAN, SYRION, KANDORIAN, EMPIRIAN, VESPERON, DROIDAN, FALKERIE,
       MANDORIAN, GAMMULAN, ZELON, VALKERIE, CREDIAN

       The race can also be:

       MIXED meaning it is not "owned" exclusively by a single government, or
       that it has no ownership (eg a comet) It is neutral.

       ALLY meaning that the object is any race that is allied to the terrans
       picked at random when the object is created

       ENEMY meaning that the object is any race that is an enemy of the terrans
       picked at random when the object is created

       NEUTRAL meaning that the object is any race that is neutral to the
       terrans picked at random when the object is created

       ANYRACE meaning that the object can be any race picked at random when the
       object is created.

       <caste>

       The caste is mandatory and can be any of the following :

       EARTHCOM, POLICE, RAIDER, CRIMINAL, INSURGENT ASSASSIN, MILITARY,
       MERCENARY, MARINE (Note: these are all aggressive castes)

       WORKER, SENGINEER, FENGINEER, PARAMEDIC, SCIENTIST, HACKER, DIPLOMAT,
       TOURIST, EXPLORER, JOURNALIST, COLONIST, TRADER, COMMERCIAL (Note: these
       are all harmless castes)

       HARMLESS  : Any harmless caste picked at random

       AGGRESSIVE: Any aggressive caste picked at random

       ANYCASTE  : Any caste picked at random from HARMLESS and AGGRESSIVE types

       [<skill>] : The skill is optional and used to define the skill level of
                   the object. If not specified, a random skill level is
                   generated which is made up of several skill related
                   attributes. Though this field is optional, use a comma place
                   holder instead of a 1 to 5 value to indicate that you want
                   the interpreter to pick a random skill.

                   Valid skill levels are from 1 (low) to 5 (high)

                     SUPERACE  : Highest
                     ACE       :
                     VET       :
                     CADET     :
                     NOVICE    : Lowest

       <id>         : This is mandatory. Each object in a script MUST have a
                      unique identifier which is used to reference it. This
                      identifier MUST be unique in the script it is defined in
                      as well as in any other scripts that are linked to the
                      current script using the #include directive. For instance,
                      you can't have 'ship1' in the current script as well as in
                      a script that is linked to the current script. You can
                      however use this identifier in any other script set that
                      is not linked to the current one.

       <file|class> : This is mandatory and can be the .3DC filename of any
                      valid object in the game or a class of object (advanced
                      users). ie BCRUZMK2.3DC (object) or BATTLECRUISERMK2
                      (class) can be used. See OBJECTS.TXT file for a list of
                      valid objects. Don't be concerned with the class at this
                      time.

       [<cvd name>] : This is optional and overrides the actual 'filename' of
                      the object being used. An object with a filename of
                      BCRUZMK2.3DC will be listed as BCRUZMK2 in the CVD. To
                      change it to something else, ie 'primary target' use this
                      parameter.

       [<ship name>]: Optional name of ship

       [<cmdr name>]: Optional name of commander. This can be any string of
                      your choice. To use a space, use the underscore character.

     EXAMPLE

     [dynamic]
     terran,military,,id,bcruzmk2.3dc,primary target,enterprise,Cpt_Picard

     EXPLANATION

     terran,military,1,id,bcruzmk2.3dc,star_ship,enterprise,capt_Picard
      \     \       \  \      \            \          \      \__ [commander]
       \     \       \  \      \            \          \________ [ship name]
        \     \       \  \      \            \__________________ [cvd name]
         \     \       \  \      \______________________________ <.3DC file>
          \     \       \  \____________________________________ <script id>
           \     \       \______________________________________ [skill]
            \     \______________________________________________ <caste>
             \___________________________________________________ <race>


5.3  [AI]

     The [ai] block contains AI processing commands for all entities within the
     script. Each entry within an [ai] block must reference an identifier in the
     [dynamic] block. All parameters are mandatory! The object's definition
     determines its attributes when created.

     SYNTAX

     [ai]
     .<id>,<shield>,<armor>,<engine>,<weapon>,<lnch bay>,<reactor>,<cloak>
     [FACE <id>]
     START <parameters>
     <nav action>
     <nav action>
     STOP
     EVENTS [<acm_id>]
     !<event id>
       <command>
     !<event id>
       <command>
     ENDEVENTS

     The actions/orders which the object can perform must be nested within and
     EVENT and ENDEVENTS block. The EVENT syntax must also contain an identifier
     which references the scenario in which the event is triggered. You can have
     as many event ids and commands within the 'event block' as you like, as
     long as they are logical and make sense.

     Every event MUST be on a separate line and preceeded by the ! (exclamation
     mark) character which MUST be on column 1 of the line.

     You can place an event id anywhere within the EVENTS/ENDEVENTS block. The
     location within the block does not matter. See SECTION 5.4 for more on
     events.

     An <event id> can be any of the three defined in the [acm] block or a user
     defined event that you create. See SECTION 5.4 for more on user defined
     events.

     The <acm_id> is a numeric value which is defined in the ACM syntax line.
     See SECTION 5.1

     The events between EVENTS and ENDEVENTS are only processed if the
     current ACM scenerio is equal to <acm_id>, otherwise they are all fired
     when the scenario starts. If you don't provide an <acm_id>, then the
     default value of 0 is used. This means that these events are processed for
     all acm scenarios.

     When the block is processed by the interpreter, ALL the <commands> defined
     for an <!event> are fired at the same time and in order. There is no pause.
     Therefore if you the first command you give the 'jump' order and the second
     command is 'halt', then the object will jump to the region and then halt
     when it gets there. Because all <commands> are processed, you can use the
     very powerful IF conditions within <!event> blocks to determine when a
     command is fired.

     WARNING: You MUST use an <acm_id> parameter when creating scripts that span
     several ACM missions in a single scenario. Failure to do this will result
     in script commands for the ENTIRE script to be fired at once. So for
     instance if you have two scenarios with the 101 and 102 ACM identifier (as
     explained in the [acm] block above) and you fail to include these
     identifiers for the events, once the script is started ALL the events for
     both missions will be fired at once. This is a sure fine way to create
     unpredictable scripts. If you only have a single ACM mission, then you can
     safely omit this parameter.

     BLOCK CONTINUATION

     AI block continuations are also allowed. To continue scripting an object
     (possibly in a different file) use the following syntax in any
     [ai] block.

     Example, I need to add new directives for 'objectA', which is defined
     somewhere in the current script file or in another file that is INCLUDED by
     the current one using the #include directive. So I would simply create new
     events for this actor within another actor's block or by itself.

     Lets assume that this block is the original definition for the object
     (where it was first created) in the current or other script file.

     [dynamic]
     terran military,,objectA,lrt10.3dc
     #
     [ai]
     .objectA,100,100,100,100,100,100,0
     FACE karl.pcx
     start inactive near earthz^jmp-12 2000 jmp-11
     cruise earthz^jmp-11
     stop
     events 101
     !begin_tod1
       activate this
     !reach earthz^jmp-11
       broadcast "Arrived at Jump Point 11 in Earth region"
     endevents

     Now, lets assume that further down in the current script file or in another
     file that is linked to this one using the #include directive, that I want
     to create additional orders that this object can perform either during
     the processing of the current ACM (id is 101) or when another is active, I
     would simply reference it by including its id in a new [ai] block (eg1) or
     in a block (eg2) already defined for another object. In which case, I would
     do the following.

     eg1:

     In this example (somewhere further along in the current or different script
     file) the continuation is in its OWN [ai] block. This is valid. You can
     even insert it AFTER the [dynamic] block for objectA but that would be BAD
     scripting practice because it makes it harder to read and is confusing.
     TIP: Always try to pair the [dynamic] and [ai] blocks for the entities they
     are created for.

     [dynamic]
     terran military,,objectB,generis.3dc
     [ai]
     .objectB,100,100,100,100,100,100,0
     start inactive near earthz^galcomhq 5000 jmp-11
     stop
     events 102
     !begin_tod2
       activate this
       broadcast "Standing by"
     endevents
     #
     [ai]
     .objectA
     events 102
     !begin_tod2
      rtb
      broadcast "Returning to base"
     endevents

     eg2:

     In this example, the continuation is within ANOTHER object's [ai] block.
     This is perfectly valid because the [ai] block for objectB is 'in scope'.
     If there was another block, ie a [dynamic] block in scope (eg3), then I
     would be forced to use the method in eg1 other the parser will flag it as
     an error.

     You could even insert an [ai] block definition before the .objectA
     identifier on line 13 of the script (after the comment separator) and it
     would be valid. This would be only to make it readable but it is valid.
     Why? Because even though you have an [ai] block for objectB and the one for
     objectA comes after, 'an' [ai] block is in scope, making the operation
     perfectly valid.

     Also, as you can see from the examples that you do not need to provide the
     'AI definition flags' for objectA (when continuing) because you had already
     provided them when the object was first created in eg1. All you need is the
     id for objectA (the actor in question).

     [dynamic]
     terran military,,objectB,generis.3dc
     [ai]
     .objectB,100,100,100,100,100,100,0
     start inactive near earthz^galcomhq 5000 jmp-11
     stop
     events 102
     !begin_tod2
       activate this
       broadcast "Standing by"
     endevents
     #
     .objectA
     events 102
     !begin_tod2
      rtb
      broadcast "Returning to base"
     endevents

     eg3:

     This is an example of what NOT to do. If you use this method, the parser
     will flag it as an error because the [dynamic] block for objectB is in
     scope and therefore you MUST use the method in eg1 to continue the orders
     for objectA. To make this valid (but a BAD scripting practice), you would
     insert an [ai] block definition on line 3 of the script. This would put
     the [ai] block for objectA and objectB in scope with no problems.

     [dynamic]
     terran military,,objectB,generis.3dc
     .objectA
     events 102
     !begin_tod2
      rtb
      broadcast "Returning to base"
     endevents
     #
     [ai]
     .objectB,100,100,100,100,100,100,0
     start inactive near earthz^galcomhq 5000 jmp-11
     stop
     events 102
     !begin_tod2
       activate this
       broadcast "Standing by"
     endevents
     #

     If you are going to be defining a continuation for another ACM mission id
     (102) (as I did in eg1) then I would need to provide the <acm_id>. For a
     secure script, even if the continuation is for the current ACM mission that
     is in scope (currently running and has not yet reached the 'resolution
     phase'), you MUST always provide the <acm_id>, this way, you are certain
     that the object is going to perform as scripted (subject to its own
     internal AI overrides of course)

     If the object is out of scope, i.e destroyed, docked etc, the entire
     process will simply be ignored because it won't find the actor. This can
     happen if you scripted a ship in, say in an earlier ACM mission and it got
     destroyed by the time it was called again in another future ACM mission.

     TIP: This permits me to mention here that if you are going to script
     entities that are to be preserved for an extended period, since you don't
     know if they will be around by the time they are needed again, it is always
     wise to either make them indestructible or use a combination of IF flags to
     see if its in scope or not. This way, your script won't fall through. An
     example would be if you scripted a transport to go from Earth to Mars in an
     ACM mission. Then several missions later, you want it to return home or
     perhaps you want the player or another AI actor, to interact with it. If
     your script relies on this sort of action, it will faill if the ship was
     destroyed in the interim. See what I mean?

     AI DEFINITION FLAGS

     The object's ai definition lists its attributes that it is created with.
     Each entry MUST be preceeded with a period indicating the starting of the
     object's definition. Though all parameters are mandatory, some are ignored
     in objects for which they are not applicable, ie asteroids do not have
     weapons, fighters do not have launch bays etc.

     The integrity level displayed for the object in it's TTD is the mean of
     it's ENGINE, WEAPON, LAUNCH BAY and REACTOR levels.  When hit, damage is
     applied to one of these systems at random and based on the proximity of the
     hit. If the mean of these systems is less than 15, the ship will be
     disabled. For a station, if it reaches 25, it will emit an SOS signal
     allowing it to be captured.

     <id>      :  Identifier created in [dynamic] block, used to reference
                  object Each object in a script MUST have a unique id.

     <shield>  :  The object's shield level. This offers a level of protection
                  to the object. When hit, the shield absorbs the damage. If
                  breached, then the armor and subsequently the object itself
                  will take damage.

                  0 (no shields) - 100 (full shields)

     <armor>   :  The object's armor level. This offers a level of protection
                  to the object. When hit, the armor absorbs the damage if the
                  shields are down or have been breached. If breached, then the
                  object itself will take damage.

                  0 (no armor)   - 100 (full armor)

     <engine>  :  This parameter affects the object's turn performance and the
                  recharge rate of it's jump engines. The lower the engine's
                  integrity, the worse the performance of the ship.

                  0 (no engines) - 100 (fully operational)

     <weapon>  :  This parameter affects the integrity of the ship's weapon
                  systems. If this value is less than 25, the guns won't fire
                  and missiles cannot be launched.

                  0 (no weapons) - 100 (fully operational)

     <lnch bay>:  This parameter affects the integrity of the ship's launch
                  bays. If this value is less than 25, support ships such as
                  fighters and shuttles cannot be launched.

                  0 (no launches) - 100 (fully operational)

     <reactor> :  This value affects the integrity of the ship's reactor system.
                  Though reactor performance is not modelled, if this value
                  drops to 0, regardless of the state of the other systems, the
                  ship/station will explode and be destroyed.

                  0 (reactor breach) - 100 (fully operational)

     <cloak    : This allows the ship to be cloaked when created if it has
      flag>      cloaking capabilities. If the ship's integrity falls below 65%
                 it will decloak and recloak once it's repaired. Ships that have
                 cloaking capabilities will use it based on their skill level.
                 However, once a ship launches a weapon or another ship, it will
                 briefly decloak and eventually recloak. A ship's cloaking is
                 activated using the 'CLOAK' script command. This flag does NOT
                 cause the object to be cloaked when created. It just says that
                 the object has a cloaking device and that it can use it as its
                 AI permits. You can cloak any object even if the parameter is
                 set to 1 because the 'CLOAK' script command does not check to
                 see if the object has this flag set to 1.

                 0 (no cloak)  - 1 (cloak capable)

     OBJECT ATTRIBUTES

     An object can have several valid attributes which augment it's definition.
     So far only FACE is supported. All attributes must appear after the object
     definition but before the beginning of the START block. When this optional
     parameter is used, any communication from the object, whether scripted or
     generated by its internal AI, will be accompanied by the image of the
     person defined. It is displayed in the NID computer or somewhere in tacOPS.

     FACE <filename.pcx>  : The image used for ship's pilot during broadcasting

     These are the only images that are supported. See BCALIENS.PDF for images
     and descriptions of these people.

       NAME            RACE            RANK/ROLE               .PCX FILENAME
     ========================================================================

     Karl Renies       Terran       Supreme Commander              KARL.PCX
     Mark Stryker      Terran       Fleet Commander                MARK.PCX
     Randy Karynia     Terran       Tacops Commander               RANDY.PCX
     Jack Dearth       Terran       Tacops Commander               JACK.PCX
     Nat Mason         Terran       Strategic Commander            NAT.PCX
     Ugo Ra-Zin        Empirian     Strategic Commander            UGO.PCX
     V'lith R'ar       Vesperon     Vesperon military rank         VLITH.PCX
     Alin Tin          Credian      Credian military rank          ALIN.PCX
     Vli Ron           Falkerie     Falkerie military rank         VLI.PCX
     Tani Shar         Syrion       Syrion military rank           TANI.PCX
     Mega Byte         Droidan      Droidan military rank          MEGA.PCX
     Z'tar Ka-Hi       Kandorian    Kandorian military rank        ZTAR.PCX
     Z'dan Nad         Valkerie     Valkerie military rank         ZDAN.PCX
     C'tha Ma          Mandorian    Mandorian military rank        CTHA.PCX
     Z'gar             Zelon        Zelon military rank            ZGAR.PCX
     Darien Mane       Gammulan     Gammulan Leader                DARIEN.PCX
     Gla Zir           Gammulan     Gammulan military rank         GLA.PCX
     Rygan             Gammulan     Gammulan military rank         RYGAN.PCX
     Tanis Veer        Gammulan     Gammulan military rank         TANIS.PCX

5.4  [EVENT]

     You already know that you can use the [acm] block event identifiers within
     the EVENT/ENDEVENT section of the [ai] block in order to make entities do
     interesting things. So far, in the examples you have seen in the previous
     sections, only the [acm] identifiers were used.

     Also, the event identifiers in the [acm] block are checked at a
     predetermined time and the <acm_tick> event is fired every 5 seconds. What
     if you wanted to create your own events that you can check at whatever
     interval you choose?

     Enter the [event] definition block. Don't confuse this with any other
     block. This block is used to register user defined timer events which occur
     once or in a user defined cyclic (repeated based on a timed pattern)
     sequence. In this block, you can create events that you can use in ANY
     object's [ai] block.

     The [event] definition block may appear anywhere in the script, and forward
     references are allowed. There may be more than one [event] definition block
     and subsequent blocks augment the last [event] block. Though you can put
     this block anywhere in the file, you must make it common practice to put it
     at the END of the file. This way, if you want to add/remove and event id,
     you know where to look.

     SYNTAX

     [event]
     !<event_identifier>            // user defined identifier
     [<date>[,<repeat interval>]]   // date, repeat etc

     The leading ! character indicates that the string is an event identifier.
     Internal event identifiers (See SECTION 7.0) are already registered
     internally and need not be registered here. This block is only for
     registering external user defined events which trigger specific actions
     determined by the script.

     The event identifier is equivalent to predefined event names and can be any
     string. The <event identifier> may NOT be a keyword nor the name of a
     previously used actor identifier.

     Optional lines following the event identifier are dates at which the event
     is signaled. For each date, an optional repeat interval (in minutes) can be
     specified. The event will be signaled on the date/time specified, and then
     again repeatedly every <repeat interval> minutes. If the <repeat interval>
     is not specified the event is signalled only once. Several lines may be
     used to list more dates/intervals when the event is signaled, until an ! is
     found which starts the definition of a new event. This is called a CYCLIC
     event. Once this type of event is fired, it will continue to be signalled
     indefinitely or until the pre-defined date expires.

     The cyclic timers are optional, in which case the event is not signaled by
     time, but by a signal action.

     EXAMPLE

     User defined events can be signaled at any time within the [ai] block of
     any object by using the 'signal <event_id>,[<time>]' script command within
     another event. You can have as many commands within an event as you like.
     You can even create an event loop if you'd like. Just make sure you get the
     timing right.

     eg1

     In this example:

     - The !saythis1 event is fired immediately (no time given) when the
     !begin_tod2 event is fired. Once fired, the 'broadcast' command defined for
     the event, is fired.

     - The !saythis2 event is fired 5 minutes after the !begin_tod2 event is
     fired.

     - The !saythis3 event is fired 2 minutes after the !saythis2 event is
     fired.

     - The !saythis4 event is fired every 6 minutes once its called for the
     first time. Giving 0 as the date, signals it at the current date/time. To
     schedule another date, refer to SECTION 4.4 on how to use the unversal
     date/time format. The commands may seem strange to you because you don't
     know about them yet. But, I have used an IF condition in this cyclic event
     so that certain conditions are tested every 6 minutes. Every 6 minutes,
     objectB checks to see if the player's BC is in its current region. If this
     is true, then it powers up its engines, arms its weapon systems and attacks
     the player. If not, it broadcasts a message until it is fired again, 6
     minutes later. You will also notice that I use the !resolve_tod2 ACM
     event to allow this object to go home. I also remembered to tell it to
     activate its engines and systems. This is a safeguard because if the player
     never shows up this region, then objectB will never be able to fly nor fire
     weapons. This means that when the ACM scenario resolves, it won't be able
     to leave.

     - Notice that even though objectB was the one that fired the !saythis3
     event, objectA can also do something because that event is also defined
     within its event definition. In this case, objectA will perform two actions
     once the event is fired. WARNING: If I had defined the cyclic !saythis4
     event for objectA, the script would still work but the logic would be
     different! Why? Because the FLEE command tells objectA to leave the area if
     the player's BC shows up. But wait! Since the FLEE command causes it to
     leave the current region and the event is cyclic, every 6 minutes, objectA
     will check its current region for the BC and if its there, it will
     again perform a FLEE to another region. Cool huh?

     Notice also that in the [event] block definition, the cyclic event timer
     only pertains to !saythis4 because it was defined immediately AFTER the
     event it was defined for. Had I placed it BEFORE !saythis4, then the
     !saythis3 event would be cyclic and !saythis4 would be a normal event that
     is fired once only.

     [dynamic]
     terran military,,objectB,generis.3dc
     [ai]
     .objectB,100,100,100,100,100,100,0
     start inactive near earthz^galcomhq 5000 jmp-11
     stop
     events 102
     !saythis1
       broadcast "standing by"
       !saythis
     !saythis2
       broadcast "still standing by"
       signal saythis3,2
     !saythis3
       broadcast "stopping all engines"
       broadcast "weapon systems now off"
       halt on this
       weapons off this
       signal saythis4
     !saythis4
       IF HERE bc THEN
        halt off this
        weapons on this
        attack it
       ELSE
        broadcast "Player not detected in current region"
       ENDIF
     !begin_tod2
       activate this
       broadcast "Standing by"
       signal saythis1
       signal saythis2,5
     !resolve_tod2
       halt off this
       weapons on this
       rtb
     endevents
     #
     .objectA
     events 102
     !saythis3
       IF HERE bc THEN
        broadcast "I'm outta here!"
        flee
       ENDIF
     endevents
     #
     [event]
     !saythis1
     !saythis2
     !saythis3
     !saythis4
     0,6
     #
     $

     Using events, you can create some pretty advanced and complex event
     conditions. In the next example, I use this trick to simulate a
     conversation among the BC crew during a scenario. Notice that I use the ACM
     !todtick (called every 5 secs) to check for the ship. If found, thats what
     triggers the dialogue. Notice how I use timing sequences to simulate
     conversation where someone says something and some time passes before
     someone else responds. Because the commands are fired all at once but are
     processed in order, everyone will speak one after the other in some
     instances.

     This is a script fragment so some definitions are missing. Notice
     the use of the FLAG1 in the 'reingard' actor. Since the !tod1tick is
     processed every 5 secs, I don't want the dialogue repeated. So, I use this
     flag to get out of the event loop once its been set, i.e. the dialogue has
     already been played once.

     eg2

     events 102
     !todtick
        IF FLAG1 reingard RETURN
        IF HERE bc THEN
         say CO,"We seem to have located the Reingard commander"
         say CO,"Scanning for vital signs now..."
         signal found_reingard,4
         signal talk1,1
         signal talk2,3
         signal talk3,4
         FLAG1 ON reingard
        ENDIF
     !talk1
        say RE,"No vital signs detected commander"
        say RE,"....looks like they're all dead"
        say CO,"Searching computer logs now"
        say RE,"I'll do a system wide analysis check..."
        say RE,"Kara, set me up with a class 5 diametric scan range"
     !talk2
        say TO,"...am getting an interference from the antimatter reactor"
        say TO,"looks like the gravimetric stabilizer has be polarized"
        say CE,"I can probably bypass it by rigging a distortion field"
        say CE,"in the systems relay matrix"
        say CE,"...lets tractor it"
        say FO,"Roger that Kendrick"
     !talk3
        say CO,"Commander, I have accessed the computer logs..."
        say CO,"The probe is broadcasting from Polaris!"
        say RE,"All we have to do now is figure out what happened to the crew"
        say CE,"....and the Hyperion Subspace Device"
      endevents
      #
      [event]
      !talk1
      !talk2
      !talk3
      found_reingard
      $

     Note the use of the $ character in these examples. This is to show that
     the [event] block is at the bottom of file. Remember what I said earlier
     that the $ character must be the last line in the script source file?

     WARNING: If you are going to be signalling an event from within the [ai]
     blocks of several actors, be sure to know *exactly* what each actor is
     going to be doing. This is one area where I've seen many scripts behave
     differently because the logic is flawed.

5.5  [SETS]

     Though you can script individual actors, there are times when you will want
     to work with a group of actors. This is where sets come in. Using sets, you
     can work with actors, entities as well as cargo items using a pre-defined
     selection set within the [set] block. Like the [event] block, you should
     try to keep the set definition block at the end of the file so that its
     easy to locate and modify.

     SYNTAX

     [sets]
     :<set identifier>              // user defined identifier
     [<set member>,...]             // set members

     The leading : character indicates that the string is a set identifier.

     The set identifier is equivalent to predefined event names and can be any
     string. The <set identifier> may NOT be a keyword nor the name of a
     previously used actor identifier. All set identifiers must be unique.

     <set member> may be a collection of races, castes, actors, objects,
     concrete classes, previously defined sets, and numeric store items. The set
     acts as a collection of one each of these entities. The <set member> may be
     given in any order and may span several lines,

     In the case of subsets, the set contains all the elements of the named
     subset as well as it's own elements. A set may not include iteself in
     its definition.

     A new set definition, new block, or end of file "closes" the current set.

     The set may subsequently be used in several internl or user defined events
     and commands including !detect, !exist, create etc. Forward referencing of
     the set is allowed.

     There can be any number of user defined sets. The only penalty of a set
     is incurred when it is used in !detect or create because each one is
     processed individually.

     EXAMPLES

     eg1

     In this example, the items placed in the cargo pod are not in a set. When
     the pod is created there will be 100x67, 1x189, 50x277 items. The items use
     the syntax of the ADD_STORE command (quantity x item_number). Once the
     'cargo_pod' actor is created, it will contain the items defined using the
     ADD_STORE command.

     [dynamic]
     terran scientist,,cargo_pod,cargo2.3dc,pod
     [ai]
     .cargo_pod,100,100,100,100,100,100,0
     start inactive near earthz^jmp-10 2000 jmp-04
     stop
     events 102
     !begin_tod2
       activate this
       add_store this,100,67,1,189,50,277
     endevents

     eg2

     In this example, the items placed in the cargo pod are in a set. Also
     notice that there are two lines in the set. You can have as many lines as
     you want. The shorter the line, the easier it is to read and understand.
     The items in the set definition use the syntax for the ADD_STORE command
     (quantity x item_number). Once the 'cargo_pod' actor is created, it will
     contain the items defined in the 'cargo_pod1' set.

     Also in this example, there are two other sets which create generic
     cargopods (with no items in them) when the !begin_tod2 event for the
     cargo_pod actor is fired. (1) The 'cargo_pod2' set uses the internal
     'cargopod' class name. This allows the system to pick a random type of
     cargopod. There are only two types of cargo objects in this internal class.
     It consists of cargo1.3dc and cargo2.3dc objects. See SECTION 8.0 for a
     list of internal classes and the OBJECTS.TXT file for a list of objects.
     (2) The cargo_pod3 set uses the object name directly.

     Note that unlike the cargo_pod actor which is created by the script, the
     other two pods are created using the CREATE command which uses the set to
     determine what type of entity to create. It creates one of each set type.

     The [event] block is just there to demonstrate how these two sets can
     co-exist at the end of the file. If you remembered the discussion on
     events, then you will see that the cargo_pod actor will signal an event 2
     minutes after it is created. It is that event that causes the two other
     pods to be created.

     Another difference with these 3 pods is that only the first one has an id.
     Using this id, you can fire an event that uses a command to add items to
     it. Since the other two don't have an id, you cannot script any events for
     them and this is why they are created with no items in them. If you target
     the first pod in the CVD, you will be able to see its contents and have a
     shuttle collect them.

     [dynamic]
     terran scientist,,cargo_pod,cargo2.3dc,pod
     [ai]
     .cargo_pod,100,100,100,100,100,100,0
     start inactive near earthz^jmp-10 2000 jmp-04
     stop
     events 102
     !createit
       create 1,cargo_pod2,cargo_pod3
     !begin_tod2
       activate this
       signal createit,2
     endevents
     #
     [sets]
     :cargo_pod1
     100,67,1,189
     50,277
     :cargo_pod2
     cargopod
     :cargo_pod3
     cargo2.3dc
     [event]
     !createit
     $

     eg3

     In this example, a set of hostile targets is defined in a set and accessed
     collectively. The friend1 actor will broadcast that message if it detects
     any member of the 'hostiles' set, in this case, hostile1 or hostile2.

     You will also notice that it also has provision for detecting just one
     ship. In which case, it will broadcast both messages if it detects hostile1
     but the second message will not be broadcast for hostile2. You could add a
     '!detect hostile2' event for a message specific to that actor.

     You may be wondering about the 'attack it' command. Well, its perfectly
     valid. The actor will act the first member of the set that it detects. If
     it gets destroyed, then it will move on to the next member until all
     members of the set are out of scope (left the region, destroyed, docked
     etc).

     The 'hostiles_class' set lists races and a caste that the player has
     determined to be hostile. In this case, if any Gammulan or Vesperon type
     actor is detected, the message will be sent. It will also be sent if an
     insurgent caste is detected. The '!detect gammulan,vesperon,insurgent'
     event could also have been used, but I used a set to illustrate the
     benefits of using a set. This set can be accessed by any object without
     have to remember all the set entities as you would if you were writing each
     one individually.

     Though you can mix and match entities in a set, be aware of how the actor
     will act based on each member of that set. In the example you will see that
     the friend1 actor will repeat the broadcast under several circumstances as
     explained above.

     Also, create unique sets when possible to avoid confusion. This means that
     while you can mix races and castes in a set, try not to put cargo items in
     that set too. You will get confused because of how the parameters are
     passed.

     [dynamic]
     terran military,,friend1,ic2.3dc
     gammulan military,,hostile1,vandal.3dc,leader
     gammulan military,,hostile2,vandal.3dc,escort
     [ai]
     .friendl,100,100,100,100,100,100,0
     start inactive near earthz^jmp-10 2000 jmp-04
     cruise earthz^jmp-04
     stop
     events 102
     !begin_tod2
       activate this
     !detect hostiles
       broadcast "hostile ships detected!"
       attack it
     !detect hostile_class
       broadcast "hostiles detected!"
     !detect hostile1
       broadcast "leader detected!"
     endevents
     #
     .hostile1
     start inactive near earthz^jmp-10 5000 jmp-04
     stop
     events 102
     !begin_tod2
       activate this
       patrol earthz
     endevents
     #
     .hostile2
     start escort hostile1 250
     stop
     events 102
     !begin_tod2
       activate this
       broadcast "escorting leader"
     !detect friend1
       broadcast "enemy target detected"
     endevents
     #
     [sets]
     :hostiles
     hostile1,hostile2
     :hostile_class
     gammulan,vesperon,insurgent
     $

     In conclusion, sets can be very powerful and make a script more dynamic and
     readable. Also, you can use sets to generate a random set of entities. The
     script for Xtreme Carnage uses sets to generate a random type of hostile
     ships in some levels.

5.6  [MACRO]

     Sometimes scripts can be repetitious and long especially if you are
     designing a lengthy campaign. In these instances, you may want to use
     macros to simplify some of these commands that you use frequently.

     Macros are defined in a [macro] block. The [macro] block should end with
     a line containing [endmacro]. The macro body may contain most types of
     commands including other script blocks.

     More than one macro can be defined in a macro block. The [macro] block is
     also subject to the guidelines for creating other blocks such as [ai] and
     [dynamic]. The block must be in scope. You are advised to keep macro blocks
     either at the beginning or at the end of the script file. This way, it is
     easy to locate and change.

     SYNTAX

     [macro]
     :<macro name>[,formal parameter[=default value]]...
     <macro body>
     :MACRO_END
     [endmacro]

     The leading : character indicates that the string is a macro identifier.

     In the macro, text substitution of formal parameters is effected by placing
     the parameter within % metacharacters, i.e

     %<formal parameter>%

     When a macro is encountered in a script, it is expanded to the general form
     using the following syntax:

     <macro name>([actual parameter][,...])

     If an actual parameter is not specified the default value (if given in
     the macro definition) is substituted for it.

     The macro name MUST begin on the first non-whitespace character in the
     line, and a macro with no arguments must be specifed as follows:

     <macro name>()

     If <macro name> is not previously defined, no expansion occurs.

     Macro definitions may call other macros, which need not be previously
     defined.

     Macro definition continuation lines for macros with many arguments is
     allowed. If the last charactor on the line is a comma, then the following
     line is considered a continuation and is appended onto the previous line.
     continuations may span several lines, eg

     :macro(param1,param2,param3,param4,param5,param6,param7,param8)
     <macro body>

     may be written as:

     :macro(param1,param2,
     param3,
     param4,param5,
     param6,param7,param8)
     <macro body>

     EXAMPLE

     This macro in eg1 generates ODS platforms using a default set of parameters
     or replacement parameters. It contains a macro for actually creating the
     ODS object as well as an event block macro!

     The lines that invoke the macro, do not need to be placed in any particular
     block but for safety's sake, put them where they are most logical. Why?
     Because the macro defines all the valid blocks required for an object. This
     includes the [dynamic] and [ai] blocks.

     In this example, two types of ODS platforms are created around Earth and
     Sygan. When the friend actor is created, it can also reference a macro
     object because the macro also provides a valid object id.

     Notice how in the first macro call, the default orbital speed of the Earth
     ODS is over-ridden with a new value.

     Observing the macro definition, you can see how easy it is to call the
     'make_ods' macro without having to write a new definition each time.

     WARNING: When calling the macro, you MUST observe the order in which the
     variables were ordered in the macro defnition. From eg1, you will see that
     the first call to the macro overrides the object type and the orbital
     speed. These values are in the proper order. If the '1000' was before the
     'xtender.3dc' override variable, the parser will flag this as error because
     that variable expects an object and not a numerical value. It is IMPORTANT
     for you to remember this. You can bypass, i.e, use the default macro
     variable, by simply using a , metacharacter where the value should be if
     you are going to be skipping one value in order to override the next.

     eg1

     [macro]
     :ods_events()
     events
     !begin_tod1
       broadcast "I'm operational"
     endevents
     :MACRO_END
     #
     :make_ods(race caste,skill,planet,
     distance=170000,
     speed=500,roll=90,pitch=0,
     obj_type=trancor.3dc,)
     [dynamic]
     %race% %caste%,%skill%,%planet%_ods,%obj_type%
     [ai]
     .%planet%_ods,100,100,100,100,100,100,0
     start orbit %planet%,%distance%,%speed%,%roll%,%pitch%
     stop
     ods_events()
     :MACRO_END
     [endmacro]
     #
     make_ods(terran military,,earth,,1000,,,xtender.3dc)
     make_ods(terran insurgent,,sygan)
     #
     [dynamic]
     terran military,,friend,ic2.3dc
     [ai]
     .friend,100,100,100,100,100,100,0
     start inactive near earthz^jmp-10 2000 jmp-04
     stop
     events 102
     !begin_tod2
       activate this
     !detect earth_ods
       broadcast "Orbital Defense System detected"
     endevents

     eg2

     In this example, a macro is used to generate a variety of ships. Note that
     I have created a macro for almost every parameter allowed.

     I have also created a macro expansion for a simple form of START/STOP type.
     You can do this if you want but just bear in mind that the START/STOP
     section in the [ai] block, takes several different parameters!
     See SECTION 6.1 for more on this section.

     Notice how I augment the default events for the second ship (insurgent)
     created in the macro, with another event. Since you can have several
     [event] blocks for an object, this is perfectly legal. Just remember what
     I've said about the scope of blocks and where to place them. If I had
     inserted the new events section when the [dynamic] section for another
     actor was in scope, an error would occur. As your scripting skills improve,
     you will see how to use the object id anywhere in a script to override the
     default events for an actor. In this example, you can assume that I have
     used this technique to augment another object's (friend1) macro events.

     [macro]
     :ship_events()
     events 102
     !begin_tod1
       activate this
     endevents
     :MACRO_END
     #
     :make_ship(st_mode,st_region,
     race caste,skill,obj_id,obj_type,cvdname,
     shield=100,armor=100,engine=100,weapon=100,bay=100,
     reactor=100,cloak=0,)
     [dynamic]
     %race% %caste%,%skill%,%obj_id%,%obj_type%,%cvdname%
     [ai]
     .%obj_id%,%shield%,%armor%,%engine%,%weapon%,%bay%,%reactor%,%cloak%
     start %st_mode% IN %st_region%
     stop
     ship_events()
     :MACRO_END
     [endmacro]
     #
     make_ship(inactive,marsz,terran military,,friend1,ic2.3dc,friendly_ship)
     make_ship(inactive,syganz,terran insurgent,,enemy1,vandal.3dc,enemy_ship)
     events 102
     !detect bc
       attack it
     !resolve_tod1
       rtb
     endevents
     #
     [ai]
     .friend1
     events 102
     !damaged this,50
       broadcast "Damaged by 50%"
     endevents
     #

     Macros can be as powerful as you want them to be. They can also be
     confusing and complex. Use wisely. When in doubt, do it the hard way.

5.7 [REGION]

    You have no access to the [region] block in the 'lite' version of the GBS.
    So, this section is for information purposes only.

    There is absolutely NO reason for you to use this block because the internal
    defaults are in use by the internal master script. Defining a [region] block
    in your own script will not only alter the game universe, it will most
    likely wreak havoc with the 'world order'.

    This block is used to define initial region settings & autogeneration.

    SYNTAX

    The following syntax is used for defining region startup parameters. A
    region may only be ONCE in the script and can apply to space or planet
    regions. See NAVCHART.PDF for more on region settings.

    SET <race>,<rp>,<dp>,<con>,<tlvl>,<dlvl>,<tclass>,<inf>,<sec>,<pop>

    <race>        - Any valid race
    <rp>          - Resource Points
    <dp>          - Defense Points
    <condition>   - Normal,Unstable,Critical,Barren,Invasion
    <tlevel>      - Tech Level (1-10)
    <dlevel>      - Defense Level (1-10)
    <tclass>      - Tech Class (AD,MN,AG,RO,HT)
    <inf>         - Inflation Level (0-5)
    <sec>         - Security Status (LEGAL,ILLEGAL)
    <pop>         - Surface Population (0-100%)

    DEFINING REGION AUTO-GENERATION ENTITIES

    The following syntax is used for auto-generated entities. If a <race>
    appears as the first parameter instead of the SET keyword, this indicates to
    the parser that it is an auto-generated entity. Autogeneration is region and
    event based. These all appear within the region block consisting of region
    names in the following format:

    Note: You can turn auto-generation on/off using the AUTOGEN script command.

    :<region>,<active_max>,<inactive_max>

    <region>       - Any space or planet region, eg EARTHZ, EARTH etc

    <active_max>   - the max number of objects that can be generated in a region
                     that is ACTIVE or one jump away from the player or a
                     player controlled probe/ship.

    <inactive_max> - the limit of the number of objects generated for a region
                     that is INACTIVE.

    The region specification is followed by one or more event probabilities and
    class instance which may be augmented. The format of each event is:

    <race>,<caste>,<probability>,<event_interval>,<loiter_interval>,
    <start_flag>,<search_flag>,<exit_flag>,<class>,<int_ag_max>,<int_ag_prob>

    <race>         - Any valid race.
                     Can also use E,F,N,* for enemy, friendly, neutral
                     (default), or random

    <caste>        - Any valid caste

    <probability>  - The probability in percent that the unit will actually
                     be generated. Floating point value between 0.002 and 100.
                     The smallest allowable value is 0.002 which might be used
                     to generate a galaxian ship. 100 means the unit is always
                     generated if the region limits are not exceeded.
    <event
     interval>     - Time in minutes between each generation of a unit of this
                     class.

    <loiter        - The max time in minutes that the unit will wait before
     interval>       leaving if it can't find anything interesting to do.

    <start         - S,P,M,U,J,*, // station/planet/moon/uncharted/jump/all.
      flag>          Acts as location mask, if not specified, won't be visited.

                     e.g PM means the unit comes from a moon or planet only
                     the actual planet or jump point etc is chosen at random

    <search        - S,P,M,U,J,*, // station/planet/moon/uncharted/jump/all.
      flag>          Acts as search mask, if not specified, won't be visited.
                     The unit will visit each flag type before leaving the
                     region. Used for search and patrol actions.

    <exit          - S,P,M,U,J,*, // station/planet/moon/uncharted/jump/all.
      flag>          Acts as exit mask and determines how entity leaves region.
                     If not specified, will not be used.

    <class>        - Class of object being generated.

    <int_ag_max>   - max number of intruders to create on players ship when
                     this object is created. The probability of this occuring
                     is given by int_ag_prob. Use 0,0 to disable the generation
                     The BC must be in the player region or the intruder
                     generation is ignored. Intruders can't beam to player's
                     ship if it is cloaked.

    <int_ag_prob>  - Intruder autogeneration probability (floating point)

    EXAMPLE

    eg1

    [macro]
    :enemy_aggressive()                                  // AG macro
    ENEMY,RAIDER,10,5,5,J,J,J,cruiser,2,5
    ENEMY,CRIMINAL,10,5,5,J,J,J,cruiser,2,5
    ENEMY,ASSASSIN,10,5,5,J,J,J,cruiser,2,5
    ENEMY,MERCENARY,10,5,5,J,J,J,cruiser,2,5
    ENEMY,RAIDER,10,5,5,J,J,J,fighter,0,0
    ENEMY,CRIMINAL,10,5,5,J,J,J,fighter,0,0
    ENEMY,ASSASSIN,10,5,5,J,J,J,fighter,0,0
    ENEMY,MERCENARY,10,5,5,J,J,J,fighter,0,0
    :MACRO_END
    #
    :random_aggressive()
    ANYRACE,MILITARY,10,5,5,J,J,J,cruiser,4,5
    ANYRACE,RAIDER,10,5,5,J,J,J,cruiser,4,5
    ANYRACE,RAIDER,10,5,5,J,J,J,fighter,0,0
    ANYRACE,CRIMINAL,10,5,5,J,J,J,cruiser,2,5
    ANYRACE,MILITARY,10,5,5,J,J,J,fighter,0,0
    ANYRACE,CRIMINAL,10,5,5,J,J,J,fighter,0,0
    ANYRACE,ASSASSIN,10,5,5,J,J,J,cruiser,2,5
    ANYRACE,ASSASSIN,10,5,5,J,J,J,fighter,0,0
    ANYRACE,MERCENARY,10,5,5,J,J,J,cruiser,2,10
    ANYRACE,MERCENARY,10,5,5,J,J,J,fighter,0,0
    :MACRO_END
    #
    [region]
    :earthz,10,5                                         // Region
    SET TERRAN,0,0,NORMAL,10,10,AD,0,LEGAL               // Region definition
    TERRAN,MILITARY,70.5,10,10,J,J,S,fighter,0,0         // AG entity
    TERRAN,HARMLESS,80.5,9,10,J,P,J,carrier,0,0          // "
    enemy_aggressive()                                   // macro expansion
    friendly_military()                                  // "
    #

    NOTES:

    (1) A region can be made truly dynamic using very powerful macros with
    eclectic entities. However, be certain that you know what you are doing.
    Since AG entities use their own internal AI logic, they will use the default
    AI rules for their 'type' based on their race/caste. So for instance if you
    generate 'terran military' and 'gammulan military' actors in the same
    region, a fight will ensue. Period. Similarly, if diplomats are generated in
    a region that has a probability of raiders showing up, they will get
    attacked. This sort of dynamic nature of the AG process is what keeps the
    universe dynamic. You can define protected regions, trade routes etc.

    It is not an easy task to create a truly dynamic world and most especially
    one which will allow directed (actor using defined scripted actions) or
    'free-form' (AG actor using internal AI rules and logic) actors. It has
    taken me over 5 years or more to get it just right and there are still a lot
    of variations that I still haven't investigated and permutations that I
    haven't considered.

    This is all due to the advanced AI that actors possess and which determines
    what they do whether they are directed or free-form. In fact, creating a
    directed actor (as you know by now) only gives it direct orders. Once it has
    performed those, or if there is a conflict with a user defined order and its
    internal AI, an actor will always consult its internal AI rules in order to
    exist as it was intended. An Insurgent is an Insurgent, even if you told it
    to halt and park next to a Terran station. The minute it is created, it will
    consult its internal AI logic in order to figure out what to do once the
    station starts launching attack ships at it. A directed actor created in a
    region, will find something to do even if you don't give it an order. In
    this instance, it acts just like a free-form actor.

    (2) The active/inactive amounts can be overridden by other objects within
    the region. This means that if a region is scripted to only have 10 AG
    entities at any one time, once those entities start launching their own
    ships (carriers etc), the number of objects in the region will increase.

    (3) An ACTIVE region is one that the player or one of his ships or probes
    has visited. It is also one that has an AI actor that requires background
    processing. This includes stations, ODS systems, comets etc. Therefore, out
    of the 91 space regions, 75 planets and 145 moons in the game, since each
    one probably has an entity, this means that about 75% of them are active at
    the start of the game. The only exception would be a region that only has a
    region with no station, ODS or comet. These actors that require constant AI
    updating are called 'dynamic' entities. Others, called 'static' entities,
    such as the planet object, jump gates etc, do not require background
    processing because they have no AI.

    Once you, one of your ships/probes, or perhaps a scripted ship pass through
    this type of region (one without dynamic actors), it will switch it from
    INACTIVE to ACTIVE. The planetary region itself (if the space region
    contains a planet/moon) however will remain INACTIVE until the said entities
    actually enter it. So, yes, the space and planetary regions are processed
    independently of each other.

    Once a region is made ACTIVE, it cannot be switched back. This is why, if
    you travel enough around the galaxy, the more skirmishes that are going on,
    the slower the game gets. In the next generation of this engine which will
    debut in the sequel, BC:3020AD, this processing has been streamlined
    remarkably. Future versions may probably have SMP support.

5.8  [CLASS]

    You have no access to the [class] block in the 'lite' version of the GBS.
    So, ignore this section entirely. Classes are internal. Messing them up by
    augmenting the internal definition with an external script, is as potential
    a disaster as mucking about in the [region] block. This section is for
    information only.

    A class defines a single object or collection of objects that work together
    as a single object. classes that make up another class are termed as
    subclasses.

    The first sub-class of a class is the leader of the class. The classes
    themselves must first be defined in the [class] block. Defining a class
    does not itself create any objects, the class must be 'called up' anywhere
    in the file (similar to macros).

    Augmentation is possible when the object is called up by following the call
    with a {} block containing appropriate extra keywords allowing the class
    definition to act as a template. Also, the addition of a %<local_param>%
    syntax allows for text macro substitution.

    Classes can refer to anything from a cargo container to a task force. Here
    I'm thinking in terms of defining an operational starstation or capital
    ship like the Galcomhq or the BC as well as small fighter wings. Subclasses
    can be internal or external. Internal sub-classes are considered 'inside'
    the class and aren't visible unless 'launched', external sub-classes escort
    the leader in the class.

    The syntax for a class is:

      class::= <identifier>([macro parameters]...) { <properties> }

    There are several properties, some are optional they could be specified in
    any order:

      <group_name>

    A group name is a name ending in .3DC and must refer to a valid object
    defined in objects.scr, one per class block.

      NAME <object name>

    Used to name ships or cargo objects (NOT special items like the HSD which
    are pre-defined).

      CONTAINS <object_name>,...

    Used for filling cargo containers with miscellaneous cargo.

      CAPACITY <carriers>,<fighters>,<transports>,<shuttles>

    This indicates how many of the ship slots there are in a class and the
    number available for each class of object to dock, ie how many can be on
    board at one time. The system will keep track of the number of total ships
    within a dockable class, for repairs/transfer of personnel/cargo/re-arming
    etc.  The time to perform these actions is dependant on the staff level
    (below) Note that the CAPACITY keyword can be also used to limit the number
    of ships that can join a fleet.

    Limiting the carrier CAPACITY number to 1 for GALCOMHQ would for example
    restrict the player from docking immediately with a BC if there is aready a
    carrier on board being repaired. The player would have to wait for that
    carrier to launch from the station. Ports are allocated to 'ship' vectors
    in the .3D file on a "round-robin" basis. The number of such vectors limits
    how many ships can be docking/launcing *at once*, but does not limit the
    number of ships that can be 'in' the station, which is controlled by the
    CAPACITY keyword.

      DOCKWITH <object.3DC>,...

    This limits the objects that the current class can dock with. Used for
    special cases.

      LOADOUT <n>:<object>,...
      LOADOUT <n>:STA,ATA,STS,...

    List of weapons for this class eg, 5:VAGRANT,4:STARFLASH semi-random
    assignments can be made using the weapon type, ie STS, ATA etc instead of
    actual weapon names. The launch priority depends on the order specified.
    The number of slots cannot exceed that defined by the .3D file /MISSILE
    control name and additional weapons are ignored.

      OBJECT <object_id>

    Assigns that object to the class

      STAFF <staff type> <initial number>,<min number>

    Each class may consist of crew-members. The initial number of staff is the
    number of staff in the class when it is created. The <min number> is the
    min number of personel capable of operating the class at peak efficiency.
    More than this value are considered 'spares'.

    The <staff type> parameter defines the type of staff member. A starstation
    might rotate the staff by periodically sending them on leave. If they are
    understaffed they are ripe for attack.  Auto-generate types that arrive
    might get hired if there is a shortage.

    Possible staff types are:

    CREW

    (required to fly or man the object), for fighters these are pilots, for
    capital craft and stations, they are officers.  To keep things simple there
    is no distinction between officers and pilots.  If the number of CREW drops
    to zero, the object becomes disabled, irrespective of it's damage factor or
    other staff values. Crew are also required to fly (eg) fighters assigned to
    a starstation, or those fighters cannot be deployed. A fighter will never
    be deployed if doing so would reduce the crew to zero. (this restriction
    would apply only to *reserved* fighters (see below for context of
    'reserved').

    MAX

    (the maximum number of staff that can fit) default is no limit. For
    starstations, if the staff number is > 90% (?) of this value then 20% (?)
    of staff will leave on the next available shuttle, go colonize a planet, go
    home, go on a crusade or similar.

    To create guests or prisoners, the staff <min number> is set to zero and
    the initial number set to the desired quantity. Guests/Prisoners cannot be
    of the types listed above that have special uses. At a starstation, people
    may arrive and then the current number of that type increases. if they
    depart it decreases.

    If the unit is destroyed, random staff will escape using whatever internal
    ships are available, according to the max limit of that craft. If the STAFF
    keyword for a particular type is not given then the class will not accept a
    person of that type, eg for a starstation to accept criminals the statement

      staff criminals 0,0

    must be present, otherwise they will be refused clearance. Note that this
    is an implementation convenience - extra storage is needed for every type
    of staff that can be on-board a class.

    WORKER

    Used to perform structural repairs and usually part of a construction unit.
    Construction will not commence if workers are not part of the unit.

    SENGINEER

    Used to perform system repairs. If a unit does not contain system
    engineers,
    no system repairs will be performed when damage occurs.

    FENGINEER

    Used for flight operations. If a unit does not contain flight engineers,
    docking and launch operations will take a random of up to 75% time
    increase.

    PARAMEDIC

    Used to cure deseases and treat injured personnel. If a unit does not
    contain paramedics, personnel will remain injured during combat.

    SCIENTIST

    Used for research purposes and usually found in exploration and
    colonization units. Colonization will not commence if a scientist is not
    part of those units. They are not really staff types since they can be
    'internal' to a unit.

    EARTHCOM

    The policing arm of the Terran government. These guys are usually found
    where insurgents, raiders and criminals are found. If this type is found
    at a unit, ie starstation, no insurgents, raiders or criminals will dock
    there. If they do, they will immediately be put in the brig. They are not
    really staff types since they can be 'internal' to a unit.

    POLICE

    A generic police force type. These guys are usually found where raiders
    and criminals are found. If this type is found at a unit, ie starstation,
    no raiders or criminals will dock there. If they do, they will immediately
    become prisoners. Non Terran police ignore insurgents since that type is
    unique to the Terran government. They are not really staff types since
    they can be 'internal' to a unit.

    RAIDER

    Should never be used as STAFF types, otherwise they are automatically put
    in
    the brig otherwise they will damage systems, steal ships and escape. If
    captured by the player's BC, they become prisoners in the detention hold.

    CRIMINAL

    Should never be used as STAFF types, otherwise they are automatically put
    in
    the brig otherwise they will damage systems, steal ships and escape. If
    captured by the player's BC, they become prisoners in the detention hold.

    INSURGENT

    They should never be used as STAFF types. This type is unique to the
    Terran nation.  They are treated as guests if they are part of a non
    Terran unit otherwise, they are immediately put in the brig or they may
    steal ships and escape. If captured by the player's BC, they become
    prisoners in the detention hold.

    HACKER

    If they are part of a unit, it allows that unit to have access to advanced
    systems. System repairs (weapons, nav units etc) are boosted by as much as
    50%. They can essentially take the place of engineers if necessary. They
    are not really staff types since they can be 'internal' to a unit.

    ASSASSIN

    Should never be used as STAFF types. If they are, they will kill all
    diplomats of a hostile nation if found in the same unit.  If captured by
    the player's BC, they become prisoners in the detention hold.

    DIPLOMAT

    Generic guests and will usually be killed or kidnapped by assassins,
    raiders and criminals. Should not really be used as staff unless the unit
    is their base ops. They are not really staff types since they can be
    'internal' to a unit.

    TRADER

    If these guys are present in a unit, it allows that unit to have access to
    advanced trade items and large quantities of inventory. For a starstation,
    having traders on board results in more frequent visits by other traders
    resulting in a steady inventory level. A random number of resource points
    is
    also awarded when a trader first docks with a starstation or starbase.
    They are not really staff types since they can be 'internal' to a unit.

    MERCENERY

    Generic military units allied to the unit they are part of. They can be
    either marines, pilots or officers which resolves the staffing problems
    if the unit loses it's own staff.  They essentially fill in vacant slots
    of required staff. They are not really staff types since they can be
    'internal' to a unit.

    TOURIST

    This type results in an upgrade of resource points to the alien nation
    which owns the unit they are part of, ie a starstation. They come and go
    at random and are never fixed. Each time they visit, a number of resource
    points is awarded. If they are part of a unit which contains criminals or
    raiders, the resource points awarded is reduced by a random value up to
    50% depending on how many criminals or raiders are at the location. They
    are not really staff types since they can be 'internal' to a unit.

    JOURNALIST

    Generic nuisance. They are usually used to pass news around the galaxy.
    If used as staff, will do nothing useful. They are not really staff types
    since they can be 'internal' to a unit.

    EXPLORER

    This type is mostly used in exploration units. They travel to all parts of
    the galaxies, on planets and moons looking for suitable worlds for
    colonization. They know all the fast routes. Once this unit finds a
    suitable planet/moon for colonization, the colonists (if exist) will
    start to build in order to colonize the planet/moon. This unit simply
    travels all through the galaxy and sends a message back to it's homeworld
    when it finds a suitable planet/moon to colonize. The alien nation, if it
    can, then despatches colonist construction, escort units etc to the
    location. They are not really staff types since they can be 'internal' to
    a unit.

    COLONIST

    Person who has opted to leave his/her homeworld for a better life
    elsewhere. They are not really staff types since they can be 'internal'
    to a unit. A colonist unit will form with an explorer or exploration unit
    until they find a world to colonize.

    MARINE

    Used for security detail within a unit. Also used for surface attacks. If
    this unit is present within a unit the risk of criminals, insurgents and
    raiders (in the brig) escaping is reduced based on the damage to the unit.
    Also, when they do escape, the chances of them being caught before they do
    much damage and/or steal ships and escape is based on the number of
    marines in the unit.

      MULTIRACIAL <probability>

    When a class is initially staffed, the race of each staff member is
    dependant on the race owning it as defined in the [units] block and
    randomly generated.  If the starstation is Terran, then only friendly or
    neutral races will be present, non-Terrans will staff the class according to
    the probability given. This keyword is only valid in a [units] block, ie it
    augments the class template. If the political temperature changes, there
    may then be enemy types on board a ship/station, they would have to leave,
    resulting in a staffing problem for the operators of that ship!

      ATTRIB <shield>,<armor>,<engine>,<weapon>,<lnch bay>,<reactor>,<cloak>

    Set the value given to a percentage of the default value. The default for
    each is 100.

    In addition to STAFF, the class may have a complement of fighters, shuttles
    or other craft, these are defined by "calling them up" or "instancing" them
    using the class name of the craft eg

     [-/+]<class_name>(<macro parameter>,...)

    The "-" indicates the sub-class is internal and does not escort the class.
    a "+" indicates an external escort class. An internal class has a
    "reserved" slot meaning that only it may use that docking slot. The CAPACITY
    keyword allows additional units to dock.

    Example (generic Battlecruiser):

    [class]
    fighter(type)
    {
       STAFF CREW 2,1  // crew of 2 needed to operate
       %type%.3DC      // note use of macro, useful for defining different
       types of
                       // 2 seat fighter. ie fighter(IC), fighter(VIPER)
    }

    bc_atv()
    {
       ATV.3DC
       STAFF CREW 0,0
       STAFF MAX 10
       DOCKWITH BCSHUTTLE.3DC // not a forward reference as BCSHUTTLE.3DC
                              // is already defined, prevents is docking with
                              // other types of ship
    }

    bc_mining_drone()
    {
       MININGDR.3DC
       DOCKWITH BCSHUTTLE.3DC
    }

    bc_shuttle()
    {
       BCSHUTTLE.3DC
       STAFF CREW 0,0         // min/max crew required to operate shuttle
       STAFF ANYCAST 0,0      // can put any caste of person in the shuttle
       STAFF MAX 20           // max personnel can put in shuttle
       -bc_atv()
       -bc_mining_drone()
    }

    battlecruiser(shipname)
    {
       NAME %shipname%
       CAPACITY 0,0,0,0       // Default, it is NOT 0,4,0,4 because the slots
       are
                              // "reserved" by being internal
       STAFF CREW 15,7        // 7 officers, + 8 pilots = 15
                              // note that to launch one of the interceptors
                              // there must be at least 9 crew because an
                              // interceptor must be launched with 2 crew
                              // members
       STAFF PARAMEDIC  1,1   // The medical officer and any paramedics on
                              // board
       STAFF SENGINEER 40,20  // system repair engineers
       STAFF FENGINEER 40,20  // flight engineers
       STAFF MARINE   100,40  // marines
       STAFF TOURIST    0,0   // No tourists present, but they may be "guests"
                              // No criminals as the STAFF CRIMINALS keyword
                              // missing
       -fighter(IC)           // 4 interceptors
       -fighter(IC)
       -fighter(IC)
       -fighter(IC)
       -bc_shuttle()          // 4 shuttles
       -bc_shuttle()
       -bc_shuttle()
       -bc_shuttle()
    }

    [dynamic]
    //
    // Makes this task force exist at the start of the game
    // Each instance of the Battlecruiser class results in
    // a different actual ship type
    //
    terran taskforce_1()
    {
       +battlecruiser(Clinton)// Flagship
       {                      // the following {...} allow us to augment it
          +fighter_2(viper)   // the flagship BC is being escorted
          +fighter_2(viper)   // by 2 vipers, they will escort it even
                              // if the following ships in the formation
                              // break off as they "belong" only to the
                              // Clinton instance of the class.
       }
       +battlecruiser(Bush)   // a lesser ship
       +battlecruiser(Reagan)
       {
          TOURIST 1,0         // Tourist on board, overrides previous values
          OBJECT HSD          // HSD is on this ship, but not other BCs
       }
    }

    Note that taskforce_1 is not associated with a 3DC file, therefore it isn't
    a visible object, however it can be "ordered" or "assigned" as a single
    unit.

    It is up to the script designer to ensure that attributes are consistent,
    for example it would be usual for an fighter class to consist of 2 crew
    members (pilots), and no paramedics or other staff!

    The class definitions are used to define object capabilities/contents, the
    autogeneration block is the simplest way of causing those objects to exist.

5.9 [COMMS]

    This block is currently unused because two-way comms was removed from the
    interpreter. A better model is being developed and if it pans out, will be
    in the next generation of the kernel. This section is for information only.

    The purpose of two-way comms is to provide the ability for the player to
    communicate with directed or free-form AI entities (which can also
    communicate with each other) and the ability for them to respond in a
    logical manner. Also, due to the variety of classes and alien nations in the
    universe, each possible comms thread needs to be unique to the race/caste
    that it is created for, otherwise, all the messages will be the same.

    Putting in two-way comms is not a simple issue and it was abandoned because
    the idea was in its infancy back when it was conceived. I expect that a huge
    database of possible comms messages would be required in order to take into
    account all possible stances (hostile,friendly etc), situations
    (combat,exploring) and actions (attack,surrender etc). These will then have
    to be linked directly to the internal rules based AI for each actor class.

    The following is based on the current specs. No further information will be
    provided, so, don't ask.

    ==========================================================================

    The blocks link message texts and sound file names with identifiers.
    The identifiers can be used in place of literals in a broadcast
    action in the AI script. At run time, the message will be picked at random
    but from the list of messages of a given type. Message types can be further
    grouped into subclasses so that they are unique based the actor's class, ie
    hostile,friendly,neutral etc.

    The player will have access to all valid out-going comms messages. These
    will be grouped according to the group identifier (see below). To
    send a message, simply select the target, call up the comms list, open up a
    group (in the example below, this would be leave_region,status_request),
    select the desired message and send it.
    Once the actor receives it, if it can communicate (comms online, is not an
    asteroid etc), then it will pick a message at random from its own internal
    table (same group) and send to player.

    Since the internal comms script can be augmented by a user defined out, it
    is possible for the player to create specific message groups and messages
    based on target types and conditions. In this manner, communications can be
    logical, less repetitive and not as boring as having to see every diplomat
    say the same thing each time you talk to them.

    The possiblities that this technology presents, provides chances for better
    converstations (scripted of course) when creating ACM missions. Besides, it
    will be faster and more robust than trying to simulate a conversation
    (albeit a one-way one) using nested events as triggers. This comms can also
    be used to the players own crew. I was planning on using an NLP as well but
    have since discarded this idea because I don't think the player is going to
    have time to type up stuff when he has several missiles headed his way.

    DEFINITION

    [comms]
    ::leave_region                         // group identifier
    broadcast "leave this region now!"     // out going message list for player
    broadcast "get OUT of this regin!"     // to select from
    broadcast "you are advised to leave"
    :yes
    .friendly
    broadcast "sure thing",sound1.wav
    broadcast "copy that",sound2.wav
    broadcast "ok",sound4.wav
    .neutral
    broadcast "er, sure, whatever",sound5.wav
    .hostile
    broadcast "yeah right",sound6.wav
    broadcast "your mama wears boots",sound7.wav
    broadcast "come get me",sound8.wav
    :no
    .friendly,neutral
    broadcast "unable to comply",sound9.wav
    broadcast "can't do that",sound10.wav
    .hostile
    broadcast "you are in for a serious beating",sound11.wav
    #
    ::status
    broadcast "What's your status?",sound12.wav
    broadcast "everything ok?",sound13.wav
    :yes
    .friendly,neutral
    broadcast "All Systems nominal",sound14.wav
    broadcast "reactor damaged",sound15.wav
    broadcast "out of weapons",sound16.wav
    .hostile
    broadcast "Mind your own business",sound17.wav
    broadcast "Toilets are backed up. Wanna look?",sound18.wav
    #

    EXAMPLE

    [ai]
    events
    !begin_tod1
       activate this
       comms on this
    !tod1tick
       IF comms off RETURN
       IF receive leave_region THEN
         IFNOT disabled THEN
          send yes
         ELSE
          send no
         ENDIF
       ENDIF
       IF receive status THEN
         IF isfriend THEN
          send yes
         ELSE
          send no
         ENDIF
       ENDIF
    endevents

6.0  START/STOP 'nav' commands

