Tutorial: Creating your first mod - emd4600/SporeModder-FX GitHub Wiki

In this tutorial, we will create a very simple mod that changes the proton missile tool in the Space stage. We will assume you have read the "Introduction to Spore modding" tutorial, and that you have already downloaded SporeModder FX.

As we explained in the introduction, most of Spore's modding is based on modifying game files. So in order to do that, first we need to unpack all those game files. The main game files are scattered across multiple .package files so, in order to make it easier, SporeModder FX has an option to unpack them all at once, with a preset:

1. The first time you open SporeModder FX, the following dialog will appear. Check the Spore (Game & Graphics) option and click on OK. Warning: this can take several minutes (or even hours if you have a slow computer!).

2. Wait until it finishes; a dialog should appear telling you everything was unpacked successfully.

If it isn't the first time you open SporeModder FX, you can always get this dialog, clicking on File -> Unpack Presets.

SporeModder FX is organized in projects; each project is a collection of files and folders, and gets packed into a single .package. So to create our first mod, we have to create a new project:

1. Click on the menu File -> New project.
2. Type a name for your mod. Ensure the Spore (Game & Graphics) options is checked under "Sources". This allows us to see Spore's files while we are editing our project.
3. Click on OK.

The layout on SporeModder FX changes automatically when loading the project. On the left, we can see a tree view with many folders: we will call that the Project view. In the center there's an empty panel, which is where we will edit and view our files: that's the Editor view.

In the Project view, we can see not only all the files in our project, but also in the files in Spore (Game & Graphics), so that's most (although not all) of the files available in the game. If you click on a file, it will be opened in the Editor view. By default, our project is empty; to add one file to the project, we have to select it and click on the Modify button that appears on top. Files in our project appear in blue in the project view.

You will have noticed something strange in the files. There are many folders and files that don't have text names, but something like 0x0302A1C9. Let's explain that.

Spore never uses file names, it uses IDs instead. In Spore, an ID is a 32-bit integer expressed in hexadecimal. If you don't know what that means, we recommend reading online, but explained shortly: it's a way to express numbers with 16 digits instead of 10. Usually, we write numbers using digits like 0, 1, 2, …, 9; in hexadecimal, we also have A (10), B (11), C (12), D (13), E (14) and F (15). So 13 is written 0xD in hexadecimal, 16 is 0x10, etc. ; we always prefix hexadecimal numbers with 0x.

So Spore uses hexadecimal numbers of 8 digits to uniquely identify files, instead of their names. Fortunately, there is a way to convert a text string like "creature" into a (almost) unique ID: calculating its FNV hash. You don't need to understand that because SporeModder FX calculates it automatically; just be aware that when you set a file name, it is implicitly being converted into its hash (for that reason, you might hear people speaking of "hash" and "IDs" as the same thing).

Another limitation of Spore's file system is that each file is always inside one, and only one, folder. So for example, SolarSystem\starg.prop.prop_t (that is, the file starg.prop.prop_t inside the folder SolarSystem) is valid, but starg.prop.prop_t isn't (because it isn't inside a folder), and SolarSystem\Stars\starg.prop.prop_t also isn't valid (because it is inside two folders).

So actually, every file isn't only identified by its ID, but also by the ID of its folder and of its extension. We often call the combination of those three IDs a Resource key, and it is usually written as groupID!instanceID.typeID. For example, file CreatureGameVerbIcons\atk_bite.png has groupID = CreatureGameVerbIcons, instanceID = atk_bite, typeID = png.

You will also notice that there are many files with a double extension, like .prop.prop_t. Spore codifies its files in many ways, often resulting in files that cannot be read with a notepad. To fix this, SporeModder FX converts them into a readable format; the double extension is a way of telling the program it needs to convert them back. So the starg.prop.prop_t has type ID prop, because that's its original extension; SporeModder FX has converted it into a .prop_t file (which is just text) so we can read it.

At the beginning of the tutorial, we said our mod will modify the "Minor Proton Missile" tool that you get at the start of Space stage. In order to do that, we have to modify the file that defines the settings of that tool: spacetools~!protonmissilelevel1.prop (remember, that means file protonmissilelevel1.prop.prop_t (because it is converted) inside folder spacetools~).

The same file can be modified by multiple mods, but Spore only sees one of them. Let me repeat: it doesn't matter how many times a file exists, when Spore wants to access a specific file (identified by its resource key, as we discussed earlier), it gets only one file (or none if it doesn't exist). So if multiple mods modify the same file, only one of them will actually be used: in that case, we say the mods are incompatible. This is important to understand: your mod should only contain the files that are strictly necessary for it to work, because if you add files that you don't need, you might end up making other mods not work. You can check the Show only modded files in the Project view to see all the files your project has.

