Understanding galaxy/system layout and code

[relanat]

Topology (a fancy name for how to lay out star systems in a certain order) can seem very confusing at first glance. But it's fairly easy once you know what is what. Hopefully this topic will help.

We'll use Stars of the Pilgrim (SOTP) and JBW's Pale Blue Light tutorial mod (PBL) as examples. To get the best use of this get the PBL mod from xelerus.de http://xelerus.de/index.php?s=mod&id=1505, a text editing program like Notepad++ or Sublime Text and a decompiled version of SOTP which is a folder called "Transcendence_Source" (search the forum/Multiverse for info on how to do this with Transdata).

Basically what we'll cover here is how to create the systems you want, how the Galactic Map is drawn and how to set up stargates so they go to the system you want. It's not everything you need to know but will help to decipher things.

All the adventures (as opposed to extensions which add on to an existing adventure) have their own star topology. SOTP has about 25 star systems and PBL has 2. They are both set up in the same way.

Firstly a UNID is set up for the SystemMap. Note that this isn't the system map you get in the game where you see all the stations and asteroids in a system. This is the map of all the systems in the adventure so the game knows what stars exist, where they are and how they are connected. Like what you see in the Galactic Map.

These examples are taken from ExtSystemMap.xml in PBL and HumanSpaceMap.xml in SOTP.

Code: Select all

<SystemMap UNID="&smPBLSystemMap;"
	name=			"Space" 
	backgroundImage=	"&rsWatsonGalaxyMap;"
	initialScale=		"100"
	minScale=		"50"
	maxScale=		"100"
		>

Code: Select all

<SystemMap UNID="&smHumanSpace;"
	name=			"Human Space" 
	backgroundImage=	"&rsHumanSpace;"
	initialScale=		"200"
	minScale=		"100" 
	maxScale=		"250"
	lightYearsPerPixel=	"0.4"

	stargateLineColor=  "#6b8299"
		>

Both have a <SystemMap UNID= starting with sm. It can start with anything but 'sm' is used by convention as short for system map.

backgroundImage= is the important one. Scroll down to the bottom of each of these files. You will see a line of code starting with <Image UNID=".

For PBL it's

Code: Select all

<Image UNID="&rsWatsonGalaxyMap;"	bitmap="Resources\WatsonGalaxyMap.jpg"	loadOnUse="true" />

For SOTP we get

Code: Select all

<Image UNID="&rsHumanSpace;"	bitmap="Resources\HumanSpace.jpg"	loadOnUse="true" />

This line of code let's the game know which image to use as the background of the Galactic Map. (Once again convention has us placing this code at the bottom of the file just so everyone knows where to look if they want this info, it just makes it easier). And sure enough if you have a look in the "Resources" folder of these adventures you will find the jpg images used. WatsonGalaxyMap.jpg (quite appropriately named and very helpful here) is a cool looking mottled purple background with a clear space in the middle for the system layout. HumanSpace.jpg will be familiar to any one who has played SOTP and pressed "n". It has the big loop defined into three areas; New Beyond, Ungoverned Territories and Outer Realm. These will be mentioned further down.

The other lines of code deal with how big the Galactic Map is, how much you can zoom it in or out and (I assume) what color the line between systems is (I didn't know you could change that until now!).

Next comes <TopologyCreator> This is the meaty bit. This is where you tell the game how many star systems you want in the adventure and how they are connected.

For PBL we have:

Code: Select all

<TopologyCreator>
	<Stargate from="SE:Outbound" to="DL:Inbound"/>
</TopologyCreator>

<Node ID="SE" x="0" y="0">
	<System UNID=	"&ssWatsonsStar;"
		name=		"Watson's Star"
		level=		"1"
		attributes=	"humanSpace; newBeyond; mainline;"
		/>
</Node>

<Node ID="DL" x="100" y="0">
	<System UNID=	"&ssDelirium;"
		name=		"Delirium"
		level=		"3"
		attributes=	"humanSpace; newBeyond; mainline;"
		/>
</Node>

Dead easy this one. Inside <TopologyCreator> you see SE to DL. These can also be seen in the <NodeID= code underneath.
Inside <NodeID="SE", two lines down is "name= "Watson's Star". So in the Pale Blue Light mod "SE" is a convenient way for the game to say "Watsons's Star".
And for <Node ID="DL", the name is "Delerium"

So from this the game will create 2 stargates. One outbound from SE, which is the system called Watson's Star,which will connect to the inbound stargate in the Delerium (DL) system. And as you see in the mod there are only two systems with one stargate connection between them. Also every individual stargate must be called something different. You can't have two stargates called "SE:Outbound" but you can have two stargates leading out from a system if they are called different names.

In SOTP it gets a bit more complicated because (among other reasons) there are so many more systems to connect.

This time the code comes from StarsOfThePilgrim.xml.

Code: Select all

<SystemMap UNID="&unidPartISystemMap;"
	displayOn="&smHumanSpace;"
	>
			
<TopologyCreator>
	<Node ID="NewBeyondMainline"/>
	<Stargate from="CP:Outbound" to="SK:Inbound"/>
			
	<Node ID="UngovernedTerritoriesMainline"/>
	<Stargate from="C9:Outbound" to="A1:Inbound"/>
			
	<Node ID="OuterRealmMainline"/>
	<Stargate from="G2:Outbound" to="EndGame"/>
			
	<Node ID="Elysium"/>
</TopologyCreator>

Note the difference here. Instead of having every system listed here they have been divided into three main groups or Node IDs; New Beyond, Ungoverned Territories and Outer Realm. This also makes it easier because the three areas have different characteristics, Charon, Sung/Huari and Ranx/Ares.

So here rather than linking systems, areas are linked. Note that except for Elysium the groups have a stargate connection after them. eg "CP:Outbound" to="SK:Inbound". We'll refer back to these later.

Now if we head back to HumanSpaceMap.xml we find the rest of the systems. This is only the code for the NewBeyond section, the Ungoverned and Outer sections have similar sections of code further down in the file.

Code: Select all

<NodeGroup ID="NewBeyondMainline">
	<Stargate from="SE:Outbound"	to="C1:Inbound"/>
	<Stargate from="C1:Outbound"	to="C3:Inbound"/>
	<Stargate from="C3:Outbound"	to="C3A:Inbound"/>
	<Stargate from="C3A:Outbound"	to="BA:Inbound"/>
	<Stargate from="BA:Outbound"	to="C4:Inbound"/>
	<StargateTable>
		<Group chance="50">
			<Stargate from="C4:Outbound" to="C4A:Inbound"/>
			<Stargate from="C4A:Outbound" to="CP:Inbound"/>
		</Group>
		<Stargate chance="50" from="C4:Outbound" to="CP:Inbound"/>
	</StargateTable>
</NodeGroup>

Looks like gibberish doesn't it. But once you learn to speak topologyese (well, it's a language now!) it all falls into place. This is a list of the stargates in the first section of SOTP.

