This document describes the API changes for the 1.7 stream:

Ship Classes

OnSubordinateAttacked Event

A ship with escorts may implement the <OnSubordinateAttacked> event to get notified whenever one of its escorts is hit. This is equivalent to an <OnAttacked> event, except aObjAttacked is the object that was attacked.

The event may return True to override the default behavior; Nil otherwise.

Drives

In prior APIs, the stock drive for a player ship class always consumed 2.0 MWs. You may now define the power consumption with the drivePowerUse= parameter on <ShipClass>.

For APIs prior to 29, omitting the drivePowerUse= parameter will default power to 2.0 MW, as before.

Starting in API 29, the default consumption will be based on the ship's absolute thrust. Thus heavier ships will consume more power, as will ships with higher thrust-to-mass ratios. You may use ~~(objGetProperty shipObj 'drivePowerUse) to determine the power used.

Armor & Devices

Maximum Speed Bonus

Armor segments can adjust a ship's speed using a new parameter on armor definitions called maxSpeedBonus=.

The parameter is the % adjustment to the ship's maximum speed (positive or negative) if all segments used the given armor. We adjust proportionally if not all segments are the same type.

For example, if an armor type has maxSpeedBonus="-10", then it means that a ship using this armor will have its maximum speed reduced by 10%. If a ''Sapphire'' yacht had all four segments of this armor, its maximum speed would drop from 0.2c to 0.18c (10%). If it only had 2 segments of the armor installed, then its maximum speed would only drop by 5% (to 0.19c).

Note that this only affects maximum speed. It does not affect maneuverability or inertia.

Distributing Armor Damage

API 29 adds the distribute= parameter to armor classes. When specified, damage is distributed across all segments of the same type. The rate of the distribution is specified (in HP per 180 ticks).

For example, imagine a ship with 4 armor segments, each with 100 hit points. If one segment takes 40 points of damage (down to 60 hp), then the damage will be distributed to the other segments over time. Eventually, all armor segments will be at 90 hit points.

Idle Power Setting for Armor

API 29 adds the idlePowerUse= parameter to armor classes. In prior versions, powered armor consumed power regardless constantly, regardless of whether the armor was regenerating or not. The idlePowerUse parameter specifies the amount of power to consume when the armor is not regenerating. This defaults to the same value as powerUse=, but it can be set to any non-negative value.

Ammo Weapons Definition

In API 29 it is possible to add ammoID= to the root element of a weapon to specify that it should use ammo. This is much more convenient than the previous method of specifying a <Missiles> element.

Install/Repair Cost

Prior to API 29, there was a bug in which costs for armor install and repair were always returned in credits, even if the item used different a different currency. In API 29, we've made the following fixes:

  • Functions which return armor install and repair cost (e.g., objGetArmorRepairPrice) now return a value in the item's default currency (i.e., whichever currency is specified in the item price).
  • The installCost= and repairCost= parameters access a currency type, just like the item price. Note: In most cases you should omit installCost and repairCost (to accept default values). If you wish to alter these prices, use installCostAdj= and repairCostAdj= instead, which are based on the default values.

Device install costs also ignored the item currency. Starting with API 29, functions which return device install prices use the default item currency.

In addition, the default install cost for devices has been changed. Previous versions used a formula, which did not scale properly at higher levels. The new default is roughly one-sixth of the standard device cost for a given level.

New Properties

