Modding Guide

Guide to modding Brotato

Warning

Brotato modding is entirely done by the community. The mods you install and create are your own responsibility. Always backup your save files before using any mods.

To backup your saves:

• Go to %appdata% -- press WindowsKey+R, type %appdata%, hit enter
  
• Make copy of "Brotato" folder

Whenever you subscribe/unsubscribe from mods, always start a fresh run. Trying to continue an existing run after changing mods will likely cause a crash.

Troubleshooting

This guide is for modders, but if you are a player who is having trouble with mods, there is a dedicated guide to help you:

https://steamcommunity.com/sharedfiles/filedetails/?id=2937226054

Intro

Brotato version 0.8 officially adds modding and Workshop support to the game. But how do you make your own mods? This guide has you covered 😁

You will learn how to do the following:

• Install Godot (via GodotSteam)
  
• Decompile the game (with GDRETools)
  
• Run the game (in Godot)
  
• Add mod folders
  
• Add dependency mods
  
• Build your mod
  
• Publish to workshop

If you get stuck, there's lot of modders and players who can help on the Brotato Discord's modding channels: https://discord.gg/j39jE6k

1 - Install GodotSteam

Brotato uses a game engine called Godot. It feels similar to Unity but is much easier to use. You can download it from the GodotEngine[godotengine.org] website.

🚨 However: The original version of Godot doesn't have built-in Steam support, so if you try to use it, you'll get a lot of errors when you try to run Brotato. To fix this, you can download GodotSteam, which is a version of Godot with inbuilt Steam support. Download it here:

• GodotSteam (for Godot version 3.6)[github.com]
  
• Direct download[github.com] (win64-g36-s161-gs328.zip)

To run it, launch godotsteam.36.editor.windows.64.exe.

💡 Tip: If you've already installed the vanilla version of Godot, you may want to set GodotSteam as the default "Open With" handler for Godot projects. To do this: Right-click a project.godot file, choose "Open with > Choose another app", check the box marked "Always use this app", click "More apps", scroll to the bottom and click "Look for another app on this PC", then browse to the GodotSteam EXE and choose it.

2 - Decompile - A) GDRE Tools

To decompile Brotato for modding, use GDRETools, which can be downloaded here[github.com].

🚨 IMPORTANT: Do not share or host the code for Brotato anywhere. If you make a GitHub repo with a full modded project, it must be private.

1) Open GDRETools. Click RE Tools > Recover Project.



2) In the top field where it says Path, copy the path your your Brotato game folder, paste it into the long Path field, and hit Enter. This will show you the contents of your game folder. Double-click Brotato.pck.



3) A window with the title "PCK explorer" will be shown. At the bottom of this window, where it says "Destination folder", click the 3 dots.

Make a folder somewhere on your hard drive, as the location you want to export the game to (eg. "C:\Mods\Brotato\BrotatoExport"). Copy that folder's path, paste it into the Path field, and press enter, like you did in the last step. Click "Select Current Folder".



4) Click "Extract...". You'll see an extraction progress window. There will be 2 of these: One for extracting the main files, and a second one (which take longer to finish) for converting the resources.

Now you can edit the project in Godot. You can either open Godot and click the Import button to add the project to Godot's list of projects when you start it, or you can simply double-click the project.godot file to open it (if you already have Godot installed).

2 - Decompile - B) steam_data.json

Before the project will run in Godot, you need to copy the file called steam_data.json from the game's own folder, and paste it into the root folder or your Godot project:

3 - Run in Godot

Before you start modding, it's a good idea to try running the game in Godot first. This will help you fix issues that might have been caused by your project setup, before you make any actual changes.

To run the game in Godot, click the play ► button in the top-right, or press F5.

If the game launches, that's perfect! It's still a good idea to keep reading here, as it might help you later.

You don't need to export!

You won't need to export the project to test it. If something is stopping the game from running in debug mode in the editor, it means there's a bigger problem that will need to be solved. The code that handles loading mods also works differently outside of the editor, so you need to stay inside it to fully test things.

