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)

# 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

# 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)

# 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)

# 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
# - denotes a comment line

Multiplayer (Multiplayer)
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).