basic unvFindObject info

Freeform discussion about anything related to modding Transcendence.
Post Reply
Militia Captain
Militia Captain
Posts: 533
Joined: Tue Nov 05, 2013 9:56 am

Fri Mar 03, 2017 11:10 pm

unvFindObject (1.7)

Earlier versions of Transcendence created the game system by system as you worked your way through the galaxy. Now all the systems are created at the start of the game. This means the function 'unvFindObject' can be used to find any station or ship that is in the game.
There are some exceptions. Some stations and ships are created as you enter a system or under other conditions. unvFindObject won't be able to find these until after you have entered a system where they have been created. After that they will appear in the unvFindObject list unless they are destroyed.

Here's what you get from the function list:

Code: Select all

(unvFindObject [nodeID] criteria) -> list of entries

   s                  ShipClass
   t                  StationType
   +/-{attrib}        Require/exclude types with given attribute

   ({objID} {type} {nodeID} {objName} {objNameFlags})
Riiiight! Easy! :lol:. It's not that bad, really.

unvFindObject by default will search every star system in a game. If you add the node ID of a star system to the code then it will limit its search to that system only. Note that the square brackets around nodeID in the function example above mean this part of the code is optional. You can leave it out without causing a code error.
A nodeID is a shortcut used by the game to identify systems. It is usually two or three letters long. eg the first system in SOTP has a nodeID of SE and is the Eridani system. More examples further down.

The 'criteria' determines what the function will list. Here's an example from Benedict03.xm1 in SOTP where the game finds a Korolov Shipping station.

Code: Select all

(unvFindObj "t +korolovShipping; +populated;")
Note that 'unvFindObj' was an earlier name for the function and has been deprecated. Use 'unvFindObject' now.
The above criteria tells unvFindObject to search through all the star systems and find any stations ("t" criteria) that have both the attributes, "korolovShipping" and "populated". Attributes are listed in the StationUNID code of a station. The standard Korolov station has quite a few. They are found in KorolovShipping.xml.

Code: Select all

attributes=	"corporate, corporateCustoms, corporateDecon, envAir, envEarth, envFire, envWater, friendly, generic, human, majorStation, korolovShipping, populated"
As you can see the two we are looking for are at the end.

In an example game I have running that code generates this list. This tells us there are 3 Korolov stations in this game that have the attribute "populated".
Let's work through them.

((1274 1056775 "C3A" "Korolov Shipping" 64) (1909 1056775 "C4" "Korolov Shipping" 64) (2012 1449990 CP "Korolov Shipping" 64))

The first entry in the list is (1274 1056775 "C3A" "Korolov Shipping" 64). Looking back at the function explanation we see that the entries are in the form ({objID} {type} {nodeID} {objName} {objNameFlags}). See the similarity. Five distinct sections enclosed in brackets.
The first section is "1274". This is the objID of this station. The object ID is a unique number given to every object in the game. It is mainly used through the function 'objGetObjByID' which gives the station object used by most functions. More on this later.

The second section is "1056775". This is the type or UNID of the station. Here it is in the decimal number form. It is the same number as the hex form 0x00102007. We humans tend to use stKorolovShipping because its a bit easier for us to remember. All are the same thing to the game with one exception. Using the stKorolovShipping UNID in the debug screen gives an error. You have to use one of the number forms there.

The third section is "C3A". This is the node ID of the system that the station is in. The game uses node IDs to identity systems instead of names. This allows the game to give different names to the same system to add variety to the game. System "C3A" can be called either Lacaille or Cygni and is the system just before Rigel Aurelius (node ID of "BA", short for battle arena). In this game Cygni was picked at random. Most SOTP systems have a choice of 4 names.

The fourth section is "Korolov Shipping". Give yourself a pat on the back for working out that this is the station name! Stations (and ship and items) can have a couple of different names. An example is mining stations. You may have seen "Port Harcourt" or "Duralloy Dreams" in your galactic travels. These are both station names but using unvFindObject will give you "Commonwealth mining colony" instead. This is because all mining stations are "Commonwealth mining colonies" but are given different names, again to add variety to the game. The name you will get with this function is the one found near the attributes in the StationUNID code. For Korolov stations it is

Code: Select all

name=	"Korolov Shipping"
The fifth and final section is called 'objNameFlags'. I haven't worked out how to use these yet but as a quick summary they are number codes that format the station name. eg if you were at a Corporate Enclave you would want the dockscreen to say "You are docked at a Corporate Enclave", not "You are docked at Corporate Enclave". By using the right name flag you can make an "a" appear in front of the name. There are a number of different name flags, see the wiki for a list of them and jump onto the IRC for help.

Militia Captain
Militia Captain
Posts: 533
Joined: Tue Nov 05, 2013 9:56 am

Fri Mar 03, 2017 11:12 pm

The second station that was found by unvFindObject gave the list entry: (1909 1056775 "C4" "Korolov Shipping" 64). It is very similar to the first entry.
The type or UNID "1056775" is the same. This means this is the same Korolov station as the previous one. So the objName and objNameFlag are also the same because the stations share the same StationUNID code.
The objID "1909" however is different to the previous one as expected (because it is unique to this particular station) and will be different to every other object ID in this game.
The node ID is also different. "C4" is the system after Rigel Aurelius and can be called Van Maanen, Moren-Lin, Jotunheim, Hena's Star or Ankaa. This information tells us that there is a standard Korolov Station (same as the first one) in the system after Rigel Aurelius (in the example game it is called Ankaa).