4 - Add Mod Folders

Make a folder called "mods-unpacked" in your Godot project. Add a folder for your mod called "Author-ModName" (but with your own author and mod name). Make sure both the author and the mod name have no spaces. Eg "CoolGuy-AmazingMod" is valid, but "Cool Guy's Amazing-Mod" is not. It's also recommended to only use standard English characters (A-z), as characters from other languages may cause issues with other people's filesystems.

At this point you'll need to know a bit about ModLoader, which is the tool that Brotato uses to load its mods. It has an in-depth wiki here[github.com]. Reading the pages linked from the Getting Started section on the wiki's homepage is highly recommended.

The most important pages are:

• Mod Structure[github.com]
  
• Mod Files[github.com]
  
• API Methods[github.com]

5 - Add Dependencies

The mods you make might depend on another mod, or even several. For example, ContentLoader is a utility mod that helps you add content to the game, so if you want to use it, you'll need to add its files to your project first.

To do this, just download the mod from wherever it's hosted, then add it to its own folder in the mods-unpacked directory in your project. Note that some mods may also have files you need to add to your .import directory too. Many popular Brotato mods are available on the BrotatoMods GitHub organisation[github.com].

To download a mod from GitHub, visit the mod's Github page, then click Releases from the right-hand sidebar. Click Assets to make them appear (if they don't already). Most mods will offer a pre-packaged mod zip, which you can just add to your project. For example, here's a screenshot of ContentLoader's Releases[github.com] page, with the mod zip highlighted:

6 - Building Mods - A) General

How you build your mod is up to you, but the best place to start is by looking at how vanilla's characters, weapons and items work.

These next sections will provide guides, offer some useful developer tips, and tell you how to get support for making your mods.

6 - Building Mods - B) Guides & Tutorials

Examples

There are two examples that you can refer to when creating your mod:

• Example Mod - ModLoader (detailed)[github.com]
  
• Example Mod - Brotato (simple)[github.com]

The "detailed" example has lots of comments that tell you exactly why things are being done, and is intended for people who are completely new to using Godot. The "simple" example just shows the bare minimum, and is better for modders who are already experienced with Godot, but is specific to Brotato.

Wiki Help

The wiki has a few pages that are incredibly helpful for modding. See "Wiki Pages" in the Links section at the end of this guide for an explanation of what these pages are for.

• Modding Notes[brotato.wiki.spellsandguns.com]
  
• Effects[brotato.wiki.spellsandguns.com]
  
• Vanilla Items[brotato.wiki.spellsandguns.com]

6 - Building Mods - C) DebugService

One of Brotato's most useful features for development is DebugService. You can use DebugService to edit your items, weapons, starting materials, and much more.

To use it, in the Filesystem tab, double-click debug_service.tscn. Next, in the Scene tab, click DebugService. Now in the Inspector tab, you'll see DebugService's various options.

Enabling "Disable Saving" is highly recommended, as it ensures your actual save file won't be overridden during mod development.

See this page on the Brotato wiki for details on what each option does:

https://brotato.wiki.spellsandguns.com/Modding_Notes#DebugService

6 - Building Mods - D) Fixing Errors

It's good practice to try launching the game every few minutes, to make sure nothing's broken. As you gain more practise with Godot, you'll need to do this less often.

If something doesn't work after launching the game, the game window will freeze and Godot will show you where the error occurred. For example, here's a screenshot of an issue with ContentLoader:



The Debugger panel at the bottom shows the error in red text. In this case, the error makes it clear what the problem is, but that won't always be the case. The code that's shown is also a bit misleading: The error is not occurring with the code shown (which logs an error), but is actually in another file. But you can see which file it started in, with the Stack Trace panel.

The Stack Trace panel is shown below the error message. In that screenshot, it's in the bottom-left. You can click on each file in the stack trace to view its code, and see where exactly in its code the error happened. You might need to click through a few of the files in the stack trace until you find the actual issue.

💡 Tip: It's generally a good idea to start from the bottom of the stack trace, and if it shows a file you've created, the error is probably in that file.

