[WIP] Community Documentation

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Post Reply
User avatar
0xABCDEF
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu May 19, 2016 12:58 am
Location: Was destroyed by a Phobos-class dreadnought in the Eridani system

Reply here if you have any unrecorded info about the modding system.
Here I will be collecting information that cannot be found on the wiki. This will include minor details all the way to missing pages. Some information will be discovered through analysis of the engine source code.

Engine Source Code on GitHub
Color Codes
Confirmed
Implied by the source code
Speculation
Uncategorized
  • <OnGlobalUniverseCreated> requires exactly one tick to pass before a dockscreen can be shown. Attempting to open a screen directly inside the event will lead to an error.
  • There is an item criterion called "M" that returns only missiles (fired by launchers). It excludes ammo, which is fired by non-launchers. An item may match "M" if its XML contains a <Missile> element.
  • There is an item criterion called "+launchedBy:{unid};" that returns only items that can be fired by the specified UNID.
  • There is a mission criterion "D" that allows only missions where the debriefer is the source
  • <OnArmorDamage> can return a list of damage effects in the format ('([damage type] [damage]) ['(blinding [time in ticks])] ['(device)] ['(disintegrate)] ['(EMP [time in ticks])] ['(radiation)] ['(reflect)] ['(shatter)])

Items
  • Functions such as (objSetItemProperty object itemStruct property) and (objSetItemData object itemStruct attrib value) change the itemStruct without updating the variable. For instance, in the following segments of code:

    Code: Select all

    (block
    	(
    		(theShip (sysCreateShip &scPhobos Nil &svAres;))
    		(theItem (itmCreate &itAresPlasmaCannon; 1))
    		)
    	(objSetItemData theShip theItem "data" 1)
    	(objSetItemData theShip theItem "data" 2)
    	(objSetItemData theShip theItem "data" 3)
    	(itmGetData theItem "data")
    	)
    
    (block
    	(
    		(theItem (itmCreate &itAresPlasmaCannon; 1))
    		)
    	(itmSetCount theItem 100)
    	(itmSetEnhanced theItem 0x010F)
    	(itmSetProperty theItem 'disrupted)
    	theItem
    	)
    
    The first part will return Nil, since the variable theItem and its data remain unchanged as (objSetItemData theShip theItem "data" 1) and everything after are executed. The second part will return a single Ares Plasma Archcannon without enhancement nor disruption as the variable theItem again remains unchanged after (itmSetCount theItem 100) and everything after. Since these functions return the updated item, solution is to set the variable every time you use one of them.

    Code: Select all

    (block
    	(
    		(theShip (sysCreateShip &scPhobos Nil &svAres;))
    		(theItem (itmCreate &itAresPlasmaCannon; 1))
    		)
    	(setq theItem (objSetItemData theShip theItem "data" 1))
    	(setq theItem (objSetItemData theShip theItem "data" 2))
    	(setq theItem (objSetItemData theShip theItem "data" 3))
    	(itmGetData theItem "data")
    	)
    
    (block
    	(
    		(theItem (itmCreate &itAresPlasmaCannon; 1))
    		)
    	(setq theItem (itmSetCount theItem 100))
    	(setq theItem (itmSetEnhanced theItem 0x010F))
    	(setq theItem (itmSetProperty theItem 'disrupted))
    	theItem
    	)
    
  • Can have event <OnAddedAsEnhancement> with the variables gSource, gItem, and aResult. Fires when the item type is used to add an enhancement through objAddItemEnhancement
  • Can have the event <OnRemovedAsEnhancement> with the variables gSource and gItem. Fires when the item type is used to remove an enhancement through objRemoveItemEnhancement.
Weapons
Source
  • Can have the event <OnCreateShot> with the variables gSource, aTargetObj, aAttacker, aOrderGiver, and aWeaponType
  • Can have the event <OnDestroyShot> with the variables gSource, aAttacker, aOrderGiver, and aWeaponType
  • Can have the event <OnDamageAbandoned> with the variables gSource, aCause, aAttacker, aOrderGiver, aHitPos, aHitDir, aDamageHP, aDamageType, and aWeaponType
Shields
Source
  • Can have the event <GetMaxHP> with the variables gSource, gItem, and aMaxHP.
  • Can have the fields 'adjustedHP, 'balance, 'damageAdj, 'effectiveHP, 'hp, 'hpBonus, 'power, 'regen, and 'weaponSuppress. These are accessible from itmGetProperty and typGetDataField
Armor
Source
  • Can have the event <OnArmorDamage> with the variables gSource, gItem, aArmorHP, aArmorSeg, aAttacker, aCause, aDamageEffects, aFullDamageHP, aDamageHP, aHitDir, aHitPos, aOrderGiver, and aWeaponType
  • Can have the event <GetMaxHP> with the variables gSource, gItem, and aMaxHP
  • Can have the data fields 'adjustedHP, 'balance, 'damageAdj, 'effectiveHP, 'hp, 'hpBonus, 'installCost, 'regen, 'repairCost, and 'shieldInterference. These are accessible through itmGetProperty and typGetDataField.
  • Can have the attributes blindingDamageAdj, blindingImmune, chargeDecay, chargeRegen, completeBonus, damageAdjLevel, decay, decayRate, deviceCriteria, deviceDamageAdj, deviceDamageImmune, deviceHPBonus, distribute, disintegrationImmune, enhancementType, EMPDamageAdj, EMPImmune, idlePowerUse, installCost, installCostAdj, maxHPBonus, maxSpeedBonus, photoRecharge, photoRepair, powerUse, radiationImmune, reflect, regen, repairCost, repairCostAdj, repairRate, repairTech, shatterImmune, shieldInterference, stealth, unid, and useHealerToRegen
  • Has the properties 'blindingImmune, 'completeHP, 'completeSet, 'deviceDamageImmune, 'deviceDisruptImmune, 'disintegrationImmune, 'EMPImmune, 'hp, 'hpBonus, 'maxHP, 'primeSegment, 'radiationImmune, 'repairCost, 'repairLevel, and 'shatterImmune. These are accessible through itmGetProperty

Events
  • AdventureDesc Events

    Code: Select all

    <OnGameStart>
    	;	This event fires on an <AdventureDesc> when a new game starts (a save file is created). Set the crawl screen here. Nothing except gPlayer is defined. Returns nothing
    	;	VARIABLE				DESCRIPTION
    	;	gPlayer				Can be used to access the player's genome
    	;	RETURN				Nothing
    </OnGameStart>
    <OnGameEnd>
    	;	This event fires on an <AdventureDesc> when the game ends for any reason. Returns nothing
    	;	VARIABLE				DESCRIPTION
    	;	aScore				The player's current score
    	;	aResurrectCount		The number of times the player died and then resurrected by loading the game from the main menu. Does not include any resurrections caused by <OnGlobalResurrect>
    	;	aSystemsVisited			The number of systems that the player has entered at least once
    	;	aEnemiesDestroyed		The number of enemy ships that the player destroyed. Does not include stations.
    	;	aBestEnemiesDestroyed	The number of times the player destroyed a ship of type aBestEnemyClass
    	;	aBestEnemyClass		The strongest enemy ship that the player destroyed
    	;	aEndGameReason		A code, specified in gamEnd or elsewhere, describing how the game ended. In SOTP, 'leftHumanSpace is the only important reason.
    	;	aEpitaph				A string, specified in plyDestroyed or elsewhere, describing what happened to the player, usually in the form "was destroyed by X in the Y system."
    	;	aEpitaphOriginal		Currently the same as aEpitaph in all cases.
    	;	aTime				A string describing the total play time in the format "[int] [unit] and [int] [lesser_unit]" (for instance, "1 day and 5 hours" or "5 hours and 10 minutes" or "7 minutes and 2 seconds") or "[int] [unit]" (in cases where the number of the lesser unit is less than one)
    	;	RETURN				Nothing
    </OnGameEnd>
    
  • DesignType Events

    Code: Select all

    <GetGlobalResurrectPotential>
    	;	Fired when the player ship is destroyed. The universe is defined and the current node is where the player died.
    	;	VARIABLE				DESCRIPTION
    	;	gPlayerShip			Can be used to get items and data. Suspended during this event.
    	;	gPlayer				Can be used to get the player's information
    	;	RETURN				An integer from 0-100 that determines this type's priority in being selected to resurrect the player at the time of death. 100 makes this type the first priority while 1 makes this type a last resort. The player is guaranteed resurrection if at least one type returns a value greater than 0.
    </GetGlobalResurrectPotential>
    <OnGlobalResurrect>
    	;	Fired when this design type is chosen to resurrect the player (must have returned a value greater than 0 in <GetGlobalResurrectPotential>). The universe is defined and the current node is where the player died.
    	;	VARIABLES			DESCRIPTION
    	;	gPlayerShip			Can be used to access items and data. Active at the time that this event fires
    	;	gPlayer				Can be used to get the player's information
    </OnGlobalResurrect>
    
  • In the events <OnDamage>, <OnDamageArmor>, <OnDamageShields>, <OnShieldDamage>, <OnShieldDown>, and <OnArmorDamage>, aDamageHP is the original ADJUSTED damage. In <OnArmorDamage>, aFullDamageHP is the original UNADJUSTED damage
Screen
TLisp
  • (msnCreate unid-list owner) takes a list of mission types and attempts to create one of each type until it finds the first mission that doesn't destroy itself in <OnCreate>

Post Reply