NOTE: Some features described in this article (particularly those related to libraries) are only available in version 1.09 and above.

======Adventures======
Transcendence is a **game engine** that can run a variety of **adventures**. Each adventure is a complete game: the player chooses an adventure to start playing and continues playing that adventure until the game ends.

Adventures are defined using **XML files**. The simplest adventure consists of a single XML file and appropriate resources (images and sounds), compiled into a **TDB file**. The single XML file is known as the adventure's **main definition file**.

The main definition file contains a series of **design type** definitions. Each design type defines the building-blocks of an adventure, such as the star systems, ships, stations, and items encountered by the player. Each design type has a globally unique identifier known as an **UNID**. UNIDs are unique across adventures and expressed as 32-bit hexadecimal numbers. To make UNIDs easier to use, the first part of an XML file has an **entity definition section** in which UNIDs are assigned a label. Instead of having to remember the exact hexadecimal number for an UNID, the developer can use the entity label instead.

This is an example of a simple adventure:

**MyAdventure.xml**
  <?xml version="1.0" ?>
  
  <!DOCTYPE TranscendenceAdventure [
     <!ENTITY myAdventure          "0xF0000000">
     <!ENTITY spaceCruiserYamato   "0xF0000001">
  ]>
  
  <TranscendenceAdventure
        unid="&myAdventure;"
        apiVersion="12"
        >
     ...
     <ShipClass unid="&spaceCruiserYamato;"
           ...
           >
        ...
     </ShipClass>
  </TranscendenceAdventure>


The example above shows the main definition file for a simple adventure. There are three sections in the file: The first line is simply the XML prologue. It is required for all XML files. (See the article on [[modding:xml:xml_syntax|XML syntax]] for more information.)

The second section (which starts with "<!DOCTYPE ...") is the entity definition section. This example defines two entity labels: "myAdventure" and "spaceCruiserYamato". (See the article on [[modding:xml:unid_assignment|UNID assignment]] for more information about UNID numbers.)

The third section, which starts with "<TranscendenceAdventure...", contains the design type definitions. The ShipClass definition is the only one shown. Note the use of the entity label "spaceCruiserYamato". Because the label "spaceCruiserYamato" has been assigned to the number "0xF0000001" in the entity definition section, this is equivalent to:

  <ShipClass unid="0xF0000001"...

You must define an entity label in an entity definition section before you can use it.

======Modules======
It is sometimes helpful for developers to split up the design type definitions across multiple XML files. In those cases, an adventure's main definition file includes other XML files using the <Module> element. The <Module> element can refer to an XML file (by filename). Module files contain design type definitions and may even include their own <Module> elements.

**MyAdventure.xml**
  <?xml version="1.0" ?>
  
  <!DOCTYPE TranscendenceAdventure [
     <!ENTITY myAdventure          "0xF0000000">
     <!ENTITY spaceCruiserYamato   "0xF0000001">
  ]>
  
  <TranscendenceAdventure
        unid="&myAdventure;"
        apiVersion="12"
        >
     ...
     <Module filename="MyModule.xml"/>
  </TranscendenceAdventure>

**MyModule.xml**
  <?xml version="1.0" ?>
  
  <TranscendenceModule>
     <ShipClass unid="&spaceCruiserYamato;"
           ...
           >
        ...
     </ShipClass>
  </TranscendenceModule>

In the example above we've moved the definition of the Space Cruiser Yamato to a separate module file.

Unlike the adventure, which has its own UNID (myAdventure), a module does not have an UNID. It is simply included by value into the adventure.

Note also that the module uses the entity label "spaceCruiserYamato" which is defined in the adventure file. A module file may use any UNID entity defined in the main definition file. A module file may also have its own entity definition section, but the entities defined therein are valid only within that module file.

======Libraries======
In the adventure example above, the definition for the Space Cruiser Yamato is part of the adventure. If another developer wanted to create an adventure using the Yamato then he or she would have to copy the definition and include it into their adventure.

If multiple adventures want to use the same design types it is better to create a library and refer to it from different adventures. A library looks very much like a module:

**YamatoLibrary.xml**
  <?xml version="1.0" ?>
  
  <!DOCTYPE TranscendenceAdventure [
     <!ENTITY yamatoLibrary        "0xF0010000">
     <!ENTITY spaceCruiserYamato   "0xF0010001">
     <!ENTITY gamelonOutpost       "0xF0010002">
  ]>
  
  <TranscendenceLibrary
        unid="&yamatoLibrary;"
        apiVersion="12"
        >
     <ShipClass unid="&spaceCruiserYamato;"
           ...
           >
        ...
     </ShipClass>
  
     <StationType unid="&gamelonOutput;"
           ...
           levelFrequency="..."
           >
        ...
     </StationType>
  </TranscendenceLibrary>

An adventure may include a library with a <Library> element.

**MyAdventure.xml**
  <?xml version="1.0" ?>
  
  <!DOCTYPE TranscendenceAdventure [
     <!ENTITY myAdventure          "0xF0000000">
     <!ENTITY yamatoLibrary        "0xF0010000">
  ]>
  
  <TranscendenceAdventure
        unid="&myAdventure;"
        apiVersion="12"
        >
     <Library unid="&yamatoLibrary;"/>
     ...
  </TranscendenceAdventure>

The library is specified by UNID (not filename). If the library is not found at create-time then we cannot start the adventure.

All of the entity labels defined by the library are available to the adventure. In other words, the adventure may refer to "spaceCruiserYamato" and "gamelonOutpost" in its own files (including its modules). The only exception is "yamatoLibrary". The adventure must define this value since it must know the UNID of the library before it can load it.

Note that the <Library> element must appear before any references to entity labels defined in the library. The best practice is to place all <Library> elements before other design types and <Module> elements.

<StationType> elements define the probability of encountering the station. Naturally, an adventure that uses a library may want to override the library's definition of the encounter. The library element provides for this, using the following syntax:

  <TranscendenceAdventure ...
     ...
     <Library unid="&yamatoLibrary;"
           noDefaultStationEncounter="true"
           >
        <StationEncounter unid="&gamelonOutput;" levelFrequency="..."/>
     </Library>
     ...

In the example above, the library element in the adventure customizes the encounter frequency of the Gamelon Outpost station. The "noDefaultStationEncounter" parameter determines how to deal with a station defined in the library but not explicitly mentioned with a <StationEncounter> element. When set to "true", omitted stations are never encountered; when set to "false", omitted stations are encountered based on the <StationType> definition in the library.

The following parameters are defined for <StationEncounter>:

  * **levelFrequency**= : If present, this overrides the levelFrequency parameters for the station.
  * **locationCriteria**= : If present, this overrides the locationCriteria parameter.
  * **additionalAttributes**= : If present, these attributes are added to the station type's attributes.
  * **enemyExclusionRadius**= : If present, this overrides the enemyExclusionRadius parameter.

In a similar way, you may use the <ItemEncounter> element to override random item probabilities:

  <TranscendenceAdventure ...
     ...
     <Library unid="&yamatoLibrary;"
           noDefaultItemEncounter="true"
           >
        <ItemEncounter unid="&waveMotionGun;" frequency="..."/>
     </Library>
     ...

The following parameters are defined for <ItemEncounter>:

  * **levelFrequency**= : If present, this overrides the levelFrequence parameter for the item.
  * **numberAppearing**= : If present, this overrides the numberAppearing parameter for the item.
  * **additionalAttributes**= : If present, these attributes are added to the item's attributes.

======Extensions======



======Core Libraries======