This article contains guidelines and instructions for controlling the spawning of stations and other encounters when a system is created. The features described here are implemented in 1.8 Beta 4.

Introduction

Station spawning is complicated because Transcendence is extensible. Traditionally, stations decide where they should spawn. For example, Ares stations spawn in the Outer Realm. The problem is that when new areas get created, station spawning breaks. Should Ares station spawn in the Near Stars (Eternity Port)? How about the Frontier (The Stars Beyond)?

The fundamental problem is that a station definition can't be expected to know about every map region where it could spawn. But every map region can't know about every station type (because extensions can also add new station types).

Core Concepts

The solution to the above dilemma is to add a level of indirection as follows:

  1. We add attributes to system topology definitions to define territory on the map. For example, we mark systems with the aresSpace attribute if Ares stations can spawn in that system.
  2. We add encounter rules to each station (or encounter) to require appropriate system attributes to spawn. For example, Ares stations would have rules saying they only spawn in systems with the aresSpace attribute.

These two rules we can handle the common expansion cases. If a mod wants to add a new map region, the mod can set appropriate attributes on the map to cause existing station types to spawn. Conversely, if a mod wants to add new kinds of stations (e.g., a new sovereign), the mod can add appropriate attributes to existing maps.

Implementation Methods

Topology Processors

We use <TopologyProcessor> element in a <SystemMap> type to add attributes to system nodes. This is more flexible than hard-coding the attributes when defining the system, and can be done without overriding the original map.

For example, the smHumanSpace map is used to define system nodes in Human Space. We use additional <TopologyProcessor> elements to set attributes like aresSpace and commonwealthSpace:

<SystemMap unid="&smAresSpace;"
   displayOn="&smHumanSpace;"
   >
   <TopologyProcessor priority="primaryColony">
      <System criteria="+outerRealm;" attributes="aresSpace"/>
   </TopologyProcessor>
</SystemMap>

The above type adds the aresSpace attributes to all system nodes in the Outer Realm (all nodes with the outerRealm attribute).

You may add any number of <System> elements inside <TopologyProcessor>, each of which can add one or more attributes to a set of system nodes. You may also have multiple attributes, separated by commas. For example:

<SystemMap ...>
   <TopologyProcessor ...>
      <System criteria="+outerRealm;" attributes="aresSpace"/>
      <System criteria="+ungoverned;" attributes="aresSpace, aresBorderZone"/>
   </TopologyProcessor>
</SystemMap>

In addition to criteria, you may specify a set of systems in terms of distances from a node or set. For example, we might want to mark all star systems within 4 gates of Jiang's Star to be sungSpace:

<SystemMap ...>
   <TopologyProcessor ...>
      <System attributes="sungSpace">
         <Criteria>
            <DistanceTo nodeID="C9" min="0" max="4"/>
         </Criteria>
      </System>
   </TopologyProcessor>
</SystemMap>

Topology Processor Priorities

In some cases, you may want to specify nodes by attributes set in other processors. For example, imagine that I wanted to define a territory relative to Ares space. In that case, I would need to refer to aresSpace in the criteria. But how can we guarantee that the Ares topology processor has already run?

The solution is to define a priority for the topology processor:

<SystemMap ...>
   <TopologyProcessor priority="secondaryColony">
   ...

Different priorities run at different times. Topology processors run in the following order:

  1. formation: Use this priority for geophysical formations, e.g., ores etc. Topology processors with this priority always run first.
  2. lifeforms: This priority runs next. Use it for indigenous spacefaring lifeforms.
  3. primaryColony: Use this priority for colonization that is independent of other sovereigns.
  4. secondaryColony: Use this priority if you depend on attributes set by primaryColony.
  5. tertiaryColony: This priority runs last. Use it if you depend on attributes set by secondaryColony.

Encounter Definitions

<StationType> and <EncounterType> elements can have an <Encounter> sub-element that defines the spawning rules. This sub-element controls three independent set of rules:

  • System Selection: Rules to pick which systems the encounter can spawn in.
  • Location Selection: Rules to pick the specific location within a system where the encounter can spawn (e.g., in an asteroid field).
  • Count Selection: Rules about the minimum or maximum number of encounters in a game or a system.

We describe each in the following sections.

System Selection By Level

The easiest selection is by level. We can choose the frequency with which an encounter will spawn depending on the system level (from 1 to 25). We use the standard levelFrequency= syntax:

<Encounter
   levelFrequency="----- cur-- ----- ----- -----"
   ...
   />

Level frequency is expressed as a set of characters grouped into 5-character chucks. Each chuck represents five levels. The first chunk of 5 characters represents levels 1 through 5. The next chunk represents levels 6 through 10, and so on.

