## Multiverse libraries index

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Atarlost
Posts: 2391
Joined: Tue Aug 26, 2008 12:02 am
Since libraries on the multiverse are not published in the catalog there is currently no way for modders to know what is available. If you have created a general purpose library please post its UNID and any reference material in this thread so people can actually find it and us it.

Atarlost_Utilities
Legacy Resources Library API15

Atarlost
Posts: 2391
Joined: Tue Aug 26, 2008 12:02 am
Atarlost_Utilities.tdb

This library is available for download on the Multiverse. It contains a number of utility functions.

<Library unid="0xA0070010">

Code: Select all

=== Bugfix for syscalcfiresolution with particles ===
In 1.2 **objIncVel** does not work on particles type projectiles.  To get around this with **sysCreateWeaponFire** use these functions.  Source is the object firing the weapon (usually //gSource//).  Angle is the angle of the shot (usually //aFireAngle//).  Speed is the weapon's shot speed (usually gotten with itmGetData).
(**AU_calcFireAngle** source angle speed) returns integer angle
(**AU_calcFireSpeed** source angle speed) returns integer speed

=== Assorted utility functions ===

(**AU_probabilisticDivide** dividend divisor) returns integer dividend/divisor rounded randomly up or down in proportion to remainder/divisor

(**AU_angleNormalize** angle) returns integer 0<=angle<360

(**AU_angleMargin** angle1 angle2) returns integer: the absolute value between two integers interpreted as angles measured in degrees

(**AU_angleBisect** angle1 angle2) returns integer: the angle that bisects the acute angle between the two angles given as arguments; if the angles are opposite this will return one of the right angles, but it is not defined which.

=== Old Northwind functions ===

(**AU_switchweapon** oldWeapon newWeaponID ship) returns undefined
This function will change the identity of an installed weapon.  OldWeapon is an item struct.  NewWeaponID is a UNID.  Enhancements are transfered.  If the weapon is a launcher the selected missile is transfered.  Damaged weapons will not be switched as it is assumed that the switching is a function of the weapon, not a transmutation imposed by an outside force.

(**AU_switchshield** oldShield newshieldID ship) returns undefined
This function will change the identity of an installed shield.  OldShield is an item struct.  NewShieldID is a UNID.  Enhancements are transfered.  Damaged shields will not be switched as it is assumed that the switching is a function of the shield, not a transmutation imposed by an outside force.

(**AU_switcharmor** oldArmor newArmorID ship) returns undefined
This function will change the identity of all instances of an installed armor.  OldArmor is an item struct.  NewArmorID is a UNID.  Enhancements are transfered.  Damage is transferred as a fraction of maximum hitpoints.  There may be some roundoff error in transfering the damage if the maximum hitpoints of both armors are not factors of 360.

=== Functions meant to be called from specific events ===

(**AU_fireWalkingRepeater** object weapon firepos fireangle repeat target bonus configList condition precalc) returns True
Designed to be called from //<OnFireWeapon>//  This function allows a repeating weapon to fire each shot at a different angle.
Call with something like (AU_fireWalkingRepeater gsource gitem afirepos afireangle afirerepeat atargetobj aweaponbonus '(-4 0 4))
The tenth argument is optional and can be a literal of a fire confirmation check (ie. a function that returns nil if the shot should be fired).
Internally aFireAgle is the angle at which the shot is actually to be fired so that firing conditionals that assume it will work properly.
It is set back to the original value before this function returns.
IMPORTANT BUG WORKAROUnuD: if using with type="particles" add an eleventh argument that is not nil.

(**AU_multishotammohandler** ammoUnid maxCount) returns True or nil
Use in //<OnFireWeapon>// with the event returning this function's return value.
AmmoUnid is the ammo to consume and maxcount is the number of shots per firing cycle.
This makes the weapon consume an ammo item for every projectile fired rather than for every keypress.

(**AU_spinupFireTest** initialFireRate finalFireRate) returns True or nil
This must operate on a weapon with a firerate of 2 and be called within <onfireweapon>.  The event needs to return what this function returns.
Note that initialFireRate and finalFireRate are in ticks, not game seconds so are equivalent to fire rates twice as great.
The weapon will begin firing at initialFireRate and will not fire faster than finalFireRate.  It's best used on heat or capacitor counter weapons.
Weapons using this function can be used by the AI so long as there is no fire rate adjustment.

(**AU_fireBuildup** source weapon) returns integer: times called consecutively
This must operate on a weapon with a firerate of 2 and be called within <onfireweapon>.
Example of use:
<Events>
<OnFireWeapon>
(block (power shot)
(setq power (min (AU_fireBuildup gsource gItem) 100))
(setq shot (sysCreateWeaponFire aWeaponType gSource aFirePos aFireAngle (typGetDataField aWeaponType "speed") aTargetObj nil aWeaponBonus))
(objIncVel shot (objGetVel gsource))
(objDestroy (objgetobjbyid (itmgetdata gitem 'shot)))
(objSetItemData gsource gitem 'shot (objgetid shot))
(objSetData shot "power" power)
"shotFired"
)
</OnFireWeapon>
<OnDamageArmor>
</OnDamageArmor>
<OnDamageShields>
(list
aShieldReflect
(multiply (objGetData aCause "power") aOriginalShieldDamageHP)
aOriginalArmorDamageHP
)
</OnDamageShields>
</Events>
This is a "simple" building power weapon.  The shot is always fired, but is not allowed to persist for more than a tick until the fire command stops.  This allows it to be used by the AI provided there is no fire rate adjustment.

(**AU_AmmoBoxHandler** boxList) returns True or nil
Use in <OnFireWeapon> with AU_AmmoBoxCounter in <OnUpdate>
//boxList// is a list of two element lists where the first element is a UNID and the second the number of shots that item provides.
eg. (list (list &itHelium3FuelRod; 2)  (list &itHeliumAssembly; 8))

(**AU_AmmoBoxCounter** boxList)
Use in <OnUpdate with AU_AmmoBoxHandler in <OnFireWeapon>
//boxList// is a list of two element lists where the first element is a UNID and the second the number of shots that item provides.
eg. (list (list &itHelium3FuelRod; 2)  (list &itHeliumAssembly; 8))

(**AU_FireConfirm** enemycriteria aimTolerance friendcriteria avoidTolerance)
Returns True if no shot should be fired either for lack of enemy or presence of friendly.  Place at the end of <OnFireWeapon>.
Eg. (AU_FireConfirm "sTAEPN:120" 30 "stAFPN:60" 10) will fire if there is an enemy within 30 degrees and 120 light seconds of aFireAngle
but not if there is also a friendly withing 10 degrees and 60 light seconds of aFireAngle.
If friendCriteria is nil the weapon will not try to prevent friendly fire.  If enemycriteria is nil the weapon will not try to conserve shots.
The criteria string must not include "N" or anything else that would make it not return a list, but should include "N:nn" to restrict range.
I suggest "sTAEPN:nn" for enemycriteria and "sTAFPN:nn" for friendcriteria where nn is the range of the weapon for most use cases.
See http://transcendence.kronosaur.com/wiki/modding/xml/spaceobject#criteria for details.
The target the function has found will be returned in aTargetObj.  If it is not in scope nothing will care that we've set it.

goes in <OnShieldDamage>.
shieldAngle is the angle, relative to the ship, that the center of the full shield points.
fullSpread is the difference between the center and edge of the full opacity section.
eg. the region of full coverage spans twice this angle with shieldAngle at the center.
decaySpread is the angle between the edge of the fully opaque shield and zero opacity.

(**AU_FluidArmor**)
This function goes in <OnUpdate> and slowly equalizes HP among like armor.

=== Unlauncher functions ===
The unlauncher code allows a weapon to have multiple ammo types while not using the launcher slot.  All ammo must be fired by another -- usually virtual -- launcher.If there is a conflict current versions of Transcendence will select the lowest UNID weapon to fire the ammo, but the list of ammo is still taken from the virtual launcher.

(**AU_initializeUnlauncher launcher)
Goes in <OnInstall>
Launcher is the UNID of the virtual launcher containing the actual projectile info.

(**AU_VirtualAmmoUpdate**)
Goes in <OnUpdate>
Simple ammo counter for unlauncher, though you can use the AU_ammoBoxCounter with each ammo type having a box size of 1.

(**AU_fireUnlauncher** launcher maxCount)
Goes in <OnFireWeapon>
Launcher is the UNID of the virtual launcher containing the actual projectile info.
MaxCount is the number of shots in the configuration when not wanting to use an ammo item per shot. (eg. like the Dragonfly doesn't).
If MaxCount is nil it is assumed to be 1.  If left off or set to 1 on a multi-shot launcher it will use one ammo item (lie the Dragonflyy).

=== Overrides ===

(**shpCanInstallArmor** theShip theArmor)
This is an override of core function to allow a ship to enforce per segment armor mass limits.
Use staticdata <maxArmorMass#>INT</maxArmorMass#> where # is the segment number and INT is the mass limit for that segment.
Segment limits higher than the ship's maxArmor attribute are ignored.
Behavior should be identical to the original when no staticdata is defined so long as the function continues to take the same arguments.

(**objCanInstallItem** theShip theDevice)
This is an override of core function to allow a ship to enforce device mass limits.
Use staticdata <maxDeviceMass>INT</maxDeviceMass> to enforce a blanket limit.  Reactors are excluded.
Use staticdata <maxShieldMass>INT</maxShieldMass> to limit shields.  This overrides maxDeviceMass.
Use staticdata <maxWeaponMass>INT</maxWeaponMass> to limit non-launcher weapons.  This overrides maxDeviceMass.
Use staticdata <maxLauncherMass>INT</maxLauncherMass> to limit launchers.  This overrides maxDeviceMass.
Use staticdata <maxDriveMass>INT</maxDriveMass> to limit shields.  This overrides maxDeviceMass.
Use staticdata <maxOtherMass>INT</maxOtherMass> to limit devices that are neither weapons, launchers, shields, drives, nor reactors.  This overrides maxDeviceMass.
Use staticdata <totalDeviceMass>INT</totalDeviceMass> to limit the total mass of all devices.  Reactors are excluded.

Additionally, the superconducting shield is given an invocation to recharge with superconducting coils with use key 'L' and the invocation on superconducting coils has its use key removed so that other shields can use the same use key without fear of conflict.
Literally is the new Figuratively

Wolfy
Posts: 5368
Joined: Tue Feb 05, 2008 1:10 am
Location: Somewhere in the Frontier on a Hycrotan station, working on new ships.
Legacy Resources Library API15

This library adds in a number of old resource files that were removed from the core game. It is automatically loaded by any extension with less than API15 - however, if you wish to explicitly use these resources in a newer extension, the available resources are as follows:

You can add this library to any API15+ mod with the following:

Code: Select all

<Library unid="0xA0030004"/>

New resources

Code: Select all

<!-- Ship images -->

<!ENTITY LRL_rsEI100P7						"0xA0031000">

<!-- Station images -->

<!ENTITY LRL_rsRedAsteroid					"0xA0031001">
Overwritten resources (un-deletes some of the resources that george deleted from these images:

Code: Select all

<!--
#########################
### Legacy Overwrites ###
#########################
-->