parameters.xml

libraries/parameters.xml is where the game keeps the numbers that are not part of any one object: how a pilot of a given skill steers, how long an autosave waits, what a build plot costs, how far from a station a ship may be and still get a dock assigned, at what distance the map fades an icon in, when fight music switches to its big version. The file is one root element with one section per subject, some seventy sections in 9.00, and each game system reads its own. One section, <scriptparams>, is not for the engine at all: it is a table of named values the scripts read through the param keyword, which makes it the natural place for an extension's own tuning values.

This article covers the format, what the sections hold, the script parameters in detail, how the expansions change the file, the script side, and how an extension adds a parameter and changes a vanilla one. It describes version 9.00.

Contents

• Terms
• How the game uses it
• The file
  • Layout
  • The sections
  • Value forms
• The script parameters
• How the expansions change it
• The script side
• Adding a parameter from an extension
• Reading on

Terms

• Section: a direct child of <parameters>, named after the system it tunes: <aiflight>, <economy>, <docking>. The schema allows each section once at most, in any order.
• Typed section: a section whose content libraries/parameters.xsd describes element by element, with a documentation line on most attributes. A little over half of the sections are typed.
• Untyped section: a section the schema declares as anycontent: any content passes validation, and the comments in the file are the only description. The player flight, camera, first person, map and loadout sections are of this kind.
• Script parameter: a <param> in a <category> of <scriptparams>, a named value a script reads as param.<category>.<name>.
• Fallback value: a value in this file that applies when an object has none of its own, such as the loadout level of a ship created without one.

↑ Contents

How the game uses it

The file is a library like the others in libraries/: the game reads it when it starts, and an expansion or an extension changes it with a <diff> file of the same name. What sets it apart is that nothing in it describes an object. A ship macro says what one ship is; parameters.xml says how every ship docks, how every pilot of a given skill steers, how every station prices a plot.

Each section belongs to one system. The engine reads <docking> when it assigns a dock and plays the landing animation, <economy> when it prices and logs trades, <holomap> when it draws the map, <platformnavigation> when it builds the navigation mesh of a station interior. Scripts do not see these sections; a few of their values reach a script as a default, listed under The script side. The section scripts do read is <scriptparams>, through the param keyword, and that section has no engine meaning: the engine holds the values, the scripts give them meaning.

Three consequences for an extension:

• A changed value applies to the whole game. The AI attack run distance, the autosave window or the plot price formula have no per-object override. A <replace> on the attribute changes it for everything.
• A new script parameter is free. <scriptparams> accepts any category and any name. An extension that adds a category of its own gets a tuning table its scripts read with one keyword, and that a player or another extension can patch with a diff.
• The schema is the documentation where there is one. A typed section carries a documentation line per attribute in parameters.xsd. An untyped section has only the comments in the file, and some of those are the developers' notes to each other.

↑ Contents

The file

Layout

<?xml version="1.0" encoding="utf-8"?>
<parameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:noNamespaceSchemaLocation="parameters.xsd">
  <playerflight>
    <input>
      <mouse>
        <curve>
          <point position="0" value="0" />
          <point position="0.05" value="0" />
          <point position="0.8" value="1" />
        </curve>
      </mouse>
      ...
    </input>
    ...
  </playerflight>
  <aiflight>...</aiflight>
  <aicombat>...</aicombat>
  ...
  <economy>
    <prices>
      <rounding up="false" />
      <build min="0.25" shipsalefactor="0.3" />
      <resource min="3600" max="144000" />
      <product factor="5000000" />
      <builder fee="50000" />
    </prices>
    ...
  </economy>
  ...
  <scriptparams>
    <category name="autosave">
      <param name="mintime" value="40min" />
      <param name="maxtime" value="80min" />
      <param name="retrytimeout" value="120s" />
    </category>
    ...
  </scriptparams>
  ...
  <storage base="10000000" />
  ...
  <missions limit="10" limitenabled="false" />
  ...
  <prestige>
    <level value="0"  name="{1001,12940}"/>
    <level value="1"  name="{1001,12941}"/>
    <level value="50" name="{1001,12942}"/>
  </prestige>
</parameters>

The root is <parameters>, with the schema declared on it, and every child is a section. The schema lists the sections in an xs:all group, so each may appear once and the order is free; the vanilla file runs roughly from flight and combat through the interface and the economy to docking and stations, with the small sections at the end. Two sections the schema knows, <playerfirstpersongeometry> and <materials>, are absent from the vanilla file.