Each character represents a frequency:

  • c = Common: This is the highest frequency for spawning.
  • u = Uncommon: Uncommon is half as frequent as Common.
  • r = Rare: Rare is one-fifth as frequent as Common.
  • v = Very rare: Very Rare is one-quarter as frequent as Rare and one-twentieth as frequent as Common.
  • - = N/A: The encounter cannot happen at this level.

In the example above, the encounter is Common at level 5, Uncommon at level 6, and Rare at level 7. The encounter never happens at any other system level.

System Selection By Attributes

You may choose systems based on attributes using the systemCriteria= parameter:

<Encounter
   systemCriteria="+aresSpace; -nearStars;"
   ...
   />

The criteria specifies that some attributes are required (+) while other attributes are excluded (-). The encounter will only spawn in systems that have all the required attributes and none of the excluded attributes.

In the example above, we spawn in any system that has the aresSpace attribute but does not have the nearStars attribute.

You may refer to any attribute on the system set in the topology itself or defined in the <SystemType> or set by a <TopologyProcessor>.

If you use systemCriteria= with levelFrequency=, then a system must match both requirements.

System Affinity

The systemAffinity= parameter is similar to systemCriteria= but gives you more fine-grained control. systemCriteria= is binary: either the spawn can happen in that system or not. In contrast, systemAffinity= adjusts the probability of spawning.

The syntax is similar, but you may use multiple + and - characters to adjust the probability. For example:

<Encounter
   systemAffinity="+++aresSpace; --nearStars;"
   ...
   />

In the example above, we strongly prefer systems with aresSpace and moderately reject systems with nearStars. The adjustments to probability are as follows:

  • +++: If attribute is not present, reduce frequency to one-tenth normal.
  • ++: If attribute is not present, reduce frequency to one-quarter normal.
  • +: If attribute is not present, reduce frequency to one-half normal.
  • -: If attribute is present, reduce frequency to one-half normal.
  • --: If attribute is present, reduce frequency to one-quarter normal.
  • ---: If attribute is present, reduce frequency to one-tenth normal.
  • *: Attribute is required; frequency reduced to 0 if attribute is not present.
  • !: Attribute is disqualifying; frequency reduced to 0 if attribute is present.

You may combine systemAffinity= with systemCriteria= and/or levelFrequency=.

System Selection by Distance

In some cases you may want to select systems based on their distance from a specific system or region. For example, you might want an encounter to spawn only in systems within three stargate jumps from a node (or a region).

The distanceCriteria= and distanceFrequency= parameters can be used to control this:

<Encounter
   distanceCriteria="+nearStars;"
   distanceFrequency="ccccu|urv--"
   ...
   />

In the example above, the distanceCriteria specifies all systems with the nearStars attribute. The distanceFrequency= parameter specifies the frequency relative to the distance of a given system from the boundary between nearStars systems and non-nearStars systems.

The vertical bar represents the boundary. The character to the left of the vertical bar represents a system with the nearStars attribute that borders on a system without the nearStars attribute. The character to the right of the vertical bar represents a system without the attribute that borders on a system with it.

Moving to the left or right of the vertical bar, we specify the frequency for systems at increasing stargate distances from the border. The u character to the left of the vertical bar means that spawning is Uncommon on a system with the nearStars attribute right on the border (i.e., one stargate jump away from a system without the attribute).

The character to the left of that, a c, means that spawning is Common in systems that are at least two jumps away from a system without the nearStars attribute.

Currently, you must specify exactly 5 character on either side of the vertical bar, with no whitespace.

You may combine this with any of the other parameters described here.

Human Space Attributes

In Human Space we define attributes for each sovereign to control where they spawn. The following are some of the most common attributes used:

  • commonwealthCore: Set for systems of the New Beyond, Ungoverned Territories, and Outer Realm. This is the main territory of the Commonwealth, with the highest probability of encounters.
  • commonwealthSpace: This region is a superset of commonwealthCore and defines the greatest extent of the Commonwealth. In general, Commonwealth stations only spawn in systems with this attribute. If a system has the commonwealthSpace attribute but not the commonwealthCore attribute, then the chance for encounters is lower.
  • corporateCore: This attribute is set wherever commonwealthCore is set. It is used for Corporate Hierarchy spawns.
  • corporateSpace: This attribute is set wherever commonwealthSpace is set. It is used analogously for Corporate Hierarchy spawns.
  • cscOperationsSpace: This attribute defines the region where CSCs are encountered.
  • outlawSpace: This attribute is shared by all common outlaw sovereigns, including: Black Market, Charon Pirates, Death Drugs Cartel, Marauders, Outlaws, and Outlaw Miners.
  • ringerSpace: This attribute defines where Ringers are encountered.
assumedpseudonym 9 Nov 2018:

 Typo in the System Affinity section, you have an extra tilde at the end of +++.

george moromisato 9 Nov 2018:

@AP: Thanks! Fixed.