Brought to you by PCGamingWiki

Events file structure

From FTL Wiki
Revision as of 17:17, 25 August 2013 by (talk) (Trivial spelling correction.)
Jump to: navigation, search
Modding guide
Events file structure
Mod manager

The events files (events*.xml) contain all the information about the events. Each beacon also corresponds to an event. The information about which events occur as beacons in which sector is stored in the sector_data.xml file.

The basis of this structure is the event object. It serves two purposes:

  • Definition of a beacon
  • Result of your actions

An event object contains various information about the properties of the beacon / effects on you. One very special type of subobject is the choice object. An event can contain multiple of these and these are the choices you can select in the popups.

The next important type is the ship object. It defines ships you encounter in events and the consequences of dealing with them.

Then there are also eventList and textList which serve the purpose of randomization, and imgList which provides background images.

If you want to know the possible values for attributes, have a look at marinepower’s list.

How it works

When you arrive at a beacon, the corresponding event is executed:

  1. All the effects of the event are executed
  2. The text is displayed
  3. If there are choices, they are displayed (otherwise just “Continue …”)
  4. If the player made a choice in (3) that had an event attached: go to (1) for that event
  5. If there is a hostile ship, enter fight. Otherwise finish.
  6. Depending on how the battle ended, go to (1) for the corresponding ending event.


General Note: almost everything in this structure is optional. Leaving out an attribute will quite often randomize its value. The syntax on this page is: elementname ['attributes']. “TEXT” in the attributes list does not refer to an attribute, but to the content of this element. Indentation marks sub-element.

For the XML noobs:

<element attribute="attribute-value">content (TEXT)</element>


Basic example:

<event name="REBEL_VS_FEDERATION" unique="true">
	  Upon arriving at this beacon, you detect a distress call.  Local scans 
	  reveal that a Federation transport is under attack from a Rebel scout!
	<img back="BACKGROUND" planet="PLANET_POPULATED"/>
		<text>Aid the Federation ship.</text>
			<text>You power up your weapons and engage the Rebel ship.</text>
			<ship load="REBEL_VS_FEDERATION" hostile="true"/>
		<text>Use this chance to escape.</text>
			  The Rebel's preoccupation with the Federation ship 
			  allows you to slip away undetected.  However you can't 
			  help but feel you should have helped them.

event [name, unique]: define an event with id `name`, make sure it appears only once per game if `unique="true"`