Anyway, let's create our mod:

1. Go to the folder spacetools~ and select the file protonmissilelevel1.prop.prop_t.
2. Click the Modify button. This will add the file into our mod and allow us to edit it.

The file you are seeing is a Property List. It is essentially a configuration file, a list of properties and their values. Each line represents a property, and has three parts: the type of the property, the name (which is also an ID) and the value. So for example:

float spaceToolDamageArea 8

This is saying "set the value of spaceToolDamageArea, which is a float property, to 8".

We want the missiles to do a lot of damage. To do that, let's find the property spaceToolMaxDamage and set it to a very high value. Do the same for spaceToolMinDamage.

That's it, that was all we had to modify to make our little mod. Now, all it remains is packing and testing it. Before that, though, we must change something in the mod settings:

1. Click in the Project Settings button.
2. Find the "Embedded package signature" option.
3. Set it to GA Patch 5.1
4. Click Apply.

This gives our modified files more priority than those in Spore. It's not necessary to do it on every mod, but in this case the tool change will not work without it. Now, let's pack the mod:

1. Click on the File -> Pack mod menu.
2. That's it! SporeModder FX generated a .package file and installed the mod. The generated package file (which you will need if you want to share the mod) is in the DataEP1 folder, wherever you installed Spore.

Aaaand that's it. We have created our first mod. If you open Spore and create a new Space game, you will be able to instantly annihilate any enemies.

If you want to publish your mod and share it to other people, there is an extra step we need to do. Nowadays, mods aren't released in their bare .package format, but inside a file called .sporemod. Here's how to create one:

1. Outside SporeModder FX (for example, in a folder where you save your mods), create a new text file and call it ModInfo.xml.
2. Open the file with a text editor, such as Notepad.
3. Copy the following contents:

<mod displayName="My Mod" unique="MyMod" description="This is the description of our brand new mod." installerSystemVersion="1.0.1.0" hasCustomInstaller="true" dllsBuild="2.5.20">
    <prerequisite game="GalacticAdventures">MyModFile.package</prerequisite>
</mod>

4. There are several fields you need to change:

• displayName: The name of your mod, which players will see.
• unique: A unique identifier for your mod, to differentiate it from other mods. This has to be unique, so for example you can prefix it with your nickname.
• description: A short description of what your mod does.
• Finally, change MyModFile.package with the name of your .package file. If you create a mod with more than one package, you can add more copies of that line.

5. Move the .package file that SporeModder FX generated into the same folder as ModInfo.xml.
6. Select the two files (the .package and ModInfo.xml) and zip them together into a .zip file, for example using 7-Zip. Mind you, you have to zip the files directly, not a folder:

7. Rename the zipped file, changing its extension to .sporemod. This is the file other players will download, so choose any name you want, as long as it has .sporemod extension.

The ModInfo.xml allows you to pack multiple packages (and .dlls, if your mod has code) into a single mod, as well as provide installation options, etc. You have more information here.

In this tutorial, we only barely scracthed the surface of how modding works. The best way to learn is to experiment yourself, and to investigate how other mods and Spore work. With SporeModder FX, you can unpack the contents of other mods clicking on the menu File -> Unpack mod (if the mod is a .sporemod file, rename it to be a .zip and unzip it to get its packages).