Story Mode and Tutorial Scripting System

### Loading Plots

Story mode in the game is defined by two or more XML files. The first file, called the PLOT file, contains a list of additional XML and LUA files. The additional XML files create the individual story threads. The Plot XML file has three tags: “Active\_Plot”, “Lua\_Script” and “Suspended\_Plot”. An active plot, as one would suspect, starts off active and will respond to various game events. A suspended plot starts off inactive and will only become active through activation by an event in a currently active plot. Here is an example of what the main XML file might look like :

```
<Story_Mode_Plots>
    <Active_Plot>TestStory.xml</Active_Plot>
    <Lua_Script>Test_Lua_LAND</Lua_Script>
    <Suspended_Plot>TestStory2.xml</Suspended_Plot>
</Story_Mode_Plots>

```

In this example, two plot threads are loaded, TestStory.xml and TestStory2.xml with TestStory.xml starting off active and TestStory2.xml starting off inactive. AI Lua scripts can also be loaded to force specific AI behavior within a specific mission.

### Defining Story Threads

A story thread block is composed of a number of events. Each event must be defined by a unique name. The name only has to be unique within the thread which it resides. An event can be defined using the following tags:

```
<Event_Name =”sample_block_name”>
  <Event_Type />
  <Event_Param1 />
  <Event_Param2 />
  <Event_Param3 />
  <Event_Param4 />
  <Event_Filter />
  <Reward_Type />
  <Reward_Param1 />
  <Reward_Param2 />
  <Prereq />
  <Story_Dialog />
  <Story_Chapter />
  <Story_Tag />
  <Story_Var />
  <Branch />
  <Perpetual />
  <Multiplayer />
  <Story_Dialog_Popup />
</Event>

```

Events MUST be set up in this order – events with incorrectly ordered tags may not function correctly or at all:

* **Event Name**

The specific and unique name for the trigger/reward block. Events must be unique within a specific story file, but not necessarily across an entire campaign.

* **Event Type**

The actual trigger event that is set off by the game/player. The available events are listed below in the “Event/Trigger List” section.

* **Event Parameter (1 – x)**

Definitions or required information for a particular event type. Each event type has its own specific required and/or optional parameters. These are listed below with their event type.

* **Event Filter**

A filter further specifies the action that will trip a trigger. A WIN\_BATTLES trigger without a filter would fire on the first battle won; add a SPACE filter and it would only fire when the first space battle was won. Not all events can use filters – they are specified below.

* **Reward Type**

The action that occurs when the event is tripped. This can be an actual reward such as “credits” or an in-game action or new event such as screen text. The rewards are listed below “Reward/Action List” section.

* **Reward Parameters (1 – x)**

As with events, rewards can use parameters to further define their effect.

* **Prereq**

The prerequisite event that must have fired before the current event can fire. Prereqs are defined by the unique event name. Multiple prereq lines can be added for an “or” situation, and multiple event names can be listed in the same line for an “and” situation.

* **Story Dialog**

The story dialog text file that is activated in the form of an in-game pop-up window.

* **Story Chapter**

The chapter heading from the text file that determines which part of the file to show in the pop-up dialog window.

* **Story Dialog Popup**

This is a true/false parameter, with the default being true. When set to true, story dialogs will spawn a pop-up window in the center of the screen. When set to false, the player will receive a notification in the radar screen and then must go to the story log to see the actual mission briefing.

* **Story Tag**

A unique name given to the story dialog box that is used by the in-game story log.

* **Story Var**

A variable name that is used to put randomized text into the story and other text lines. Often used to insert random planet names into the mission to vary it from game to game.

* **Branch**

A unique name that can be applied to one or more event blocks. A branch name identifies the blocks as a group, and a branch can then be turned on or off as a whole through other Event/Reward blocks. Generally used for branching story arcs.

* **Perpetual**

This is a “true/false” flag (defaults to false). When set to “true” the block will fire every time the situation is fulfilled, instead of the normal once only.

* **Multiplayer**

Currently unused.

### Event/Trigger List

Each event must have the Event\_Type tag. This tag defines which game events will trigger this event. Here is a list of event types with their parameters.

