This record describes API changes in 1.9 Beta 4.

Ship Classes

  • Added lifeSupportPowerUse= parameter to <Hull>.

Station Types

Squadrons

In API 52 we introduce a new concept for station defenders: squadrons. A squadron is simply a set of ships that share the same rules for spawning and reinforcements. Importantly, a station may have multiple squadrons defined, each with different rules for reinforcements.

The simplest version defines spawning and reinforcements on a single line:

<StationType ...>
   ...
   <Squadron table="&tbDefenders;" count="4" reinforce="auto"/>
   ...
</StationType>

The above definition creates at least 4 ships out of the tbDefenders table. If one or more ships are destroyed, we summon news ones from the table until we're back up to 4.

The count= parameter defines how many ships we want to maintain in the squadron. The following are valid values:

  • A number [count="4"]: This defines the minimum number of ships to create from the table. We only include principal ships (i.e., excluding escorts).
  • A dice range [count="1d4"]: Same as above but we roll a random number at the beginning of the game and use that as the minimum number of ships to create.
  • A challenge rating [count="challenge:standard"]: We continue creating ships from the table until the total combat strength matches the given specified challenge for the system level. For example, standard challenge is equal to 2.5 ships of the system level.
  • A property [count="property:defenderCount"]: We read the property (on the station) to determine the number of ships required.

The reinforce= parameter defines when we summon reinforcements. The following values are valid:

  • auto: In auto mode we summon reinforcements as soon we drop below the level specified by count=. We will summon reinforcements until we get back to the specified level. If the reinforce parameter is omitted, we default to this value.
  • none: This means that we never summon reinforcements.
  • A number, dice range, or challenge rating: If we drop below the specified level, then we summon reinforcements to get back to the level specified by either count= or reinforce= (whichever is greater).
  • A property [reinforce="property:reinforcementCount"]: This tells the engine to evaluate the given property to get the required count of ships. If the value is non-Nil but not a number, then we treat this the same as auto.

In addition, we support several modifying parameters that alter the reinforcement behavior:

  • reinforceFrom="...": This is either "build" or "gate". If set to "build" then we build the reinforcements on the station. Otherwise, the reinforcements enter via gate.
  • reinforceLimit="...": This limits the total number of reinforcement calls. After we reach this limit, we stop summoning reinforcements for this squadron. This is often used to prevent farming.
  • reinforceMinInterval="...": This is the minimum number of seconds (realtime) to wait between calls for reinforcements. The default is 20.

Lastly, the most important part of this feature is that you can specify multiple squadron definitions for a station:

<StationType ...>
   ...
   <Squadrons>
      <Squadron table="&tbDefenders;" count="4"   reinforce="auto"/>
      <Squadron table="&tbCivilians;" count="1-4" reinforce="auto"/>
   </Squadrons>
   ...
</StationType>

Radiation Checks and Decontamination

In prior version we used <GetGlobalDockScreen> to bring up a decontamination screen. Starting in API 52, we use a slightly different method.

Stations (or ships) that need to check whether the player is radioactive should define the property rpg.checkRadioactive to True. This will cause the engine to check for radiation and refuse docking if the player is radioactive.

For stations that decontaminate, define the new trade directive:

<StationType ...>
   ...
   <Trade ...>
      <Decontaminate criteria="*" priceAdj="100"/>
   </Trade>
</StationType>

The above code will decontaminate the player's ship on docking (assuming the player can afford it).

The base decontamination cost will be computed based on the armor level of the ship. We charge 20 times the cost to repair 1 hit point on armor of the given level (times all armor segments).

