Adventure Extensions Introduction (basic)

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Transcendence version 099 brings us a new era in extensions with the introduction of the Adventure Extension, where we can create new networks of star systems for the game.

Adventure Extensions are an easy to learn process, which I am going to walk you through in this little introduction to the new format.

(As of the time of this writing, Adventure Extensions are still experiencing some bug that prevents their use in extensions for the unpacked version of the game. 099b should correct this issue. Get a jump on making your adventures by unpacking transcendence and starting to build some new networks! How to Unpack XML)

Here is a sample adventure extension that shows the minimum requirements:

Code: Select all

<?xml version="1.0" ?>


<TranscendenceAdventure
      UNID=            "0xDDED000F"
      version=         "0.99"
      >



   <AdventureDesc
          UNID=            "@1"
         name=            "Sample Adventure"
         backgroundID=      ""
         >
   </AdventureDesc>

   <SystemTopology>

      <Node ID="SE" rootNode="true">
         <System name="Eridani"            level="1">
            <System UNID="&ssStartonEridani;"/>
         </System>

         <StarGates>
            <StarGate Name="Outbound" DestID="EndGame"/>
         </StarGates>
      </Node>

      <Node ID="EndGame"
            endGame="true"
            endGameReason="escaped"
            epitaph="escaped the Sample Adventure"
            >
      </Node>

   </SystemTopology>

</TranscendenceAdventure>
This adventure extension loads and plays just fine. It includes a single system, Eridani, plus the End game system (I believe that is now required).

So that is the structure of a simple adventure extension.

Let's take a look at the sections in more detail next.

The opening and closing elements:

Code: Select all

<TranscendenceAdventure
      UNID=            "0xDDED000F"
      version=         "0.99"
      >



</TranscendenceAdventure>
Every adventure extension will be enclosed in these. I call 'em tags. An important consideration is the UNID- you need one of those. And I found out that the UNID prefix must match if you add any other design elements such as ships, stations, items, systems or graphic/sound resources. My UNID prefix there is 0xDDED. A UNID prefix is what we register in this thread.

The new topology system for the main transcendence xml and for any adventure extensions uses two elements. George explains them at the mod section of the main website here. The first element is the adventure description:

Code: Select all

   <AdventureDesc
          UNID=            "@1"
         name=            "Sample Adventure"
         backgroundID=      ""
         >
   </AdventureDesc>
For my simple sample, you can see I don't have much in there. I will go into more depth about this in a later post- this new element allows us to choose a full screen image to show as the background for the start of the game, as well as setting up the "crawl text" to tell a little storyline- it is what is used for the new intro to the game. You can modify this new introduction easily to suit the adventure you are creating.

Every adventure extension is required to have this element.

The UNID is a little strange there, isn't it? Well, that one is from the sample that George gave me, and seems to work well so I leave it alone. I am not sure what other values it will take- it doesn't take @2, for instance.

The next required element in an adventure extension is the actual network container:

Code: Select all

 <SystemTopology>


   </SystemTopology>
Inside the network container you will find Nodes. Nodes are the actual systems in the game:

Code: Select all

      <Node ID="SE" rootNode="true">
         <System name="Eridani"            level="1">
            <System UNID="&ssStartonEridani;"/>
         </System>

         <StarGates>
            <StarGate Name="Outbound" DestID="EndGame"/>
         </StarGates>
      </Node>

Each node corresponds to a star system in the network- nodes come in many forms from simple like this sample to very complex. Nodes have several important parameters that must be present:

Nodes must each have a unique ID. This is used as a sort of pointer to the system, regardless of the name of the system. In script we often refer to the nodeID as a way to identify the system we are targeting.

Nodes must have a <System> element which defines a name, a level, and a UNID for the star system. You can place a <table> in the system element to create a random selection:

Code: Select all

		<System
				level=			"1"
				attributes=		"newBeyond"
				variant=		"commonwealth"
				>
			<Table>
				<System chance="30" name="Groombridge" UNID="&ssEarthSpaceStandard;"/>
				<System chance="40" name="Lalande"	UNID="&ssEarthSpaceRedDwarf;"/>
				<System chance="30" name="5 Indi"		UNID="&ssEarthSpaceAsteroids;"/>
			</Table>
		</System>
Notice that this System element includes the new attributes parameter. You can define attributes for a system which can be accessed in script in the game. Scripts and attributes for systems are topics for more advanced tutorials, however.

Be sure that the chances all add up to 100 if you are using a table in the system element. You can use the tables to do many different things- but I have yet to test if attributes can be placed there to create randomly selected system attributes- I will check on that soon.

Nodes also must have a stargate element:

Code: Select all

         <StarGates>
            <StarGate Name="Outbound" DestID="[nodeID]" DestGate="[gateID]"/>
         </StarGates>
