ThePrivateer's Beginner's Guide to Modding

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Post Reply
User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Sun Dec 19, 2010 11:59 pm

Beginner's Guide to Modding



A quick word...
Inspired by Shrike's Ten Points thread, I decided to make one thread that simply lays out basic coding skills for beginning modders. It combines everything I have learned, as a beginner myself and hopefully will help other modders gain enjoyment from this fabulous hobby.


Introduction
What you will need to mod Transcendence:
  • A good text editor with syntax highlighting -- Notepad++
    A rudimentary understanding of XML -- XML on Wikipedia
    A copy of Transcendence -- Version 1.04
    An account on this forum (optional, but worthwhile)
    A will to mod and perseverence!
Transcendence Mods
Mods in Trans (short for Transcendence) are made from XML files and are placed in an Extensions folder inside the folder where Trans is stored.
If you want to take a look at some mods, go to Xelerus, the home of Trans Mods.

To make your first mod, first create the Extensions folder where Transcendence.exe is stored (the folder may already exist, so in that case, skip this step!).

Now open up Notepad++ and save a blank .xml file into the Extensions folder. Call it "MyMod.xml".

Transcendence Tags
As previously mentioned, Trans uses .xml tags. A tag looks like this:

Code: Select all

<ExampleOnly>
</ExampleOnly>
There is an opening tag <ExampleOnly>, and a closing tag </ExampleOnly>.

So, to start making a Trans mod, you need to put the very first line of code. Open up the MyMod.xml file and type in (or copy/paste) the following lines.

Code: Select all

<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
	<!ENTITY unidExtension	"0xDAFCFF00">
]>
<TranscendenceExtension UNID="&unidExtension;" version="1.0" name="MyMod" credits="Yourself">
</TranscendenceExtension>
So what was that all about? Well,<?xml version="1.0" ?> is for the XML file itself, so that is required for all XML coding, regardless of whether it is for Transcendence or not.

<!DOCTYPE TranscendenceExtension
[
<!ENTITY unidExtension "0xDAFCFF00">
]>

This tells Trans that you are making an Extension (a mod). Making an Adventure is more complex, so I won't mention that here. For now, we'll work only with Extensions.
Between the square [] braces, lies very important stuff -- UNIDs.

Everything in Trans has a UNique IDentifier -- from little asteroids, to the sun, every weapon, station, ship, item...you name it, it has a UNID. Most of these are already pre-defined by Transcendence, but we can create our own. More on that later, though.

The <!ENTITY unidExtension "0xDAFCFF00"> defines the Identifier for the Mod itself. The Hexadecimal-styled letter/number code defines several things.
The "D" is commonly used for mods.
The "AFC" is my own code used on Xelerus and the forums -- you need to register your own to submit mods to Xelerus.
The "FF00" can be any number you want and will slowly increment as you add more stuff to the Mod; you will see that in action later.

<ENTITIES> should be unique -- so make sure that the Hexadecimal number is different each time you make a mod.
Also, when naming an entity, you may want to add your screen-name initials to it, like this:

Code: Select all

<!ENTITY itThepMyWeapon "0xDAFC1000">
Next,<TranscendenceExtension UNID="&unidExtension;" version="1.0" name="MyMod" credits="Yourself"> tells Trans what version the game is for, what it's name is and who made it.

Finally comes </TranscendenceExtension>, the closing Tag for the entire mod.

And that, my friend, is a mod. It will run, and display itself when you press F2 in-game as an installed extension.
However, it does not yet do anything...so let's fix that!

Tweaking
For this mod, we're going to 'tweak' an existing weapon to make it super powerful - the default Recoilless cannon found on the Sapphire starting ship.
Add a few lines after <TranscendenceExtension UNID="&unidExtension;" version="1.0" name="MyMod" credits="Yourself"> .
Then type the following code (or copy/paste)

Code: Select all

<ItemType UNID="&itRecoillessCannon;"
			name=				"recoilless cannon"
			level=				"1"
			value=				"300"
			mass=				"2500"
			frequency=			"uncommon"
			modifiers=			"MajorItem; NAMI"
			showReference=		"true"

			description=		"Recoilless cannons are slower than the ubiquitous laser cannon but pack a bigger punch."
			>

		<Image imageID="&rsItems1;" imageX="96" imageY="0" imageWidth="96" imageHeight="96"/>
		<Weapon
				type=				"missile"

				damage=				"kinetic:1d6+1; momentum1"
				fireRate=			"15"
				missileSpeed=		"40"
				interaction=		"80"
				lifetime=			"60"
				powerUse=			"10"

				sound=				"&snRecoillessCannon;"
				>
			<Effect>
				<Bolt
						length=				"16"
						width=				"3"
						primaryColor=		"0xcd, 0xf3, 0xff"
						secondaryColor=		"0x8f, 0xa9, 0xb2"
						/>
			</Effect>
		</Weapon>
	</ItemType>
