Transcendence Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
NOTE: The SystemMap type is a new design type slated for official support in version 1.1. The documentation here is preliminary and may change between now and the release of 1.1. This documentation is current as of version 1.07; some features may not work in 1.06a and below.

===== Overview =====
<SystemMap> defines the properties and behaviors of a set of [[topology nodes]] arranged on a two-dimensional map. The SystemMap type is the recommended way of defining topologies in an adventure. It supercedes (and encapsulates) the [[<SystemTopology>]] element used in prior versions.

An extension may have zero or more SystemMap types. An adventure must have at least one (or, for backwards compatibility, the older <SystemTopology> element).

The core purpose of a SystemMap is to procedurally generate a set of topology nodes, link them together into a stargate network, and assign properties to them, such as name, system type, and list of attributes.

===== Basic Attributes =====
**UNID=** The [[UNID]] of the system map.

**name=** The name of this map.

**backgroundImage=** The UNID of a background image to use for the map.

**initialScale=** A percent value indicating the initial zoom level of the map. For example, a value of 100 means that the map should be shown at 100% scale. The default is 100. NOTE: The display engine currently only supports scales of 25, 50, 100, 200, and 400.

**maxScale=** A percent value indicating the maximum zoom level of the map. See **initialScale**. The default is 50.

**minScale=** A percent value indicating the minimum zoom level of the map. See **initialScale**. The default is 200.

**displayOn=** This optional attribute specifies the UNID of the system map that should be used to display the topology nodes contained in this map. Use this in extensions when you want to add topology nodes to an existing map. If this option is specified, parameters related to display (such as **name** and **backgroundImage**) are ignored.

==== <Uses> ====
In some cases, a system map may want to refer to nodes in a different map. In that case, you must use the <Uses> sub-element to point to the destination system map. This guarantees that the target system map is loaded before this one. The **UNID=** attribute on <Uses> specifies the system map to use.

Note: If you use the **displayOn=** property you do not need to specify that map with <Uses>; it will automatically be loaded first.

===== Topology Node Definitions =====
A system map contains zero or more //node definition// sub-elements that define the topology.

A system map must also have one or more <RootNode> sub-elements. Topology generation consists of iterating over all <RootNode> elements in order. We begin by creating the node or nodes specified by //node definition// element pointed to by the <RootNode>. For each node created in this way, we follow any stargate links and create destination nodes if necessary. We continue in this way, following stargates and creating nodes as necessary, until all nodes reachable from the original root node have been created.

See: [[Topology]] for more information about topology generation.

====<Network>====
This is a //node definition// element that creates zero or more nodes and connects them by stargates.

The **ID=** attribute specifies the ID of the network. You may refer to this ID from a <Stargate> element in a <Node> definition.

The **<Nodes>** sub-element contains a list of <Node> elements to create.

The **<Stargates>** sub-element contains a list of <Stargate> elements, each of which defines a stargate between two nodes specified in the <Nodes> element.

The <Stargate> element has two attributes: **from=** Identifies one of the nodes and **to=** identifies the other. Note: There is no need to specify both sides of the gate. If a stargate is defined from node "A" to node "B" we automatically create a reverse stargate from "B" to "A" as well.

The **to** attribute in <Stargate> may have the special value, **[FragmentExit]**. In that case, the stargate leads to wherever the fragment specifies.

The **from** and **to** attributes may specify a stargate name using the following syntax: {nodeID}:{stargateName}. For example, **from="A:Gate1"** creates a gate named "Gate1" in node "A". If a stargate name is not specified, a name is automatically generated.

Any <Stargate> element may contain a **chance=** attribute, specifying that the stargate has the given probability of appearing. For example, **chance="50"** on a <Stargate> element means that the stargate only appears on 50% of the games.

The <Stargates> element may contain a <Table> sub-element instead of a list of <Stargate> sub-elements. In that case, we randomly pick one entry in the <Table> and generate the stargates specified therein. Use the <Group> sub-element in a <Table> to group a set of stargates under a single entry.

If a stargate points to a network, then it will resolve to the first node in the <Nodes> element or to the node specified by the <FragmentEntrance> element under <Stargates>.