The third entry is a different Korolov station. Although it looks the same as a standard one it is the station in the Charon system that usually gets destroyed by the Charon Pirates. We can tell this by looking at the third section, the node ID, which is "CP" (short for Charon Pirates), the Charon system. (Charon is one of a handful of systems in SOTP which always have the same name, some other examples are Heretic, St Kats, Eridani).
Looking at the list entry (2012 1449990 CP "Korolov Shipping" 64) we see that the objID is different as expected but here the second section or type is also different, "1449990". Converted to hex it becomes 0x00162006 and is the same as stKorolovAtCharon. (This info can be found in the file HumanSpaceVol1.xml in Transcendence_Source.)

Here's the code for the standard Korolov station:

Code: Select all

<StationType UNID="&stKorolovShipping;"
	name=		"Korolov Shipping"
and the Charon Korolov station:

Code: Select all

<StationType UNID="&stKorolovAtCharon;"
	name=		"Korolov Shipping"
Because the name is the same for both so is the name flag. Note that there is actually a fourth station that has the attributes "korolovShipping' and "populated". It is the Korolov station that is rebuilding that appears after you have destroyed all the pirate stations in Charon. unvFindObject couldn't find it now because it hasn't been created yet and won't be until Charon is clear of pirate stations. After that happens the list will still be three entries long because the rebuilding station replaces the existing Charon station. So the third list entry will be different.

Militia Captain
Militia Captain
Posts: 533
Joined: Tue Nov 05, 2013 9:56 am

Fri Mar 03, 2017 11:16 pm

OK. Now we have a rough idea of what is in the list, how do we use it.

The list entries from unvFindObject aren't designed to be used by any other function. All they are is information for us to use.

To do this we need to select the section we want and convert it into a form the game can use.
This is usually by using the '@' or "item" function. Note that 'item' has been deprecated so use '@' in your code. The game sees them as the same function. '@' is used to select an entry from a list.
The function explanation for '@' is (@ list index). 'list' is the list we want to select an entry from and 'index' is the position of the entry in the list. Important note: 'index' is a number and in the game the values for it start with 0, not 1. See examples below.

What unvFindObject has given us in this example is a list of three entries. These 3 entries each have 5 entries.

As a practical example here's what to do if we want the name of the system that contains the second standard Korolov station.
Firstly we generate the 'unvFindObject' list which contains all the stations with the two attributes.

Code: Select all

(setq stationList (unvFindObject "t +korolovShipping; +populated;"))
What we have done here is create the list which contains the information about the three stations and, using 'setq stationList' called it 'stationList'. The game jargon for this is "setting a variable". From now if the game sees 'stationList' is will equate that with ((1274 1056775 "C3A" "Korolov Shipping" 64) (1909 1056775 "C4" "Korolov Shipping" 64) (2012 1449990 CP "Korolov Shipping" 64)) It's a way of reducing the amount of typing and code needed in modding.

Then we use '@' to select the second entry from the above list 'stationList'. This is the one with the objID of 1909, (1909 1056775 "C4" "Korolov Shipping" 64). Here's how.

Code: Select all

(setq selectedEntry (@ stationList 1))
The 'list' section of this '@' code is the three entries generated by unvFindObject (stationList) as we have seen above. The 'index' is 1 because we want the second entry. Remember, 'index' values start with zero for the first entry and go up from there. So 'index' 0 gives the first entry, 1 gives the second entry, 2 gives the third entry, etc. I know, it's weird, but you get used to it.
So the above code gives us (1909 1056775 "C4" "Korolov Shipping" 64). By using 'setq selectedEntry' we have again given the game a shortcut by setting a variable, this time called 'selectedEntry'. Every time it sees 'selectedEntry' from now it will equate that with (1909 1056775 "C4" "Korolov Shipping" 64).

To select the node ID from our 5 sections of information in 'selectedEntry' we use '@' again.

Code: Select all

(setq selectedNodeID (@ selectedEntry 2))
So the '@' function will get the third entry (using 'index' 2) of selectedEntry and (setting another variable) call it 'selectedNodeID'. This is the nodeID "C4".

Now we use another function 'sysGetName'. This function gives us the name of a star system. Heres the layout:

Code: Select all

(sysGetName [nodeID]) -> name
If no nodeID is used in this function it will give you the name of the star system you are currently in. If you include a nodeID then you will get the name of the system with that nodeID.

Code: Select all

(sysGetName selectedNodeID)
In the example game this will give us Ankaa.

So what use is this. Mostly it is so you can tell the player where to get something or where to go for a mission.
You could have the text "You will find the Holy Grail at the second Korolov station in the (sysGetName (@ (@ (unvFindObject "t +korolovShipping; +populated;") 1) 2)) system" which uses the above code in condensed form. Doing this means you will always be able to send the player to the second Korolov station regardless of which system it is in.

Other examples might be to count how many Ares Shipyards there are in the galaxy and award the player a medal if half of them are destroyed.
I've used the nodeID and objID to set a directional indicator to a specific station in a specific system as the player enters that system.
The more you use this function, the more ideas about how to use it pop into your head.

Finally you can also search by UNID like this;

Code: Select all

(unvFindObject "t +unid:&stTinkerGathering;")
or in the debug screen;

Code: Select all

(unvFindObject "t +unid:0x08040080")
Using this format and the UNID of the standard Korolov station would give a list of only the two standard Korolov stations and not include the one in Charon.

Hope that helps. Enjoy unvFindObject!

Post Reply