This is an old revision of the document!
A DesignType is a XML tag that defines a chunk of game data. Most XML tags contained directly under a root level element are DesignType tags.
These are types that you can deal with instances of directly.
These are types that you only ever seem to reference by unid.
All design design types must have a UNID attribute. They may also have an attributes attriute which lists keywords for filtering, and an inherit that lists another design type to inherit data from.
These are codes used to enumerate types with the typFind function.
* = all types $ = currency UNID a = an adventureDesc UNID b = item table UNID c = effect type UNID d = dock screen UNID e = space environment UNID f = overlay UNID (apparently original name was 'energy field') g = globals UNID (currently returns nothing?) h = ship table UNID i = item type UNID m = image UNID n = system node UNID (currently returns nothing?) p = power UNID q = system table UNID s = ship class UNID t = station type UNID u = sound UNID (currently returns nothing?) v = sovereign UNID w = name generator UNID (currently returns nothing?) y = system type UNID z = system map UNID _ = template type UNID // We don't support enumerating template types (TSE/CDesignType.cpp) V = Include Virtual types +isPlayerClass:true/false = filters in/out ship classes with playersettings +unid:[a unid] = returns the requested unid if extant, or nil
Most functions that deal with types directly start with 'typ'.
The only events that can be placed on any type are global events. These events are called as global, independant code blocks that have nothing to do with any created object anywhere in the game universe.
Returns data for the f2 screen.
This event is raised when the game wants to compute the list of stats and achievements for the current game. The type may return nil to indicate that it has no stats to report. Or it may return a list of stats, where each stat is a list consisting of the following elements (in order):
Every time the player docks with any spaceObject, GetDockScreen is called on the actual spaceObject that the player docks with, and GetGlobalDockScreen is called on every design type that has it defined. The results of all the events are collated into a list and the highest priority dockscreen in that list is what's actually invoked.
Because all these events are called an unspecified number of times to accumulate the data, you don't want to do anything in them that causes side-effects, especially repeatable side effects like creating ships or items.
If the dockscreen invoked is set as a nested screen, then the process will be run again when the screen is exited; in this case, it's important to make sure the screen resolves whatever issue triggered it, or you might end up being presented with it over and over again.
As of 1.08b, the base game uses priorities in the 1-10 range. George's notes from Commonwealth.xml indicates a general scheme:
; Screens that prevent docking: 10 ; Screens that imprison the player: 8 ; Screens that confiscate: 6 ; Screens that complete missions: 4
This is an overview of all of the places where the base game uses these events. Note that in each event, the situations are checked from top to bottom and the first one matching is returned.
|global||svBlackMarket||“sTAV +blackMarket;”||ship is contaiminated||dsRefuseContamination||10||-|
|player has pending BM crime||dsBlackMarketPayDebt||8||-|
|no black market id||dsBlackMarketRefuseDock||6||-|
|player pending BM promotion||dsBlackMarketPromotion||4||-|
|global||svCommonwealth||“sTAV +commonwealthCustoms;”||ship is contaminated||dsCommonwealthDecon||10||-|
|player has pending CW crime||dsCommonwealthImprison||8||-|
|player has slaves to free||dsCommonwealthFreeSlaves||8||-|
|player has black market container and no smuggler's hold||dsCommonwealthImprison||8||-|
|player has illegals and no smugglers hold, or military and no ID||dsCommonwealthConfiscate||6||-|
|global||dsFleetDelivery||“sTAV”||station is mission target||dsFleetDelivery||4||-|
|global||svCommonwealthFleet||“sTAV +commonwealthFleet;”||ship is contaminated||dsFleetDecon||10||-|
|player has pending fleet crime||dsFleetImprision||8||1|
|player has pending commonwealth minor crime and is low fleet rank||dsFleetDischarge||8||1|
|no military id||dsFleetRefuseDock||6||1|
|player has pending minor commonwealth crime and is high ranking||dsFleetCrimeWarning||5||1|
|global||svCorporate||“sTAV +corporateCustoms;”||ship is contaminated and station has “corporateDecon”||dsCommonwealthDecon||10||-|
|ship is contaminated||dsRefuseContamination||10||-|
|player has pending corp crime||dsCorporateImprision||8||-|
|global||svRingers||“sTAV +ringers;”||player has pending ringer crime||dsRingerImprision||8||-|
|global||svSistersOfDomina||“sTAV +sistersOfDomina;”||ship is contaminated||dsSistersDecon;||10||-|
|player hasn't seen sisters intro and is in a level 1 system||dsSistersIntro||4||-|
|local||stTinkerGathering||station is not abandoned||ship is contaminated||“Decon”||10||2|
(Probably lets multiple ressurection systems fight out which one gets proiorty when the player dies)
This is the most useful global dockscreen event. It lets you extend dockscreens with new actions without overwriting them, so multiple extensions can affect the same screens without interfering. (Well, until the screen runs out of room for new actions to show on the screen – even then, hotkeys work at this point).
By the time this function is called, the global gPlayerShip has already been updated to point to the new ship, so the old ship event variable above is needed if you want to transfer equipment around or anything.
Also called at game startup after the first system is fully created, hence, a good place to put any run-once code that gives the player items or whatnot. Minimal example of such a setup, taken from the <Events> section of an <ItemType>; this installs the item as well:
<OnGlobalPlayerEnteredSystem> (if (not (typGetGlobalData &itWvrHomeDrive; 'given)) (block nil (objAddItem gPlayerShip (itmCreate &itWvrHomeDrive; 1)) (shpInstallDevice gPlayerShip (itmCreate &itWvrHomeDrive; 1)) (typSetGlobalData &itWvrHomeDrive; 'given true) )) </OnGlobalPlayerEnteredSystem>
For systems, all instances executed whenever a system is created.
This event is called after a system is created (right after <OnCreate> for the system). You may use this event to create new objects in the system or to otherwise alter the system. Remember that there is no guarantee that other systems have been created at this point. Look at Huari.xml for an example of how this event is used.
Warning : multiple instances of this event can be created on multiple system types. They will ALL be called when ANY system is created, and their order can NOT be forecast.
For topology, once when the topology is created.
This event is called at the beginning of the game right after the complete system topology has been generated. You may use this event to explore the topology and add data to topology nodes that may later be used inside systems. Remember that no systems have been created yet. You can only call functions that work on topology nodes.
For an example of how this event is used, look at Huari.xml.
Called only when a game is loaded from a .sav file from the front menu.
Called whenever the game is saved to disk, including going through stargates, exiting, dying, and initially starting the game.
todo: figure out why this is also declared in spaceobject