A DesignType is a XML tag that defines a chunk of game data. Most XML tags contained directly under a [[modding:xml:xml#root level element]] are DesignType tags.

=====DesignType Types=====

====Instantiated DesignTypes====

These are types that you can deal with instances of directly.

  * [[ItemType]] as itemStructs
  * [[MissionType]] as a missionobject
  * [[OverlayType]] as an element on spaceobjects
  * [[ShipClass]] as a spaceobject
  * [[StationType]] as a spaceobject
  * [[SystemType]] as a node
  * [[TemplateType]] as another type!

====Singleton DesignTypes====

These are types that you only ever seem to reference by unid.

  * [[AdventureDesc]]
  * [[DockScreen]]
  * [[EconomyType]]
  * [[EffectType]]
  * [[Effect]] //(Deprecated in favor of EffectType per the source)//
  * [[EncounterTable]] //(Same as ShipTable)//
  * [[Image]]
  * [[ItemTable]]
  * [[Power]]
  * [[ShipTable]]
  * [[Sound]]
  * [[Sovereign]]
  * [[SpaceEnvironment]]
  * [[SystemMap]]
  * [[SystemPartTable]]

=====Attributes=====

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.

=====Data Fields====

  * extensionUNID -- which extension is to blame for this type
  * unid -- the unid that you just had to look this field up with
  * version -- ?

=====Criteria=====

These are codes used to enumerate types with the [[modding:function:typFind]] function.

<code>
* = 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?)((please verify))
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
</code>

  * There is currently no way to get a list of only vitual types except filtering one list against the other.
  * Use +attrib and -attrib to select attributes
  * Type codes are only additive, e.g., "$q" will return both currencies and system tables in one list.
  * There appears to be some way to use > >= < <= $ # and a number to do aditional filtering. (I haven't been able to make this do anything obvious -Weaver)


=====Functions=====

Most functions that deal with types directly start with 'typ'.

  * [[modding:function:sysAddTypeRecurringTimerEvent]]
  * [[modding:function:sysAddTypeTimerEvent]]
  * [[modding:function:sysCancelTypeTimerEvent]]
  * [[modding:function:typCreate]]
  * [[modding:function:typDynamicUNID]]
  * [[modding:function:typFind]]
  * [[modding:function:typFireObjEvent]]
  * [[modding:function:typGetDataField]]
  * [[modding:function:typGetGlobalData]]
  * [[modding:function:typGetStaticData]]
  * [[modding:function:typHasAttribute]]
  * [[modding:function:typIncGlobalData]]
  * [[modding:function:typSetGlobalData]]
  * [[modding:function:unvUNID]]

=====Events=====

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.


====<GetGlobalAchievements>====

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):

  * **The name of the statistic.** E.g., "Profit on goods and materials". The name will be displayed in the stats list; it should have sentence capitalization, but no terminating punctuation.
  * **The value of the statistic.** E.g., 1700 or "More wealth than you can imagine". If this value is an integer, we format it with thousands-separators. If it is a string, it should have sentence capitalization but no terminating punctuation. The value may also be **nil**, indicating that no value is needed.
  * **The section in which the stat belongs.** E.g., "commerce". This is an optional value the indicates the section where the stat should appear. The section name should be lowercased and may not contain a forward-slash character ("/"). See the article on [[game:statistics]] for more information.
  * **The sort key within the section.** You may optionally specify a sort key for the stat within its section. If this is omitted, the name of the stat is used as the sort key.

====<GetGlobalDockScreen>====
  * **gSource** - the spaceObject the player just docked with
  * **RETURN:** (list dockscreenUnid pirorityNumber) or Nil if the event dosen't want to add a dockscreen to the override stack at this time.

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.

^event^type^gsource criteria^situation^screen^priority^notes^
|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|

  * 1 -- These events only act on stations that also have the fleetLaw attribute
  * 2 -- This is the only place as of 1.08b that the base game uses a station-specific GetDockScreen event. This is also the only one in the base game directs to a non-nested screen, since the target screen is local and set up to send you to a specific screen afterwards.

====<GetGlobalPlayerPriceAdj>====
**[apiVersion 14]** This event allows a type to alter the prices charged/offered to the player for any station. The event should return either Nil (no change in price) or a percent value. For example, returning 90 means that the price is adjusted to 90% of its original value.

The following parameters are defined:

  * aService: This is the service that the player is using. It is one of the following values:
    * priceOfferedToPlayer: The price that the station offers the player to buy and item.
    * priceForPlayerToBuy: The price that the player can buy the item for.
    * valueOfDonation: The value of an item being donated by the player.
    * priceToRefuel: The price of refueling.
    * priceToRepairArmor: The price to repair armor.
    * priceToReplaceArmor: The price to replace armor.
    * customPrice: A custom service.
  * aProviderObj: The object providing the service to the player (generally the station).
  * gItem: The item in question.
  * gData: Arbitrary data passed in by the caller (used for custom services).

**NOTE:** This event works in conjunction with a new set of functions that compute price (e.g., objGetRefuelItemAndPrice). Not all stations have been converted to use the new functions, so not all services will work. As of apiVersion 14, this event will work for buying/selling and donations, but not for other services (such as refueling).
====<GetGlobalResurrectPotential>====

(Probably lets multiple ressurection systems fight out which one gets proiorty when the player dies)

====<OnGlobalObjDestroyed>====
  * aObjDestroyed
  * aDestroyer
  * aOrderGiver
  * aWreckObj
  * aDestroyReason

This is called whenever an ship or a station are destroyed.

NOTE: This is //not// called for other kinds of objects, such as missiles.
====<OnGlobalPaneInit>====
  * aScreenUNID is the UNID of the screen being shown
  * aScreen is the screen name (if this is a local screen)
  * aPane is the pane being shown

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).


====<OnGlobalPlayerChangedShips>====

  * aOldPlayerShip

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.

====<OnGlobalPlayerEnteredSystem>====

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:

<code>
<OnGlobalPlayerEnteredSystem>
  (if (not (typGetGlobalData &itWvrHomeDrive; 'given)) (block nil
    (objAddItem gPlayerShip (itmCreate &itWvrHomeDrive; 1))
	(shpInstallDevice gPlayerShip (itmCreate &itWvrHomeDrive; 1))
	(typSetGlobalData &itWvrHomeDrive; 'given true)
  ))
</OnGlobalPlayerEnteredSystem>
</code>

====<OnGlobalPlayerLeftSystem>====

====<OnGlobalResurrect>====


====<OnGlobalSystemCreated>====
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.**

====<OnGlobalSystemStarted>====
**[apiVersion 14]** This is called whenever a system starts running (i.e., is created or loaded from disk). This event happens //before// the player enters the system; you may use it to change the system to simulate things that might have happened while the player was away.


====<OnGlobalSystemStopped>====
**[apiVersion 14]** This is called whenever a system stops running (i.e., is saved to disk). This event happens //after// the player leaves the system.

====<OnGlobalTopologyCreated>====
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.

====<OnGlobalUniverseCreated>====


====<OnGlobalUniverseLoad>====

  * aReason: 'resurrect or Nil
  * Return value is discarded by engine

Called only when a game is loaded from a .sav file from the front menu.

====<OnGlobalUniverseSave>====

  * No variables initialized for this event
  * Return value is discarded by engine

Called whenever the game is saved to disk, including going through stargates, exiting, dying, and initially starting the game.

====<OnGlobalUpdate>====
**[apiVersion 14]** Called once every 15 ticks.

====<OnRandomEncounter>====
// todo: figure out why this is also declared in spaceobject //