I'm happy to announce the immediate availability of Transcendence 1.5 Beta 1!

This version of the core engine is designed to support the upcoming Eternity Port expansion, but it also has many improvements for the core game, particularly for modders.

Dock Services Screen

Transcendence 1.5 features a set of completely reworked dock services screen. As you can see from the picture above, armor and devices are visually represented (instead of being shown in list).

More importantly, the new screens allow the player to buy and install upgrades from the station in one step. This will make it easier for new players to figure out how to upgrade their ship.

There are three dock services screen, one for armor & shields, one for weapons, and one for miscellaneous devices.

Modding Considerations

There is a new attribute, dockServicesScreen=, for the <PlayerSettings> element that specifies the dock services screen to use for a particular player ship class.

For API version 23 and above, this defaults to the new screens (&dsRPGDockServices; = 0x00010029). For previous API versions, we default to the old set of screen (&dsRPGDockServicesCompatible; = 0x0001002A).

If you wish your player ship extension to use the new dock screens, simply switch to API version 23. If you wish to stick with the old screens (but want to use API 23) then use the dockServicesScreen= attribute to point to the old screen.

And, of course, if you wish you can create your own set of screens and point to them.

Note that in both cases we rely on stations having a <Trade> element to define the devices and armor they install. (See Commonwealth.xml for an example.)

XML Manipulation & Override

Another major feature in 1.5 is the ability to modify the XML for a given type. This is a feature based on suggestions from this forum thread.

The basic recipe looks like this:

  1. In the root element of your extension (<TranscendenceExtension>), add usesXML="true". This tells the engine that you need the XML for all the types to be kept around for you.
  2. In <OnGlobalTypesInit>, you may use a new function, typGetXML to get the XML for a type that you wish to override.
  3. There are new functions that manipulate the XML returned by typGetXML. For example, you can set attributes or add elements.
  4. Once you've manipulated the XML, you may call typCreate to dynamically create a new type or override an existing type.

Here is an example:


...
<OnGlobalTypesInit>
(block (cannonXML)
; Get the XML for the recoilless cannon

(setq cannonXML (typGetXML &itRecoillessCannon;))

; Change the name of the item

(xmlSetAttribute cannonXML 'name "my recoilless cannon")

; Redefine

(typCreate &itRecoillessCannon; cannonXML)
)
</OnGlobalTypesInit>
...

XML Manipulation Functions

There are several new functions that allow you to manipulate the XML returned by typGetXML:


(xmlAppendSubElement xml xmlToAdd [index]) -> True/Nil
(xmlAppendText xml text [index]) -> True/Nil
(xmlCreate xml) -> xml
(xmlDeleteSubElement xml index) -> True/Nil
(xmlGetAttrib xml attrib) -> value
(xmlGetAttribList xml) -> list of attribs
(xmlGetSubElement xml tag|index) -> xml
(xmlGetSubElementCount xml) -> number of sub-elements
(xmlGetSubElementList xml [tag]) -> list of xml
(xmlGetText xml [index]) -> text
(xmlGetTag xml) -> tag
(xmlSetAttrib xml attrib value) -> value
(xmlSetText xml text [index]) -> True/Nil

Warnings & Precautions

This functionality gives you a powerful new way to override the core XML, but it requires thought and finesse to implement properly. Here are a few warnings and precautions:

  • Do not make too many assumptions about how core types might change in the future. For example, imagine you add a new action to the Ship Status screen. A future version might deprecate the entire screen.
  • Do not make assumptions about the XML, because it might change from version to version. Whenever possible, check the current XML before making changes. For example, you might search the XML for the Ship Configuration action instead of assuming that it is the first action.
  • Do not assume that you are the only extension making changes. Whenever you make a change, ask yourself, "what if someone else is doing this too?" For example, if you changing the price of all weapons, make a change relative to the current price. Instead of hard-coding a new price value, add 10% or 50% or whatever to the current price.
  • Consider other ways to override before resorting to this method. For example, you can override ship images with the <ShipClassOverride> element. Using that technique is more likely to be compatible than changing the XML directly. [In general, my goal is to provide built-in override methods for the most common cases.]
  • NOTE: In 1.5 Beta 1 there is currently a bug in which registered extensions do not properly register the useXML flag when they are first downloaded. To work around this, close and restart Transcendence (after the extension has been downloaded).

Other Modding Enhancements

1.5 Beta 1 has the following additional modding enhancements and changes for API version 23:

  • Added <Orb> effect. This is a parameterized effect used for painting suns. Here is an example.
  • Added 'dockingPortCount and 'openDockingPortCount to objGetProperty.
  • Added 'level property to objGetProperty.
  • Added 'cyberDefenseLevel property.
  • 'category property returns 'beam' for beams.
  • Added shipConstructionEnabled and shipReinforcementEnabled properties.
  • Added 'orbit to objSetProperty
  • Added 'interiorHP and maxInteriorHP properties to ships.
  • Default fireRateAdj for <StationType> is 40 instead of 80 (API <23 still defaults to 80).
  • Added optional combination of <Ships> and <Reinforcements> for stations.
  • cyberDefenseLevel defaults to ship level.
  • Wreck chance defaults to some value as a function of ship mass.
  • Missile definitions may be part of the missile item.
  • disarm= attribute for OverlayType.
  • paralyze= attribute for OverlayType.
  • spin= attribute for OverlayType.
  • drag= attribute for OverlayType.
  • <Counter> element for OverlayType (implemented "progress" and "radius").
  • Allow dice range in <Offset> directive
  • Added (sysCreateLookup)
  • gravityRadius= parameter on stars
  • Added gData param to typTranslate and objTranslate
  • Added LocationCriteriaTable to item tables.
  • Added ability to suppress enable/disable device message.
  • Added <Controls> to dock screen panes
  • Added (scrSetControlValue)
  • id= attrib for <StaticData> and others (to match <Language>).
  • Added (scrTranslate)
  • Added (scrSetDescTranslate)
  • Added dockServicesScreen= to <PlayerSettings>
  • Added <LocationCriteriaTable> for station images.
  • regen= replaces repairRate for <StationType> (hp repaired per 180 ticks)
  • shipRegen= replaces shipRepairRate for <StationType>
  • Added +launchedBy:{unid} special attribute for items
  • sysCreateStation takes an optional event handler arg.
  • Added (typHasEvent)
  • Damage cannot be negative (clips to 0).
  • Added rotationColumns= to images
  • Added 'holdAndAttack order.
  • Added 'noTargetsOfOpportunity AI setting.

Enhancements & Bug Fixes

  • New star effects
  • Ships with multiple primary weapons use damage type adjustment of target to figure out which weapon to use.
  • Cannot enable/disable devices if paralyzed.
  • Pteravores can be removed at docking services.
  • Fixed grid painting for double-stars
  • Fixed crash bug with <Particles>
  • Fixed bug with Anton (and others) flying in the wrong direction.
  • Fixed bug with dsLoot.