modding:xml:adventures_and_extensions
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | |||
modding:xml:adventures_and_extensions [2012/08/11 22:32] – gpm | modding:xml:adventures_and_extensions [2014/12/27 04:40] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | 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' | ||
+ | |||
+ | 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=" | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | ]> | ||
+ | | ||
+ | < | ||
+ | unid="& | ||
+ | apiVersion=" | ||
+ | > | ||
+ | ... | ||
+ | < | ||
+ | ... | ||
+ | > | ||
+ | ... | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | |||
+ | 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: | ||
+ | |||
+ | The second section (which starts with "< | ||
+ | |||
+ | The third section, which starts with "< | ||
+ | |||
+ | < | ||
+ | |||
+ | 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' | ||
+ | |||
+ | **MyAdventure.xml** | ||
+ | <?xml version=" | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | ]> | ||
+ | | ||
+ | < | ||
+ | unid="& | ||
+ | apiVersion=" | ||
+ | > | ||
+ | ... | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | **MyModule.xml** | ||
+ | <?xml version=" | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | ... | ||
+ | > | ||
+ | ... | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | 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), | ||
+ | |||
+ | Note also that the module uses the entity label " | ||
+ | |||
+ | ======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=" | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | ]> | ||
+ | | ||
+ | < | ||
+ | unid="& | ||
+ | apiVersion=" | ||
+ | > | ||
+ | < | ||
+ | ... | ||
+ | > | ||
+ | ... | ||
+ | </ | ||
+ | | ||
+ | < | ||
+ | ... | ||
+ | | ||
+ | > | ||
+ | ... | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | An adventure may include a library with a < | ||
+ | |||
+ | **MyAdventure.xml** | ||
+ | <?xml version=" | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | ]> | ||
+ | | ||
+ | < | ||
+ | unid="& | ||
+ | apiVersion=" | ||
+ | > | ||
+ | < | ||
+ | ... | ||
+ | </ | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | Note that the < | ||
+ | |||
+ | < | ||
+ | |||
+ | < | ||
+ | ... | ||
+ | < | ||
+ | | ||
+ | > | ||
+ | < | ||
+ | </ | ||
+ | ... | ||
+ | |||
+ | In the example above, the library element in the adventure customizes the encounter frequency of the Gamelon Outpost station. The " | ||
+ | |||
+ | The following parameters are defined for < | ||
+ | |||
+ | * **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 < | ||
+ | |||
+ | < | ||
+ | ... | ||
+ | < | ||
+ | | ||
+ | > | ||
+ | < | ||
+ | </ | ||
+ | ... | ||
+ | |||
+ | The following parameters are defined for < | ||
+ | |||
+ | * **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====== | ||