GitHub Integration & Automatic Mod Publishing

SporeModder FX now comes with GitHub integration. GitHub is a platform for hosting open-source software. It is based on the version control software git; it allows you to keep track of all the changes and versions you do to your files.

The recommended and default way of making mods with SporeModder FX has changed. Now, it is recommended you install git and create a GitHub account; SporeModder FX will integrate with it to let you use it easily. Hosting your mods on GitHub has several advantages:

• It lets you publish the mod with a single button. This will package all your projects, compile all your DLLs, and bundle it into a .sporemod file.
• It will make your mod automatically available in the Spore Mod Browser
• It helps the Spore modding community grow! We all can learn from what other mods do by looking at their source files and code.

The new mod structure

Before, a mod was just a .package file, which in SporeModder FX meant a folder with some subfolders and files. Now, that has changed. A mod is now a collection of two kinds of projects: typical package projects, and C++ projects. The mod folder now has this kind of structure:

My Spore Mod/
├─ .github/
├─ ├─ workflow/
├─ ├─ ├─ build.yml
├─ data/
│  ├─ Package Project 1
│  ├─ Package Project 2
├─ src/
│  ├─ Visual Studio C++ Project
├─ .gitignore
├─ ModInfo.xml
├─ README.md

These folders and files are:

• data/ contains the package projects created by SporeModder FX
• src/ is where you can store Visual Studio projects, if your mod uses C++ code.
• ModInfo.xml is a set of properties that get bundled into your mod, and that the ModAPI Launcher Kit reads.
• README.md is a Markdown file that will be shown in GitHub. You can consider it the main page for your mod.
• .gitignore is a git file that ensures no unwanted files get committed into the repository.
• .github/workflow/build.yml is a GitHub Action that automatically compiles and publishes your mod.

Setting up your GitHub account

To use the GitHub Integration / Mod Publishing feature, you need a GitHub account; if you don't have one, you can create it here. The first time you open SporeModder FX, it will ask you your GitHub username and email (we won't send you anything!); you can also get the dialog by clicking the Log in to GitHub button in the Git & Mod Publish tab:

After you set the username and email, a new window will appear with an 8-letter code. You must click on the URL, which will open GitHub on your browser, and you must paste the code there. This will authorize SporeModder FX to upload stuff to your account.

Additionally, if you want to be able to create repositories from SporeModder FX, you must add its app to your GitHub account: https://github.com/apps/sporemodder-fx

After you set the device code and return to SporeModder FX, it will configure your account so that it accepts git requests from your computer. This is done automatically by generating SSH keys (only if you didn't have them already).

Creating a new mod

Like before, you can create a new mod with the New Project button. This creates a project that will be compiled as a .package, which is the format Spore uses for its data. The window that opens lets you decide whether you want this package project to be a new mod, or to be part of an existing mod.

You must decide a name for your mod and a unique tag. This tag is a name that uniquely identifies your mod, and it is used by mod manager programs like the ModAPI Launcher Kit.

Connecting with GitHub

When you create a new mod, a git repository is created in the mod folder. git lets you keep track of all the changes you do to your files, but initially everything is local: it is only in your computer, not yet in GitHub. In the Git & Mod Publish tab you have two options:

• Create GitHub Repository: this will create a new repository in your GitHub account, and connect the local mod repository with it. To use this option, you must have added SporeModder FX to your GitHub's apps: https://github.com/apps/sporemodder-fx. This is the recommended option.
• Connect to Existing Repository: if you want to create your repository manually in GitHub, or you already had a repository, you can use this option to connect it to your local mod repository.

If you connect to an existing repository, add the spore-mod topic to it in GitHub, so the Spore Mod Browser can find your mod. Repositories created through SporeModder FX already have this.

Configuring the mod

There are two buttons for settings now:

• Project -> Project Settings decides configuration for your package project, such as the final file name.
• Git & Mod Publish -> Mod Properties is where you can change what players see of your mod: the mod name, a website, a description, etc. You can also see a list of what .package projects and .dll C++ projects will get bundled with your mod.

The mod properties are stored in a file called ModInfo.xml. If you want more advanced configuration, you can edit the file manually.

Publishing the mod

Once you have a set of changes you want to save, you can use the Git Commit button. This tells git to remember the state of the repository at this point. It means you can always go back to this state and recover the files.

Git Commit only acts on your local repository. If you want to store the changes online, in your GitHub account, use Git Sync (Push & Pull) button. There, the Push button will upload local changes to GitHub. You must commit changes first.

Finally, when you are ready to publish your mod, you can use the Publish Mod button. Be sure to commit your changes first; any changes that are not committed will not be included in the mod. The pop-up window will ask you to include a version number for your mod, such as v1.0. Tags like v0.4-beta will mark your mod as experimental, which will show a warning when users install it (you can change this behavior in Mod Properties).

Once you decide the version, click Publish. After a few minutes, a new draft will appear in your GitHub repository's Releases page. Remember: this is a draft! It is not public until you decide it. We recommend you test your mods before publicly publishing them.

Note: You can use this setup even if your mod only has C++ code. Publish Mod will skip any empty SporeModder FX package projects.