The following properties are accessible via itmGetProperty and objGetItemProperty:

  • We now support a set of properties to return special damage attributes. For example, the 'damageRadiation property returns the value of the radiation attribute. The result is the number specified in the damage definition.
  • 'averageDamage: Average damage, in HP, for a single shot of the weapon (including all fragments, and adjusted for enhancements).
  • 'damage: For weapons, the average damage per 180 ticks (adjusted for enhancements).
  • 'damageWMD180: Whereas 'damageWMD returns the WMD value in the damage definition (from 0 to 7), this property returns the average amount of WMD damage per 180 ticks. Note that this takes into account the fact we always do at least 1 point of WMD damage per hit.
  • 'currency: Returns the default currency for the item. This is the same as (itmGetDefaultCurrency item), which is now deprecated.
  • 'fireDelay: For weapons, this is the number of ticks elapsed between shots, adjusted for enhancements.
  • 'fuelCapacity: For reactors, returns the fuel capacity (1 = 1 helium fuel rod); includes enhancements.
  • 'fuelCriteria: For reactors, this is a item criteria describing the set of compatible fuel items.
  • 'fuelEfficiency: For reactors, this is the power produced per fuel unit (including enhancements).
  • 'fuelEfficiencyBonus: For reactors, this describes fuel efficiency as a percent change from the standard, which is 15. Includes enhancements.
  • 'hpBonus: For shields and armor, we return the percent bonus to HP for each damage type (returned in a struct). Note that this is the bonus relative to standard armors of this level; it includes any enhancements.
  • 'maxDamage: Maximum damage, in HP, for a single shot of the weapon (including all fragments, and adjusted for enhancements).
  • 'maxHP: For shields, this is the maximum number of HP, taking enhancements into account.
  • 'maxSpeed: For drive devices, returns the maximum speed (0-100). This takes enhancements into account.
  • 'minDamage: Minimum damage, in HP, for a single shot of the weapon (including all fragments, and adjusted for enhancements).
  • 'power: Now takes enhancements into account for all devices.
  • 'thrust: For drive devices, returns the additional thrust (including enhancements).

Item Components

This API includes engine support for crafting component, like Tinkers and UAS Armor Forge. Instead of defining components as custom data structures, we add new structures to support component definition.

Defining Components

An item type may have a <Components> element to define the components that are required to craft the item. For example:

<ItemType unid="&itNanoforgedTitaniumArmor;"
   ...
   />

   <Components>
      <Item count="6" item="&itTitaniumOre;"/>
   </Components>
</ItemType>

NOTE: It is perfectly valid to have the component list be randomized. In that case, the engine determines the actual list of components at the beginning of the game and keeps it consistent throughout.

Images

<ImageComposite> Type

Today it is possible to share images across types. For example, you can define &rsMyStationImage; as an <Image> type (with its own UNID) and use it in multiple station types. But some stations have complex image definitions, such as the image for stars (which have a color filter) or asteroid images (which are randomized).

This API allows you to share complex image definitions by introducing the <ImageComposite> type:

<ImageComposite unid="&rsRockyPlanetoidSizeG;">
   <ImageVariants>
      <Image	imageID="&rsRockyAsteroids;" imageX="980" imageY="0"   imageWidth="175" imageHeight="175"/>
      <Image	imageID="&rsRockyAsteroids;" imageX="980" imageY="175" imageWidth="175" imageHeight="175"/>
   </ImageVariants>
</ImageComposite>

This composite image can be used in any station type with the <ImageLookup> element:

<StationType ...
   />
   ...
   <ImageLookup imageID="&rsRockyPlanetoidSizeG;"/>
</StationType>

Image Viewport

A rendered 3D image appears different in a 2D game depending on the position and orientation of the camera. In Transcendence, if the camera is H units above the object, it must be H/2 units to one side. Thus we are always viewing an object at a 26.56 degree angle.

The size of the camera viewport also affects the rendered image. If the viewport is H units wide, then the camera is very close to the subject and the distortion increases (particularly at the edges). Conversely, if the viewport is H/10 units wide, then the camera is very far away and the object is closer to isometric projection.

In prior APIs, the viewport was controlled with the viewportSize= parameter on an image reference. This is a pixel value corresponding to the viewport size; if the value is omitted, we assume the viewport size is the same as the image width.

In API 29, there is a new way to specify the viewport size as a ratio of the camera height: viewportRatio=. Since this is a dimensionless unit, it is easier to determine its value in a 3D program. By default, this value is 0.5—that is, the viewport is one-half the height of the camera.

Dock Screens

Item List Display Control

We've added a new type of control for dock panes: <ItemListDisplay>. This is used to display sets of items. For example, we show required components for foundry screen.

scrSetBackgroundImage

API 29 adds a way to modify the background image at runtime (e.g., inside of OnPaneInit). The function takes a special kind of image descriptor, which is represented as a struct and has the following format:

  • If the image descriptor is Nil then we set the background to whatever the screen defaults to.
  • The type can be one of the following: none, image, or object.
  • With type: 'none, we show no background image.
  • With type: 'image, we expect the image field to be the UNID of an image to display as the background.
  • With type: 'object, we expect the obj field to be an object whose image will be displayed as the background.

