Modding 101: A Tutorial On How to Create A Playership Mod

This is a moderated forum that collects tutorials, guides, and references for creating Transcendence extensions and scripts.
Post Reply
User avatar
Darth Saber
Militia Commander
Militia Commander
Posts: 290
Joined: Mon Aug 04, 2008 4:53 pm
Location: Korriban

I was asked by digdug and bimbel to create a tutorial on how to build a playership mod. So here it is, and pardon me if it seems lengthy, but it is just about as short as I could get it:


Modding 101: A "Short" Guide To Creating A Mod
By Darth Saber
--------------------------------------------------------------------------------------
Transcendence works with two things: 1. a correctly written module (mod) in the *.xml format; and 2. image graphics: Windows bitmap (*.bmp) for bitmasks; *.bmp or *.jpeg for bitmaps. To create a *.xml of your own: Find the HighScores.xml, and open it with Notepad. Next press the "ctrl + a " key. This will highlight all of the text; then press the "backspace" or "delete" key. After that, choose the "Save As" option from the file menu and type a name. Then close both files; now you have a *.xml to place your mod in. Because it would take too much space to describe the creation of your own ship graphics, and there are various ways to do this, I will concentrate on the code part of your mod, and will be using generic Transcendence graphics.

1.) UNIDs : Open the "resource" folder in Transcendence, find the file "Transcendence.xml," and open it with "Notepad." You can do this by right-clicking the file and selecting the "edit" option. Once the file is open, click "edit" on the menu, select "find" and type: "UNID." Scroll down and read the information on that topic down to PLAYER SHIP EXTRA DATA. The UNID is the key identifier of your mod; in order to create a mod, you will need to create a separate UNID for each entity of your mod.

2.) Now we will look at the code of a mod, and I will place my comments in {brackets}.
--------------------------------------------------------------------------------------
This is the original code of the Wind Slaver as found in the "SungSlavers.xml" of the resource folder:
--------------------------------------------------------------------------------------
<?xml version="1.0" ?> {This tells the game the version of the xml. Leave this unchanged}
<!DOCTYPE TranscendenceExtension {Tells Transcendence that this file is meant for it. Leave this unchanged.}
[ { "[" and "]>" are opening and closing tags}
<!ENTITY scWindSlaver "0x00193002"> {This is the original UNID for the Wind Slaver}
]>

<TranscendenceExtension UNID="0x00193002" version="0.99c">
{You must declare what version your mod was built for.}