text [TEXT, load]
The event’s text (`load` loads a textList instead)
choice [TEXT, lvl, req]
A choice for this event. See below for more info. A default “Continue…” is displayed if no choices are defined.
show a distress beacon on the map for this event
environment [type]
Setting – type is one of: nebula, asteroid, sun, storm
fleet [TEXT]
show a fleet in the background? One of: rebel, battle, fed
img [back, planet]
sets the background images. planet is rendered in front of back, both are the id of an imageList. Giving one is enough.
Turn this beacon into a store
ship [hostile, load]
loads an enemy ship (ship id specified in load)/ sets/changes it’s hostility status (true/false)
Special element – when present this is a repair station in sector 8
autoReward [TEXT, level]
Gives you a random revard
level is one of: LOW, MED, HIGH, RANDOM;
TEXT is one of: standard (scrap + 2 resources), stuff (less scrap, mostly resources (intended for surrenders)), scrap_only, fuel, missiles, droneparts, fuel_only. missiles_only, droneparts_only (`fuel`, `missiles` and `droneparts` include some scrap), weapon, augment, drone
augment [name]
Gives player an augmentation, `name` is an augmentation id or "RANDOM"
weapon [name]
Gives the player a weapon, `name` is weapon an id or "RANDOM"
drone [name]
Gives the player a drone schematic
crewMember [TEXT, amount, class]
If amount > 0: gives you amount crewmembers of race class.
If amount = 1: you can specify TEXT to name the new crewmember
If amount < 0: kills -amount of your crewmembers.
FTL 1.03.3 introduced class="traitor" when amount is negative, which adds hostile crew with the same name/race/sex as those lost.
damage [amount]
causes damage / negative amount heals
boarders [class, max, min]
`min`-`max` boarders of race `class`
"Your Map is updated" – reveals current sector map
modifyPursuit [amount]
Modifies the advance level of the rebel fleet by `amount` (may be negative)
quest [event]
Sets a quest marker on your map that corresponds to `event`
unlockShip [TEXT, id]
Unlock Ship with id `id` and display TEXT
Special element – teleports you to the secret sector (crystal)
item_modify [steal]
adds or removes items – this is displayed next to the choice text, unless `steal="true"`
item [max, min, type]
adds/removes `min`-`max` items, type is one of: scrap, fuel, drones, missiles
status [amount, system, target, type]
Modify the effective capacity of a system for either the player's ship or a nearby ship, while at this beacon.
target="player" / "enemy".
amount=An integer, whose meaning varies based on the status type. (This editor doesn't know what negative values might do.)
type="limit": Set a maximum.
type="divide": Divide (rounded down).
type="loss": Subtract. (TODO: Confirm this)
type="clear": End all status effects on the target's system. This often appears in the destroyed/deadCrew tags of a ship, which was loaded by an event that imposed a status effect. The amount for this is typically 100, for whatever reason.
NOTE: statuses on the same system will NOT stack. The last status applied will be the one that takes effect.


The choice element is only valid within an event. You can give just one choice with the text “Continue…” to tell a story or otherwise give temporal structure to your event. If an event has multiple choice elements, the player has to choose. Blue options are defined by using the attributes req and lvl.

Basic example:

	<choice hidden="true">
		<text>Try to communicate peacefully.</text>
		<event load="DONOR_PONY_PEACE"/>
	<choice hidden="true">
			<text>This isn't the time for exobiology. You head back to the ship.</text>
	<choice hidden="true" req="slug">
		<text>(Slugman Crew) Attempt to communicate telepathically.</text>
choice [hidden, lvl, req]
Defines a choice. Use req + level to generate blue choices: req can be the name of any race, weapon, drone, augmentation or system/subsystem. Add level to require a minimum level of system/subsystem
The hidden="true" attribute determines whether rewards (fuel, drone parts, scrap, etc) appear in the text for that choice. Omitting the hidden tag will cause any <item_modify> or <autoReward> materials to show after the text of the choice. It also causes unavailable options (blue options determined by req) to be hidden, rather than grayed out.
event [load]
Event to be triggered when this choice is taken. This element is required. One of:
  • A complete event, as detailed above (which can again contain choices)
  • empty with just the load attribute given: loads the event with the given id
  • completely empty (<element />), if you want nothing to happen at all.
text [TEXT]
The text for this choice

Event list

Event lists are a replacement for events. They contain multiple events, and wherever an event id is to be given (the load attributes), you can give the id of an eventList instead. A random event in the eventList is then chosen. All the events in a eventList have the same probability. If you want one of the events to be more likely, add it to the eventList multiple times.

Basic example:

<eventList name="DEAD_CREW_DEFAULT">
		<text>There are no more life-signs remaining on the ship. You strip it of useful materials.</text>
		<autoReward level="HIGH">standard</autoReward>
		   Now that their ship has been emptied of hostiles, you search it.
		   Eventually you find a prisoner who offers to join your crew.
		<crewMember amount="1"/>
		<autoReward level="MED">scrap_only</autoReward>
		<text>You find a weapon system on their ship. With no crew to stop you, you can install it on your own.</text>
		<autoReward level="MED">weapon</autoReward>
eventList [name]
define an eventList with id name
[load]: either use the structure of an event as detailed above or leave it empty and set the load attribute to an event id.

Text list

Text lists help to randomize events. Instead of giving an event a text, you can specify a textList to use. The game will pick one of the texts in the textList at random.

Basic example:

<textList name="BOSS_REPAIR_STATION">
	<text>There is a a mobile ship construction platform stationed at this beacon. After a brief exchange they give you clearance to receive emergency repairs and military supplies.</text>
	<text>An Engi civilian ship-yard has been converted into a military refueling station. They offer you the chance to patch up your ship and refresh some supplies.</text>
	<text>Chatter on the comm suggests the nearby Federation base is outfitted with a repair station. When you forward your mission priority they quickly help repair your ship and give you some supplies.</text>
	<text>A forward construction station is in the process of repairing damaged war ships. Your command codes convince them to do a quick patch job on your ship.</text>
	<text>A trade station was abandoned nearby. Some Federation engineers re-purposed their shipyard to perform military repairs. They offer to help fix your ship.</text>
textList [name] 
Define a textList with id name
text [TEXT, back, planet] 
back and planet can be set to use specific images if this text is chosen.


Basic example:

<ship name="PIRATE_SLAVER" auto_blueprint="SHIPS_PIRATE">  
	<surrender  chance="0.2" min="2" max="4">
		<text>We surrender! Take one of our slaves as tribute; if you destroy us they'll all die anyway!</text>
			<text>Accept their offer.</text>
				<crewMember amount="1"/>
				<ship hostile="false"/>
			<text>Surrender is not an option.</text>
	<escape  chance="0.5" min="2" max="4" load="PIRATE_ESCAPE"/>
		<text>The slave ship is destroyed. They won't continue their evil trade, but many lives were probably lost on that ship.</text>
		<autoReward level="HIGH">standard</autoReward>
	<deadCrew load="DEAD_CREW_SLAVER"/>

The subelements deadCrew, destroyed, escape, gotaway and surrender are events. They have exactly the same structure as the event object detailed above. But instead of giving them content you can also leave them empty and set the load attribute to the id of a normal event.

ship [auto_blueprint, name]
Define a ship of id name. Use blueprint or blueprintList auto_blueprint
define the crew’s race. Can have one or more crewMember subelements, their props should add up to 1.
crewMember [prop, type]
The crewmember is of race type with probability prop
deadCrew [load]
Event. Triggered when all the crew are dead
destroyed [load]
Event. Triggered when you destroyed the ship
escape [chance, load, max, min, timer]
Event. Triggered when the ship decides to try and escape. TODO: document the chance, max, min and timer attributes.
gotaway [load]
Event. Triggered when the ship jumped away successfully.
surrender [chance, load, max, min]
Event. Normally used to offer surrender, but could basically be used for anything. TODO: document the chance, max, min and timer attributes.
weaponOverride [count]
Override the ship’s weapons from the blueprint. TODO: how does count work?
name [TEXT]
The id of the weapon to put on the ship

Image list

Image lists are basic lists of images. They can be specified as back and planet in events and texts of textLists. One of the images is chosen at random.

Basic example:

<imageList name="BG_NEBULA">
	<img w="1280" h="720">stars/bg_darknebula.png</img>
	<img w="1280" h="720">stars/bg_blueStarcluster.png</img>
	<img w="1280" h="720">stars/bg_smallbluenebula.png</img>
imageList [name]
Create an imageList with id name.
img [TEXT, h, w]
specify an image