This page up to date for:

The template featured on this page is a work progress but you should be able to get a project started and publishing to the Thunderstore

Your First Mod

You will learn:

How to use the LCMTemplate with Publishing to setup a new plugin project
How to configure your Thunderstore publishing workflow to automatically publish when your plugin updates
How to deploy your plugin to the game folder for debugging

Prerequisites:

Visual Studio / VS Code / C# Compatible IDE
Dotnet 8 installed
Git for Windows / Git installed
A Github account
A Thunderstore Account (for publishing)
- A Thunderstore Team to publish to.
- A Thunderstore Service Account to automatically publish to your team

Table of Contents
Initialize Your Plugin Repository

Initialize Your Plugin Repository

Install the Template

Always keep in mind that dotnet templates are arbitrary code that can execute on your machine. Make sure you trust the source of any template you install!

Before installing any template, take a moment to review all the files and be certain you trust the source. Our template’s source code can be found here.

When you’re ready to install the template run the following commands in your terminal:

git clone https://github.com/LethalCompanyModding/LCM-Template-TSPublishing template
cd template
dotnet new install .

If you have an existing install of the template you may need to add –force to the end of the above command to force it to update the template.

Create the Remote Workspace

Create a new repository that will be the home of your plugin. Give it a name and description but otherwise do not use any other settings on this page. Do not create a readme and do not select a license, we will do this later.

Once you have created the new repository by clicking the [Create Repository] button and waited for github to finish working, take note of the URL in your address bar, this will be needed for creating the template in the next step.

Create the Local Workspace

Create a new folder with your project name wherever you’d like it to be on your computer and then open your terminal inside that folder. Initialize the project using the template by using the following command after substituting your own information in for the bracketed terms. Don’t worry if its a little confusing, I will describe each item and give an example below.

Template Options

ALL of these options are mandatory

ProjectGUID: This is your project's fully qualified name. It will only be used by BepinEx for the purpose of uniquely identifying your plugin in the chainloader. If you do not know how to create a unique reverse FQDN for your project then follow this format: com.github.your-user-name.repo-name. Make sure it is lower case
ProjectAUTHOR: This is the exact name of your Thunderstore Team as it appears on the Thunderstore. ~~Double~~ Triple check that this is correct.
ProjectDESC: This is a brief description of what your mod does. It should be fewer than 250 characters or publishing will fail.
ProjectURL: This is a link to your newly created Github repository from the previous step (Remember when I told you to save that address?)

Example Command:

This command will not work in powershell due to bad escaping. You should run this command via GitBash

dotnet new LCM_TS_Publishing \
 --ProjectGUID com.github.robyn.mycoolmod \
 --ProjectAUTHOR RobynLlama \
 --ProjectDESC "The coolest mod ever made" \
 --ProjectURL https://github.com/LethalCompanyModding/LCM-Template-TSPublishing

Sync Your Project’s Origin

The template actually copies the complete git history of our source files into your new project. This is a good thing because you can receive updates to the template with just a single merge request if something needs to change in the future. But, obviously, you want to be able to push your own changes to your own project. Eventually this step will be done automatically, for now, follow along with these 3 commands to remove the template as the origin and add your own, then add the template as an upstream source to fetch updates from.

Before starting, make sure you know your repo’s .git url. You can get this by going to your repo in Github and looking for a button that says “<> Code” on it. Click that to get a dropdown and then copy either the HTTP or SSH git link to use in the next command.

You will need to run these commands in GitBash on Windows

git remote remove origin
git remote add origin >Your repo .git url here<
git remote add upstream git@github.com:LethalCompanyModding/Thunderstore.git

Building and Running Your First Mod

Now that the template has been successfully installed and your project has been created, you simply use your IDE’s build task or run dotnet build in your project’s folder. This will create an artifact at ./bin/Debug/YourProjectName.dll which you may copy to your BepinEx plugins folder.

Automated Publishing with a Github Action

The template comes pre-loaded with a github action that will allow you to automatically publish a new release to the Thunderstore in response to a version tag.

Setting Up Your Publishing Key

If you already have a service account key or know how to set one up, feel free to skip this step

Log in to your Thunderstore account that owns the team that will be publishing this mod
Navigate to the Thunderstore Teams page and click on the name of the team that will be publishing this mod
On the left hand side navigation menu choose Service Accounts and then Add Service Account
Copy the key somewhere safe for now

A service account key should be treated like a password, it can be used to publish to your team and cannot be viewed again once you leave the page. Github also encrypts all secrets so it is not possible to recover it once entered.

Navigate to the settings menu for your repository on github and on the left hand navigation pane select Secrets and Variables then Actions. In this menu choose New Repository Secret and name it EXACTLY TCLI_AUTH_TOKEN then paste in your service account key as the secret and save it.

Running the Publish Action

Once ready, publishing your project is extremely simple.

First, You need to edit your project’s csproj file’s version field to be a higher number than it was before (For example: If I previously released my project at version 1.0.0 then I would consider 1.0.1 as a valid higher version).
Second, Create a new tag with the same name as the version you just set. Your IDE may have a specific way to create and push tags (For example: In VSCode press F1 and then type create tag and follow the prompts then F1 and push tags and choose origin). If your IDE does not integrate with git or you just want to do it the old fashioned way then this example will create an annotated 1.0.1 tag with the comment “Release version 1.0.1 and then push it:

git tag -a 1.0.1 -m "Release version 1.0.1"
git push origin --tags

Pushing a new tag like this will trigger the workflow to compile and upload your mod to the Thunderstore.

Troubleshooting

Type or Namespace BepinEx Could Not Be Found

In some cases your IDE may not register the types from Nuget packages immediately. Try running dotnet restore in your project’s folder and restarting your IDE.