The process for loading the universe is very tricky, unfortunately. If you could possibly rely on TransData, or even the TSE C++ library, you might be better off. Still, I understand that there are some things that you can only do if you parse it yourself. Sometimes you just gotta re-invent the wheel. I'll try to help where I can:
DEFINITIONS
A "type" is a single definitions of some object--a ship, an item type, a dock screen, whatever. All types have an UNID. For example, the <ItemType> definition for a laser cannon is the type with UNID = 0x0000400D. A type can be overridden if you define an object with the same UNID.
An "extension" is a collection of types. And extension also has an UNID (but it is not technically a type because you can't override it). There are three kinds of extensions: adventures, expansions, and libraries. [Forget for a moment, the common usage of extension as something that extends an adventure. At the engine level, everything is an extension.]
An "adventure" is a special kind of extension that is required to have certain types (such as an <AdventureDesc>) and is required to defined a topology. But other than that, it is just a plain old extension.
Similarly, a "library" is also a special kind of extension, which is included in a special way (described below).
Unless I specify otherwise, when I say "extension," I mean any one of the three types: adventures, expansions, or libraries.
A "module" is an XML file that is included syntactically into some other file. It DOES NOT have an UNID, and it is equivalent to an include file in C. If you could copy the contents of a module XML file and paste into the place where it is referenced, it should behave identically (minus prologue, etc.). Modules, of course, can include other modules recursively.
An extension has a root XML file, which starts with one of the following tags: TranscendenceAdventure, TranscendenceExtension, TranscendenceLibrary. This root XML file may reference modules (which are included syntactically) and it may reference libraries.
TRANSCENDENCE.XML
The Transcendence.xml file is a special file that is used to generate Transcendence.tdb. Unlike every other TDB file, Transcendence.tdb contains MULTIPLE extensions. Transcendence.xml does not follow the same syntax as extensions because it is parsed by TransCompiler to generate Transcendence.tdb.
This is why it uses a filename to refer to the libraries and adventure. Once they're loaded into the TDB file, they are referenced by UNID.
ENTITIES
1. The biggest divergence from true XML is in the handling of entity declarations and libraries. In particular, a library reference (<Library ...>) pulls in all entities defined in that library. It is (currently) illegal to use an entity defined in a library BEFORE the library reference. But it is legal afterwards.
2. Entities declared in the root XML of an extension are visible to all modules included by that extension. And if you use a library, the entities defined by that library are visible to any module you subsequently import.
3. Entity declarations are only exported from the root XML of a library. That is, if a library has multiple <Modules>, and those modules define entities, those entities stay PRIVATE to the module; they are not exported. Only the entities defined in the library's root XML are exported.
4. Obviously, loading order matters if you're trying to resolve an entity. If you're loading a module and it has an entity, you can't resolve that entity until you've loaded all the libraries used by the root extension of the module.
PROCESSING ORDER
When loading the universe, the engine follows a recursive procedure:
Code: Select all
LoadExtension (E)
{
for each library L used by E
LoadExtension(L)
}
LoadUniverse ()
{
LoadExtension(the-adventure-chosen-by-the-user)
for each expansion E chosen by the user
LoadExtension(E)
}
This order is important for entity definitions but also for overrides. There are very few cases of core extensions overriding types, but it does happen. Expansions, of course, very often override types.