↑ Contents

The sections

The tables below name every section of the vanilla file, what it holds, and whether the schema types it. "Typed" means parameters.xsd describes the content and documents the attributes; "any" means the schema accepts anything there, and the file's comments are all there is. In a typed section the attribute documentation is the place to read before changing a value.

Flight and movement

Combat

On foot

Interface and map

Scanning and drops

Economy and stations

Docking

Sound and voice

Scripts and the rest

↑ Contents

Value forms

A section writes its values in a few recurring forms:

• Attributes on the section itself, for a section with one or two values: <storage base="10000000" />, <missions limit="10" limitenabled="false" />.
• Nested elements with attributes, one element per topic: <economy><prices><builder fee="50000" /></prices></economy>. Most sections are of this form, two or three levels deep.
• Curves: a list of <point position="..." value="..." />, in the input sections, the collision damage of <physics>, the curve factors of <masstraffic> and the anomaly sound. A typed curve carries a default for an input outside its points.
• Keyed lists: <tag id="..." speed="..." />, <ware ware="..." amount="..." />, <entry mode="..." icon="..." />, <dock tags="..." />, <threshold classes="..." />, <skill level="..." />, <level value="..." />, <race id="..." />.
• References into other files: colours by name from libraries/colors.xml, the schema saying so on each such attribute; sounds by id; materials as library.name; macros; icons; texts as {page,id}; order ids in <building>.
• Units: the engine sections hold plain numbers, and the schema's documentation says the unit, seconds, metres, degrees or percent. The script parameters are expressions and carry their unit in the value: 40min, 20km.
• Comments: XML comments throughout, and a comment attribute on <param> and on the navigation mesh overrides, "for documentation purposes only" in the schema's words.

↑ Contents

The script parameters

<scriptparams>
  <!-- Script access via param keyword (e.g. param.boarding.recruitstrength) -->
  <category name="crewtransfer">
    <param name="podmacro" value="macro.ship_gen_xs_escapepod_01_a_macro" />
    <param name="max_npcs_per_pod" value="3" comment="Number of people that can be assigned to the same pod" />
    <param name="max_travel_time" value="5min" comment="Max pod travel duration (not including scheduled launch delay) after which the transferred crew is expected to arrive at destination" />
  </category>
  <category name="docking">
    <!-- max distance at which player.occupiedship might be given permission to dock. -->
    <param name="maxdistance" value="table[
           {class.ship_xs} = 500m,
           {class.ship_s} = 5km,
           {class.ship_m} = 5km,
           {class.ship_l} = 15km,
           {class.ship_xl} = 15km]"/>
  </category>
</scriptparams>

• <category name>: an identifier, letters, digits and underscores not starting with a digit. It is the first part of the keyword path.
• <param name>: an identifier, the second part of the path.
• value: a script expression, the schema's expression type. The vanilla values show the range: a number, a number with a unit (40min, 120s, 20km, 150m), a boolean, a quoted string ('initial'), an enumeration constant (macro.ship_gen_xs_boardingpod_01_a_macro, formationshape.pointguard, class.ship_s, ware.ore, tag.console_01), a list, or a table keyed by such constants. A float literal may carry the f suffix, as in 0.9f.
• comment: documentation only.

A script reads a parameter as param.<category>.<name>. The result has the type the expression yields; the script side has no declaration of it, so the script has to know what it reads, and a checker cannot tell. A table parameter is read by key, param.docking.maxdistance.{$ship.class}; the ? suffix tests whether a key exists, and an @ before param suppresses the error for a parameter that may be missing, the form Timelines uses for its optional entries.

The vanilla categories, and who reads them:

Nothing in the engine knows these names. A category or a parameter an extension adds is as valid as a vanilla one, and a vanilla value an extension replaces changes every script that reads it. The autosave window is the common case: two replaced values, and the game saves on a different rhythm.

↑ Contents

How the expansions change it

Four of the five expansions ship a <diff> on the file, and all four add rather than replace. Kingdom End and Split Vendetta each <add> a navigation mesh override to <platformnavigation>/<navmesh_overrides>, one by id for a Boron throne room, one by template for a Split frigate with a comment on the gap it closes. Cradle of Humanity adds a ware to <economy>/<illegalwares>. Timelines adds a <scriptparams> category for its scenario consoles and a navigation mesh override for a Terran corvette. Tides of Avarice ships no file. No expansion changes a vanilla value.