In this case, the error did happen in the last file in the stack trace. Here's what it looks like if you were to click that last stack trace file.



And that's perfect! It's shown us exactly what the problem is: We've used an invalid path on that line, #22, in our mod_main.gd file. Now we can fix it and get back to modding 😄

Godot Log

If something doesn't work, you can check the full Godot log file, which you'll find here:

%appdata%\Brotato\logs\godot.log

6 - Building Mods - E) Help & Support

Discord

If you're stuck, jump into the Discord and ask for help in the #modding-help channel!

https://discord.com/invite/j39jE6k

If someone is supporting you on Discord then the first thing to do is provide your mod code, either as an uploaded ZIP, or as a link to your mod item on the workshop. People who support you might ask for your godot.log file, so be sure to have it ready!

7 - Publish to Workshop - A) Notes

Before you can publish something on the Steam workshop, your account needs to have spent at least $5 USD (or €5).

7 - Publish to Workshop - B) Mod Zip

To publish your mod, first make sure your mod ZIP is ready.

Mod ZIP File

First, select your mod ZIP file. Your mod should be a ZIP file that uses the structure shown on the ModLoader wiki -- see the ModLoader wiki[github.com] for more details.

yourmod.zip
├───.import
└───mods-unpacked
    └───Author-ModName
        ├───mod_main.gd
        └───manifest.json

💡 Tip: An easy way to remember the ZIP structure is that is mirrors the structure of your project. So the root of your ZIP is the same as the root of your project.

🚨 Important: Do not include any dependencies in your mod. They are added via your item's workshop page.

Notes on .import files:

• Your mod only needs to include the .import folder if your mod has custom assets (eg. PNG files), and should only include your own mod's assets -- so nothing from vanilla should be in there.
  
• If your mod uses custom assets but you doesn't include them in your mod's .import folder, they won't be shown, so remember to add them!
  
• If you do use custom assets, it's strongly recommended that you prefix them with your mod name, eg. "amazingmod_weaponicon.png". This makes it much easier to find your custom assets from your .import folder, for when you copy them into your mod ZIP file.

Testing Before Publish

You can test your mod ZIP to see if it works by adding it to a test folder in your workshop content folder. The workshop content folder is usually this, but it depends on where you've installed Steam:

C:\Program Files (x86)\Steam\steamapps\workshop\content\1942280

To test your mod:

• Open the game's workshop folder (ie. the path shown above).
  
• You'll see your subscribed mods as numbered folder.
  
• Make a new folder, call it whatever you want.
  
• Put your mod ZIP file into that folder.
  
• Launch the game. It will run exactly as though you'd subscribed to the mod.

7 - Publish to Workshop - C) Upload

Uploader Tool

To upload mods with the uploader tool, first you need to switch to the modding branch. To do this, right-click Brotato in Steam and choose Properties, then Betas. Choose the modding branch from the listed options.



Now, when you next launch Brotato from Steam, you'll have the option to launch the uploader.



🚨 Important: You have to run the upload tool from Steam itself. Trying to run it by double-clicking the uploader EXE (GodotWorkshopUtility.exe) in the game folder will not work.

Here's what the mod uploader looks like (explanation after the screenshot...):

Mod Image

Next, select your image. The ideal size is 512 x 512px. Here's a demo image at this size, which you can use for reference (direct link here):

Workshop ID

Finally, if you've already published a mod, you can set the ID of that mod to update it. You can get the ID from the URL of your mod. For example, Blobfish's example mod has this URL:

https://steamcommunity.com/sharedfiles/filedetails/?id=2929535073

So the workshop ID for that mod is 2929535073.

After Publishing

Once you've published your mod, visit it on the Workshop to edit the description, make it visible, and add more images if you want them.

Important: Mods are set to "Hidden" by default. You will need to edit a published mod to make it publicly visible.

For gallery images, a good size to use is 637 x 358px. Here's an example image at this size, for reference (direct link is here):

Links

This section has links to more information.

