sysFindObject info

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Post Reply
Militia Captain
Militia Captain
Posts: 888
Joined: Tue Nov 05, 2013 9:56 am

Here's the function help (1.8b2).
(sysFindObject source criteria) -> list of objects

criteria is a string that must specify one or more of the following categories:

* Include all categories
b Include beams
G Include ONLY stargates
G:xyz; Include ONLY stargate with ID 'xyz'
k Include markers
m Include missiles
s Include ships
t Include stations (including planets)
T Include structure-scale stations
t:xyz; Same as "t +xyz;"
T:xyz; Same as "T +xyz;"
z Include the player

and may contain any number of the following options:

A Active objects only (i.e., objects that can attack)
D:xyz; Only objects with data 'xyz'
E Enemies of the source only
F Friends of the source only
H Only objects whose base = source
I:angle; Only objects that intersect line from source
J Same sovereign as source
J:unid; Sovereign unid = unid
K Killed objects only (i.e., objects that cannot attack)
L:x-y; Objects of level x to y.
M Manufactured objects only (i.e., no planets or asteroids)
N Return only the nearest object to the source
N:nn; Return only objects within nn light-seconds
O:docked; Ships that are currently docked at source
O:escort; Ships ordered to escort source
O:guard; Ships ordered to guard source
P Only objects that can be detected (perceived) by source
R Return only the farthest object from the source
R:nn; Return only objects greater than nn light-seconds away
S:sort; Sort order ('d' = distance ascending; 'D' = distance descending
V Include virtual objects
X Only objects whose target is the source
Y Only objects angry at (or enemies of) the source
Z Exclude the player
+xyz; Only objects with attribute 'xyz'
-xyz; Exclude objects with attribute 'xyz'
=n; Only objects of level n. You can also replace = with >, <, >=, or <=, but they need to be escaped in XML.

+/-data:xyz; Include only/exclude objects with data 'xyz'
+/-isPlanet:true; Include only/exclude planets
+/-property:xyz; Include only/exclude objects with property 'xyz'
+/-unid:xyz; Include only/exclude objects with UNID 'xyz'

Order doesn't matter as long as multi-character items end with semicolons.
If the source is nil, the center of the system is used for position, and other criteria related to the source are ignored.
There is also an option of "B:xyz;" which works the same as "+xyz;" where 'xyz' is an attribute.

Very useful function and often the only way to identify an object. But can be a bit confusing (it certainly was for me)!

(sysFindObject source criteria) -> list of objects

Objects are the things that fill the star systems in Transcendence. These include planets, asteroids, ships, wrecks, stations, missiles, markers, beams and more. The 'obj' series of functions is used on objects and they are different from items. Autons can be both but are objects when they are 'use'd or deployed; flying around in other words. Virtual objects can also occur. These are special objects which are designed to never be visible in the game but generally to allow object code to be run without having a real object present. Also this function only works on objects in the current system.

The 'source' is usually either an object or Nil. Common examples are the playership, another ship, a marker, station or planet/asteroid. Nil, when used as the 'source', has a position of system coordinates 0,0 which is the centre of the system (usually the star). But this is only important for distance criteria as we will see later.

Three common uses of 'sysFindObject' are to find objects by some identifier, by relationship or by distance.

The identifiers can be any of the "+/-" criteria, sovereign, level and more.
A common example is (sysFindObject Nil "s+specialAttribute;") where 'specialAttribute' can be an attribute of your mod playership. This will give a list of every ship in the system which has the attribute 'specialAttribute'. If only your mod playership has this attribute then we get a list of one object, the playership.
Or using (sysFindObject Nil "T+property:abandoned;") will give a list of all the destroyed stations in the system.
The criteria '+unid:xyz;' is very handy. Using it with '*' as the main criteria will give a list of all the objects of that type or UNID in the system. So (sysFindObject Nil "*+unid:&stSistersOfDomina;") gives, in this case, a list of Sisters Of Domina stations.
Note the use of 'Nil' as the 'source' for these examples. This is because we aren't concerned with where the objects are or who they are friendly or enemy with, just whether they have the identifier we are using.

The relationship criteria use sovereigns and dispositions to sort the objects. The most common ones are 'F' and 'E'. Here we need to use something other than 'Nil' for the 'source'. An example is (sysFindObject gPlayerShip "sE"). This gives a list of ships which are enemies of gPlayerShip (in other words the player). Using 'Nil" gives a different list because ships which are enemies of the player may not also be enemies of 'Nil'.

The distance criteria are really handy. To use them we set 'source' as the object we want to measure from. So to get a list of enemy ships within 300 light seconds of the playership we would use (sysFindObject gPlayerShip "sEN:300"). Using (sysFindObject Nil "sEN:300") will give a different list as the distance is being measured from the center of the system as noted above, not from the playership.
To find the stargate which is closest to the center of the system, however, we can use 'Nil" as the source. (sysFindObject Nil 'GN) will return the stargate which is closest to the system center. One important difference here is that the criteria 'N' and 'R' for 'nearest' and 'farthest' object return only one object, not a list. More to follow on this.
Stupid code. Do what I want, not what I typed in!
Militia Captain
Militia Captain
Posts: 888
Joined: Tue Nov 05, 2013 9:56 am

