Transcendence Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
==== Beginner's Guide to Modding ==== 
**By ThePrivateer**\\ 

** 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 -- [[http://www.notepad-plus-plus.org/|I use Notepad++]]
  *A rudimentary understanding of XML -- [[http://en.wikipedia.org/wiki/XML|Wikipedia]]
  *A copy of Transcendence -- [[http://neurohack.com/downloads/Trans110.zip|The latest copy]]
  *An account on the official forums (optional, but worthwhile) -- [[http://www.neurohack.com/transcendence/forums/|The Forums]]
  *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 [[http://xelerus.de/|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++ (or your chosen editor) 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>
<ExampleOnly>
</ExampleOnly>
</code>
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>
<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
	<!ENTITY unidExtension	"0xDAFCFF00">
]>
<TranscendenceExtension UNID="&unidExtension;" version="1.0" name="MyMod" credits="Yourself">
</TranscendenceExtension>
</code>

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.
<code>
<!DOCTYPE TranscendenceExtension
[
	<!ENTITY unidExtension	"0xDAFCFF00">
]>
</code>
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>
<!ENTITY itThepMyWeapon "0xDAFC1000">
</code>

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>
<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>
</code>
This code is exactly the same as found in the Transcendence game. This isn't the right thread to explain weapons (go [[http://www.neurohack.com/transcendence/forums/viewtopic.php?t=1789|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>
damage="kinetic:10d500; momentum7"
</code>
Trans uses [[http://en.wikipedia.org/wiki/D66_%28die%29|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>
<!ENTITY itSuperWeapon   "0xDAFCFF01">
</code>
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>
UNID="&itRecoillessCannon;"
</code>\\ 
Change it to say:
<code>
UNID="&itSuperWeapon;"
</code>
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 [[http://www.neurohack.com/transcendence/forums/viewtopic.php?t=2173|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>
<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>
</code>
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>
<Device deviceID="&itSuperWeapon;"/>
</code>

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, [[http://xelerus.de/index.php?s=mod&id=847|here]]