The above design allows for more introspection on stations. Some examples:

  • If you need to know if a station checks for radiation, check the rpg.checkRadioactive property. You can generate a list of all stations with that property.
  • Use a special attribute, +service:decontaminate;, to see if a station charges for decontamination.
  • Use (objGetRemoveConditionPrice stationObj shipObj 'radioactive) to determine the price a station charges for decontamination.

AutoLoot

You may define a station type to be automatically looted when the player passes over it:

<StationType ...
      autoLootCriteria="..."
      >
   ...
</StationType>

The autoLootCriteria is an item criteria that must match for the items to be looted. If all the items on the station fit in the player's cargo hold, then they will all be looted. Otherwise, none will be looted.

The station may have an <OnAutoLoot> event, which will be called when it is auto looted.

Ship AI

New Order: attackOrRetreat

The attackOrRetreat order is identical to the attack order, but it ends if the ship ever drops below 25% armor integrity or %50 hull integrity.

New Order: deterChase

The deterChase order causes a ship to chase an enemy until it leaves a certain radius around the base. This order is used by the guard and patrol orders to chase enemies.

New Order: orbitExact

The orbitExact order takes a target and a struct of parameters. We orbit the target in an exact orbit as specified by the parameters. If enemy ships approach, we attack while staying in orbit.

The parameters are:

  • radius: The orbit radius, in light-seconds.
  • speed: The angular speed in degrees per tick.
  • angle: Starting position, in degrees (or auto).
  • timer: Seconds left in order.

New Order: orbitPatrol

The orbitPatrol order is the same as the patrol orbit except it uses the orbit behavior of orbitExact.

Miscellaneous

  • New AI setting targetsStations: When set, the ship will target enemy stations in addition to enemy ships.

Repairer Items

  • Repairer items now support <Scaling> levels.

Weapon Items

Miscellaneous

  • Added noDetonationOnEndOfLife= parameter. If true, then we do not detonate fragmentation weapons at end of life (they just disappear).
  • Added direction= and arcAngle= to create fragmentation weapons that can explode asymmetrically.

Item Enhancements

  • Added +bonus: Enhances reactor and drive devices.
  • Added +cyberDefense:{n}: Adds n to cyberdefense.
  • Added +perception:{n}: Adds n to perception.
  • Added +stealth:{n}: Adds n to stealth.

System Types

RandomStationTable

<RandomStationTable> can be used to pick a random station from a list. This sounds like the exact thing that <Table> does, but they differ in how they handle stations with spawn limits.

Here are two examples:

<Table>
   <Station chance="25" type="&stArmorDealer;"/>
   <Station chance="25" type="&stIceFarm;"/>
   <Station chance="25" type="&stContainerHabitat;"/>
   <Station chance="25" type="&stHotel"/>
</Table>

<RandomStationTable>
   <Station chance="25" type="&stArmorDealer;"/>
   <Station chance="25" type="&stIceFarm;"/>
   <Station chance="25" type="&stContainerHabitat;"/>
   <Station chance="25" type="&stHotel"/>
</RandomStationTable>

At first it seems as if these two tables behave identically. Each randomly picks a station from the list with equal probability. But the difference is in how the handle the hotel (&stHotel;). Hotels have an encounter option that makes them unique in a star system. The <Table> definition ignores that rule. If the hotel comes up, it gets created, even if there is already a hotel in the system.

In contrast, the <RandomStationTable> definition is smarter. If a hotel is already in the system, then it ignores that option and picks from the remaining stations.

In the <Table> definition it is possible to reverse the behavior as follows:

<Table>
   ...
   <Station chance="25" type="&stHotel"  optional="true"/>
</Table>

The optional= parameter tells the table not to create a hotel if creating it would violate its limits. But even then it differs from <RandomStationTable>: instead of choosing one of the other stations to create, it creates nothing.

Starting in API 52, there is also a way to override the behavior of <RandomStationTable>:

<RandomStationTable>
   ...
   <Station chance="25" type="&stHotel"  ignoreLimits="true"/>
</RandomStationTable>

The ignoreLimits= parameter tells the code to create the hotel even if it exceeds defined limits.

TLisp

New Events

  • <OnSystemObjCreated>: Fires when a new ship or station is created in the system.
  • <OnSystemStarted>: Fires on a <SystemType> when the system loads.
  • <OnSystemStopped>: Fires on a <SystemType> before the system is unloaded.

New Functions

  • (dbgClear): Clears the console window.
  • (sysGetNextNodeTo [fromNodeID] toNodeID): Returns the nodeID to travel to if you want to reach toNodeID.
  • (scrGetSessionData screen attrib): Retrieves data on the dock session.
  • (scrSetSessionData screen attrib data): Stores data on the dock session.
  • (sysVectorInPolygon vector list-of-points): Returns True if the given vector is inside the polygon defined by the list of points.

New Properties

  • ai.combatStyle property for ships.
  • ai.status property for ship (used for debugging).
  • ai.waitingForShields property for ships.
  • alignment property for sovereigns.
  • challengeRating property for ships and stations.
  • compartmentRegen for ships and devices.
  • damageAdj.xyz and hpBonus.xyz properties to shields. For example, damageAdj.laser returns the damage adjustment to laser damage.
  • dualPointOrigin for weapons.
  • detectRange for objects. This is the range (in light-seconds) at which the object can be detected with normal perception.
  • inheritFrom property for all types.
  • inPlayerSquadron property for ships. True if the ship is part of the player's squadron.
  • maneuver property for ships. Max rotation in degrees per second.
  • maxAcceleration property for ships (in km/second).
  • miningType property for asteroids.
  • questTarget property, which supersedes check for questTarget attribute and which can be set dynamically.
  • reaction property for missiles. True if caused by explosion or ejecta.
  • shotsPerAmmoItem property for weapons.
  • stealth property for objects.
  • tracking property to missile objects.

Miscellaneous

  • Added fouled as a condition, which is set when foreign objects are attached to the hull (e.g., pteravores).
  • Added Q directive to sysFindObject to select for objects that can perceive the source.