Using the function.

Using 'sysFindObject' gives us a list of objects. Unfortunately this is a list of numbers which don't mean much to us humans, although the computer likes them!
To check if the criteria we have used is giving us the objects we want it can be handy to convert the list to a list of names. Note that the game doesn't need this, it's only to help us when we are modding.
We can use the 'map' function to do this.

Code: Select all

(map (sysFindObject Nil "someCriteria") theObj (objGetName theObj))
Using this code we can change the list of objects to names. You can use any criteria in the 'sysFindObject' code and this 'map' code will convert it to names.
This is an example from a game that I had running when I wrote this topic.

Code: Select all

(sysFindObject Nil "T+property:abandoned;")
(620174352 621770400 620149272)
Doesn't mean much in this form except that there are three destroyed stations in the system.

Code: Select all

(map (sysFindObject Nil "T+property:abandoned;") theObj (objGetName theObj))
("NavSign Eridani-900" "Starton Residentials" "Sisters of Domina")
This is more useful. (I confess that I destroyed the Residentials and Sisters stations to get examples for this topic, but it wasn't me that did the Nav sign!)

In the example above the objects and the names are enclosed in brackets, (). This is because the objects are part of a list. 'sysFindObject' produces a list of objects, even if it is a list of only one object! But most 'obj' functions don't work with lists, they need a single object. To get a single object from a list we use the '@' function, formerly known as the (now deprecated) 'item' function; (@ list index).
'@' works on a zero-based numbering system. This means that the first object in the list is in the '0' index position. The second object is in the '1' index position, etc.
So to use the Starton Residentials station we select it using this code:

Code: Select all

(@ (sysFindObject Nil "T+property:abandoned;") 1)
which returns the second object in the list.
The exceptions to this are the criteria 'N' and 'R' which give the nearest or farthest object only.
These are not in list form (this can be seen as they are not enclosed in brackets) so it is not necessary to select them using '@'.

Most of the example criteria above are enclosed in double quotes, ". This isn't always necessary. Simple criteria can be used by prefixing them with a single quote like this example:

Code: Select all

(sysFindObject Nil 'GN)
However any of the criteria that use a colon, ':', need to be enclosed in double quotes as do criteria which use semicolons, ';'.

These are only simple examples. As the function help says "and may contain any number of the following options".
'TAFM returns a list of friendly, active stations that aren't planets or asteroids.
"s0:escort; +commonwealth; +property:radioactive;" used with gPlayerShip as the 'source' would return a list of radioactive ships which have the attribute "commonwealth" and are escorting the playership (which admittedly isn't very common)!

It isn't always possible to select the object you want using only 'sysFindObject', Sometimes it is necessary to reduce the list using 'sysFindObject' as far as possible and then use the 'filter' function to further reduce the list. But it can always be done.
Any problems or queries can be posted here or go to the Transcendence Discord and ask there.
Stupid code. Do what I want, not what I typed in!
Post Reply