<!-- Slaver, Wind --> {The Title of the Ship; this is optional, but helps in keeping the idea of the mod clear"

<ShipClass UNID="&scWindSlaver;" {This tells the game that the information following it what the ship is, and its specifications.}
manufacturer= "" {If you want to have your own shipyard, simply type the name in here}
class= "Wind slaver" {Like a car you have the manufacturer, the model (class), and the type of vehicle it is)
type= ""
score= "320" {Your ship's base score; the points you earn in the game are added to this.}
techOrder= "mech" {Is your ship mechanical (mech) or can you interface with it like a Borg? (biomechanical)}

mass= "50" {How heavy is your ship; the heavier the ship, the harder to turn and the more power it takes to get moving.}
cargoSpace= "10" {How much stuff do you want to haul; this is by weight.}
thrust= "400" {How much energy it takes for your ship to get moving.}
maneuver= "1" {How quick do you want your ship to turn? Too low a number = a ship harder to control.}
maxSpeed= "30" {What do you want your ship's top speed to be? Remember, the faster it is, the more uncontrollable it may become.}

cyberDefenseLevel= "4" {Starships use computers to track and destroy enemies; what level of programming do you want you ship to have?}

leavesWreck= "35" {How fast do you want to be able to leave a wreck which you have just looted?}

attributes= "genericClass, sungSlavers" {These attributes are generally not used in player ships}
> {Closing tag}

<Armor> {Opening tag - tells the game that what follows, is the type of armor the ship has, and where it's at on the ship.}
<ArmorSection start="315" span="90" armorID="&itHeavyCeramicPlate;" areaSet="0,2" />
<ArmorSection start="225" span="90" armorID="&itHeavyCeramicPlate;" areaSet="3,4" />
<ArmorSection start="135" span="90" armorID="&itHeavyCeramicPlate;" areaSet="1,6" />
<ArmorSection start="45" span="90" armorID="&itHeavyCeramicPlate;" areaSet="7,13" />
</Armor> {Closing tag - tells the game that the armor block is finished.}

{Note: a list of armors can be found in the "resource" folder, in the file: "StdArmor.xml." Choose wisely; not all armor is equal.}

<Devices> {Opening tag - telling the game that what follows are the devices which are pre-installed on the ship; ready when you start the game.}
<Device deviceID="&itNeutronBlaster;"/> {A list of weapons can be found in the "StdWeapons.xml" file of the "resource" folder.}
</Devices> {Closing tag - device block is finished}

<Image imageID="&rsMediumShips1;" imageX="480" imageY="0" imageWidth="48" imageHeight="48" imageFrameCount="0" imageTicksPerFrame="0"/>
{The above file tells Transcendence which graphics to use for this ship.}

<AISettings {Artificial intelligence settings block}
fireRateAdj= "20" {These first three are self explanitory. "Perception" is how far the ship can see; higher number = further distance.}
fireRangeAdj= "50"
fireAccuracy= "90"
perception= "4"
/> {Closing tag}

<DriveImages> {This block tells Transcendence where to put the exhaust flameswhich come out of the back of some of the ships, not all ships have this.}
<NozzleImage imageID="&rsDriveExhaust;" imageX="48" imageY="0" imageWidth="48" imageHeight="48" imageFrameCount="0" imageTicksPerFrame="0"/>
<NozzlePos x="-30" y="-4"/>
<NozzlePos x="-30" y="5"/>
</DriveImages> {Closing tag}

</ShipClass> {Closing tag}

</TranscendenceExtension> {This is the ultimate closing tag; it tells the game that the mod is finished / finished loading.}
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
This above was the Transcendence code of the Wind Slaver. To make it playable, more code is needed:. Here is an example of one which I built.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
<!ENTITY unidExtension "0xD1024060"> {This is needed for player ships to aviod confusion in loading the mod.}
<!ENTITY scPlayerWindSlaver "0xD1024061"> {This is my version's ship UNID.}
<!ENTITY rsWolfenArmor "0x0000F00B"> {The armor graphics that I am using.}
]>

<TranscendenceExtension UNID="0xD1024060" version="0.99c">

<!-- Playable Wind Slaver-->

<ShipClass UNID="&scPlayerWindSlaver;"
manufacturer= "Sung Shipyards"
class= "Wind Slaver"
type= ""
score= "320"
techOrder= "mech"

mass= "50"
reactorPower= "5000"
fuelCapacity= "50000"
cargoSpace= "1000"
thrust= "400"
maneuver= "1"
maxSpeed= "30"
maxDevices= "15"
maxCargoSpace= "60000"
cyberDefenseLevel= "6"

leavesWreck= "35"
>

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

<Devices>
<Device deviceID="&itNeutronBlaster;"/>
<Device deviceID="&itClass3Deflector;"/>
</Devices>

<Image imageID="&rsMediumShips1;" imageX="480" imageY="0" imageWidth="48" imageHeight="48" imageFrameCount="0" imageTicksPerFrame="0"/>

<Items>
<Item count="1" item="&itTargetingComputerROM;"/>
<Item count="1" item="&itWeaponSpeedROM;"/>
<Item count="1" item="&itEnhanceSRSROM;"/>
<Item count="10" item="&itDeconGel;"/>
</Items>


<AISettings
fireRateAdj= "10"
fireRangeAdj= "50"
fireAccuracy= "90"
perception= "20"
/>

<PlayerSettings {This block lets the game know that this ship is controllable by the player.}
desc= "This Wind Slaver is an example of a playership mod."
startingCredits= "3000000" {Starting cash}
initialClass= "true">

<ArmorDisplay> {This tells how the armor is displayed.}
<ArmorSection name="forward" imageID="&rsWolfenArmor;" imageX="0" imageY="0" imageWidth="90" imageHeight="9" destX="23" destY="32" hpX="55" hpY="27" nameY="8" nameBreakWidth="360" nameDestX="12" nameDestY="0"/>
<ArmorSection name="starboard" imageID="&rsWolfenArmor;" imageX="90" imageY="0" imageWidth="9" imageHeight="56" destX="104" destY="41" hpX="98" hpY="60" nameY="30" nameBreakWidth="275" nameDestX="0" nameDestY="8"/>
<ArmorSection name="aft" imageID="&rsWolfenArmor;" imageX="99" imageY="0" imageWidth="90" imageHeight="9" destX="23" destY="97" hpX="55" hpY="97" nameY="74" nameBreakWidth="200" nameDestX="0" nameDestY="8"/>
<ArmorSection name="port" imageID="&rsWolfenArmor;" imageX="189" imageY="0" imageWidth="9" imageHeight="56" destX="23" destY="41" hpX="12" hpY="60" nameY="52" nameBreakWidth="200" nameDestX="0" nameDestY="8"/>
</ArmorDisplay>

<ShieldDisplay>
<Image imageID="&rsZubrinShields;" imageX="0" imageY="0" imageWidth="136" imageHeight="136"/> {Generic shield display; use this when using trans graphics.}
</ShieldDisplay>

{Below is the reactor display block, which is viewed in the upper left hand corner of the screen during gameplay.}

<ReactorDisplay> {Opening tag}
<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> {Closing tag}

</PlayerSettings>

</ShipClass>

</TranscendenceExtension>
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
If you were to copy this code into the xml file you created earlier, minus my comments, the ship would be playable right now; I know this because I just tried it myself.
As a beginning modder, I learned by asking questions, following advice, asking more questions, and by looking at the codes and functions of the mods which others have posted. People learn in different ways, and I hope that I have helped to point you in the right direction. As a final piece of advice, I would have you visit http://xelerus.de and download / print their function list. This list contains many of the codes and functions used in Transcendence. If you need further help, register as a member of the Transcendence Community and ask post your needs / questions / problems, and we will help you gladly. - Darth Saber
george moromisato
Developer
Developer
Posts: 2997
Joined: Thu Jul 24, 2003 9:53 pm
Contact:

Very cool! It's great to have these kinds of tutorials.

Here is some more additional info on some of the attributes. Hope it helps:

score= is the number of points that you gain if you kill this ship class. This is ignored for player ships (unless the player happens to meet and kill another player ship class)

techOrder= is currently ignored.

thrust= is the thrust of the default drive. Higher numbers mean that the ship accelerates faster. If you later install a drive upgrade, then the upgrade's thrust will be added to this.

cyberDefenseLevel= This determines the ship's defenses against cyber attack (e.g., Sung shields down attack). The higher the number, the greater the defense.

leavesWreck= This is the percent chance that killing this ship class will leave a wreck.

<AISettings> element is only used by AI ships (it is ignored for player ships).

Nice work on the tutorial.
User avatar
digdug
Fleet Admiral
Fleet Admiral
Posts: 2620
Joined: Mon Oct 29, 2007 9:23 pm
Location: Decoding hieroglyphics on Tan-Ru-Dorem

Good job Darth Saber! :D
Moved to Extension Reference and added to the Tutorial Sticky list.
User avatar
Darth Saber
Militia Commander
Militia Commander
Posts: 290
Joined: Mon Aug 04, 2008 4:53 pm
Location: Korriban

Thank you both so much. I have not been modding for very long in comparison to those such as dvlenk6, digdug, -etc. so I felt that I was not exactly qualified to "teach," so I am grateful that you liked the tutorial. George: thank you for psting about the elements of code; I wrote about them based on what I could observe in creating mods. Thank you for clarifying these for me. :D
IceMephit
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu Oct 22, 2009 4:46 pm
Location: Maine

<?xml version="1.0" ?>
<!DOCTYPE TranscendenceExtension
[
<!ENTITY unidExtension "0xD1024060">
<!ENTITY scPlayerWindSlaver "0xD1024061">
<!ENTITY rsWolfenArmor "0x0000F00B">
]>

How do you come up with these 3 unid? The other modded ships all have different numbers?
This is my first ship and everything else was fairly simple to follow.

Thanx
For Sale: One slightly used EI500 freighter. Hull damaged, primary weapon defective, shields inoperable. Must be towed to Dry-dock. Make an offer!!
User avatar
Aeonic
Militia Commander
Militia Commander
Posts: 469
Joined: Sun Jun 14, 2009 1:05 am
Location: Designing his dream ship.

Every object in the game needs to have a unique ID value, so...

Every modder needs to register their own ID in the database, which there is a post for around here. You register the first four numbers, for example, mine is:

EE24

Which leaves the remaining four numbers to assign for individual mods. So perhaps I have a custom playership I want to use the values:

0030 through 003F

(they're in hex, by the way)

Then I would create my mod and assign values starting with:

0xEE240030 and continue down the line, like this:

Code: Select all

<!DOCTYPE TranscendenceExtension
[
<!ENTITY idShip					"0xEE240030">
<!ENTITY scShipClass			"0xEE240031">
<!ENTITY rsShipImage			"0xEE240032">
<!ENTITY rsShipLarge			"0xEE240033">
<!ENTITY rsShieldsImage		"0xEE240034">
<!ENTITY rsArmorImage			"0xEE240035">
]>
Last Cause Of Death: Destroyed by Karl Svalbard's last Lucifer missile, right after I blew him up. And the crowd cheers.
Image
IceMephit
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu Oct 22, 2009 4:46 pm
Location: Maine

Awesome. Thanx for the info. With y'alls help, i may just be able to make a ship. yeehaw!!!!!!!
For Sale: One slightly used EI500 freighter. Hull damaged, primary weapon defective, shields inoperable. Must be towed to Dry-dock. Make an offer!!
User avatar
Darth Saber
Militia Commander
Militia Commander
Posts: 290
Joined: Mon Aug 04, 2008 4:53 pm
Location: Korriban

Thank you for using my tutorials IceMephit; it is nice to know that they are still useful. Aeonic, thank you for helping him out, you did a fine job of instructing him. If you both need anything, let me know.

IceMephit, is your username pronounced: "Ice - Me - Fit," or "Ice - Mephit?" My curiosity comes from my being a descendant of the Egyptian Pharoh Sety I; "Mephit" is an Egyptian sounding name, which is why I ask.
IceMephit
Militia Lieutenant
Militia Lieutenant
Posts: 124
Joined: Thu Oct 22, 2009 4:46 pm
Location: Maine

Its technically Ice Mephit. Mephit being an extraplanar imp, this one in particular native to cold and ice.

Also, if it wasn't for your tutorial and others, I could not have done a mod at all. Now, I just need to learn to use gMax or something to make my own graphics :)
For Sale: One slightly used EI500 freighter. Hull damaged, primary weapon defective, shields inoperable. Must be towed to Dry-dock. Make an offer!!
User avatar
Aury
Fleet Admiral
Fleet Admiral
Posts: 5421
Joined: Tue Feb 05, 2008 1:10 am
Location: Somewhere in the Frontier on a Hycrotan station, working on new ships.

@IceMephit-
I can help you with that (learning gmax)

@Darthsaber- nice tutorial! I would suggest using

Code: Select all

Code Tags
to help make the xml parts stand out better.
(shpOrder gPlayership 'barrelRoll)
(plySetGenome gPlayer (list 'Varalyn 'nonBinary))
Homelab Servers: Xeon Silver 4110, 16GB | Via Quadcore C4650, 16GB | Athlon 200GE, 8GB | i7 7800X, 32GB | Threadripper 1950X, 32GB | Atom x5 8350, 4GB | Opteron 8174, 16GB | Xeon E5 2620 v3, 8GB | 2x Xeon Silver 4116, 96GB, 2x 1080ti | i7 8700, 32GB, 6500XT
Workstations & Render machines: Threadripper 3990X, 128GB, 6900XT | Threadripper 2990WX, 32GB, 1080ti | Xeon Platinum 8173M, 48GB, 1070ti | R9 3900X, 16GB, Vega64 | 2x E5 2430L v2, 24GB, 970 | R7 3700X, 32GB, A6000
Gaming Systems: R9 5950X, 32GB, 6700XT
Office Systems: Xeon 5318Y, 256GB, A4000
Misc Systems: R5 3500U, 20GB | R5 2400G, 16GB | i5 7640X, 16GB, Vega56 | E5 2620, 8GB, R5 260 | P4 1.8ghz, 0.75GB, Voodoo 5 5500 | Athlon 64 x2 4400+, 1.5GB, FX 5800 Ultra | Pentium D 3.2ghz, 4GB, 7600gt | Celeron g460, 8GB, 730gt | 2x Athlon FX 74, 8GB, 8800gts 512 | FX 9590, 16GB, R9 295x2 | E350, 8GB | Phenom X4 2.6ghz, 16GB, 8800gt | random core2 duo/atom/i5/i7 laptops
User avatar
Darth Saber
Militia Commander
Militia Commander
Posts: 290
Joined: Mon Aug 04, 2008 4:53 pm
Location: Korriban

Thanks, Wolfy; I see what I can do, when life slows down a little bit.

I would be grateful if you would teach me about GMax as well.
User avatar
Aury
Fleet Admiral
Fleet Admiral
Posts: 5421
Joined: Tue Feb 05, 2008 1:10 am
Location: Somewhere in the Frontier on a Hycrotan station, working on new ships.

I'm currently working on that tutorial.
(shpOrder gPlayership 'barrelRoll)
(plySetGenome gPlayer (list 'Varalyn 'nonBinary))
Homelab Servers: Xeon Silver 4110, 16GB | Via Quadcore C4650, 16GB | Athlon 200GE, 8GB | i7 7800X, 32GB | Threadripper 1950X, 32GB | Atom x5 8350, 4GB | Opteron 8174, 16GB | Xeon E5 2620 v3, 8GB | 2x Xeon Silver 4116, 96GB, 2x 1080ti | i7 8700, 32GB, 6500XT
Workstations & Render machines: Threadripper 3990X, 128GB, 6900XT | Threadripper 2990WX, 32GB, 1080ti | Xeon Platinum 8173M, 48GB, 1070ti | R9 3900X, 16GB, Vega64 | 2x E5 2430L v2, 24GB, 970 | R7 3700X, 32GB, A6000
Gaming Systems: R9 5950X, 32GB, 6700XT
Office Systems: Xeon 5318Y, 256GB, A4000
Misc Systems: R5 3500U, 20GB | R5 2400G, 16GB | i5 7640X, 16GB, Vega56 | E5 2620, 8GB, R5 260 | P4 1.8ghz, 0.75GB, Voodoo 5 5500 | Athlon 64 x2 4400+, 1.5GB, FX 5800 Ultra | Pentium D 3.2ghz, 4GB, 7600gt | Celeron g460, 8GB, 730gt | 2x Athlon FX 74, 8GB, 8800gts 512 | FX 9590, 16GB, R9 295x2 | E350, 8GB | Phenom X4 2.6ghz, 16GB, 8800gt | random core2 duo/atom/i5/i7 laptops
Post Reply