For example:

(scrSetBackgroundImage {
   type: 'object
   obj: gPlayerShip
   })

The above will show the current player ship (the large, hero image) as the background for the dock screen.

Effects

Looping Image Animations

For combined effects, e.g., an effect with an animating image and a particle system, we no longer assume that the animating image loops. Instead, we only play the animation sequence once.

If you wish to loop the image, use lifetime="-1" to indicate that the image should live forever. A positive value for lifetime means that the image lives for that number of ticks. The default is the number of ticks required for a single animation.

Fire Effects

Fire effects (i.e., muzzle flash) now default to standard effects based on damage type (just like hit effects). Well-known UNIDs 0x00000070 through 0x0000007F are used for defaults.

Hit Effects

Hit effects now get parameters in gData about the damage. The following fields are defined in gData inside <GetParameters> event:

  • objHit: The object that was hit.
  • cause: The object that caused the damage (generally the projectile object).
  • attacker: The object that fired.
  • orderGiver: The object that is responsible. E.g., when an auton attack, the attacker is the auton and the owner of the auton is the order giver.* damageHP: The amount of damage caused.
  • damageType: The type of damage.
  • hitDir: The direction of the hit, relative to the center of the object hit.
  • armorSeg: The armor segment that was hit, if any.
  • weaponUNID: THe UNID of the weapon firing the projectile.

Orb Effect

  • Added animate="fade", which linearly decreases the radius and intensity over the lifetime of the effect.
  • Added animate="explode", to simulate an explosion.
  • Added style="flare", which adds hexagonal spikes to the glow. When combined with animate="fade" this can replace the <Flare> effect.
  • Added style="fireblast", which uses fractal clouds to simulate a fireball. Combine this with animate="explode".
  • Added style="cloud", which paints a fractal cloud with pixel values ranging from primary to secondary color.
  • Added distortion="...", which is a value from 0 to 100 representing the amount of distortion of fireblasts. With distortion 0, the blast is spherical. With greater distortion, the blast has fractal edges.
  • Added animate="dissipate", which is similar to explode except that color fades from primary to secondary color.
  • Added animate="flicker", in which radius varies randomly.
  • Added blendMode="screen", which makes overlapping orbs brighter.
  • Added spikeCount="...", to control the number of spikes for flares and other styles.

Particle Jet

  • <ParticleJet> has been renamed to <ParticleSystem>, to make it useful for more cases. The old name will continue to be a synonym, but the new name is the recommended tag.
  • Added style= parameter to choose different kinds of particle effects. The default is jet, which emits particles along a given line.
  • Added style="radiate", which emits particles in all directions. This is the same as the <ParticleCloud> effect.
  • Added emitLifetime= parameter to specify the duration (in ticks) of particle emissions.

Other Effect Changes

  • <GetParameters> event can disable the sound of an event. Returning the field noSound: true will disable sound for that instance. This only works for the root event.

TransLisp

  • For backwards compatibility, the add and multiply functions convert their inputs to integers before the operation. This is consistent with pre-float versions of TransLisp, but it changes behavior from API 28.
  • (itmGetProperty item 'components) -> returns a list of item structures representing the components for the given item.
  • There is a new special attribute for items: +hasComponents:true. This special attribute can be used in item criteria to filter items that have components.
  • (objGetProperty obj 'currency) -> returns the default currency for the object (generally, a station). This is the same as (objGetDefaultCurrency obj), which is now deprecated.
  • (objGetProperty obj 'scale) -> returns the scale of the object. One of the following: star, world, station, ship, flotsam.
  • Added round, floor, and ceil functions. They work on any number and always return doubles. NOTE: I was tempted to automatically cast the result to integers, but this would break if the original value was out of 32-bit range.
  • (convertTo type value) -> coerces value to the given type. See typeof for a list of valid types.
  • Added (resColorBlend ...) to generate colors.
  • Added (scrSetBackgroundImage ...). See Dock Screen section above.
  • Added (objGetProperty obj 'dockingPorts), which returns a list of docking port descriptors.
  • Added (objSetProperty obj 'operatingSpeed 'half) to order a ship to travel at half speed. This can be reversed with (objSetProperty obj 'operatingSpeed 'full). You can also get the property to determine the current operating speed.