Just below this code you find

Code: Select all

<!-- ERIDANI -->

<Node ID="SE" x="-15" y="-66">
	<System 
			name=		"Eridani"
			level=		"1"
			attributes=	"humanSpace, mainline, newBeyond"
			>
		<System UNID="&ssStartonEridani;"/>
	</System>

(There is also some <MapEffect> code which is what prints the big faded letters "New Beyond" and does other stuff on the Galactic Map but that's for another topic.)
In this lot of code we again see "SE" as a Node ID. But this time if you look at the name= it says "Eridani". "SE" was also used in PBL but because SOTP and PBL are completely separate adventures this can work. But only one NodeID can be called "SE" in each adventure. The next lot of code is for the Rigel Aurelius system and it has a Node ID of BA. Then comes Charon (CP) and St Katherines (SK). These systems appear in every SOTP game and are always laid out in the same way.

So looking at the stargate code above we see a stargate linking SE, which is Eridani, to the C1 system. "But what's the C1 system called", you ask? Well it depends. Below the St Kats code there is a section headed MINOR NEW BEYOND SYSTEMS. It has info on the C1, C3, C3A, C4 and C4A systems, all of which are in the above stargate list.
Here's the C1 code.

Code: Select all

<Node ID="C1" x="18" y="-139">
	<System
			level=		"1"
			attributes=	"humanSpace, mainline, newBeyond"
			>
		<Table>
			<System chance="25" name="Groombridge"	UNID="&ssEarthSpaceStandard;"/>
			<System chance="25" name="Lalande"		UNID="&ssEarthSpaceRedDwarf;"/>
			<System chance="25" name="5 Indi"		UNID="&ssEarthSpaceAsteroids;"/>
			<System chance="25" name="Foum Alhaut"	UNID="&ssEarthSpaceDesert;"/>
		</Table>
	</System>
</Node>

Yep, that's right. That's why sometimes the second system has a different name. The C1 system (which is the second star system straight after Eridani) doesn't have a set name. Instead of having a "name=" line of code there is a <Table> of names. The "chance=25" code means there is a 25% chance of any of these names coming up in any particular SOTP game. If you want to do a lot of modding it's worthwhile starting to think of systems by their Node ID rather than their name. So think BA system instead of the Rigel system because NodeID is used quite a bit in code whereas name is used more in gameplay.

Looking back at the list of stargates we get a topology which will look like this

SE Eridani (always occurs)
C1 (maybe named Groombridge, 25% chance)
C3 (maybe named Cairn, 25% chance)
C3A (maybe named Lacaille, 50 % chance; because there are only two name options in the code with chance=50)
BA Rigel Aurelius (always occurs)
C4 (maybe named Jotunheim, 25% chance; but there are 5 choices with chances ranging from 8% to 25%)

After C4 there is a bit more code trickery. Observant players will have noticed that sometimes there is one system between Rigel and Charon and other times it is two systems.

Extracted from the stargate list above is the relevant code:

Code: Select all

<StargateTable>
	<Group chance="50">
		<Stargate from="C4:Outbound" to="C4A:Inbound"/>
		<Stargate from="C4A:Outbound" to="CP:Inbound"/>
	</Group>
	<Stargate chance="50" from="C4:Outbound" to="CP:Inbound"/>
</StargateTable>

Again a <Table> (in this case a <StargateTable>) is used to add a degree of variation to the game. Here there is a 50% chance of either having a stargate straight from C4 to CP (Charon) or having a stargate from C4 to C4A (maybe named Kaus Media, 25% chance, there are 5 options with chances from 5 to 25%) and then another stargate from C4A to CP which adds another system to the map. Note that the C4A system is there all the time but only appears if the 50% chance is positive. So you can have as many systems in your adventure as you like but if the stargates don't link them they wont appear in the game.

So to finalise the stargate list for the New Beyond area we add

C4A (50% chance this system will appear in the game), and
CP Charon (always occurs)

Now we have to go back to the <TopologyCreator> code in StarsOfThePilgrim.xml to get the next stargate. The code there had

Code: Select all

<Stargate from="CP:Outbound" to="SK:Inbound"/>

This not only takes us from CP (Charon) to SK (St Katherines) but also connects the New Beyond area to the Ungoverned Territories area. If you look at the Ungoverned Territories stargate list it starts from "SK:Outbound" and goes through 7 to 9 more systems (the number depends on more <StargateTable>s) until it gets to the C9 system (Jiang's Star). This then connects to the Outer Realm through the last <TopologyCreator> stargate. Finally the last system in the Outer Realm stargate list is G2 which is Heretic.

That's how to create a straight topology. Start at one system, connect to the next one, then connect that one to the next one, etc. As long as you have the NodeIDs defined and a stargate linking your systems to the starting system you have created your own universe.

[relanat]

Galactic map placement

Now we'll look at drawing the Galactic Map. If you look at the PBL Galactic Map you see two systems, Watson's Star and Delerium,
Watson's Star is in the centre of the map and Delerium is 100 pixels to the right. This is deliberate and (thank you, JBW) very easy to explain.

Transcendence uses a coordinate system to place the systems on the Galactic Map. Coordinates 0,0 (x is always listed first) is the centre of the map. Increasing the x value will move the system to the right and decreasing the x value (making it a negative number) will move it to the left. The y coordinates move the placement of the system up and down. If the y coordinate is positive the system will be placed above the centre of the map, if it's negative then the system will be below the centre.


In the Node ID code on the first line you will see x and y coordinates

Code: Select all

<Node ID="SE" x="0" y="0">
	<System UNID=	"&ssWatsonsStar;"
		name=		"Watson's Star"
		level=		"1"
		attributes=	"humanSpace; newBeyond; mainline;"
		/>
</Node>

<Node ID="DL" x="100" y="0">
	<System UNID=	"&ssDelirium;"
		name=		"Delirium"
		level=		"3"
		attributes=	"humanSpace; newBeyond; mainline;"
		/>
</Node>

For SE the coords are x="0" and y="0". This places Watson's Star in the middle of the Galactic Map. For DL we have x="100" y="0". Because of the way the game works this will put Delerium 100 pixels to the right of Watson's Star. This is called the x axis. If JBW had used x="200" then Delerium would have been 200 pixels (or twice as far) to the right. Note that the game will automatically draw the line connecting the two systems. You don't have to do that. (And if you have more than one stargate connection from a system the game will draw them all automatically.)

If the x value for DL had been negative, say -100, then Delerium would have appeared the same distance away but to the left.

In SOTP we have

Code: Select all

<Node ID="SE" x="-15" y="-66">

which is Eridani. This appears near the centre of the map and is actually 15 pixels to the left of centre because the x coordinate is -15. It is also just below (66 pixels) the centre of the map because the y value is -66.

So if you wanted to place a system over near the right hand side of the map you could use coordinates like CP (Charon) The CP coordinates are x="267" y="-40". So a large positive x value puts it well to the right and small y value puts it neither up nor down.

To place a system both to the right and up we can use values like the C5 system (Draconis/Hadar/etc; a quick look at the stargate list for the Ungoverned Territories tells us this is the second system after St Katherines). The C5 coords are x="162" y="130". So this tells us large positive values for x and y move the system up and right.

This really confused me the first time I did it. The best way is to check the coords in SOTP and work back from them, If you want to place a system up and to the left find a system roughly where you want to place your system and use those coordinates. You'll need to fine tune the results but it makes it easier initially.

As a rough guide:
positive x values move the system to the right of centre
negative x values move the system to the left of centre
postive y values move the system up from the centre
negative y values move the system down from the centre

I hope that helped. The wiki has more info http://wiki.kronosaur.com/modding/xml/systemmap but be aware that some of it is dated. JBW has also done a tutorial on this and I'll add the link when I find it. EDIT: See the next post for the link.
You can also look at Wolfy's topology extension example https://forums.kronosaur.com/viewtopic.php?f=8&t=7644 and PM's Xen System mod http://xelerus.de/index.php?s=mod&id=1487 for info on adding systems to an existing topology.

[JohnBWatson]

Found the tutorial I told you about.

http://forums.kronosaur.com/viewtopic.p ... 904#p69904

[digdug]

this is a great post, I think it can go in the modding reference section ?