This code is exactly the same as found in the Transcendence game. This isn't the right thread to explain weapons (go here for weapon modding). However, this will be an easy-to-see mod, and it will get you more acquainted with <Tags>.

Go to the part that says
damage="kinetic:1d6+1; momentum1"

Change that to say:

Code: Select all

damage="kinetic:10d500; momentum7"
Trans uses dice algebra to work out amounts. By changing the values, we will make a super charged kinetic weapon that deals massive damage.
Save your xml file and run Transcendence.
Start a new game, choose the Sapphire and then fire your new weapon at random ships and stations.

If done correctly, you will see your weapon is much stronger than usual.

Congratulations, you have just made your very first mod! Often referred to as God Mods, these types of mods make weapons ridiculously overpowered, armour indestructible or give the player tons of cash.

So, let's recap
Right, so you have:
  • Made a <TranscendenceExtension>
    Defined a UNID
    Tweaked a standard weapon to GodMod status
    And made it run successfully!

The Next Step
After flying around for a little bit with your new weapon, you will notice that something is a bit off.
Namely, when you encounter another ship that also uses the Recoilless Cannon, you will most likely be blasted to smithereens. Because we have modded the weapon, all ships that use the weapon receive the new super-strong weapon.

So, how do we fix that?

Well, the best and easiest way to make and control a weapon, is buy declaring it with a new UNID.

Open up MyMod.xml once more. Add a new entity as follows:

Code: Select all

<!ENTITY itSuperWeapon   "0xDAFCFF01">
There are a variety of different prefixes assigned to entities, most of which can easily be picked up from the entity you were modding in the first place.

Notice that the hexadecimal is now "0xDAFCFF01" - one more than the previous "0xDAFCFF00" UNID for the extension itself.

Now, go down to the recoilless cannon. The UNID should look like this:

Code: Select all

UNID="&itRecoillessCannon;"
Change it to say:

Code: Select all

UNID="&itSuperWeapon;"
This now stops the old &itRecoillessCannon; used in all of Transcendence from being modded.

At this stage, if you ran Transcendence, all the recoilless cannons in the gameworld would be back to their own under-powered selves.

Giving the player the weapon
The final step, to give this new weapon to the player ship itself.
Darth Saber has done a fantastic job of describing how to mod a new player ship into the game, and alter all of the things that come with that.
The link is here.
What follows is my own, very compact version of that tutorial, which, unlike Darth's, focuses instead on modding the existing Sapphire-class player ship, rather than inserting a brand new ship into the game.

Just before the closing </Transcendence Extension>,
add the following (lengthy) code snippet.

Code: Select all