A <Stargate element requires 3 pieces of information:
Name of the gate.
DestID to link to.
DestGate to target.

This defines the links to other nodes that the system has. In transcendence there are two types of gates: Inbound and Outbound. Gate names can be changed, but that is a more advanced subject. For now, remember that every system UNID in the game except special cases like Eridani, Elysium, and Huaramarca have an inbound and an outbound gate placed in the system type definition (which is what the system UNID in the system element of the node refers to).

The Stargates element can also take the <table> element-

Code: Select all

			<Table>
				<StarGate chance="50" Name="Outbound" DestID="C3A" DestGate="Inbound"/>
				<StarGate chance="50" Name="Outbound" DestID="BA" DestGate="Inbound"/>
			</Table>

Tables allow randomly chosen connections to be made. I have used the tables in a stargate element to create some highly complex segmented topologies in the past, and look forward to doing more in the future!

That about covers it for the basics of the Node and SystemTopology elements.

A final bit to add here is how to use adventure extensions to add regular design type elements such as items, ships, stations, and more. This is totally possible, and easy to do. As a note about adding items and other design types to the adventure extension, keep in mind that anything you add in won't be accessible from any other adventure extension- so the items are isolated in this type of extension. This makes for an interesting combination for mod extensions- you can use regular extensions for those things that you want to be generally available in any games, or make adventure specific things that will only be available in the adventure extension. (I am about 95% sure that items in an adventure extension won't be loaded in any other games, seems to be the case in all my tests)

Here's the sample adventure extension with a test item added:

Code: Select all

<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
  [

	<!ENTITY itTestItem				"0xDDED4002">

	
  ]>


<TranscendenceAdventure
      UNID=            "0xDDED000F"
      version=         "0.99"
      >

	<ItemType UNID="&itTestItem;"
			name=				"Test Item"
			level=				"1"
			value=				"70"
			mass=				"1"
			frequency=			"common"
			
			modifiers=			"Info; MinorItem;"

			description=		"This test item is here to show how regular design types are added to an adventure extension."
			>

		<Image imageID="&rsItems1;" imageX="192" imageY="96" imageWidth="96" imageHeight="96"/>


	</ItemType>


   <AdventureDesc
          UNID=            "@1"
         name=            "Sample Adventure"
         backgroundID=      ""
         >
   </AdventureDesc>

   <SystemTopology>

      <Node ID="SE" rootNode="true">
         <System name="Eridani"            level="1">
            <System UNID="&ssStartonEridani;"/>
         </System>

         <StarGates>
            <StarGate Name="Outbound" DestID="EndGame"/>
         </StarGates>
      </Node>

      <Node ID="EndGame"
            endGame="true"
            endGameReason="escaped"
            epitaph="escaped the Sample Adventure"
            >
      </Node>

   </SystemTopology>

</TranscendenceAdventure>
As you can see, simply add the normal UNID declaration at the top, and then add the item into the root element ( <TranscendenceAdventure> is the root element )

That's it- a simple adventure extension you can build into a sprawling, complex network filled with your heart's desire as far as transcendence gaming is concerned. :)
Last edited by Periculi on Mon Aug 25, 2008 5:32 am, edited 1 time in total.
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Something that Fatboy discovered that should go here-

When you are using the adventure extensions and copying the existing topology over into it to add things, you can run into a little snag involving Huaramarca.

This is due to the topology being overwritten without including the Huaramarca node id that is located in Huari.xml.

To fix this, be sure to get that node into your adventure extension topology as well.

You can alternately remove it by overwriting the Huaramarca system to remove the <OnGlobalTopologyCreated> event that causes the link to be made, but that kills the link to Huaramarca.

This only occurs if you have the nodeIDs and attributes in them that Huaramarca wants to connect to in your topology. If you are using new or alternate nodeIDs, or changing the attribute "ungoverned" in the nodes this will also prevent it.
schilcote
Militia Captain
Militia Captain
Posts: 726
Joined: Sat Feb 02, 2008 7:22 pm

Do we have to put topology in are adventures? Like, if i made a mod that used vanilla topology, but included Stephinian stuff, would I have to copy the whole topology from Transcendence.xml, or just have no topology tag? If not, why?
[schilcote] It doesn't have to be good, it just has to not be "wow is that the only thing you could think of" bad
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

You don't even need to USE the adventure extension format UNLESS you want to add a new topology or add changes to the existing one. If you are changing the existing topology you must first place the entire topology in the adventure extension, then make your changes there.

If Stephinian stuff doesn't include any <Node> changes, then just use the regular extensions format.
schilcote
Militia Captain
Militia Captain
Posts: 726
Joined: Sat Feb 02, 2008 7:22 pm

