There is also an option of "B:xyz;" which works the same as "+xyz;" where 'xyz' is an attribute.(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.
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.