Godot Documentation

You'll need to visit the docs often while you're modding.

• Docs Home[docs.godotengine.org]
  
• GDScript Basics[docs.godotengine.org]

Note that if you google documentation, you'll be taken to the docs for Godot v4, which is the latest version. But Brotato was built with Godot 3.5. To make sure you're looking at the correct page, look at the URL: if it says "/stable/", then it's 4.0, and you should replace "/stable/" in the URL with "/3.5/".

Wiki Pages

The Brotato Wiki already has a ton of info that can help you when modding:

• Notes[brotato.wiki.spellsandguns.com]
  
  • Huge page with tons of info you'll want to know about when modding.
• Effects[brotato.wiki.spellsandguns.com]
  
  • List of every effect that vanilla uses. (note: this page may be slightly out of date).
• Vanilla Items[brotato.wiki.spellsandguns.com]
  
  • Interactive grid of vanilla's items. Very useful for quickly checking vanilla's stat distribution. Includes buttons to filter by the stat they affect.

GitHub

Major orgs and repos related to modding Brotato.

• BrotatoMods - GitHub Organisation[github.com]
  
  • GitHub org for many popular Brotato mods, including mods made by Darkly77 and KANA.
    
• GodotModding - GitHub Organisation[github.com]
  
  • Hosts ModLoader itself, and has a very useful org homepage with links to extra information, including other Godot games that can be modded.
    
• ModLoader[github.com]
  
  • Repo for ModLoader. A slightly modified version of this is used by Brotato.
    
• ModLoader - Wiki[github.com]
  
  • The ModLoader wiki covers everything you'll need to know about using it.
    
• ModLoader - Example[github.com]
  
  • An example mod. Heavily commented to tell you exactly what to do when making your very first mod.
    
• Godot Workshop Utility[github.com]
  
  • Repo for the mod uploader utility that Brotato uses. Developed by Blobfish, and hosted on their own GitHub profile.
    

Misc

• Mod Migration Guide[github.com]
  
  • Guide for migrating mods that were made before v0.8, covering the things that are new, and things that will need updating in older mods.
    
• VS Code Extension: godot-tools[marketplace.visualstudio.com]
  
  • If you prefer to edit code with VS Code, this extension is essential!
    

[OrangeLuck]

thank u silver i finally fond it.

[Silver]

Hey darkly77, thanks for a great guide. If you have a moment, the links to GodotSteam are dead and should be changed to the Codeberg links. I think these are correct, but obviously verify:
https://codeberg.org/godotsteam/godotsteam/releases/tag/v3.28/
https://codeberg.org/godotsteam/godotsteam/releases/download/v3.28/win64-g36-s161-gs328.zip

Also, I'd love an IMPORTANT or WARNING note on the version. Having live links is probably enough, but it took me a while to figure out that I needed EXACTLY that link. Not even 3.6.1 was acceptable, only 3.6.

Also, a note on decompile - A) GDRE tools to select both the brotato.pck and the DLC pck to decompile them together would be a useful update. I could be wrong (brand new modder here) but I think you have to have the DLC included if you want to develop mods that use curse. It took me a while to figure out why I didn't have the DLC in my dev environment and how to add it.

[frantic]

I don't think we're getting an update for this one lads, some steps are straight up obsolete as of right now and they have been so for a long while

[继妹]

90 mins later still dont have mods, shouldnt be so hard

[Guiliam Jaeger]

看不懂 不会用啊

[Morrow]

The latest version of the game needs to be opened with GodotSteam 3.6.
Here is the download link:
https://github.com/GodotSteam/GodotSteam/releases/tag/v3.28

[OnkelStinson]

hi, can you update this guide pls and i need more explaination about where to decompile and import things

[DannDaMANN]

Brotato now uses Godot version 3.5.3. Please update guide with accurate information.

[alveolate]

not sure what i'm doing wrong... i subbed a few workshop mods but none of them are showing up in brotato mods menu? it's just an empty black square T_T

[FreeBird76]

TYVM <3<3<3