Brought to you by PCGamingWiki

Events file structure

From FTL Wiki
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.

This list by marinepower is outdated, but provides some of the possible values for attributes, which may be helpful to some degree.

How it works[edit]

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 sector if `unique="true"
text [TEXT, id, load]
The event’s text. If no TEXT is specified then either id or load is used.
`id` loads a text from text_events.xml
`load` loads a textList
choice [req, lvl, max_lvl, max_group, hidden, blue]
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)), fuel, missiles, droneparts (`fuel`, `missiles` and `droneparts` include some scrap), fuel_only, missiles_only, droneparts_only, scrap_only, 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, skills, amount, class]
If amount > 0: gives you amount crewmembers of race class.
If amount = 1: you can specify TEXT to name the new crewmember AND set their skills, ex.: <crewMember repair="1" combat="2" shields="0.5" amount="1" class="human">Melvin</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, system, target, effect]
'positive' amount causes damage / 'negative' amount heals hull, system targets system/subsystem (when a system is specified, both the hull AND the system will take damage), target can be either 'player', 'ship' or 'both', effect can be 'fire', 'breach', 'random', 'all' or 'none'
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.
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 denoted as a percentage, typically 100 to fully (100%) clear an effect.
NOTE: statuses on the same system will NOT stack. The last status applied will be the one that takes effect.
Removes a random crew member.
clone [TEXT]
true/false. Determines whether the lost crew member can be cloned, thus, only of pertinence when the player has a clone bay.
text [TEXT, id, load]
A description detailing what happens to the crew member in the event the player has a clone bay. Of course, this should match the value of clone. If no TEXT is specified then either id or load is used.
`id` loads a text from text_events.xml
`load` loads a textList
remove [name]
Removes the blueprint specified by `name` and displays the "item_removed" text (found in text_misc.xml, default is "Item removed: \1", where \1 is the specified blueprint). Note that the "item_removed" text displays regardless of whether or not an item was actually removed. Thus, remove should only be used when `name` shares its value with the `req` of the closest choice above its declaration.


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 [req, lvl, max_lvl, max_group, hidden, blue]
Defines a choice.
the name of any race, weapon, drone, augmentation or system/subsystem.
  • When hidden is set to true, the choice will be visible, able to be selected, and will be a blue choice (unless blue is set to false), if and only if the player has whatever is specified by the req, otherwise it will not be shown (hidden).
  • When hidden is omitted or set to false and the player does not have the listed req, the player will be able to see the choice but will be unable to select it (it will be grayed out).
lvl (used with req)
integer >= 0. Sets a minimum level of system/subsystem or amount of crew of a certain race.
max_lvl (used with req and typically lvl)
integer >= 0. add this to require a maximum level of system/subsystem. If both lvl and max_lvl are 0, then the choice will only show if the player does not have the listed req, in which case it can be any type of req (not limited to system/subsystem).
max_group (used with req and possibly lvl)
integer >= 0. Sets a grouping for the choice. When multiple choices have different req attributes and possibly varying degrees of lvl, but the same max_group: from the choices that the player could choose only the last choice will appear, and it will appear as the very last choice unless there are choices with higher max_group amounts (that the player can select).
true/false, false if omitted. When set to false or omitted, it causes rewards (fuel, drone parts, scrap, etc) in the choice's event (specified by <item_modify> or <autoReward>) to appear next to the choice's text. See req for behavior of hidden when used alongside req.
blue (used with req)
true/false, true if omitted. Determines whether the choice will appear as (literally) a blue choice. Only has meaning when used alongside req, as only req can make the choice blue in the first place.
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, id, load]
The event’s text. If no TEXT is specified then either id or load is used.
`id` loads a text from text_events.xml
`load` loads a textList

Event list[edit]

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[edit]

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[edit]

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