This record describes API changes in 1.9 Alpha 2.

Item Enhancements

In previous versions there were two primary techniques for enhancing items: enhancer items and anonymous enhancement.

The enhancer item technique relies on an item, such as a field crystal to define the enhancement conferred. For example, a yellow etherium crystal would use objAddItemEnhancement to enhance a shield generator, passing itself as a parameter. Inside of objAddItemEnhancement we would ask the yellow etherium crystal for the enhancement code to add to the shield generator.

The anonymous enhancement technique calls shpEnhanceItem with an enhancement code. Inside of shpEnhanceItem we don't know how the enhancement came to be, we just apply it.

The UI in 1.9 Alpha 2 shows the player where an enhancement came from, so in the future we want to encourage the enhancer item technique. In order to support this, we've made a few changes.

shpEnhanceItem optionally takes a struct instead of just an enhancement code. The struct has the following fields:

  • enhancement: This is the enhancement code (required).
  • lifetime: Use this for temporary enhancements (optional).
  • type: This is the enhancer item that gave us the enhancement (optional). If specified, this is shown in the UI.

objEnhanceItem

In API 46 we've introduced a new function: objEnhanceItem which takes a target item and an enhancer item. The function works as follows:

First we call <OnEnhanceItem> on the enhancer item. This event allows the enhancer item do do whatever it wants to enhance the target item. The parameters are:

  • gItem, which is the enhancer item.
  • gSource is the object with the target item
  • gData defines targetItem as the item that will get the enhancement.

<OnEnhanceItem> should return a struct with the following fields:

  • resultCode: This is the result of the enhancement. See objEnhanceItem for a list of result code.
  • desc: If the enhancement failed in some way, this is the text to display to the player.

If the enhancer item does not handle <OnEnhanceItem>, then we look for a custom property named core.enhancement. If that is available, we use that for the enhancement to confer.

Lastly, if there is no such property, we call <GetEnhancement> which should return an enhancement struct (or an enhancement code).

Note that objEnhanceItem is a complete superset of objAddItemEnhancement, so the latter has been deprecated. shpEnhanceItem is available for anonymous enhancements, but it is not recommended.

objCanEnhanceItem

We've also added the function objCanEnhanceItem. This function is used to determine whether an enhancer item can successfully enhance a target item. The results are the same as for objEnhanceItem, but the enhancement is not actually carried out.

This function calls <CanEnhanceItem> instead of <OnEnhanceItem>. Enhancer items that implement the latter should always implement <CanEnhanceItem> also.

Criteria

Starting in API 46 you can combine criteria with an OR operator: |. All directives after the | are OR'ed. For example, imagine a systemCriteria definition:

<Encounter
   systemCriteria="+dwargSpace;"
   />

The above selects all nodes that have the dwargSpace attribute. You can use the | operator to include more nodes:

   systemCriteria="+dwargSpace; | +urakSpace;"

This will select all nodes that have either dwargSpace or urakSpace as attributes. You may add as many sub-expressions are you wish:

   systemCriteria="+dwargSpace; | +urakSpace; | +aresSpace;"

The OR operator works for system criteria, location criteria, system affinity, item criteria, object criteria (sysFindObject), and type criteria (typFind).

Ship Brokers

<StationType ...>
   <Events>
      <GetShipClassesForSale>

         ; gSource is the ship broker object.
         ;
         ; Returns a list of ship class UNIDs for the ships that this
         ; broker sells. We will choose a random set of these.

      </GetShipClassesForSale>
   </Events>
</StationType>

Custom Properties

In the previous version we introduced custom properties (see API 45. In this version we made the following improvements:

  • <DockScreen> now supports custom properties. <Data> and <Variant> properties are accessible while the screen is up; other properties are stored in the type.
  • <OverlayType> now supports custom properties. <Data> and <Variant> properties are stored in the overlay instance. Other properties are stored in the type (for all instances).

Item Types

<OnShow> for Display Attributes

When defining display attributes, you may add an <OnShow> event to determine whether or not the display attribute shows up. This is done inside the display attribute definition:

<Type ...>
   ...
   <AttributeDesc>
      <ItemAttribute label="My Attrib" criteria="asw +notForSale; F:rv-;">
         <OnShow>
            ; gType is the UNID of the containing type
            ; gItem is the item that we're showing
            ...
            ; Return True to show this display attribute
            ; Return Nil to not show it.
         </OnShow>
      </ItemAttribute>
   </AttributeDesc>
</Type>

Missions

  • In API 46 you may specify noInProgress="true" for a mission type to skip the in progress dock screen.

Station Types

CanAttack

Prior to API 46, many station types specified canAttack="true" to indicate that they are active objects that could threaten their enemies. This flag is used in target calculations.

In API 46, it is generally no longer necessary to specify canAttack="true". Stations with weapons, turrets, or defenders are automatically considered as canAttack="true" for purposes of targeting, etc.

Enemy stations with no weapons, turrets, or defenders, are not considered capable of attacking. The auto-target code will prefer attacking objects over non-attacking stations in this case. For example, if firing an omnidirectional cannon and there is a non-attacking enemy station next to an enemy ship, the cannon will prefer the enemy ship, even if the station is closer.

ignoreFriendlyFire

Starting in API 46, the XML attribute noBlacklist has been renamed to ignoreFriendlyFire for consistency with the property of the same name that does the same thing.

Obsolete Types

API 46 deprecates the following design types. Use alternatives before marking your extension as API 46 compatible:

dsUseArmorPatch
rsWolfenGunship
rsWolfenGunshipHD
rsSteelSlaverHD
rsZulu
rsBorer
scBorerCaptured

TLisp

New Properties

  • armorCount for ships.
  • enhancement for items.
  • stealth for armor items.

New Functions

  • msnIncProperty
  • objIncOverlayProperty
  • objIncProperty
  • sysGetAscendedObjects: Returns a list of ascended objects.

Changed Functions

  • objGetCondition now returns 'shieldBlocked if the ship has its shield generator disabled by meteorsteel.
  • objMatches now includes destroyed objects by default. This is needed because we often use this inside of <OnObjDestroyed>. To force exclusion of destroyed objects, select active objects only (with A criteria).
  • shpInstallArmor now returns the installed item (instead of True) if successful.