This guide will take us through using the best methods of saving progress, the software development workflow envisioned and supported, to publishing and maintaining a mod. It's about a half hour read.

Here's what you'll need to do the job; the software and accounts are free

• Mod Manager mod by Fluffy
  
• ModDiff mod by Krypt
  
• Visual Studio Code[code.visualstudio.com] lightweight code editor
  
• Git[git-scm.com] version control system
  
• Account on GitHub[github.com]
  
• Steam software distribution platform
  
• Account on Steam
  
• A sense of curiosity

If you're reading this, then likely you already have Steam and Rimworld installed, and an account on Steam. Getting the rest in place will probably take around 1/2 an hour. If you get it done in under 15 minutes, then extra spiffy on you.

A more in-depth tutorial on how to use the computer's software install features and create accounts on their websites is beyond the scope of this guide.

This editor has an optional built-in improvement over the process of File->Save, even better than auto-save: Always save. What you are seeing is what is stored on disk. Great tech upgrade guys.

Additional XML code completion and error checking, search in store for redhat.vscode-xml
Rimworld XML coloring mod, search in store for madeline.rwxml-lang-serv

This storage facility has an associated issues tracker for handling bugs, feature requests and other issues. Here is an example issue,[github.com] resolved over the course of a couple days. I like to think of that example as Baby's First Issue, because the blame lies outside the mod. This is definitely not the norm.

Embrace learning from failure, Padawan[i.imgur.com]
Because in this line of work you'll have your fill.
It helps to think of bugs as the garbage generated by any production process.

On most bug hunts you are the detective at a crime scene. And you can collect evidence for your wall of clues. With your detective super-power you can tag anything as a clue related to an issue. You can bring to light a trail of evidence that forms a narrative.

It's so automated that simply mentioning issue #1 is enough to generate a link, and poof: There's another entry on the detective's wall of clues.

So, can we just go right ahead and sign you up for one of our secret Nightstalker decoder rings?[en.wikiquote.org]

Our first goal is to have everything related to the mod stored in one folder, inside This will expedite testing the mod on the local machine, saving progress on GitHub and distributing the mod on Steam.

So we create a home for our new mod: ..\Mods\HelloWorld

Let's start populating our new HelloWorld mod folder. Next order of business, tell Git to treat this location as a repository. This will set up an invisible .git folder to hold git-related stuff.

In Visual Studio Code

1. File -> close current workspace
   
2. Source Control (3rd button down on the left) -> Open Folder... Mods\HelloWorld
   
3. Source Control -> Initialize Repository

Save the workspace
File -> Save workspace as... Mods\HelloWorld\Hello World.code-workspace

We now have the spark of an idea for a mod: There's a folder with something in it.

We'll gather our changes, package them up with a label describing them, and push it out to GitHub.

Staging changes involves choosing which changed files go into a Commit package. Most of the time the answer is all changed files. There's a quick select all button right here:


For the description in the text box above, "Initial commit" is a good choice.

First time pushing a commit to GitHub needs a little startup housekeeping to automatically set up the project on GitHub and link to it. Press the cloud button and select publish


From now on, we can just press Ctrl+Enter after entering the description to send a new commit to GitHub.

Next up, the About folder and it's three files that describe the mod. Below are linked examples of all three that can be copy/pasted and edited. They are commented.





About.xml example[github.com]

Manifest.xml example[github.com]

Preview.png example[i.imgur.com]




We now have the necessary file setup to qualify as a mod.
Stage a new commit with these changes, call it maybe "Skeleton framework" and push it to GitHub.

In Visual Studio Code:
In ..\About\Manifest.xml, set a new version number.
Stage a commit maybe called "Pre-Release version XXX" and push it to GitHub

Browse to https://github.com/[YOURNAME]/HelloWorld/releases and start a new release
Tag it with the version number, tick the pre-release checkbox and publish it.

After publishing the new release version on GitHub
In Rimworld, switch to developer mode and open the mods manager. Select your mod and click the author's upload button.



Go to your published items in Steam/Workshop and marvel at your handiwork.

PS: Subscribing to your own mods results in two copies of the mod existing on the local machine, so make sure you want that before subscribing.

Programming is an iterative process that's never complete. It's been said artists don't finish art, they abandon it, and that's the case with mods as well. Always another update to do, and it can be quite an addiction if you like this kind of work.

There are basically two levels of update that a developer uses:

• Session updates, day-to-day saving of progress, done at the end of each session of work
  
• Release version updates, done when some part of the project has reached a usable state

In Visual Studio Code, click Source Control tab (3rd down on the left.) Any files that are different from the latest ones on Github will be listed here under Changes. The code windows also highlight those changes in case you want to review them.


We want to mark changed files for upload, a process called staging changes.

To do this, click the "+" button, either on the Changes section divider for all files as illustrated, or on individual files for fine grained control.

This places them in the category of Staged Changes, that can be reviewed for further edits or removed from the staged changes category if desired.

Once you have a set of staged changes you're satisfied with, add a short one line text description of the work in the message box above the staged changes. Maybe something like the purpose or reason these changes were made.

This description text can contain special references to issues on github by typing # followed by the issue number. Such reference numbers get automatically noted as a comment in the associated issue(s).

After typing a description in the text box above the staged changes, press Ctrl+Enter to push the changes out to github.

A release is when we reach some point in our coding that makes it worth sharing our progress. Maybe we just finished a long collection of art icons, or finally got that compatibility patch to work. Whatever the case, we just did a session update that we want to share.

To recap from the section Hello, World/Making a Release, we do several steps in this order

1. Do the Session Update that included the changes we want to share
   
2. Do another new Session Update that just has a version number change in it (Manifest.xml)
   
3. Browse to github and create a new release using this new version number
   
4. In-game upload to Steam the current state of the mod