Transcendence Community Wiki

On Ministry, you can use Inactive + API Spec to see all the updates that George has done.

You can CTRL+CLICK to set the default tab on dockscreens.

This page will contain a legend for terms often used when talking about Transcendence functions and their syntax.

An atom is anything that is not a list. In Transcendence this boils down to numbers, strings, literals, primitives, and lambdas.

• Atom Functions
  • isatom

A list is an ordered sequence of atoms and/or other lists. Items can be added and removed from lists in place, and lists can be searched and accessed with various functions. There are many Transcendence functions that return lists of various kinds of game objects based on location and criteria.

Lists are the only container data structure available in transcendence. However, a list of lists such as ( (key1 value1) (key2 value2) …) can be used as a relational array with the (lookup) function.

• Basic List Functions
  • append
  • count
  • item
  • list
  • shuffle
  • find
  • subset
• Iterating Functions
  • enum
  • enumWhile
  • filter
• In-Place Modification Functions
  • lnkAppend
  • lnkRemove
  • lnkRemoveNil
  • lnkReplace

Numbers in Transcendence are signed integers of a limited size (2^32-1?). They behave pretty much as integers could be expected to.

• Math functions
  • add
  • divide
  • max
  • min
  • modulo
  • multiply
  • power
  • sqrt
  • subtract