I mean in case the player wants to turn the Stephinian weapons and ships on and off, like if player wants to play the pure vanilla game without any off-balance weapons then player can, but if he wants my super-laggy weapons in the game, then he can just choose the "Stephinian Weapons" adventure, and blast off.
[schilcote] It doesn't have to be good, it just has to not be "wow is that the only thing you could think of" bad
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Weeelllll... adventure extensions require topologies.
schilcote
Militia Captain
Militia Captain
Posts: 726
Joined: Sat Feb 02, 2008 7:22 pm

Ah well. I think I'll wait untill version 1 to start with the adventure extention thing. At least publicly I think. I like to learn about something before I use it. Plus you can be sure that there are bugs.
[schilcote] It doesn't have to be good, it just has to not be "wow is that the only thing you could think of" bad
User avatar
Mutos
Militia Lieutenant
Militia Lieutenant
Posts: 218
Joined: Thu Aug 14, 2008 3:31 am
Location: Near Paris, France
Contact:

Hi all,


Tried the sample code, works fine, but when I try to insert a system between start and end, there's a problem.

Code is :

Code: Select all

<?xml version="1.0" ?>


<TranscendenceAdventure
      UNID=            "0xD4100001"
      version=         "0.99"
      >



   <AdventureDesc
          UNID=            "@1"
         name=            "Mutos test from Periculi Sample Adventure"
         backgroundID=      ""
         >
   </AdventureDesc>

   <SystemTopology>

      <Node ID="SE" rootNode="true">
         <System name="Eridani"            level="1">
            <System UNID="&ssStartonEridani;"/>
         </System>

         <StarGates>
            <StarGate Name="Outbound" DestID="NewSystem"/>
         </StarGates>
      </Node>

      <Node ID="NewSystem">
         <System name="MyNewSystem"            level="2">
            <System UNID="&ssEarthSpaceStandard;"/>
         </System>

             <StarGates>
                        <StarGate Name="Outbound" DestID="EndGame" DestGate="Inbound" />
                        <StarGate Name="Inbound" DestID="SE" DestGate="Outbound" />
             </StarGates>
      </Node>

      <Node ID="EndGame"
            endGame="true"
            endGameReason="escaped"
            epitaph="escaped the Sample Adventure"
            >
      </Node>

   </SystemTopology>

</TranscendenceAdventure>
I tried to keep it simple by just taking an existing system and inserting it with Inbound and Outbound gates. It makes a memory error when jumping out of Eridani.

I'll read more later but now got to go to work... However, a sample with a functionning 3-systems code coudl be good to see ^-^
@+

Benoît 'Mutos' ROBIN
Hoshikaze 2250 Project
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Hello there, Mutos. Welcome to the extension reference section, where you can read up on how to do things.

I am going to explain the way to fix it, as I probably caused the confusion for you with that bad bad sample.

Your <Stargate is missing a DestGate = "[gateName]".

Looks like I actually need to fix the tutorial. The Stargate element I posted shows the gate to the EndGame, and is also missing the DestGate = "gateName"

Node SE needs to be fixed like this:
<StarGate name=Outbound" DestID="NewSystem" DestGate="Inbound"/>

Node NewSystem needs to drop DestGate from outbound like this:
<StarGate Name="Outbound" DestID="EndGame" />

That pesky EndGame node doesn't have a gate, and I should have been more clear on the How-To.

Hope that helps. :)

And if not, try this:

Code: Select all

<?xml version="1.0" ?>


<TranscendenceAdventure
      UNID=            "0xD4100001"
      version=         "0.99c"
      >



   <AdventureDesc
          UNID=            "@1"
         name=            "Mutos Sample Topology"
         backgroundID=      ""
         >
   </AdventureDesc>

   <SystemTopology>

      <Node ID="SE" rootNode="true">
         <System name="Eridani"            level="1">
            <System UNID="&ssStartonEridani;"/>
         </System>

         <StarGates>
            <StarGate Name="Outbound" DestID="NewSystem" DestGate="Inbound"/>
         </StarGates>
      </Node>

      <Node ID="NewSystem">
         <System name="MyNewSystem"            level="2">
            <System UNID="&ssEarthSpaceStandard;"/>
         </System>

             <StarGates>
                        <StarGate Name="Outbound" DestID="AnotherSystem" DestGate="Inbound" />
                        <StarGate Name="Inbound" DestID="SE" DestGate="Outbound" />
             </StarGates>
      </Node>

      <Node ID="AnotherSystem">
         <System name="a Second System"            level="2">
            <System UNID="&ssEarthSpaceStandard;"/>
         </System>

             <StarGates>
                        <StarGate Name="Outbound" DestID="EndGame" />
                        <StarGate Name="Inbound" DestID="NewSystem" DestGate="Outbound" />
             </StarGates>
      </Node>

      <Node ID="EndGame"
            endGame="true"
            endGameReason="escaped"
            epitaph="Learned to make a Section of Topology!"
            >
      </Node>

   </SystemTopology>

