basic custompicker dockscreen list format info

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

Sat Mar 24, 2018 10:07 am

This had me stumped for a while until I found George's notes in RPGShipScreens.xml (1.8a4a) so posted here for greater visibility.

CustomPicker screens need a specific format for the list entries that appear in the display area.
The list format is as follows:
0. The main name or text that appears first and has the larger text size.
1. The icon.
2. The subheading which appears underneath and in smaller text size.

Here's an example taken from a development version of the Scorpion GodPlayership,

Code: Select all

<Dockscreen UNID="&dsD789GodFindShipDockscreen;"
		name=		"Find Ships"
		type=			"customPicker"
		nestedScreen=	"true"

		initialItem="=(or (isError shipTextAndCursorPlacer) (not shipTextAndCursorPlacer) (eq (scrGetListCursor gScreen) shipListPos))"
			;CustomPicker screens need a specific format for the lists that appear in the display area.
			;The list format is as follows: (from RPGShipScreens.xml)
			; 0.	The main large name that appears first, here the type name followed by the sovereign name.
			; 1.	The icon (or in this case Nil as no icon is used).
			; 2.	The subheading, here the UNID in entity, hex and decimal format.

		(block (nonAutonBAShipUNIDList nameList)
				;We create a list of all ship types but exclude autons and Battle Arena ships.
			(setq nonAutonBAShipUNIDList (filter (typFind 's) theShipType (not (or (typHasAttribute theShipType 'battleArena) (typHasAttribute theShipType 'auton)))))
				;We set what we want to appear in the list entries. Here the type name and sovereign name, with a sub-text
				;	of all the formats of the UNID; entity, hex and decimal.
			(setq nameList 
				(map nonAutonBAShipUNIDList 'excludeNil
						(cat (typGetProperty theType 'name) " - " (sovGetName (typGetProperty theType 'defaultSovereign)))
						(cat (unvEntity theType) " - " (mathDecToHex theType) " -- " theType)
				;Now we sort the list alphabetically by type name as that is the first entry.
			(sort nameList)
In the image below you see the end result. A dockscreen with a list of ships showing the ship name and sovereign, and in the second line, the UNID in ENTITY, hex and then decimal format. Note that all three UNIDs are the same UNID just in different languages, human (or entity), hex and decimal.

In the code, note the type="customPicker" code on the third line. So we are in a customPicker screen.

Inside the <List> block we have 'rowHeight=' and 'initialItem='.

'Row height' determines the height of each list entry. Be aware if they are made too small the text and image may overlap into the list entry below it. There are normally 7 list entries in a dockscreen, here there are 10 and this can be increased up to at least 15 (and possibly higher) by changing this value.
'Initial item' uses code to set the cursor at a specific list entry when you enter the screen. Much easier than scrolling down from the top all the time but not relevant here.

Now we get to the code for the list. We are generating a list of ship types so they can be found in a game by using 'unvFindObject'.
However Battle Arena gladiators, which all have the attribute 'battleArena' in their code and autons ('auton' attribute in their code) are excluded.

So we filter a list of all ship types (typFind 's) to remove the gladiators and autons and create a new list called 'nonAutonBAShipUNIDList'.

Then we use 'map' to create the info we need to have the list appear as it does.

Using 'map' with this code actually creates a list of lists which we have called 'nameList'. Confusing? Yeah, it was for me too.

What we have created is a list of 152 ship types. This is all the ships in the game less the gladiators and the autons. It starts at the Antares I and finishes with the Zulu-class gunship. (Note that the (sort nameList) code is necessary to put them in alphabetical order; hat-tip to the forum people)

But each of these list entries is also a list, a three part list as determined by the code above.

Using the Antares I as an example. The first part of the Antares Iist entry is the large text which says "Antares I-class freighter - Corporate Hierarchy"
The second part is "Nil" and the third and last part is the sub heading."scAntaresI - 0x153002 -- 1388546".

Looking at the specific code shows how this is done.

Code: Select all

	(cat (typGetProperty theType 'name) " - " (sovGetName (typGetProperty theType 'defaultSovereign)))
	(cat (unvEntity theType) " - " (mathDecToHex theType) " -- " theType)
This directly relates to George's comments in the game code.
; 0. The main large name that appears first, here the type name followed by the sovereign name.
; 1. The icon (or in this case Nil as no icon is used).
; 2. The subheading, here the UNIDs in entity, hex and decimal format.

The first line of code, enclosed in the 'cat' brackets sets the large text and separates it with a 'dash'.
The second entry is always Nil here (because I don't know how to do it) but can be code which makes a small image appear to the left of the text. Like the item image in a station 'buy' screen. This is a subject for another topic but see PM's Trading Post Menu mod for an example of how to do this.
The third entry again uses 'cat' to create a line of text which gives the UNID in the three different formats separated by dashes. The use of two dashes after the hex UNID is deliberate as it acts as a reference point in later code but these separators can be anything you like; asterisks, slashes, letters, numbers, etc.
'mathDecToHex' is a custom function by NMS (ty) that converts UNIDs from decimal to hex format.

Note that the game will always look for the three sections of the list entry. If we didn't include the second entry, 'Nil", the game would assume the subheading is image code and not display the second line of text. You won't get an image either as that code won't make sense to the game.
Also there doesn't have to be three parts to the list entry, only if you want a subheading to show. If there is only one part, eg the ship name, then the game will just show that in the large text size.

Hope that helps. It's only the most basic info. Other modders please add any relevant info or correct anything I've said. Thanks.

EDIT: Just noticed that some new code has been added to do this in API 38. It uses different code to do the same thing. See the API 38 Ministry topic for more details.
custompicker info image.JPG
custompicker info image.JPG (88.08 KiB) Viewed 117 times

Post Reply