A literal is a sequence of non-whitespace characters or a parenthesis enclosure prefixed with a ' (apostrophe), such as 'theLiteral or '(literal (list)). Once created, a literal is indistinguishable from a string. Literals tend to be used when code-like tokens are desired, such as in (set 'name (objGetName theShip)), or (shpOrder theShip 'wait).

Trivia: The “q” in (setq) is short for “quote”, as the function is a shorthand for and optimization of (set 'varname data), or (set quote…).

A string is a sequence of characters surrounded by “ (double quotes). Strings are used for nearly all text output to the player, as well as for some internal utility.

Despite being sequences, strings are considered atoms, and most of the list manipulation functions do not work on them.

• String Functions
  • cat
  • count
  • find
  • int
  • isint
  • strCapitalize
  • strFind
  • subset
  • subst

A lambda is a function stored as data: it is a list of arguments to take and an expression to substitute the arguments into. Typically that expression is a block, to allow for multiple sequential expressions and local variables, but this is not required.

If a lambda is referenced anywhere but as first element of a parenthesis contraption, it is considered data, so you can copy the functionality to another lambda or overwrite its containing variable with a different lambda. If a lambda is printed, its code is shown.

Lambdas-as-data are always truth values, regardless of their return values, so you can have variables containing optional functions (or nil) and gate their execution such as with (if a (a)) to avoid errors about expected function names.

• Lambda Related Functions
  • isFunction

A primitive is an in-built native function provided by Transcendence.exe to the tlisp environment, such as (for) or (if) or (objUnregisterForSystemEvents). There's not much you can do with primitives aside from call them, copy them to other names (e.g., (setq * multiply)), or accidentally mask them with variables ((setq list (list 10 20 30)) could give you no end of confusion, for example…).

• Primitive Related Functions
  • isFunction
  • isPrimitive

This section needs to be expanded

Game object references are numbers or lists that represent specific instances or configurations of objects. They are internal representations that should be considered black boxes which can be created or retrieved, stored, and then passed back to functions that manipulate them, but never directly altered in script.

An itemStruct describes a specific qunatity of a specific item in a specific condition (installed, damaged, enhancement type/level, data set by itmSetData etc). They do not, however, represent a specific location of an item; 5 helium3 fuel rods on your ship will have the same itemStruct as 5 helium3 fuel rods stored on a Charon frigate.

A spaceObject is an instance of a station (star, planet, space station) or a ship that exists somewhere within the current system. As spaceObjects are thin carriers for C++ pointers, it's possible to crash the game by mishandling them. In particular, they can't be stored for longer than a single invocation of an event because they become invalid when the system changes (or possibly even when the objects are destroyed).

An objectID is a global and saveable reference to a specific spaceObject that can be safely stored in persistant data. You an create one for a given spaceObject with objGetID, and you can convert the ID back to an object with objGetObjByID, which simply returns 'nil' if the object is not currently or no longer available.

An item is considered unknown if the player does not know anything about the item except for its general type. Items are unknown at the start of the game if their ItemType definition has a unknownType=”<UNID>“ field, in which case they will appear as if they were of the unknownType until identified. (The engine will randomly pick one of the list of names given for each item type at startup.)

Some kinds of equipment will be identified when installed (such as cargo expansions) or used (such as weapons), but many types of item that use the identification feature need to set the known status in script. Once an item is known, via any means, the status cannot be revoked.

• Known-status functions
  • itmIsKnown
  • itmSetKnown

An item is considered referenced when is statistics (such as damage or resistance) are known by the player. This only applies to equipment items. Reference status cannot be revoked once applied.

While the functions to manage referenced status are still available, this feature has been unused since sometime around version 1.0 of Transcendence. All items are now natively referenced from the beginning of the game. The functions only appear in the Rowena's Weapons and Armor ROMs, which now never spawn.

• Reference Functions
  • itmSetReference
  • itmHasReference

When dealing with fonts in DockScreens there are several options. All of them use the Convection Font.

NAME			FONT		SIZE	BOLD
Small			Convection	10	No
Medium			Convection	13	No
MediumBold		Convection	13	Yes
MediumHeavyBold		Convection	14	Yes
Large			Convection	16	No
LargeBold		Convection	16	Yes
Header			Convection	19	No
HeaderBold		Convection	19	Yes
SubTitle		Convection	26	No
SubTitleBold		Convection	26	Yes
SubTitleHeavyBold	Convection	28	Yes
Title			Convection	56	No
LogoTitle		Blue Island	60	No
Console			Lucida Console	14	No

https://github.com/kronosaur/Transcendence/blob/9bc026da2ce44ef2a2414f0ec65e9d1016136683/Transcendence/Transcendence.h#L50

These codes are used in various functions that need to check for or list spaceobjects.

G         Stargates only
G:xyz;    Stargate with ID 'xyz'
s         Include ships
t         Include stations (including planets)
T         Include structure-scale stations
T:xyz;    Include stations with attribute 'xyz'
A         Active objects only (i.e., objects that can attack)
B:xyz;    Only objects with attribute 'xyz'
D:xyz;    Only objects with data 'xyz'
E         Enemy objects only
F         Friendly objects only
H         Only objects whose base = source
M         Manufactured objects only (i.e., no planets or asteroids)
N         Return only the nearest object to the source (this returns a list in ascending distance order)
N:nn;     Return only objects within nn light-seconds
NN:nn;    Return only nearest object if it's within nn light seconds (just combination of two above codes)
O:abc;    Ships whose order is abc [docked, patrol, escort etc...]
P         only objects visible to source
J         only objects from a given sovereign
J:&unid;  only objects of that sovereign
K         only objects that cannot attack
R:nn;     Return only objects greater than nn light-seconds away
V         Include Virtual objects
Z         Exclude player
z         Only include player
b         Beam Objects
m         Missile Objects
X         Objects targeting Source
S:d       returns objects sorted by distance (in ascending order)
S:D       returns objects sorted by distance (in descending order)
I:angle   returns only objects that intersect a line from the source at the given angle
+xyz;     Include objects with the given attribute
-xyz;     Exclude objects with the given attribute
+unid:UNID                   Return ships of type UNID. 
+isPlayerClass:true/false    Filter based on presence of PlayerSettings in object's type, ships only.
+data:attribute              Checks if (objGetData theObject 'attribute) is non-nil
-data:attribute              Checks if (objGetData theObject 'attribute) is nil

Note: Virtual stations are not searched by default through t; therefore you should use V as well if searching for a virtual station.

Moved to SpaceObject subsection.

These are codes used to enumerate types with the typFind function.

* = all types
$ = currency UNID
a = an adventureDesc UNID
b = item table UNID
c = effect type UNID
d = dock screen UNID
e = space environment UNID
f = overlay UNID (apparently original name was 'energy field')
g = globals UNID (currently returns nothing?)
h = ship table UNID
i = item type UNID
m = image UNID
n = system node UNID (currently returns nothing?)
p = power UNID
q = system table UNID 
s = ship class UNID
t = station type UNID
u = sound UNID (currently returns nothing?)
v = sovereign UNID
w = name generator UNID (currently returns nothing?)
y = system type UNID
z = system map UNID 
_ = template type UNID 	//	We don't support enumerating template types (TSE/CDesignType.cpp)

V = Include Virtual types 

+isPlayerClass:true/false = filters in/out ship classes with playersettings
+unid:[a unid] = returns the requested unid if extant, or nil

• There is currently no way to get a list of only vitual types except filtering one list against the other.
• Use +attrib and -attrib to select attributes
• Type codes are only additive, e.g., “$q” will return both currencies and system tables in one list.
• There appears to be some way to use > >= < ⇐ $ # and a number to do aditional filtering. (I haven't been able to make this do anything obvious -Weaver)

Moved to DesignType subsection.

These flags are used for controlling the formatting of names of items, ships and stations.

Flags can be added together to create a certain formatting, ie. 3 would be pluralized and capitalized.

0x001 (1)   = capitalize
0x002 (2)   = pluralize
0x004 (4)   = prefix with 'the' or 'a'
0x008 (8)   = prefix with count (or 'a')
0x010 (16)  = prefix with count
0x020 (32)  = no modifiers
0x040 (64)  = prefix with 'the' or 'this' or 'these'
0x080 (128) = short form of name
0x100 (256) = actual name

Damage types are represented as integers or hexadecimal values in script

-1       - Generic
0  (0x0) - Laser
1  (0x1) - Kinetic
2  (0x2) - Particle
3  (0x3) - Blast
4  (0x4) - Ion
5  (0x5) - Thermo
6  (0x6) - Positron
7  (0x7) - Plasma
8  (0x8) - Antimatter
9  (0x9) - Nano
10 (0xA) - Graviton
11 (0xB) - Singularity
12 (0xC) - DarkAcid
13 (0xD) - DarkSteel
14 (0xE) - DarkLightning
15 (0xF) - DarkFire

The game uses frequency values to say how often something appears in the game. The known values are:

* Common: 20
* Uncommon: 10
* Rare: 4
* VeryRare: 1

A string with series of 5 characters separated by spaces. Each character represents a level. '-' means no chance for an occurance at that level. 'c' means it is common for an occurance at that level. 'u' means it is uncommon for an occurance at that level. 'r' means it is rare for an occurance at that level and 'v' means it is very rare for an occurance at that level.

An example LevelString would be

vrucu rv---

Which translates to

• Level 1: VeryRare
• Level 2: Rare
• Level 3: Uncommon
• Level 4: Common
• Level 5: Uncommon
• Level 6: Rare
• Level 7: VeryRare

In practice this means more level 4 items will be generated than level 5 and 3, which in turn will generate more than level 2 and 6, which in turn will generate more than level 1 and 7.

Enhancements on items are reported as hexadecimal values (sometimes converted to integers) This is a list of known enhancements and their values:

Y and X are hexadecimal values (0-F)

--  SHIELD

    --  DAMAGE REFLECT  - Damage Bounces off shields
        0x03YX - Refect damage type Y with X chance

    --  DAMAGE TRANSPARENCY - Damage Passes throught shield
        0x83YX - Pass throught damage type Y with X change

--  ARMOR

    --  REGENERATION
        0x0200

    --  DECAY
        0x8200

    --  IMMUNITIES
        0x0B00 - RADIATION
        0x0B10 - BLINDING
        0x0B20 - EMP
        0x0B30 - DEVICE DAMAGE
        0x0B40 - DISINTEGRATION
        0x0C00 - BLINDING/EMP/DEVICE DAMAGE

    --  INTERFERES WITH SHIELDS
        0x8C00

    --  REGENERATES NEAR SUN
        0x0D00

    --  REFUELS REACTOR NEAR SUN
        0x0E00

--  WEAPON

    --  DAMAGE BONUS - Adds from 10 to 150% damage bonus
        0x010X

    --  DAMAGE PENALTY - Adds from 10 to 150% damage penalty
        0x810X

    --  SPEED - Increases shooting speed of weapon up till 30/sec
        0x100X - X can be 2, 4, 6 or 8

    --  DECREASE SPEED
        0x900X - X can be 2, 4, 6 or 8

--  SHIELD/ARMOR

    --  HP BONUS - Adds from 10 to 150% HP bonus of armor/shield
        0x010X

    --  HP PENALTY
        0x810X

    --  DAMAGE REDUCTION
        0x060X - reduce ENERGY damage
        0x070X - reduce MATTER damage
        0x08YX - reduce Y and Y+1 type damage
        0x09YX - reduce Y type damage
        0x0AYX - reduce type Y damage and Y+2 type damage with 1.5X

    --  DAMAGE INCREASE
        0x860X - increase ENERGY damage
        0x870X - increase MATTER damage
        0x88YX - increase Y and Y+1 type damage
        0x89YX - increase Y type damage
        0x8AYX - increase type Y damage and Y+2 type damage with 1.5X

--  SHIELD/WEAPON

    --  EFFICIENCY - Decreases the energy consumption of weapon
        0x0F0X

    --  DECREASE EFFICIENCY
        0x8F0X

Other possible enhancements documented in this thread.

0x0001	+Enhanced seems to be a generic enhancement
0x0002	seems to be a generic negative enhancement
0x0003+	+Unknown
0x0100	+% hp bonus
0x0200	+regen
0x03XY	reflect X (Y%?)
0x040X	+ X repair I'm guessing this repairs itself when hit by X damage type
0x0500	+ Resistant seems to add broad resistance to everything
0x0600	+Energy Resistant resists energy damage types
0x070X	+Matter Resistant resists matter damage types
0x08YX	reduce Y and Y+1 type damage (eg ion +thermo)
0x09YX	reduce Y type damage
0x0AYX	reduce type Y damage and Y+2 type damage with 1.5X (eg ion +posi)
0x0BY0	immune to Y subtype (eg. device damage)
0x0B00	+Radiation Immune
0x0B10	+Blinding Immune
0x0B20	+EMP Immune
0x0B30	+Device Damage Immune
0x0B40	+Disintegration Immune
0x0B50	+Unk Immune
0x0C00	+Ionization Immune immune to blinding\device\EMP
0x0C10 still +Ionization Immune
0x0D00	+SolRegen
0x0E00	+SolFuel
0x0F00	+Efficient this will apply to armor, but may only have an effect on powered armor

0x8000	+Unknown
0x810X	-X% hp reduce
0x8200	decay
0x83XY	transparent to X (Y%??)
0x84XY	X repair (Y??)
0x850X	+Vulnerable seems to remove broad resistances to everything
0x860X	+Energy Vulnerable
0x870X	+Matter Vulnerable
0x88YX	vulnerable to Y and Y+1 type damage
0x89YX	vulnerable to Y type damage
0x8AYX	vulnerable to Y damage and Y+2 type damage with 1.5X
0x8BY0	still does immunities
0x8C00	+no shields
0x8C10	still no shields
0x8D00	still +SolRegen
0x8E00	still +SolFuel
0x8F00	-Drain again I'm guessing this would effect powered armor

Enhancements in string form are also supported

{number}			Interpret as a mod code
+armor:{n}			Add armor special damage, where n is an item level
+hpBonus:{n}			Add hp bonus.
+immunity:{s}			Immunity to special damage s.
+reflect:{s}			Reflects damage type s.
+regen				Regenerate
+resist:{s}:{n}			DamageAdj for type s set to n
+resistDamageClass:{s}:{n}	DamageAdj for type s (and its next-tier mate) set to n
+resistDamageTier:{s}:{n}	DamageAdj for type s (and its tier mate) set to n
+resistEnergy:{n}		DamageAdj for energy damage set to n
+resistMatter:{n}		DamageAdj for matter damage set to n
+shield:{n}			Add shield disrupt special damage, where n is an item level
+speed:{n}			Faster. n is new delay value as a percent of normal

More enhancements can be found here.

When you retrieve the category of an item in script, it is given as an integer. The category can be inferred from this list:

1    (0x0001) - Misc Item
2    (0x0002) - Armor
4    (0x0004) - Weapon
8    (0x0008) - Special Devices (Patch Spider, Jumpdrive, Enhancers)
16   (0x0010) - Missile Launcher
64   (0x0040) - Reactor
128  (0x0080) - Shield
256  (0x0100) - Cargo bay
512  (0x0200) - Fuel
1024 (0x0400) - Ammo
2048 (0x0800) - Drive
4096 (0x1000) - Useable

When retrieving items based on item criteria, these are the flags used:

*   all categories
a   armor
b   miscellaneous devices (Patch Spider, Jumpdrive, Enhancers)
c   cargo hold
d   device (weapon, shield, drive, etc.)
f   fuel
l   launcher
m   missile/ammo
p   weapon, primary (excluding launchers, same as w~l)
r   reactor
s   shields
t   miscellaneous
u   useable (armor coating, ROM, etc.)
v   drive
w   weapon (including launchers)
I   is installed
D   is damaged
N   is not damaged
S   is usable
V   is Virtual
U   is not installed

Some special attributes

canBeDamaged:true  only items that can be damaged
damageType:Laser   only items that have a certain damage type. Also limits to weapons (obviously)
unid:0xXXXX        only items with matching UNID

In addition there exists a special syntax for negating, filtering on levels etc…

~                  Negate. Eg. w~l will match weapons that are not launchers.
^                  Force. Eg. a^u will match armors that are usable
< and >      Less than and Greater than. There are several ways to use these operators
  <=$500        Items that cost less than 500 credits
  >=#25         Items where there are greater than 25 in the stack. Used when getting items from objects
  <=6           Items below level 6
L                  New in 1.04. Level Constraint. Eg. L:1-5 selects levels between 1 and 5 (inclusive). Replaces above syntax.

F                  Rarity. Eg. F:cu will only select Common or Uncommon items 

There are some modifiers which can be used. Modifiers are case sensitive. Modifiers can be added freely in mods.

The following modifiers are not given in Transcendence.xml

These are the orders used in vanilla or known to exist. They all have slightly different function signatures. The number preceding is the internal order number. Not all of the orders can be used with shpOrder. See this thread for more information:

http://www.neurohack.com/transcendence/forums/viewtopic.php?p=42708#p42708

needs to be expanded with signatures and more descriptions

1    guard                      Guard target
2    dock                       Dock with target
3    attack                     Attack target
4    wait                       Unsure. Wait at position for a time in seconds
5    gate                       Go to nearest gate (or specified gate) and use it
6    gateOnThreat
7    gateOnStationDestroyed
8    patrol                     Patrol a target at a set distance (in ls)
9    escort                     Escort target
10   scavenge
11   followPlayerThroughGate
12   attackNearestEnemy         Name says it all
13   tradeRoute
14   wander                     Wander around the system
15   loot                       Loot target (must be a wreck)
16   hold                       Hold position (optionally for a certain period)
17   mine                       Mine a target object (only for Ferian Controller)
18   waitForPlayer
19   attackPlayerOnReturn
20   follow                     Follow target
21   navPath
22   goto                       Go to target
23   waitForTarget
24   waitForEnemy
25   bombard                    Bombard target
26   approach                   Approach a marker until a certain distance?
27   aim                        Aim at target
28   orbit                      Orbit around a target at a set distance (in ls)
29   holdCourse                 Hold a certain course for a certain time (in ticks)
30   turnTo                     Turn the ship in direction (angular)
31   attackHold                 Attack target but hold position (no chasing)
32   attackStation              (Found in TSE/Utilites.cpp, no idea what it does)

The functions objGetDataField and typGetData access predetermined data tags, of which these are known:

cargoSpace
explosion
fireAccuracy 
fireRangeAdj
fireRateAdj 
launcher 
launcherUNID
level
maxSpeed
maneuver
manufacturer
name - combined class and type
primaryArmor
primaryArmorUNID
primaryWeapon
primaryWeaponRange
primaryWeaponRangeAdj
primaryWeaponUNID
score
shield
shieldsUNID
thrustToWeight
speed                 - speed of missile or a weapons projectile

new fields in 1.04

deviceSlots           - available for ships, used for devices
deviceSlotsNonWeapons - total number of device slots that take non-weapons
deviceSlotsWeapons    - total number of device slots that take weapons
genericName           - <del>manufactuer/</del>class/type as string - unlike ticket says, does not give manuf.
hullMass              - mass of hull without items/devices in tons
maxArmorMass          - max size of compatable armor segments in kilograms
maxCargoSpace         - max possible cargo space with expansions in tons
fuelCapacity          - max fuel in reactor/shipclass, fuel provided by fuel items
fuelCriteria          - criteria string of fuel that reactorDevice/shipClass takes
fuelEfficency         - reactorDevice (and shipclass) attribute
power                 - max power output of reactorDevice/shipclass
maxSpeed              - driveDevice max speed provided
thrust                - thrust provided by driveDevice, maybe ship?
cargoSpace            - amount that a cargoDevice will increase cargospace
armorItems            - list of armor items from shipClass
deviceItems           - list of device items from shipclass
category              - data field on item for 'weapon' 'shield' etc

Mainly from this forum page.

Superseded by this

Friendly            Will not fight back (unless scripted or prompted by AI)
Neutral             Will attack if attacked.
Enemy               Will openly attack.

All Sovereigns are Friendly to others of same Sovereign.

Destructive Chaos   Enemy to all not of exactly same Sov
Constructive Chaos  Enemy to Destructive. Neutral to Neutral.
                    and Constructive Order, Friendly to Constructive Chaos
Destructive Order   Enemy to Constructive. Neutral to Neutral and Destructive Order.
                    Enemy to Destructive Chaos.
Constructive Order  Enemy to Destructive. Neutral to Neutral
                    and Constructive Chaos. Friendly to Constructive Order.
Neutral             Enemy to Destructive Chaos. Neutral to everyone else.

These are the IDs of the messages sent to the player throughout the game. Use plyEnableMessage to turn them on or off.

commsHint
dockHint
mapHint
autopilotHint
gateHint
useItemHint
refuelHint
enableDeviceHint
switchMissileHint
fireMissileHint

Also, you can use allHints to enable/disable all hints

Shield and Level adjustment curves

Dbglog has a limit of 931 characters.
Not in 1.2, dbglog can print past this limit.
sysVectorPolarOffset starts with 0 to the right and rotates counterclockwise
Ticks and real seconds