</TranscendenceAdventure>
User avatar
Mutos
Militia Lieutenant
Militia Lieutenant
Posts: 218
Joined: Thu Aug 14, 2008 3:31 am
Location: Near Paris, France
Contact:

Hi Periculi,


Thanks for the fix, have not tested it but will asap. Didn't understand the meaning of the DestGate, indeed it's simple once you get the logic behind ^-^ But before, pfff... Now, got it ^-^

EDIT #1 : Just tested it, it works OK. I'll analyse that and try to get what to do to have a non-linear topology...

EDIT #2 : just trying to get the end gate to come back to initial system is not possible. Maybe loops are impossible...
@+

Benoît 'Mutos' ROBIN
Hoshikaze 2250 Project
User avatar
Fatboy
Militia Lieutenant
Militia Lieutenant
Posts: 247
Joined: Fri Feb 22, 2008 1:52 am
Location: California

I know your problem with your code,

Code: Select all

<Node ID="NewSystem">
         <System name="MyNewSystem"            level="2">
            <System UNID="&ssEarthSpaceStandard;"/>
         </System>

             <StarGates>
                        <StarGate Name="Outbound" DestID="EndGame" DestGate="Inbound" />
                        <StarGate Name="Inbound" DestID="SE" DestGate="Outbound" />
             </StarGates>
      </Node>


should be

Code: Select all

<Node ID="NewSystem">
         <System name="MyNewSystem"            level="2">
            <System UNID="&ssEarthSpaceStandard;"/>
         </System>

             <StarGates>
                        <StarGate Name="Outbound" DestID="EndGame" />
                        <StarGate Name="Inbound" DestID="SE" DestGate="Outbound" />
             </StarGates>
      </Node>
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Loops are very possible.

The only thing that I have found that can cause a problem for a loop is the use of [Prev] in the DestID somewhere in the loop. This is because it is possible to go a direction that the designer didn't intend, and get the wrong nodeID placed for a gate.

Imagine that this represents a loop of 4 nodes:

Code: Select all

    
   BA
SE<  >SK
   CP
Say you have the nodes SE BA CP SK, as seen above SE links to BA and CP with the little < indicating the gate links. BA links to SE and SK, you see?

If you have a gate in CP to SE that uses a [Prev], and you enter CP from SE you get the correct link made.

If you enter CP from SK, even though the gate in SE still leads to CP the gate in CP using the [Prev] turns into a second SK gate. This breaks the loop.

As for EndGame, I haven't really ever tried to place a connection to it in a node with more than 1 entry gate. It usually just resides in Heretic type systems where the game ends, rather than in the first system you encounter.

I would treat EndGame as a very special case and keep it in a similar format to it's normal game use- there is plenty to learn connecting topology nodes that are playable without worrying about the EndGame node.
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

How to make a non-linear topology, part 1:

The first thing that you will need to do is arrange a way to get more than 2 gates in a system.

Because the game systems in normal transcendence only place Inbound and Outbound gates, making a fork in the road isn't really possible without altering the systems.

You will need to arrange a method that allows you to have at least a third gate in a system.

You can create a new system to 'fork' from, or create a set of special systems to do different configurations, which is a method I have applied in the past with relative success.


George added better functions to handle this in the scripting, but you will need to learn how to use those.

Once you have created a way to go beyond the Inbound and Outbound gates, designing a non-linear topology is easy.

Just plan out your system and add as many links to the nodes as you need to accomplish the goal you have. I have put as many as 100 gates in a single node before without any problems whatsoever, and built topology systems with hundreds of nodes- so I know for a fact that Transcendence can handle any network you dream up.


Good luck, and have fun building networks!
Last edited by Periculi on Fri Sep 05, 2008 10:56 pm, edited 1 time in total.
User avatar
Mutos
Militia Lieutenant
Militia Lieutenant
Posts: 218
Joined: Thu Aug 14, 2008 3:31 am
Location: Near Paris, France
Contact:

Hi Periculi,


Thanks for the useful information, I'll tackle this asap and tell you...

EDIT #1 : wow, nice, it works well...
Last edited by Mutos on Tue Aug 26, 2008 4:35 am, edited 1 time in total.
@+

Benoît 'Mutos' ROBIN
Hoshikaze 2250 Project
User avatar
Periculi
Fleet Officer
Fleet Officer
Posts: 1282
Joined: Sat Oct 13, 2007 7:48 pm
Location: Necroposting in a forum near you

Take your time. :wink:
Post Reply