* STORY\_ACCUMULATE (# of credits)
* STORY\_AI\_NOTIFICATION (event name string) (planet list)
* STORY\_BASE\_DESTROYED (system name) (space, ground, either) (filter)
* STORY\_BEGIN\_ERA (Era)
* STORY\_CHECK\_DESTROYED (faction) (filter)
* STORY\_CLICK\_GUI (GUI element name)
* STORY\_CONQUER (System name) (no param 2) (who does the conquering)(filter)
* STORY\_CONQUER\_COUNT (# of systems)
* STORY\_CONSTRUCT (Object name) (number to construct) (side doing construction) (filter)
* STORY\_CONSTRUCT\_LEVEL (System name) (1-5) (Filter)
* STORY\_DEFEAT\_HERO (Hero name)
* STORY\_DEPLOY (Hero name) (System name)
* STORY\_DESTROY (Object name)(System name)(number to destroy)(destroyer)(filter)
* STORY\_ELAPSED (Seconds)
* STORY\_ENTER (System name) (Filter)
* STORY\_FLAG (flag name) (flag value)(compare method)
* STORY\_FLEET\_BOUNCED (planet name)
* STORY\_GENERIC (generic trigger type)
* STORY\_LAND\_ON (System name) (Filter)
* STORY\_LAND\_TACTICAL (land tactical plot file name) (system name)
* STORY\_LOAD\_TACTICAL\_MAP (planet name) (required hero)(ground/space)
* STORY\_LOSE\_BATTLES (# of battles) (ground/space/either)
* STORY\_MISSION\_FAILED (xml plot file)
* STORY\_MOVE (Hero name) (System name)
* STORY\_MOVIE\_DONE
* STORY\_SELECT\_PLANET (system name)
* STORY\_SPACE\_TACTICAL (space tactical plot file name) (system name)
* STORY\_SPEECH\_DONE (speech name)
* STORY\_TACTICAL\_DESTROY (object name) (?) (# destroyed)
* STORY\_TECH\_LEVEL (tech level)
* STORY\_TRIGGER (no parameters)
* STORY\_UNIT\_PROXIMITY (unit object name) (target object) (max distance)
* STORY\_VICTORY (faction)
* STORY\_WIN\_BATTLES (# of wins) (Filter) – Not yet implemented
* STORY\_ZOOM\_INTO\_PLANET (system name)
* STORY\_ZOOM\_OUT\_PLANET (system name)

#### Trigger/Event Descriptions

**STORY\_ACCUMULATE**

**(# of credits)**

Triggers when the amount of credits in the parameter have been accumulated.

**STORY\_AI\_NOTIFICATION**

**(event name string)**

**(comma delimited planet list for trigger to occur)**

This trigger causes a specific LUA script event to fire in galactic mode on the planets listed in the parameters.

**STORY\_BASE\_DESTROYED**

**(system name)**

**(space, ground, either)**

**(filter)**

Triggers on the destruction of a ground base or a space station on a specific planet. Note that the ground base version has not been tested since the change to base building. The filter identifies which side is losing the base.

**STORY\_BEGIN\_ERA (Era)**

Triggers on the beginning of a specific Time Era (1-5).

**STORY\_CHECK\_DESTROYED**

**(faction)**

**(filter)**

Checks to see if the specified items in the filter belonging to the specified faction have been destroyed. Usable filters are DESTROY\_ALL, DESTROY\_ALL\_UNITS, DESTROY\_ALL\_STRUCTURES.

**STORY\_CLICK\_GUI (GUI element name)**

Used for tutorial use, triggers when a specific GUI element is clicked. The GUI elements must placed in the parameter by its object name from CommandBarComponents.XML.

**STORY\_CONQUER**

**(System name)**

**(no param 2)**

**(who does the conquering filter)**

Triggers when the control of the planet changes. Parameters provide the specific planet and who does the conquering.

**STORY\_CONQUER\_COUNT**

**(# of systems)**

**(who does the conquering filter)**

Triggers when a specific number of planets have been conquered. The filter designates who is doing the conquering.

**STORY\_CONSTRUCT**

**(Object name)**

**(number to construct)**

**(side doing construction filter)**

Triggers when a specific object or objects are constructed by the player/AI.

**STORY\_CONSTRUCT\_LEVEL**

**(System name)**

**(1-5)**

**(space/land/either)**

**(side doing construction)**

Triggers when a space station or land base of the specified level is constructed by the specified side.

**STORY\_DEFEAT\_HERO**

**(Hero name)**

Triggers when the specified hero is defeated in combat.

**STORY\_DEPLOY**

**(Hero name)**

**(System name)**

Triggers when the specified hero is dragged (deployed) to the ground in galactic mode. Works for major and minor heroes. This trigger requires that the hero object, not the hero team object, is placed in the parameter.

**STORY\_DESTROY**

**(Object name)**

**(System name)**

**(number to destroy)**

**(who does the destroying)**

**(filter)**

Triggers when a specified object or objects are destroyed in galactic mode. If you want to trigger via destruction in a tactical combat, use STORY\_ TACTICAL\_DESTROY instead.

**STORY\_ELAPSED**

**(Seconds)**

Triggers after the specified number of seconds have gone by. The time is measured from the triggering of the pre-requisite if one is stated, otherwise it triggers from the beginning of the campaign/tactical map.

**STORY\_ENTER**

**(System name)**

**(Filter)**

**(entering ship)**

**(orbiting ship)**

**unused**

**(bounce fleets if param 3 or 4 are not fulfilled 1=true/0=false)**

Triggers when anyone of the stated faction enters space around the stated planet. Any object will trigger an enter trigger, unless parameter 3 or 4 are used. Parameter three is a hero unit that is required to be in the fleet to set off the trigger. Parameter four requires the specific hero unit to be in orbit when something enters the system to trigger. If parameter six is set to true, a fleet moved to the set location will bounce back to its origin if parameter three or four are not satisfied.

**STORY\_FLAG**

**(flag name)**

**(flag value)**

**(compare method)**

Checks the value of a story flag against a set value and triggers if that value is correct. The compare methods can be GREATER\_THAN, LESS\_THAN, EQUAL\_TO, GREATER\_THAN\_EQUAL\_TO, LESS\_THAN\_EQUAL\_TO.

**STORY\_FLEET\_BOUNCED**

**(System name)**

Triggers when a fleet attempts to stop on a planet that has been restricted by use of the SET\_PLANET\_RESTRICTED reward. Does not fire if the fleet is only passing through.

**STORY\_GENERIC**

**(generic trigger type)**

The generic trigger is used for a variety of events that don’t quite fit into any other category. The trigger types can all be listed in the same parameter separated by spaces. The current trigger types available are:

END\_SETUP (triggers at end of setup phase in tactical combat)

CLOSE\_STORY\_DIALOG (the story dialog box is closed)

MERGE\_FLEETS (fleets are merged in galactic mode)

FLEET\_TOOLTIP (a fleet tooltip is activated in galactic mode)

LAND\_TOOLTIP (a land tooltip is activated in galactic mode)

DRAG\_SELECT (units are drag selected in tactical mode)

RETREAT\_COMPLETE (a retreat has been activated and completed successfully)

RETREAT\_CLICKED (the player has clicked the retreat button)

SLICE\_DIALOG (the player has opened the “rebel steal tech” menu)

CLICK (triggers on any mouse click)

**STORY\_LAND\_ON**

**(System name)**

**(Filter)**

Triggers when a unit is landed on a particular system. This is used for any unit that is NOT a hero (heroes use STORY\_DEPLOY).

**STORY\_LAND\_TACTICAL**

**(land tactical plot file name)**

**(system)**

Prepares a specific plot and story file to be loaded when a land battle is activated on the specified planet.

**STORY\_LOAD\_TACTICAL\_MAP**

**(planet name)**

**(required hero)**

**(ground/space)**

Triggers when a tactical battle on a specific planet is triggered and a specified hero is present in the attack force. Generally used in conjunction with STORY\_LAND\_TACTICAL or STORY\_SPACE\_TACTICAL.

**STORY\_LOSE\_BATTLES**

**(# of battles)**

**(Ground/Space/Either)**

Fires when the specified number of battles in the specified mode are lost. Can take the same filters as STORY\_WIN\_BATTLES.

**STORY\_MISSION\_LOST**

**(xml plot file)**

Trigger fires when the mission dictated by the XML file in the parameter is determined to be a loss.

**STORY\_MOVE**

**(Hero name)**

**(System name)**

Triggers when the specified hero enters space over the specified planet. Use this trigger instead of STORY\_ENTER when you want the hero and not just any fleet to trigger the script.

**STORY\_MOVIE\_DONE**

Triggers when a currently playing movie file is finished.

**STORY\_SELECT\_PLANET**

**(system name)**

Triggers when the user selects the specified planet with the mouse.

**STORY\_SELECT\_UNIT**

**(object name)**

Triggers when the player selects a specified unit. Note that any unit with that object name will trip the trigger.

**STORY\_SPACE\_TACTICAL**

**(space tactical plot file name)**

**(system)**

Prepares a specific plot and story file to be loaded when a space battle is activated on the specified planet.

**STORY\_SPEECH\_DONE**

**(speech name)**

Triggers when the stated speech event concludes. This can be either the event playing to conclusion, or when the player cancels the sound (such as by closing the dialog box that plays the speech event).

**STORY\_TACTICAL\_DESTROY**

**(object name)**

**(?)**

**(#)**

Triggers when the specified number of objects are destroyed in a tactical battle. If you want to track destroyed objects in galactic mode, use STORY\_DESTROY

**STORY\_TECH\_LEVEL**

**(tech level)**

Triggers when the specified tech level is reached.

**STORY\_TRIGGER**

Triggers when the specified pre-requisite story block has triggered. There are no parameters for this trigger.

**STORY\_UNIT\_PROXIMITY**

**(unit object name)**

**(target object)**

**(max distance)**

Triggers when the specified object gets near the second object in tactical mode. If the first parameter is unused, the trigger will fire when any object nears the trigger object. You can also specifiy how close to get to the trigger object before firing. This trigger will work with invisible marker objects as well as visible ones.

**STORY\_VICTORY**

**(faction)**

Triggers when the stated faction is victorious in a tactical mission. In general this trigger is used to set win variables at the end of a mission. Because this trigger can be fired by console commands, it is important to avoid using any pre-requisite tags.

**STORY\_WIN\_BATTLES**

**(# of wins)**

**(space/land)**

Triggers when the player wins the specified number of battles of the specified type (space/land).

**STORY\_ZOOM\_INTO\_PLANET**

**(system name)**

Triggers when the player zooms into the specified planet in galactic mode.

**STORY\_ZOOM\_OUT\_PLANET**

**(system name)**

Triggers when the player zooms out from a planet in galactic mode.

### Reward/Action Events

Rewards are the actions that occur when the story trigger has fired. Rewards are not required for an event block to function. Like story events, the rewards can have several parameters and filters associated with them.

#### Reward/Action List

ACTIVATE\_RETRY\_DIALOG

ADD\_OBJECTIVE (text ID)

BUILDABLE\_UNIT (Unit name to unlock) (Unit name to lock – optional)

CHANGE\_OWNER (object type) (desired faction)

COMMANDBAR\_MOVIE (movie name)

CREDITS (# of credits)

DESTROY\_OBJECT (object name)

DISABLE\_AUTORESOLVE

DISABLE\_BRANCH (branch name) (enable/disable)

DISABLE\_BUILDABLE (object name)

DISABLE\_DIRECT\_INVASION

DISABLE\_EVENT (event type)(button name)

DISABLE\_RETREAT (faction) (on/off)

DISABLE\_REINFORCEMENTS (disable/enable) (faction)

DISABLE\_STORY\_EVENT (event name) (enable/disable)

DUAL\_FLASH (duration in seconds) (time between flashes in seconds)

ENABLE\_BUILDABLE (object name)

ENABLE\_DIRECT\_INVASION

ENABLE\_EVENT (event type)

ENABLE\_GALACTIC\_REVEAL (enable/disable)

ENABLE\_OBJECTIVE\_DISPLAY (on/off)

ENABLE\_VICTORY (enable/disable)

FINISHED\_TUTORIAL (text ID of tutorial mission)

FLASH\_FLEET\_WITH\_UNIT (object name)

FLASH\_GUI (gui element name)

FLASH\_PLANET\_GUI (planet name) (GUI element) (fleet #)

FLASH\_PRODUCTION\_CHOICE (object name)

FLASH\_SPECIAL\_ABILITY (ability name)

FLASH\_UNIT (command bar region) (name of unit)

FORCE\_CLICK\_GUI (gui element)

FORCE\_RESPAWN (hero name)

FORCE\_RETREAT (faction)

HIDE\_CURSOR\_ON\_CLICK (1 or 0)

HIDE\_TUTORIAL\_CURSOR

HIGHLIGHT\_OBJECT (object name) (highlight/un-highlight)

INCREMENT\_FLAG (flag name) (amount to increment – pos/neg)

LOCK\_CONTROLS (lock/unlock)

LOCK\_PLANET\_SELECTION (lock/unlock)

LOCK\_UNIT (unit name)

MULTIMEDIA (many…see below)

NEW\_POWER\_FOR\_ALL (object name) (power name)

OBEJECTIVE\_COMPLETE (text ID)

OBJECTIVE\_FAILED (text ID)

PAUSE\_GALACTIC

PICK\_PLANET (filter) (planet variable name)

PLANET\_FACTION (planet name) (new faction)

POSITION\_CAMERA (object name)(camera offset)

REMOVE\_ALL\_OBJECTIVES

REMOVE\_OBJECTIVE (text ID)

REMOVE\_STORY\_GOAL (story tag)

REMOVE\_UNIT (object name)

RESET\_BRANCH (branch name)

RESET\_EVENT (event name)

RESET\_GALACTIC\_FILTERS

REVEAL\_ALL\_PLANETS

REVEAL\_PLANET (planet name) (hide/show)

SCREEN\_TEXT (text name from XLS) (time shown) (variable)

SELECT\_PLANET (planet name)

SET\_FLAG (flag name) (flag value)

SET\_MAX\_TECH\_LEVEL (faction) (tech level)

SET\_PLANET\_RESTRICTED (planet name) (1=on, 0=off)

SET\_TACTICAL\_MAP (map name) (Ground/space)

SET\_TECH\_LEVEL (faction) (tech level)

SHOW\_COMMAND\_BAR (on/off)

SPAWN\_HERO (Hero name) (System name – optional)

SPEECH (speech event ID)

START\_CINEMATIC\_MODE

START\_MOVIE (movie file name)

STOP\_CINEMATIC\_MODE

STORY\_ELEMENT (plot name)

STORY\_GOAL\_COMPLETED (story tag)

STORY\_OBJECTIVE\_TIMEOUT (seconds)(objective TXT ID)

SWITCH\_CONTROL (faction to change) (desired AI)

TRIGGER\_EVENT (event name)

TUTORIAL\_DIALOG(dialog text ID)(1= disable continue button)

TUTORIAL\_PLAYER (faction)

UNIQUE\_UNIT (Unit name) (System name – optional)

UNPAUSE GALACTIC

USE\_RETRY\_DIALOG

VICTORY (winning faction)

ZOOM\_IN
ZOOM\_OUT

#### Reward/Action Descriptions

**ACTIVATE\_RETRY\_DIALOG**

This force-fires the replay dialog used during a scenario loss. Normally this reward is only used in testing.

**ADD\_OBJECTIVE**

**(text ID)**

Adds an objective to the tactical objective window

**BUILDABLE\_UNIT**

**(Unit name to unlock)**

**(Unit name to lock – optional)**

Unlocks a unit for production in galactic mode, and can optionally lock a unit as well. This can be used to upgrade units; for example, you unlock the X-wing mark II and lock the original X-wing.

**CHANGE\_OWNER**

**(object type)**

**(desired faction)**

Changes the faction of the designated object. Currently it will change the faction for ALL of the objects on the map of the same object name. The second parameter is the faction you want the object to be.

**COMMANDBAR\_MOVIE**

**(movie file name)**

Plays a movie in the radar map window. The movie must be defined in MOVIES.XML

**CREDITS**

**(# of credits)**

Adds the stated number of credits to the galactic reserve

**DESTROY\_OBJECT**

**(object name)**

Instantly destroys the first object of the stated name the system can find.

**DESTROY\_AUTORESOLVE**

Disables autoresolve battles for the player.

**DISABLE\_BRANCH**

**(branch name)**

**(enable/disable)**

Enables (setting of 0 in the parameter) or disables (setting of 1 in the parameter) any story event blocks that have the stated branch name in their makeup. Note that ALL blocks of the stated branch are affected. If you want only one part of the story branch to be affected, use DISABLE\_STORY\_EVENT.

**DISABLE\_BUILDABLE**

Removes an object from the build menu. This is independent of tech level releases, so an object that is available by tech level can be removed from the build menu with this command.

**DISABLE\_DIRECT\_INVASION**

Disables the “invade!” button when initiating a land tactical battle.

**DISABLE\_EVENT**

**(event type)**

**(button name)**

Disables a specific user event. Events include:

TUTORIAL\_ZOOM – disable planet zooming

TUTORIAL\_CLICK\_GUI – disable clicking of a button specified in param 2

TUTORIAL\_ALL – disable all player input

**DISABLE\_REINFORCEMENTS**

**(disable (1) or enable (0))**

**(faction)**

Enables or disables the ability to get reinforcements in space or land tactical for the specified faction. If no faction is specified, both sides are disabled.

**DISABLE\_RETREAT**

**(faction)**

**(disable (1) or enable (0))**

Disables or enables retreating for the specified faction.

**DISABLE\_STORY\_EVENT**

**(event name)**

**(enable/disable)**

Prevents (parameter of 1) or allows (parameter of 0) the specified event block from triggering. If you want to enable/disable an entire branch, use DISABLE\_BRANCH.

**DUAL\_FLASH**

**(duration in seconds)**

**(time between flashes in seconds)**

Will cause the next two flash event blocks to alternately flash back and forth for the set number of seconds. The second parameter is the pause between flashes. Works with either FLASH\_GUI or FLASH\_PLANET\_GUI.

**ENABLE\_BUILDABLE**

Reinstates an object to the build menu that was previously removed by DISABLE\_BUILDABLE.

**ENABLE\_DIRECT\_INVASION**

Enables the “invade!” button when initiating a land tactical battle. Note that “enable” is the default, so this is only needed if you have previously used DISABLE\_DIRECT\_INVASION.

**ENABLE\_EVENT**

**(event type)**

Enables a specified user event. Available events are:

TUTORIAL\_ZOOM – enables player planet zooming

TUTORIAL\_CLICK\_GUI – enables a currently disabled button

TUTORIAL\_ALL – enables all player input that was previously disabled

**ENABLE\_FOW**

**(enable (1) /disable (0))**

Locks and unlocks visible fog of war.

**ENABLE\_FOW**

**(enable (1) /disable (0))**

Turns on/off the automatic reveal of planets in galactic mode. This is generally set on or off in the campaign file, but can be manipulated through story.

**ENABLE\_OBJECTIVE\_DISPLAY**

**( on (1) off(0) )**

Turns the tactical objective window on or off.

**ENABLE\_VICTORY**

**(enable (1) /disable (0))**

Locks and unlocks the game’s ability to declare a victory. Useful when you want events to happen after all units/structures are destroyed.

**FINISHED\_TUTORIAL**

**(tutorial mission text ID)**

This marks the specified tutorial finished for the player. Note that this is tracked in the game’s section of the Windows Registry.

**FLASH\_FLEET\_WITH\_UNIT**

**(object name)**

Finds the first object of the named type and flashes the fleet that contains it. Primarily used for single type units like heroes. Note that since the flash arrows are linked to the fleet object, they will move with the fleet.

**FLASH\_GUI**

**(gui element name)**

Creates a flashing arrow tutorial arrow to appear over the specified GUI element on the main interface or the zoomed in interface. Does NOT work for the planets in the main viewing area – for that, use FLASH\_PLANET\_GUI. The GUI elements are referenced by their object name in CommandBarComponents.XML. Note that multiple flashes will move the arrows from one element to the next, but the last one will always remain on the screen until removed with HIDE\_TUTORIAL\_CURSOR.

**FLASH\_PLANET\_GUI**

**(planet name)**

**(GUI element)**

**(fleet #)**

**unused**

**(optional 1)**

Flashes a GUI element on the main planet screen. Only the first two parameters are used unless referenicing a fleet position, in which case they are numbered 0-2. The following elements can be used: FLASH\_AFFILIATION, FLASH\_FLEET, FLASH\_TROOPS, FLASH\_PLANET\_NAME, FLASH\_CREDITS, FLASH\_PLANET\_VALUE, FLASH\_WEATHER.

If the optional parameter is used, the flash cursor will be persistent, staying in place even after tactical battles. It must be removed with another script.

**FLASH\_PRODUCTION\_CHOICE**

**(object name)**

Flashes the stated object in the production menu. Note that you must specify an object that can actually be built (generally a company object and not a single object name). Also note that the flash is tied to a button, so if the production menu changes while the flash is active, it could render the flash inaccurate.

**FLASH\_SPECIAL\_ABILITY**

**(name of special ability)**

Flash the special ability button of the specified special ability. The ability names can be found in the XML entry for the unit that uses it.

**FLASH\_UNIT**

**(command bar region)**

**(name of unit)**

This will search the specified region (REGION\_ORGANIZE, REGION\_PRODUCTION, REGION\_SELECTION) and flash the first unit type matching the supplied name.  REGION\_ORGANIZE currently consists of all of the fleet slots, the land slots and the special structure slots and it searches in that order.  Note that if you want to flash a unit such as a stormtrooper on land and there’s also one in space, it will find and flash the space one first.

**FORCE\_CLICK\_GUI**

**(GUI element)**

Forces a click on the specified command bar component.

**FORCE\_RESPAWN**

**(hero name)**

Forces a hero to instantly respawn. Note that the hero must already be in the midst of a re-spawn timer before this will work.

**FORCE\_RETREAT**

**(faction)**

Forces the named faction to retreat from a tactical battle.

**HIDE\_CURSOR\_ON\_CLICK**

**(0 = hide last cursor / 1 = hide all cursors)**

Hides a flash cursor when the player clicks the mouse. If the second parameter is on, it will hide all of the currently displayed flash cursors.

**HIDE\_TUTORIAL\_CURSOR**

Removes the tutorial arrow cursor from the screen.

**HIGHLIGHT\_OBJECT**

**(object name)**

**(highlight (1) or un-highlight (0))**

**(unique ID)**

Highlights the specified object in ground tactical mode for use in directing players to objectives. The unique ID number is used to add/remove a radar blip for the object. The third parameter is optional.

**INCREMENT\_FLAG**

**(flag name)**

**(amount to increment – pos/neg)**

Increments a flag (created with set flag) by the specified amount. The amount can be any number, positive or negative.

**LINK\_TACTICAL**

**1 (planet name)**

**2 (ground/space)**

**3 (attacking faction)**

**4 (map name)**

**5 (defending faction)**

**6 (pathfinder object (optional))**

**7 (story script file name)**

**8 (use persistence (1), no persistence (0) – defaults to 0)**

**9 (use pre-battle cinematic (1), no cinematic (0) – defaults to 1)**

**10 (start scene faded out (1), start normally (0))**

**11 (start scene in letterbox (1), start normally (0))**

**12 (none)**

**13 (show battle pending dialog (1) do not show battle pending dialog (0))**

Forces a tactical battle when the trigger fires.

**LOCK\_CONTROLS**

**(lock (1) /unlock (0))**

Locks or unlocks all player input.

**LOCK\_PLANET\_SELECTION**

**(lock (1) / unlock (0))**

Locks a select ring to the currently selected planet. The player will not be able to select any other planet until it is unlocked with the same reward.

**LOCK\_UNIT**

**(unit name)**

Locks a unit out of the production menu (it can no longer be built)

**MOVE\_FLEET**

**(starting planet)**

**(destination planet)**

**(filter)**

Moves a fleet from one planet to another. Always moves the fleet in the first position.

**MULTIMEDIA**

**(text string to display)**

**(duration to display text)**

**(object/variable to include in text)**

**(remove text 1=yes/0=no)**

**(use teletype display for text 1=yes/0=no)**

**(text color)**

**(text is a sub-title 1=yes/0=no)**

**(speech file to play)**

**(command bar movie to play)**

**(loop movie 1=yes/0=no)**

This event replaces the SPEECH, COMMANDBAR\_MOVIE and SCREEN\_TEXT events, but all are still functional.

**NEW\_POWER\_FOR\_ALL**

**(object name)**

**(power name)**

Attaches a new special power to all current and future objects of the specified name. In general, this can be used to attach power to heroes (major or minor).

**OBJECTIVE\_COMPLETE**

**(text ID)**

Marks a goal on the tactical objective window as complete (adds a check mark and changes the text color).

**OBJECTIVE\_FAILED**

**(text ID)**

Marks a goal on the tactical objective window as failed (adds a red ‘X’ and changes the text color).

**PAUSE\_GALACTIC**

Pauses all game behavior in galactic mode. Note that this does not pause story scripting, only timers and movement.

**PICK\_PLANET**

**(filter)**

**(planet variable name)**

This allows you to select a random planet from among those owned by the specified factions and assign it to a variable name. This can then be inserted into story arc dialog (using the Story\_Var flag) or tutorial text (using %s in the text line).

**PLANET\_FACTION**

**(planet name)**

**(new faction)**

This reward destroys everything on the stated planet and switches its allegiance to the new stated faction. This generally should be followed up by a trigger that populates the planet with objects of the new faction.

**POSITION\_CAMERA**

**(object name)**

**(offset)**

Positions the camera above the named object. Parameter two is input in an X,Y,Z format and offsets the camera from the zero position (zero being directly above the object’s center point).

**REMOVE\_ALL\_OBJECTIVES**

Removes all of the listed objectives from the tactical objective list.

**REMOVE\_OBJECTIVE**

**(text ID)**

Removes an objective from the tactical objectives list. Note that this does not complete the goal, it only removes it.

**REMOVE\_STORY\_GOAL**

**(story tag)**

This removes the specified story goal/replay from the story log. If you want to keep the goal there but mark it as completed, use STORY\_GOAL\_COMPLETED instead.

**REMOVE\_UNIT**

**(object name)**

Removes a unit from play permanently. Used on heroes, they won’t respawn. Note that this does not distinguish same-name objects, so if used on a generic unit, all units of that name will be removed (though more can be built).

**RESET\_BRANCH**

Resets all of the events and counters of the specified branch name so that they can fire a second time.

**RESET\_EVENT**

Resets the event and counters of the specified name so that it can fire a second time.

**RESET\_GALACTIC\_FILTERS**

Sets all of the galactic view filters to off.

**REVEAL\_ALL\_PLANETS**

Reveals all the planets on the galactic map.

**REVEAL\_PLANET**

**(planet name)**

**(hide (0) /show (1))**

Hides or reveals the specified planet. Note that other planets within a single hyperspace jump and those planets connected with a trade route will also be revealed.

**SCREEN\_TEXT**

**(text name from XLS)**

**(time shown)**

**(variable)**

**(remove)**

**(teletype off (0) or on (1) – defaults to on (1))**

**(RBG color value for text – leave blank for default)**

This puts up a tutorial text line on the screen in the upper left corner for the amount of time specified. The time can be set to -1, in which case it will remain on the screen until another SCREEN\_TEXT reward using param4 (Remove) is used. The variable is optional, and is used to insert a text flag into the sentence (such as those created with PICK\_PLANET).

**SCROLL\_LOCK**

**(disable scrolling=1, enable scrolling=0)**

Locks the map scrolling in galactic mode. Note that this only locks out player scrolling; the map can still be scrolled via XML or LUA scripting commands.

**SELECT\_PLANET**

**(planet name)**

Forces the selection of the specified planet.

**SET\_FLAG**

**(flag name)**

**(flag value)**

Creates a new flag and sets it to a specified value. All flags must have a unique name. The flag value can be changed using the INCREMENT\_FLAG reward, or queried using the STORY\_FLAG trigger.

**SET\_MAX\_TECH\_LEVEL**

**(faction)**

**(tech leve)**

Sets the max tech level for a specified faction. The tech level can never be raised until this script is used again or the SET\_TECH\_LEVEL reward is used.

**SET\_PLANET\_RESTRICTED**

**(planet name)**

**(1=on, 0=off)**

Sets the planet up so that only fleets that will trigger story events at the planet are permitted to stop there.  Any other fleet will pass straight through or (if the planet was the fleet’s final destination) be bounced back to the previous planet it visited.  Persists until turned off (by issuing the same reward with the second parameter set to 0).

**SET\_TACTICAL\_MAP**

**(map name)**

**(ground/space)**

Forces the system to load the specified tactical map in place of the default map for the planet. Generally used in conjunction with STORY\_LOAD\_TACTICAL\_MAP to determine which planet and hero trigger the map change, and with STORY\_LAND\_TACTICAL or STORY\_SPACE\_TACTICAL to connect it to a specific tactical story plot.

**SET\_TECH\_LEVEL**

**(faction)**

**(tech level)**

Forces the specified faction to the specified tech level.

**SHOW\_COMMAND\_BAR**

**(on=1, off=0)**

Hides or replaces the bottom command bar.

**SPAWN\_HERO**

**(Hero name)**

**(System name)**

Insta-spawns a hero. If no planet is specified, the hero will spawn on the home planet designated in the campaign file, or the nearest friendly planet if the home planet is no longer under the correct faction control. Note that the hero TEAM must be specified, not just the hero unit.

**SPEECH**

**(speech event ID)**

Plays the specified speech event.

**START\_CINEMATIC\_MODE**

Activates the “BattleCam” mode and locks it on (no player control).

**START\_MOVIE**

**(movie file name)**

Plays a movie of the specified file name. Note that the BIK extension is not needed in the parameter, but the movie file must appear in MOVIES.XML to be recognized.

**STORY\_ELEMENT**

**(name of plot)**

Activates a story file that is currently marked as “suspended” in the plot file.

**STOP\_CINEMATIC\_MODE**

Stops the cinematic mode, whether turned on via the START\_CINEMATIC\_MODE or player input.

**STORY\_GOAL\_COMPLETED**

**(story tag)**

Marks the story dialog goal as completed in the player story log. The story dialog will still be viewable if the player desires, but it will be grayed out.

**STORY\_OBJECTIVE\_TIMEOUT**

**(seconds)**

**(objective text ID)**

Fires when the specified tactical objective has not been completed within the specified amount of time.

**SWITCH\_CONTROL**

**(faction to change)**

**(desired AI)**

Mimics the Switch\_Control console command; changes the AI behavior of the specified faction. This can be used to turn on the AI for a currently dormant faction.

**TRIGGER\_EVENT**

**(event name)**

Forces an event to fire.

**TUTORIAL\_DIALOG**

**(dialog text ID)**

**(1= disable continue button)**

Places a tutorial complete text message on the screen. If the second parameter is added, the continue button will be grayed out.

**TUTORIAL\_PLAYER**

**(faction)**

Sets the player of the stated faction to tutorial mode, which affects build times and such to make things faster.

**UNIQUE\_UNIT**

**(Unit name)**

**(System name – optional)**

Insta-spawns a single object of the specified name. If no planet is specified, the object will spawn on the home planet designated in the campaign file, or the nearest friendly planet if the home planet is no longer under the correct faction control. Be sure to use the object name for the squadron or company rather than single units unless the object is always solo.

**UNPAUSE\_GALACTIC**

Unpauses the galactic game that has been paused using PAUSE\_GALACTIC.

**USE\_RETRY\_DIALOG**

This allows the current mission to be replayed when it is lost. This reward should be added to the beginning of every mission using a STORY\_TRIGGER as the event.

**VICTORY**

**(winning faction)**

Forces a victory for the specified faction (which can be the same as a loss for the player faction). An optional parameter 2 can be set to on (1) to lower the delay time before cutting back to galactic mode.

**ZOOM\_IN**

Forces a zoom in to the currently selected planet.

**ZOOM\_OUT**

Forces a zoom out from the currently selected planet.

### Prerequisites (Prereq)

Prerequisites are lists of other events that must have been triggered prior to this event being able to be triggered. Unlike parameters, multiple events listed on the same prereq are treated as an AND condition. Multiple prereq lines can be specified and the various lines are treated as an OR condition. This differing behavior from the other event entries is necessary in order to allow for all possible logical combinations. An example of prerequisites could be :

<Prereq>eventA eventB</Prereq>

<Prereq>eventC</Prereq>

In this example, the event can be triggered only if eventA AND eventB have already been triggered OR if eventC has already been triggered. In C-style notation, it could be written as

(eventA && eventB) | eventC

### Filters

Filters can be used to make a trigger or reward more specific. The following are available:

FILTER\_FRIENDLY\_ONLY

FILTER\_NEUTRAL\_ONLY

FILTER\_ENEMY\_ONLY

FILTER\_FRIENDLY\_AND\_NEUTRAL

FILTER\_ENEMY\_AND\_NEUTRAL

FILTER\_FRIENDLY\_AND\_ENEMY

GROUND

SPACE

### Story Dialogs (Story\_Dialog,Story\_Chapter)

Story dialogs can be used to give feedback to the user and are a special version of a reward. When an event is triggered, a dialog box which can contain text, graphics and even movies will be opened up for the player. Story dialogs are separate text files, not XML. Two tags are used to define which dialog to show to the user. The first is the story name. The second is the chapter in that story to show. Here is some sample xml code

<Story\_Dialog>SampleStory</Story\_Dialog>

<Story\_Chapter>0</Story\_Chapter>

This will open up SampleStory and display chapter 0.

#### Sample Story Dialog

[CHAPTER 0] (chapter heading – referenced in the script XML)

1. Initial dialog box display

TITLE TEXT\_STORY\_TRANSMISSION\_17 (dialog box heading, text is XLS tag)

TEXTCOLOR 255 255 255 255 (text color for preceding text line)

TEXT TEXT\_STORY\_TANI\_00 (mission title)

IMAGE Mon\_Mothma.tga

1. Main Text, beginning of Mission

WAIT 500

SFX Button\_Press

NEWLINE 1

TEXTCOLOR 255 255 255 176

TEXT TEXT\_STORY\_TANI\_01 (First block of text – generally spoken)

1. Wait 1 second and then show First Task

WAIT 1000

PAUSE 1

SFX Button\_Press

NEWLINE 2

TEXTCOLOR 255 255 255 176

TEXT TEXT\_STORY\_TANI\_02 (task line)

1. Wait 10 seconds and then unpause the game

WAIT 10000

PAUSE 0

#### Possible Dialog Commands

**DIALOG** – Play a dialog speech file (use speech event name)

**IMAGE** – Show a still image in the dialog box (image name)

**MOVIE** – Play looping movie in radar map window (movie name from MOVIES.XML)

**MOVIE\_ONCE** – Play a movie once (movie name from MOVIES.XML)

**NEWLINE** – skip to next line (number of lines to skip)

**PAUSE** – turn pause on (1) or off (0)

**SFX** – play a sound effect (sound event from XML)

**TEXT** – show text (text name from XLS)

**TEXTCOLOR** – color the text just called just above this line (RGB-A numbers)

**TITLE** – text that appears in the window bar of the dialog box (incoming transmission usually used)

**WAIT** – wait for a specified amout of time (in ticks)

**WAIT\_SPEECH** – Wait for the above speech line (DIALOG) to finish before continuing

# ```

```

Since many if not most events should not be available under multiplayer, the multiplayer tag lets the designer state that the event is available in multiplayer games. In practice, it may be necessary to just create new plot threads for multiplayer (this is untested).