NOTE: As of version 1.07, <Network> elements should only be used as fragments (i.e., only from a <Stargate> element with a **destFragmentRotation** attribute.

====<Node>====
A <Node> element is a //node definition// element that creates a single node. The element may have the following attributes and sub-elements.

**ID=** This is a globally unique identifier for the node. Unless defined inside a fragment, the identifier must be unique in the entire topology, not just in the SystemMap. If the node is defined inside a fragment (i.e., a sub-topology designed to be re-used in multiple places) then you must use the '+' character as a prefix for the ID to indicate that the node is relative to the fragment.

**pos=** This is the position of the node on the map, relative to the center of background image. The position consists of x and y Cartessian coordinates (down is negative) separated by a comma.

**attributes=** This is a comma-separated list of attributes for the node. The attributes for a node can be used by <TopologyProcessor> elements to add new attributes or define the system type. The attributes for a node can also be accessed with the [[functions:sysHasAttribute]] function.

===<System>===
The <System> sub-element specifies the system type of the node. The sub-element has the following attributes:

**UNID=** This is the UNID of the <SystemType> to use for this node.

**name=** This is the name of the system.

**level=** This is the level of the system.

**attributes=** Additional attributes may be specified here. These attributes are combined with any attributes defined at the node level.

The <System> element may contain a <Table> sub-element to randomly determine the system type and other parameters. In that case, UNID must be blank and the <Table> sub-element contains one or more <System> entries, each of which has a **chance=** attribute. The <System> sub-elements inside a <Table> must contain an **UNID** attribute and may contain **name**, **level**, and **attributes**, which override the setting at the parent level.

===<Stargate>===
The <Node> element may contain zero or more <Stargate> elements specifying a stargate to another node. Each <Stargate> element has the following attributes:

**to=** This is the ID of the //node definition// element that the stargate connects to. You may specify a destination stargate using the following syntax: {nodeID}:{stargateName}. For example, **to="B:Gate1"** connects this node to stargate "Gate1" in node "B". If no stargate is specified, a new one is created with an autogenerated name.

**name=** This is an optional attribute that specifies the name for the stargate. If unspecified, the name is automatically generated.

**destFragmentRotation=** If specified, this means that the //node definition// element specified in **to** is a topology fragment that may be re-used in multiple places in the topology. This specifies a rotation angle (in degrees) by which the destination fragment should be rotated.

**destFragmentAttributes=** If we're pointing to a fragment, these attributes are applied to all nodes created by the fragment definition.

**destFragmentExit=** If we're pointing to a fragment, this is the ID of a //node definition// element that the fragment should link to. This is used, for example, when a fragment is spliced in between two <Nodes> in a topology.

The <Stargate> element may contain a <Table> sub-element. In that case, the <Table> contains a list of entries, each of which specifies one or more <Stargate> elements. One entry is randomly chosen.

=== <MapEffect> ===
Use the <MapEffect> sub-element to optionally specify an [[:Effects|effect]] to paint on the map at the position of this node. This is used, for example, to randomly paint nebulae on the map at appropriate locations.

The <MapEffect> sub-element may contain any valid effect element.

==== <NodeTable> ====
A <NodeTable> is a //node definition// element that randomly selects a node definition element from a table. For example, imagine that you want to create a topology in which node "A" randomly leads either to node "B" or to node "C". You can create a <NodeTable> with **ID="T"** and create a stargate from node "A" to "T". <NodeTable> "T" can then randomly choose between "B" or "C".

This technique is particularly useful when several nodes need to point to a random fragment. In that case, the <NodeTable> can contain a list of fragments and the source nodes can point to the table.

A <NodeTable> has the following attributes and sub-elements:

**ID=** This is the globally unique ID for the table.

=== <Node> ===
A <NodeTable> may contain zero or more <Node> sub-elements. Each <Node> sub-element has the following attributes:

**chance=** This value represents the chance that this particular entry in the table will be chosen. The probabiliy of this entry being chosen is proportional to the ratio of **chance** to the sum of all **chance** values for all entries.

**ID=** This is the globally unique ID of the //node definition// element to select if this entry in the <NodeTable> is chosen.

====<Random>====
A <Random> element is a //node definition// element that creates a random network of nodes. The nodes are all connected to each other by at least one stargate. The <Random> element may have the following attributes and sub-elements:

**ID=** This is the ID of the node definition. You may refer to this from a <Stargate> element.

**count=** This is the number of nodes to create in the random network. You may use a [[dice range]].

**minSeparation=** This is the minimum separation between any node in the random network (in pixels). Note that this is only a guideline for the random algorithm. There are cases in which two nodes will be placed closer than this value.

===<Area>===
The <Area> sub-element defines the area in which the random nodes will be placed. The <Area> element may contain one or more sub-elements. Each sub-element specifies an area on the map. The union of all the areas defined by each sub-element is the area in which the nodes will be placed.

The <Line> sub-element defines a line between two points, specified by the **from=** and **to=** attributes. The **radius=** attribute defines the maximum distance from the line that a node can appear. Typically, the <Line> element is used to define a path along which nodes may be placed.

The **from=** and **to=** attributes may have the special value **[FragmentEntrance]** to represent the position of the node that leads to this fragment. Similarly, they may have the special value **[FragmentExit]**.

===<NodeTemplate>===
The <Random> element may have a most one <NodeTemplate> sub-element. The <NodeTemplate> element optionally defines the attributes and system properties to set for all random nodes (i.e., all nodes that are not specified in the <SetNodes> element).

===<SetNodes>===
The <SetNodes> sub-element defines a list of <Node> elements that are to be placed. Each <Node> element in the list is placed randomly in the defined <Area>. If there are fewer <Node> elements than then count of nodes in the <Random> network, then the remaining nodes are initialized with the <NodeTemplate> element. If there are more <Node> elements, then the remainder are ignored.

===== TopologyProcessor =====
When the entire topology has been created, we iterate over all <TopologyProcessor> nodes in order and apply them to the topology. A TopologyProcessor is an element that can assign additional attributes to existing nodes and a SystemType to nodes that do not already have one. There can be multiple instances of a TopologyProcessor in a SystemMap. Additionally, TopologyProcessors are recursive in that the <Group>, <Processor>, and any element with a <System> subelement will act as a TopologyProcessor of its own, using the nodes filtered by the parent.
  * Zero or one <Criteria>. Determines criteria (in addition to any pre-existing criteria) for determining which nodes the processor applies to. If there is no <Criteria>, all nodes are affected. This works for the <TopologyProcessor>, which will process every single node on the map.
    * An <Attributes> element that filters nodes by their attributes
      * **criteria=** Contains the attributes to filter with.
        * **"*"** specifies any node that already satisfies the parent criteria.
        * **"+{attribute};"** means that nodes must have {attribute}. "+systemType:0;" specifies nodes without a <SystemType>
        * **"-{attribute};"** means that nodes must not have {attribute}
  * Zero or one <System>.
    * **name=**
    * **attributes=** The attributes to apply to the affected nodes.
    * **level=**
    * **unid=** The UNID of the new SystemType to assign to the affected nodes.
    * Zero or one <Table>. Only works if none of the above attributes are defined in the element.
  * Zero or more <Group>. Same as <TopologyProcessor>.
  * Zero or more <ConquerNodes>. In this processor category, "Conquerors" take turns attempting to "occupy" every eligible node. Each node can be taken by only one Conqueror. Every turn, a conqueror first attempts to create one new seed, then each of its seeds attempt to expand into adjacent nodes.
      * One or more <Conqueror>
      * **seedChance=** The percentage chance that this conqueror will create a seed somewhere((Please verify))
      * **maxSeeds=** The total number of seeds that this conqueror can have. ((Please verify))
      * **expandChance=** The percentage chance that one seed will attempt to expand into an adjacent node ((Please verify))
      * **maxNodes=** The total((Please verify)) number of nodes that can be conquered by this conqueror's seeds.
      * One <SeedChance>
        * One or more <Node>
          * **criteria=** The additional criteria that a node must satisfy to be seeded. "*" refers to any node that satisfies the base criteria
          * **weight=** The percent chance that a seed will choose this node to attempt its expansion on.
          * **successChance=** The percent chance that a seed will be successful in attempting to conquer this node
      * One <ExpandChance>
        * One or more <Chance>
          * **criteria=** The additional criteria that a node must satisfy to be conquered by the seed
          * **weight=** The percent chance that a node will be conquered by the seed
          * **successChance=** The percent chance that a conqueror will be successful in attempting to create a seed in a node.
      * One <Processor>. Same as <TopologyProcessor>
  * Zero or more <DistributeNodes>
    * **nodeCount=**
    * One <Criteria>
  * Zero or more <FillNodes>. Processes every eligible node in random order.
    * <Attributes>
    * <Criteria>
    * <System>
  * Zero or more <LocateNodes>
    * **percentile=**
    * One <Criteria>
    * One <MapFunction>
  * Zero or more <PartitionNodes>
    * **partitionOrder=**
      * **"random"**
    * One or more <Partition>
      * **nodeCount=**
      * One <System>
  * Zero or more <RandomPoints>
  * Zero or more <Table>
    * Zero or one <Criteria>
    * Zero or more <System>
      * **chance=** The chance that the **attributes** and **unid** of this element will be applied to the affected nodes.