Transcendence Community Wiki

User Tools

Site Tools

Trace:
modding:xml:api_version

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
modding:xml:api_version [2012/08/11 23:08] – created gpmmodding:xml:api_version [2024/10/22 20:28] (current) – wolfy
Line 1: Line 1:
 +Every extension declares the version of Transcendence that it is compatible with. This allows the Transcendence engine to maintain the greatest level of compatibility while still adding new features and evolving the API.
  
 +Starting with Transcendence version 1.08e, the method for declaring the compatibility version has itself changed. An extension using 1.1+ features must declare itself compatible by adding a new property in its root element:
 +
 +  <TranscendenceExtension ...
 +     apiVersion="{version}"
 +     ...
 +     >
 +  ...
 +
 +Where {version} is a the version number of the API that the extension is compatible with. If the extension runs on an //earlier// engine that doesn't support the given API version, then the engine will refuse to load the extension. Conversely, if the extension runs on a //later// engine with a later API, the engine will try to preserve API compatibility with the extension's declared API version.
 +
 +For example, an extension with apiVersion="13" is declaring that it requires Transcendence 1.2 Alpha 1 to run. And that if it runs on a later version, it should use API version 13 compatibility (even if later versions change the API in some way).
 +
 +Extensions may still use the older **version** property to specify that they wish to be compatible with older versions.
 +
 +The following API versions are implemented:
 +
 +====API Version 53====
 +
 +Transcendence 1.9
 +
 +====API Version 52====
 +====API Version 51====
 +====API Version 50====
 +====API Version 49====
 +====API Version 48====
 +====API Version 47====
 +====API Version 46====
 +====API Version 45====
 +====API Version 44====
 +====API Version 43====
 +====API Version 42====
 +====API Version 41====
 +====API Version 40====
 +====API Version 39====
 +====API Version 38====
 +====API Version 37====
 +====API Version 36====
 +====API Version 35====
 +====API Version 34====
 +
 +Transcendence 1.7 Beta 5
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=66822|Full API spec on Ministry]]
 +
 +====API Version 33====
 +
 +Transcendence 1.7 Beta 4
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=62046|Full API spec on Ministry]]
 +
 +====API Version 32====
 +
 +Transcendence 1.7 Beta 3
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=61158|Full API spec on Ministry]]
 +
 +====API Version 31====
 +
 +Transcendence 1.7 Beta 1
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=57824|Full API spec on Ministry]]
 +
 +====API Version 30====
 +
 +Transcendence 1.7 Alpha 2
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=54396|Full API spec on Ministry]]
 +
 +====API Version 29====
 +
 +Transcendence 1.7 stream
 +
 +[[http://ministry.kronosaur.com/record.hexm?id=8048|Full API spec on Ministry]]
 +
 +====API Version 27====
 +====API Version 26====
 +====API Version 25====
 +====API Version 24====
 +====API Version 23====
 +====API Version 22====
 +====API Version 22====
 +Transcendence 1.3 and above.
 +
 +====API Version 14====
 +Transcendence 1.2 Beta 1 and above.
 +
 +=== Dynamic Effects ===
 +Dynamic effects are visual effects whose parameters are modified at runtime. A dynamic effect uses the <GetParameters> event on an <EventType> to dynamically set the effect parameters. For example:
 +
 +  <EffectType UNID="..."
 +        instance="creator"
 +        >
 +     <Effect>
 +        <Ray
 +           style="..."
 +           ...
 +           >
 +           
 +           <Events>
 +              <GetParameters>
 +                 (block Nil
 +                    ...
 +              
 +                    {
 +                       length: ...
 +                       width: ...
 +                       intensity: ...
 +                       }
 +                    )
 +              </GetParameters>
 +           </Events>
 +        </Ray>
 +     </Effect>
 +  </EffectType>
 +
 +In the above example, the parameters for the <Ray> effect are being set by the <GetParameters> function, which returns a struct. Each field in the struct represents a parameter in the <Ray> element to be set.
 +
 +The **instance** parameter on <EffectType> defines when <GetParameters> is called to set the effect parameters. The valid instances are:
 +
 +  * creator: The effect parameters are defined each time the effect is created (e.g., when the weapon is fired).
 +  * game: The effect parameters are defined once at the beginning of the game and shared. For example, if multiple weapons use the same effect, all will use the same parameters.
 +  * owner: The effect parameters are defined once per effect owner. For example, if multiple weapons use the same effect, the effect will be defined separately for each weapon.
 +
 +NOTE: As of API version 14, only the <Ray> effect supports dynamic effects.
 +
 +=== Enhancement Devices ===
 +In previous APIs the <EnhancerDevice> element was used to define a device that could enhance other devices (weapons, shields, etc.) In API version 14 there is a new element, called <EnhancementAbilities> that may be added to any device class (e.g., a <Shields> device).
 +
 +The <EnhancementAbilities> element may contain zero or more <Enhance> sub-elements, each of which defines an enhancement conferred on other devices. The <Enhance> sub-element has the following parameters:
 +
 +  * type: This is a user-defined string representing the type of enhancement. Only a single enhancement of each type will be applied.
 +  * criteria: This is an item criteria specifying the set of devices that will be enhanced by this device.
 +  * enhancement: This defines the enhancement applied to the set of devices that match the criteria. This is expressed as an enhancement code (see shpEnhanceItem) or as one of the following special codes:
 +    * "+hpBonus:{n};" where {n} is the percent bonus.
 +    * "+shield:{n};" where {n} is a level. This is equivalent to the shield:{n} damage modifier.
 +    * "+speed:{n};" where {n} is the percent value of the new weapon delay time relative to the current one. E.g., 75 = 75% of the original delay time.
 +
 +=== New Functions ===
 +
 +  * (cnvDrawLine): Draws a line on a <Canvas> element.
 +  * (objGetArmorRepairPrice obj armorItem hpToRepair): Returns the price that a station (obj) will charge the player to repair the given number of hp on the given armor item. Returns Nil if the station cannot repair. This function uses the new <RepairArmor> sub-element in <Trade>. NOTE: This function includes price adjustments from called <GetGlobalPlayerPriceAdj>.
 +  * (objGetArmorReplacePrice obj armorItem): Returns the price to replace one of the player ship's armor segments with the given item. NOTE: This function calls <GetGlobalPlayerPriceAdj>.
 +  * (objGetPlayerPriceAdj obj [data]): Returns the player price adjustment (see <GetGlobalPlayerPriceAdj>).
 +  * (scrGetListCursor) and (scrSetListCursor).
 +  * (sysMatches [nodeID] criteria): Returns True if the given nodeID matches the given criteria.
 +  * (typeof exp): Returns the type.
 +  * (typMatches unid criteria): Returns True if the given design type matches the given criteria.
 +
 +=== Updated Functions ===
 +
 +  * plyGetKeyEventStat has two new stats: 'missionSuccess and 'missionFailure, which return the number of missions succeeding and failing respectively.
 +  * scrSetData: Data set now persists across nested screens. E.g., if screen A calls nested screen B then all the data set by screen A remains when screen B closes.
 +  * sysGetNodes: No longer returns the special EndGame node (only returns valid nodes that the player can enter).
 +  * unvFindObj: Now returns the object name (and name flags) also.
 +
 +=== Global Events ===
 +
 +  * <GetGlobalPlayerPriceAdj>: Allows a type to adjust the price that a station will charge the player for a service or an item. The event may return **Nil** to skip price adjustment, or it may return an integer indicating the percent to adjust the price by. For example, returning 75 make the price 75% of the original price. The parameters for the event are:
 +    * aService: The service that the player is using. One of the following: priceOfferedToPlayer, priceForPlayerToBuy, valueOfDonation, priceToRefuel, priceToRepairArmor, priceToReplaceArmor, priceToInstallDevice, priceToRemoveDevice, customPrice.
 +    * aProviderObj: The object that is offering the service (e.g., the station selling the item).
 +    * gItem: The item involved in the service (if any).
 +    * gData: Any custom data passed in to (objGetPlayerPriceAdj).
 +
 +=== Missions ===
 +
 +  * maxAppearing parameter on <MissionType> limits the number of times the mission is assigned.
 +
 +=== Object Ascension ===
 +Object ascension is used to move objects (stations and ship) across systems. At any time while in a system, you may call (sysAscendObject obj) on any object (except the player ship). The object will disappear from the current system and remain in the "ascended region". While an object is ascended, it cannot be manipulated (the previous object pointer becomes invalid).
 +
 +At any time in any other system, you may call (sysDescendObject objID pos) on a previously ascended object (you must use an object ID, returned by objGetID, instead of the object pointer). The ascended object will descend to the current system and continue operating as normal.
 +
 +There is a new AI setting parameter: ascendOnGate="true". If set to true, an object will automatically ascend when it gates out. You may set this on a <AISettings> element on a <ShipClass> or dynamically set it with (shpSetAISetting obj 'ascendOnGate True).
 +
 +=== Object Events ===
 +
 +  * <OnPlayerBlacklisted>: Fires to a station when it blacklists the player. For example, if station A blacklists the player, it will get the <OnPlayerBlacklisted> event (gSource is the station).
 +  * <OnObjBlacklistedPlayer>: Fires when any registered object blacklists the player. You must call objRegisterForEvents to receive this event.
 +
 +=== Object Properties ===
 +
 +  * 'playerBlacklisted property: Returns True/Nil is the player is blacklisted by a station. E.g., (objGetProperty someStation 'playerBlacklisted) return True if someStation has blacklisted the player.
 +  * 'playerMissionsGiven: The number of missions that this object has assigned to the player.
 +  * 'underAttack property: Same as (objIsUnderAttack).
 +  * You may use the "property:" criteria to select objects that have a specific property. For example, (sysFindObject nil "T +property:immutable;") finds all immutable stations in the system (e.g., stargates). Any boolean property for objGetProperty is accepted.
 +
 +=== Ship Classes ===
 +
 +  * Added thrustRatio= parameter to <ShipClass>
 +  * <Armor> element in <ShipClass> can use armorID and count (instead of separate elements for each segment).
 +
 +=== Ship Interior ===
 +For capital ships and freighters you may use an <Interior> element to specify internal hit points and structure. Normally, a ship is destroyed whenever damage penetrates through any single armor segment. If a ship has interior structure, any damage that gets past the armor will be inflicted on the interior.
 +
 +The interior of a ship consists of one or more //compartments// (defined by a <Compartment> sub-element). Each compartment starts with a number of hit points (defined by the hitPoints= parameter). A compartment may optionally define a size and position (using posX, posY, sizeX, sizeY in the same coordinate system as ship thruster effects). If a compartment does not specify a size and position, it is assumed to encompass the whole ship.
 +
 +When damage penetrates the ship's armor, we check to see which compartment it hit (by position). That compartment takes the damage. If the compartment at that position already has 0 hit points, or if no compartment could be found at that position, damage passes to any compartment with a null position (any compartment that encompasses the whole ship).
 +
 +When all compartments reach 0 hit points, the ship is destroyed.
 +
 +A compartment may specify a type to define its purpose. Depending on the type, additional effects may occur when the compartment is damaged. The following types are implemented in API version 14:
 +
 +  * cargo: A cargo compartment holds the ship's cargo. When this compartment is hit, there is a chance that some items in the cargo hold will be damaged or destroyed. The chance increases as the compartment loses hit points.
 +  * general: If the type is "general" or if no type is specified, the compartment has hit points but otherwise has no effect when damaged.
 +  * mainDrive: This compartment holds the ship's engines. When this compartment is hit, there is a chance that the main engines will be damaged. If they are damaged, the engines will drop to half-speed. The engines will be repaired after some amount of time (1-2 minutes of real time).
 +
 +If a ship has interior structure, devices are automatically subject to damage. If a device is hit and if the armor in that position has been reduced to 0, there is a chance that the device will be damaged permanently.
 +
 +=== Ship Orders ===
 +
 +  * (shpOrder shipObj 'fireEvent targetObj event): To execute this order we fire the given event to the given object. This is useful to program a ship to notify some other object that it has reached a certain point in its orders. For example, you could order a ship to attack a target and follow up with an order to fire an event. When the order to attack is complete, the next order will fire an event, allowing you to execute whatever script you want.
 +  * (shpOrder shipObj 'sendMessage targetObj string): This order sends the given message to the given targetObj. For example, you may use this to send a message to the player from the ship.
 +  * (shpOrder shipObj 'waitForUndock targetObj): This order keeps the ship waiting until the given targetObj undocks from its station.
 +
 +=== Miscellaneous ===
 +
 +  * <Globals> are now reloaded at new game and load game (based on enabled extensions).
 +  * linkedFire="always" now works for AI ships.
 +  * Removed "planet" attribute from planets. Use special attribute isPlanet:true instead. (This is because being a planet depends on more than just its size. An object around a star is a true planet, but the same object around a gas giant is a moon.)
 +  * <Siblings> element now accept multiple child directives (like <Orbitals>).
 +  * Stations are now affected by custom damage.
 +
 +====API Version 13====
 +Trascendence 1.2 Alpha 1 and above.
 +
 +=== Devices ===
 +
 +  * Added hpBonus to <Device> and <DeviceSlot>
 +
 +=== Stations ===
 +
 +  * Added maxLightRadius= parameter to stars (<StationType>)
 +  * Added <FilterColorize> element to station <Image> tags.
 +  * Added <AcceptDonation> tag to <Trade>
 +  * Added <Refuel> tag to <Trade>
 +  * Added <InstallArmor> tag to <Trade>
 +  * Added <InstallDevice> tag to <Trade>
 +  * Added <RemoveDevice> tag to <Trade>
 +  * Added maxAppearing parameter to <StationType>
 +
 +=== System Definition ===
 +
 +  * Added aOrbit variable to <Code> in system definitions.
 +  * Added <OrbitalDistribution> as <SystemType> directive
 +  * Added radius= and angle= to <Offset> directive in <SystemType>
 +  * Added minDist= and maxDist= to <RandomLocation>
 +  * Added minDist= and maxDist= to <FillLocations>
 +  * Added count= to <FillLocations> (used if percentFull is omitted).
 +  * <RandomStation> directive in <SystemType> takes parameters valid for <Station>
 +  * Added "systemLevel:..." syntax to levelFrequency in <RandomItem>
 +  * Deprecated <FillRandomLocation>; use <FillLocations> instead.
 +
 +=== New and Changed Functions ===
 +
 +  * (msnFireEvent)
 +  * (msnGetProperty): Added 'acceptedOn property to missions
 +  * (msnGetProperty): Added 'description property to missions
 +  * (msnGetProperty): Added 'name property to missions
 +  * (msnGetStaticData)
 +  * (objGetProperty): Added 'orbit to station properties
 +  * (objGetProperty): Added 'repairArmorMaxLevel property to stations.
 +  * (objGetProperty): Added 'installDeviceMaxLevel property to stations.
 +  * (sysOrbitPos)
 +  * (typFind): Added isEnemyOf:{unid} to typFind (for station types)
 +  * (typTranslate)
 +  * (unvFindObj)
 +
 +=== Miscellanous ===
 +
 +  * Added <Type> to create generic types (for holding global data, etc.)
 +  * <Language> elements parse and translate escape sequences (e.g., %name%).
 +
 +=== Core Libraries ===
 +
 +  * Added stK-TypeStar to Universe library
 +  * Added stNebulaStar to Universe library
 +  * Non-random star systems now create extra stargates if needed.
 +  * Only nodes with "huaramarcaGate" attribute are eligible for gate to Huaramarca.
 +  * Added "BasicFuel" attribute to all basic fuels (all except uranium, Heliotrope fuel, and longzhu)
 +  * Added dsPRGReful screen
 +  * srvFindRepairArmor checks for <RepairArmor> tag, so "NPCService" data is deprecated
 +  * Added dsRPGDeliveryMission
 +
 +====API Version 12====
 +Transcendence 1.08e and above.
 +
 +  * **apiVersion** property used to specify compatibility version.
 +  * Player ship classes must use "00200000_PlayerShip" attribute in order to appear as a player ship in //Stars of the Pilgrim// adventure.
 +  * Engine validates existence of sound references. I.e., types cannot refer to non-existent sound UNIDs.
 +  * An extension/adventure cannot define multiple types of the same UNID (an error will be reported). In previous versions one of the types was silently ignored.
 +
 +====API Version 1.1====
 +Transcendence 1.04 and above.
 +
 +NOTE: You must use **version="1.1"** to access this API version.
 +
 +====API Version 1.0===
 +Transcendence 1.0 and above.
 +
 +NOTE: You must use **version="1.0"** to access this API version.
 +
 +  * For version 1.0 and below, when defining weapons, passthrough should not equal "0" (or it will default to "50").
 +  * For version 1.0 and below, when defining <SmokeTrail> effects there was a bug with emitSpeed. Double the normal speed for compatibility.
 +  * For version 1.0 and below, when defining weapons, the shield damage modified used a different calculation because we only allocated 3 bits for the damage range.e.