<ShipClass UNID="&scSapphirePlayer;"
			manufacturer=		"Zubrin Systems"
			class=				"Sapphire"
			type=				"yacht"
			score=				"95"

			mass=				"30"
			reactorPower=		"150"
			fuelCapacity=		"37500"
			cargoSpace=			"50"
			thrust=				"150"
			rotationCount=		"40"
			maneuver=			"2"
			maxSpeed=			"20"

			maxArmor=			"6000"
			maxCargoSpace=		"150"
			maxDevices=			"8"

			leavesWreck=		"30"
			
			attributes=			""
			>

		<Armor>
			<ArmorSection start="315" span="90" armorID="&itReactiveArmor;" areaSet="0,2" />
			<ArmorSection start="225" span="90" armorID="&itReactiveArmor;" areaSet="3,4" />
			<ArmorSection start="45"  span="90" armorID="&itReactiveArmor;" areaSet="7,13" />
			<ArmorSection start="135" span="90" armorID="&itReactiveArmor;" areaSet="1,6" />
		</Armor>

		<Devices>
			<Device deviceID="&itRecoillessCannon;"/>
			<Device deviceID="&itClass1Deflector;"/>
		</Devices>

		<Items>
			<Item count="4d6" item="&itHelium3FuelRod;"/>
		</Items>

		<AISettings
			fireRateAdj=		"30"
			fireAccuracy=		"90"
			perception=			"4"
			/>

		<Image imageID="&rsSapphireYacht;" imageX="0" imageY="0" imageWidth="48" imageHeight="48"/>

		<DriveImages>
			<NozzleImage imageID="&rsDriveExhaust2;" imageX="0" imageY="0" imageWidth="48" imageHeight="48"/>
			<NozzlePos x="-28" y="-4"/>
			<NozzlePos x="-28" y="5"/>
		</DriveImages>

		<PlayerSettings
			desc=				"The versatile Sapphire yacht strikes a good balance between a gunship and a freighter."
			largeImage=			"&rsZubrinLarge;"
			initialClass=		"true"
			startingCredits=	"10d100+1000"

			startingSystem=		"SE"
			startingPos=		"Start"
			>

			<ArmorDisplay>
				<ArmorSection name="forward"
						imageID="&rsZubrinArmor;" 
						imageX="0" imageY="0" imageWidth="52" imageHeight="29"
						destX="42" destY="15" hpX="55" hpY="14"
						nameY="8" nameBreakWidth="200" nameDestX="0" nameDestY="10" />

				<ArmorSection name="starboard"
						imageID="&rsZubrinArmor;" 
						imageX="52" imageY="0" imageWidth="22" imageHeight="59"
						destX="92" destY="45" hpX="95" hpY="60"
						nameY="30" nameBreakWidth="360" nameDestX="12" nameDestY="0" />

				<ArmorSection name="port"
						imageID="&rsZubrinArmor;" 
						imageX="142" imageY="0" imageWidth="22" imageHeight="59"
						destX="22" destY="45" hpX="15" hpY="60"
						nameY="52" nameBreakWidth="200" nameDestX="0" nameDestY="8" />

				<ArmorSection name="aft"
						imageID="&rsZubrinArmor;" 
						imageX="74" imageY="0" imageWidth="68" imageHeight="14"
						destX="34" destY="103" hpX="55" hpY="105"
						nameY="74" nameBreakWidth="360" nameDestX="12" nameDestY="0" />
			</ArmorDisplay>

			<ShieldDisplay>
				<Image imageID="&rsZubrinShields;" imageX="0" imageY="0" imageWidth="136" imageHeight="136"/>
			</ShieldDisplay>

			<ReactorDisplay>
				<Image imageID="&rsZubrinReactor;" 
						imageX="0" imageY="0" imageWidth="256" imageHeight="60"/>

				<PowerLevelImage imageID="&rsZubrinReactor;"
						imageX="0" imageY="60" imageWidth="202" imageHeight="14"
						destX="54" destY="9"/>

				<FuelLevelImage imageID="&rsZubrinReactor;"
						imageX="0" imageY="74" imageWidth="194" imageHeight="14"
						destX="54" destY="37"/>

				<FuelLowLevelImage imageID="&rsZubrinReactor;"
						imageX="0" imageY="88" imageWidth="194" imageHeight="14"/>

				<ReactorText x="62" y="22" width="154" height="14"/>
				<PowerLevelText x="62" y="0" width="154" height="9"/>
				<FuelLevelText x="62" y="51" width="154" height="9"/>
			</ReactorDisplay>

		</PlayerSettings>

	</ShipClass>
That is the declaration for the Sapphire yacht, taken directly from Transcendence itself. For more information on all the working bits and pieces, I highly reccomend Darth Saber's thread (linked above), which is how I learnt how to mod ships.

However, we only want to do one thing to the sapphire - replace the existing <Device deviceID="&itRecoillessCannon;"/> tag.

The Device tag, nested inside <Devices> declares what devices the player starts out with in that ship.
Change <Device deviceID="&itRecoillessCannon;"/> to read:

Code: Select all

<Device deviceID="&itSuperWeapon;"/>
Load Transcendence and you will find that only the Sapphire yacht has the new super powered kinetic weapon.

Congratulations!
You have just:
  • Declared a new UNID
    Modded in a new weapon
    Modded the Sapphire yacht to use this weapon
That's pretty much the end of the ThePrivateer's Beginner's Guide to Modding.
It covers basic techniques to get any modder up and running. You now have the basic skills the get out and start modding up a storm.
From here on out, you will learn the most by good old trial and error. Play as many mods as possible, dissect them until you understand them, post on the forums or ask on the IRC about things you can't work out and most importantly, have fun!.



If for some reason your mod didn't work out as expected, you can download the actual mod from Xelerus, here
Last edited by ThePrivateer on Tue Jan 04, 2011 4:53 am, edited 6 times in total.

User avatar
Star Weaver
Militia Commander
Militia Commander
Posts: 311
Joined: Sun Nov 07, 2010 10:20 pm
Location: . . . between the stars and the warm black sky . . .

Mon Dec 20, 2010 3:23 am

You can actually have all mods use &unidExtension; since it's customary to invoke it once and only once right after it's defined in each mod.

Privateer: I think he means naming things like I do:

Code: Select all

<!DOCTYPE TranscendenceExtension 
	[
	<!ENTITY UNIDExtension			"0xE7F30004" >
	<!ENTITY itWvrTestNonWeapon "0xE7F30005" >
	<!ENTITY itWvrTestWeapon		"0xE7F30006" >
	<!ENTITY scWvrTestShip			"0xE7F30007" >
]>
All my stuff has Wvr in it as a sort of developer tag namespace sort of dealy.

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Mon Dec 20, 2010 3:53 am

Star Weaver wrote:You can actually have all mods use &unidExtension; since it's customary to invoke it once and only once right after it's defined in each mod.

Privateer: I think he means naming things like I do:

Code: Select all

<!DOCTYPE TranscendenceExtension 
	[
	<!ENTITY UNIDExtension			"0xE7F30004" >
	<!ENTITY itWvrTestNonWeapon "0xE7F30005" >
	<!ENTITY itWvrTestWeapon		"0xE7F30006" >
	<!ENTITY scWvrTestShip			"0xE7F30007" >
]>
All my stuff has Wvr in it as a sort of developer tag namespace sort of dealy.
Ahhhh. I get it. Thanks! ;)

[Added to the post]

User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2756
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Tue Dec 21, 2010 6:52 pm

Might I recommend that this would be something awesome to put on the wiki?
Image
Image

*** AWAY ON SABBATICAL ***
** USE EMAIL TO CONTACT ME **

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Tue Jan 04, 2011 4:54 am

The Guide is now finished.

I have posted the full xml file on Xelerus, under the Devloper's Vault sub section.

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Wed Jan 05, 2011 3:34 am

Ttech wrote:Might I recommend that this would be something awesome to put on the wiki?
Now that it's finished, that's probably a good idea.

Only problem, it's all done in BBCode, so it would take a while to copy over into Wiki-code (spelling?).

Any good community chaps willing to take up that project for me? :D

User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2756
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Wed Jan 05, 2011 7:35 pm

ThePrivateer wrote:
Ttech wrote:Might I recommend that this would be something awesome to put on the wiki?
Now that it's finished, that's probably a good idea.

Only problem, it's all done in BBCode, so it would take a while to copy over into Wiki-code (spelling?).

Any good community chaps willing to take up that project for me? :D
Which is why I suggested it right when you started, there is a converter, bbcode->wiki
Image
Image

*** AWAY ON SABBATICAL ***
** USE EMAIL TO CONTACT ME **

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Wed Jan 05, 2011 11:57 pm

Ttech wrote:
ThePrivateer wrote:
Ttech wrote:Might I recommend that this would be something awesome to put on the wiki?
Now that it's finished, that's probably a good idea.

Only problem, it's all done in BBCode, so it would take a while to copy over into Wiki-code (spelling?).

Any good community chaps willing to take up that project for me? :D
Which is why I suggested it right when you started, there is a converter, bbcode->wiki
Should I just put in a link from the Tutorials Page for now?

Or should I make it a wiki page so that others can add to it? We could create a community-pruned Beginner's Guide (as there doesn't actually seem to be any other guide like my own)

User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2756
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Thu Jan 06, 2011 2:35 am

I'd create a page on the wiki personally.
Image
Image

*** AWAY ON SABBATICAL ***
** USE EMAIL TO CONTACT ME **

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Thu Jan 06, 2011 3:38 am

Ttech wrote:I'd create a page on the wiki personally.
Hm, well I'll try and do it if I have some spare time....

edit: I added a hyperlink from the wiki to this page until I create an actual wiki page.

User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2756
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Thu Jan 06, 2011 4:42 pm

Sounds good to me.
Image
Image

*** AWAY ON SABBATICAL ***
** USE EMAIL TO CONTACT ME **

User avatar
ThePrivateer
Militia Captain
Militia Captain
Posts: 943
Joined: Tue Oct 12, 2010 5:12 am
Location: Starton Australia

Sat Jan 08, 2011 6:12 am

OK update!

There is now a wiki page here.

The Tutorials page on the Wiki now has a link to the new wiki page.

I recently got DigDug to add this thread to the forum tutorials page

I think that covers all the links! Phew! :D

User avatar
Ttech
Fleet Admiral
Fleet Admiral
Posts: 2756
Joined: Tue Nov 06, 2007 12:03 am
Location: Traveling in the TARDIS
Contact:

Sat Jan 08, 2011 6:58 pm

Yeah that should do it. I'm just happy its on the wiki. :)
Image
Image

*** AWAY ON SABBATICAL ***
** USE EMAIL TO CONTACT ME **

Post Reply