unlocks.xml

Flying close to a station and scanning it, or one of its signal leaks, can reveal something worth money: a discount on what the station sells, a commission on what it buys, or a blueprint. What can be revealed, under which conditions, how much it is worth and for how long is defined in libraries/unlocks.xml. The game picks from these entries whenever the player's scan qualifies, by weight among those whose conditions fit the station.

This article covers the format, the conditions and their meaning, the global limits, the script side and how an extension adds an unlock. It describes version 9.00.

Contents

• Terms
• How an unlock is triggered
• The file
  • Layout
  • Globals
  • Conditions
  • Actions
  • Values with units
• The script side
• Adding an unlock from an extension
• Reading on

Terms

• Unlock: one entry of the file, a discount, a commission, a blueprint or an information unlock. The file calls the whole mechanism an unlock and names the entries bonuses in places.
• Discount: a percentage off the prices a station sells at, for a time. Commission: a percentage on top of the prices it buys at. Both are granted to the player, at one station.
• Signal leak: the small glowing object on a station's hull the player scans in the ship or on foot. A data leak is one kind of it.
• Scanner level: the level of the player ship's scanner, which decides which leaks and which unlocks are available.
• Secrecy: a level, -1 to 3, that a station's information and blueprints carry; an unlock can be limited to a secrecy range.

↑ Contents

How an unlock is triggered

The schema describes the trigger as a check against the station the player is looking at:

1. The player is in range and looking at the station. The <globals> entry sets how close the player has to be before any check runs, and how far the player must move before the next check at the same place. The entry's own <distance> and <viewangle> narrow that further.
2. An entry qualifies when all of its conditions hold: the station's owner, the player's relation to that owner, what the station buys or sells, its secrecy level, the scanner level of the player's ship, and whether the player is on foot or in a spacesuit.
3. One entry is picked by weight among those that qualify. With a signal leak the pick is limited to the entries with leak set, which is the default.
4. Its actions apply. A discount or commission gets an amount and a duration rolled from the entry's ranges and is shown to the player; a blueprint is granted. The entry's <rechecktime> then holds it back at that station, and the global rechecktime holds every unlock back for a moment.

The scripts take over from there: event_player_signal_unlock_finished fires with the leak and its object, and event_player_discount_added and event_player_commission_added carry the name, the amount and the end time.

↑ Contents

The file

Layout

<unlocks>
  <globals threshold="800m" rechecktime="5s">
    <adjustment discount="{20212,1201}" commission="{20212,1301}" />
  </globals>
  <discount id="fruitfulcultivation" name="{20210,1011}" description="">
    <conditions weight="20">
      <wares sells="wheat meat spices spaceweed"/>
      <viewangle max="20"/>
      <distance exact="600m"/>
      <scannerlevel max="2" />
    </conditions>
    <actions>
      <amount min="2" max="6"/>
      <duration min="24h" max="48h"/>
    </actions>
    <rechecktime min="24h" max="36h"/>
  </discount>
  <commission id="orebounty" ...> ... </commission>
  <blueprint id="common_blueprint_l1"> ... </blueprint>
  ...
</unlocks>

• <globals> holds the limits that apply to every entry, and the names of the adjustment offsets.
• Each <discount>, <commission> and <blueprint> is one unlock. The schema also allows <information> entries, which unlock a chain of information about an object; vanilla has none.

The base file holds the vanilla discounts and commissions, a few of each per ware group and scanner level, the four blueprint unlocks, and the discount the diplomacy system of 9.00 grants. No expansion ships an unlocks.xml.

The schema, libraries/unlocks.xsd, documents every element and attribute, and a syntax example sits in a comment at the top of the file.

↑ Contents

Globals

↑ Contents

Conditions

<conditions> carries a weight, the entry's share of the pick among those that qualify, and three flags: firstperson for an unlock that needs the player on foot, spacesuit for one that needs a spacesuit, and leak, true by default, for whether the entry may be picked when a signal leak is scanned. The children narrow it:

Vanilla's discounts and commissions come in two tiers by scanner level: the ones with scannerlevel max="2" give two to six percent and the ones with min="3" six to fourteen. Each is tied to a ware group through <wares>, which is how a food discount appears at a farm and an ore commission at a refinery.

↑ Contents

Actions

<actions> is required for a discount or a commission and holds what it grants:

A blueprint unlock has no <actions>: what it grants is a blueprint the game picks within the entry's <blueprintsecrecy> bounds. Vanilla has a common and a rare blueprint unlock per scanner tier, the rare one with a fifth of the weight.

<rechecktime>, on the entry itself, is how long the unlock stays unavailable at a station once it has triggered there, as an exact value or a range.

↑ Contents

Values with units

Distances and times are written with their unit: 600m, 2km, 5s, 40min, 24h. A value without a unit is accepted by the schema, and the form with a unit is what vanilla writes everywhere.

↑ Contents

The script side

The file's entries are what the game triggers on its own; the actions above are how a script grants a discount or commission directly, with an amount and a time of its choosing. Vanilla's diplomacy script does exactly that for the diplomacy discount: the entry in the file carries leak="false", and the script grants it with add_player_discount when the action's reward comes due.

↑ Contents

Adding an unlock from an extension

A new unlock is a diff on libraries/unlocks.xml and a text for its name. The example below, for a fictional extension example_unlock, adds a discount on hull parts and claytronics at stations that sell them, for players with a level 3 scanner, worth a little more than the vanilla ones and lasting longer.

libraries/unlocks.xml:

<?xml version="1.0" encoding="utf-8"?>
<diff>
  <add sel="/unlocks">
    <discount id="example_constructionsurplus" name="{1234567,1}" description="">
      <conditions weight="5">
        <wares sells="hullparts claytronics"/>
        <viewangle max="20"/>
        <distance exact="400m"/>
        <relation min="0.01" max="1.0"/>
        <scannerlevel min="3"/>
      </conditions>
      <actions>
        <amount min="12" max="16"/>
        <duration min="48h" max="72h"/>
      </actions>
      <rechecktime min="36h" max="48h"/>
    </discount>
  </add>
</diff>

t/0001-l044.xml, with the page id the extension owns:

<?xml version="1.0" encoding="utf-8"?>
<language id="44">
  <page id="1234567" title="Example unlocks" descr="" voice="no">
    <t id="1">Construction Surplus</t>
  </page>
</language>

Some points about the example:

• The id is unique across every kind of entry, discounts and commissions alike, so a prefix of the extension's own keeps it clear of vanilla's and of other extensions'.
• The weight is measured against vanilla's: the level 3 discounts carry 5, so this one is as likely as any of them at a station that sells hull parts; a higher weight makes it the usual result there.
• The relation line keeps it for players at least friendly with the owner; without it the default allows anyone not hostile.
• No script is needed. The game triggers the entry, shows it, applies it to the station's prices and removes it when the duration ends.

The extension itself, its folder, content.xml and diff files, is covered in Anatomy of an extension and XML diff patching.

↑ Contents

Reading on

factions.xml defines the relation ranges the <relation> condition refers to.

↑ Contents