↑ Contents

The script side

No vanilla UI script reads a script parameter: the interface sections of the file reach the UI through the engine, and a Lua side that needs a script parameter gets it from a script.

↑ Contents

Adding a parameter from an extension

An extension's own tuning values are a new <scriptparams> category, and a vanilla value it wants different is a <replace> on the attribute. The example below, for a fictional extension example_parameters, does both: it adds a category with an interval, a hint position and a table of text ids by ship class, replaces the autosave maximum, and turns the simultaneous mission limit on. Its script shows a reminder every interval, the text picked by the class of the ship the player flies, at the configured position.

libraries/parameters.xml:

<?xml version="1.0" encoding="utf-8"?>
<diff>
  <add sel="/parameters/scriptparams">
    <category name="example_parameters">
      <param name="reminder_interval" value="15min" comment="Time between two reminders" />
      <param name="reminder_position" value="7" comment="Index into hintpositions: 7 is bottom centre" />
      <param name="reminder_texts" value="table[ {class.ship_m} = 11, {class.ship_l} = 12, {class.ship_xl} = 13 ]" comment="Text id on the extension's page per ship class; classes not listed get no reminder" />
    </category>
  </add>
  <replace sel="/parameters/scriptparams/category[@name='autosave']/param[@name='maxtime']/@value">60min</replace>
  <replace sel="/parameters/missions/@limitenabled">true</replace>
</diff>

md/example_parameters.xml:

<?xml version="1.0" encoding="utf-8"?>
<mdscript name="Example_Parameters" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="md.xsd">
  <cues>
    <cue name="Reminder">
      <delay exact="param.example_parameters.reminder_interval" />
      <actions>
        <do_if value="player.occupiedship and param.example_parameters.reminder_texts.{player.occupiedship.class}?">
          <show_help custom="readtext.{1234567}.{param.example_parameters.reminder_texts.{player.occupiedship.class}}" position="param.example_parameters.reminder_position" duration="10s" />
        </do_if>
        <reset_cue cue="this" />
      </actions>
    </cue>
  </cues>
</mdscript>

t/0001-l044.xml:

<?xml version="1.0" encoding="utf-8"?>
<language id="44">
  <page id="1234567" title="Example parameters" descr="" voice="no">
    <t id="11">Reminder: this is a medium ship.</t>
    <t id="12">Reminder: this is a large ship.</t>
    <t id="13">Reminder: this is an extra large ship.</t>
  </page>
</language>

Some points about the example:

• The category is the extension's settings table. Any script reads param.example_parameters.<name>, and a player or another extension changes a value with the same <replace> on @value the example applies to the autosave, selected by category and parameter name.
• A value is an expression. 15min is a time, 7 an integer, and the table is keyed by class. constants. A string would need quotes. The reading script decides what the value means; delay takes the time, show_help the index.
• A delay, not a check interval. A cue's checkinterval must be constant, by its documentation, so the loop is a <delay> with the parameter as its expression, followed by reset_cue.
• The ? on the table lookup keeps small ships quiet: a class without an entry gives no reminder, instead of a reminder with an empty text.
• The position is the index into <hintpositions>; 7 is the bottom centre entry of the vanilla list.
• The two replaced values apply to the whole game, as every value in this file does: the autosave triggered by the timer comes after an hour instead of eighty minutes, and the engine's limit of ten simultaneous missions, defined but switched off in vanilla, is on.
• The texts are the extension's own: page 1234567 stands for its page. readtext.{page}.{id} resolves a text id held in a variable, where the {page,id} form needs constants.

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

↑ Contents

Reading on

loadoutrules.xml is the file behind the unit fill that <loadout> sets the default level for. jobs.xml explains the quota cleanup that <jobs> tunes, and god.xml the quotas and module limits that <god> and <economy>/<modulelimits> factor. drops.xml holds the drop lists while <drop> holds the chances. notificationtypes.xml defines the notifications whose cooldowns sit in the cooldown category. quotas.xml limits mission offers per type and space, a separate mechanism from the player's mission limit in <missions>.

↑ Contents