Welcome to the Modding Guide for Mudborne!

For playing with mods, you can use Steam Workshop as normal:
https://steamhost.cn/steamcommunity_com/app/2355150/workshop/

Here you can find content created and uploaded by other players to add to your game. To play the content, first browse through the workshop and see what takes your fancy!

BACK UP YOUR SAVES BEFORE USING MODS!


Once you've found something that looks fun, click on the item and then click the big 'Subscribe' button to add it to your profile.

The next time you load up the game, head to the 'Modding' menu, and you'll see any subscribed items listed.


Here you can choose which mods to 'activate', by default they'll just be downloaded but not run. Once you've selected which mods you want to be active then you can select a file and play as normal!

Playing with mods doesn't prevent you from unlocking achievements <3

If you want to remove a mod, deactivate it from the modding menu, and then quit the game and restart to unload any mod content. Removing mods with mod content still active in your save may lead to unexpected consequences!

If you get an issue when running a workshop mod, please report it to the mod creator via the workshop item page! Let them know the issue you are having, or the crash message if you are getting one.

I do not control what get's posted/created on the workshop, so it will be on all of you to collectively vote on what is good/bad/broken, and let the creators know.

If you're sharing mods you've created with your friends and don't want to upload them to Steam Workshop, or you're playing on a non-Steam platform but still want to play mods, you can install them manually.

Obviously quick stranger danger here, don't download and unzip or run files from random people!

In game, go to the Modding menu and click the "Mods Folder" button to find your local mods folder. Put the zip file in here and unzip it, calling the folder whatever you'd like, i.e. "my_friends_mod"

Restart the game, and then if it's a valid mod you'll see it in the 'Modding' menu and can activate it as mentioned above.

BEFORE MODDING BACK UP YOUR SAVES!
IF YOU DONT KNOW WHAT YOU ARE DOING YOU CAN MESS UP YOUR SAVES PERMANENTLY.

To make mods for Mudborne, you'll need a copy of the game, a code editor of your choice (I recommend VSCode[code.visualstudio.com]!), and some knowledge of Lua[www.lua.org] and LÖVE[love2d.org]!

Mudborne is built on LÖVE, which is a framework for making games written in Lua. If you're new to Lua or LÖVE then I recommend the following resources to get you started:

Learn LÖVE: https://sheepolution.com/learn
LÖVE Cookbook: https://diminim.github.io/love-cookbook/
Programming In Lua: https://www.lua.org/pil/contents.html
Lua Manual: https://www.lua.org/manual/5.4/

It's worth noting that Mudborne uses the currently unreleased LÖVE 12.0, but the wiki is for 11.0. Most stuff is the same and you can still use deprecated methods, but you can view new methods and changes here:
https://love2d.org/wiki/12.0

---

Once you're comfortable with both Lua and LÖVE, you can move onto reading through the game code! If you're on Windows you can simply right-click the .exe and open it with an unarchiving tool like you would a zip file. Inside you'll find all the goodies that make the game tick.


MacOS users can simply view the app contents and find the ".love" file in "Mudborne.app/Contents/Resources/", Linux users I don't think I need to tell you anything!

Now you can view the files you can have a nose around! There's a few readme files that will guide you around the codebase and see the mess that is every released game :p

Some locations for some common things you probably want:

• game/resources/re_locale.csv => all game text, across all languages
  
• game/resources/re_dictionary.lua => this is the game 'dictionary', all definitions and data for each item are defined here
  
• game/resources/maps => the Tiled files are here, allowing you to open the world map in Tiled and nose around
  
• game/resources/sprites => the Aseprite files and the raw spritesheet .pngs are here, allowing you to get any sprite from the game

---

When a player subscribes to a mod the game automatically downloads it to the steam workshop folder folder, however there's also a second mod folder that let's players load mods locally. Open the game, head to the Modding menu, and click the Mods Folder button to view it. This is where you can make a folder to load locally while developing your mod.


Go and download the 'Mod Template' from Github:
https://github.com/Mudborne-Modding/mod-template
(Green 'Code' button > Download ZIP)


Put that ZIP in the Modding folder, and extract it - name the folder something like "my_cool_mod", and then you can open that folder in your code editor to get cracking!

The "mod.lua" file is the base of your whole mod, and is what allows the game to communicate with whatever you've created. Each of the hooks inside the file are called by the game if you define them - you don't have to use them all if you don't need to!


Outside of the hooks show above there's no API to speak of, as you can directly call any scripts you need, make your own classes, modify existing classes etc.
You can call most of the LÖVE API too!*.
https://love2d.org/wiki/Main_Page

If you're unsure how to do something, have a look how the game does it! You can also go have a look at the example mods in the workshop or Github, which do a few different bits and bobs that might spark some ideas:

Example Function Mod
Example mod that adds an 'auto-plant' ability, planting an acorn when a tree is chopped down.
Example Frog Mod
Example mod that adds a new frog to the game, with it's own book entry and genetic code.
Example Language Mod
Example mod that adds a new language to the game.

There are three custom API methods I have included to help load files:
"mod.load(filename)" and"mod.save(data, filename)", which let you save any Lua table as a json file, and load it back later. This will save/load to the "mods/data/" folder, which is used by all mods, so be sure to name your file something unique!
There is also "mod.read(mod_id, filename)" which will read a file from your mod's folder and return the raw data back.

*Your mod code is sandboxed, meaning your code cannot call certain methods - this is for some player safety/sanity and include:

• love.event
  
• love.filesystem
  
• love.system
  
• love.thread
  
• love.touch
  
• love.video
  
• love.window

Outside of that you can go crazy!

---

If you've managed to unzip the mod template in the correct location, when you open the game you'll see your mod listed in-game on the Modding menu.


You can then mark it as active. When you load into a save you'll see the 'Hello World' from the "draw" hook drawn on the player as you walk around.


The first event that will be called is your mod's "load" function (once!), after that it'll then be any of the other events you've defined. 'load' is called before the player has picked a save file, so if you have file specific logic, wait for "game.g.game_state" to be "GAME" in step/tick/tock before doing something (see example mods above for some usage)

To make it easier to debug things I'd recommend running the game .exe from a command line/terminal with the following commands:

Windows: PATH/TO/Mudborne.exe
MacOS: PATH/TO/Mudborne.app/Contents/MacOS/love
Linux: PATH/TO/AppRun
(You can find your game files from Steam, Mudborne > Settings Cog > Properties > Installed Files > Browse)

This will then show you the normal game logs alongside anything you've added with "print()"

If you'd like to chat with other mod creators, then feel free to join the Discord[tngineers.com] - there's some dedicated channels just for modding and I'll be there also!

---

As well as looking for a "mod.lua", the game will also look for a "config.json" file at the root of your mod folder. This allows you to set the title of the mod, your own name as the author, as well as specify the path to a 16x16px ".png" image for the game to use as the icon in the Modding menu.


The "icon" key is relative to the root of your mod folder.

Once you're happy with your mod you can upload it to the Steam Workshop and make it available to other players!

First you'll need to make sure you've agreed to the Steam Workshop Legal Agreement:
https://steamhost.cn/steamcommunity_com/sharedfiles/workshoplegalagreement

Then you can download the Mudloader[github.com], a small app I've created to allow you to upload your mods to Steam - you can view all the source code on Github, and see that like Mudborne it's also made with LÖVE! Get the release for your OS from the Releases section:
https://github.com/Mudborne-Modding/mudloader/releases

Make sure you have Steam open and are logged in, then run the Mudloader! You'll be greeted with a very basic screen that looks like this:


Click 'Create New' to make a new workshop entry. Once created you'll be able to view the item on Steam with the "View Item" link. The majority of the workshop stuff is done on Steam, you can set the description, add images, tags, and edit the visibility on Steam.


The Mudloader is just for uploading the actual mod code, or setting a title/icon for the mod. Once you're ready to upload your code, click "Upload Mod" and find the folder that contains your mod.lua file! All your mod contents should be in this same folder.

Once selected the Mudloader will upload the files to Steam, only uploading what has changed. If it works, you'll be able to see that your workshop page now has a build size! You can then subscribe to your new item and check that it all works as expected in-game.

When you're happy with everything you can then set the visibility of your mod to 'Active' from the workshop page.


It'll then be visible to all other players, congratulations on your first mod! :D

The luasteam API I use for the Mudloader is pretty limited, and doesn't let me retrieve the workshop items you've created automatically. When you make a new item in the Mudloader, I store that data locally as a .json file, which you can view with the 'Edit Config' button.

If you change the name of the mod from Steam Workshop, or delete an item, those changes won't be seen by the Mudloader - but you can edit the config as needed to make sure it matches.

Each item in the config has three keys, "id", which is the id shown in the URL if you click on your workshop item, "title" which is the name of the item, and "version" which is 0 if you haven't uploaded anything yet, and 1 if you have.

While working on your mod, you probably want to turn on developer mode!

You can do this by typing "/r1bb3t" in one go - if it worked you'll see a big pink "DEV MODE ENABLED" message appear in the top-left.


While in dev mode, you can run specific commands by typing "/" followed by the command. You can also press "." to toggle the dev overlay which shows collision and general performance stats. While in this mode you can press "," to toggle the profiler - when you press it again it'll dump the contents to a "profile.txt" in your save folder.

Common Commands:
"/gimme {SPECIES}"
(spawns that frog, {SPECIES} is 'frog1', number between 1-30)

"/gimme {SPECIES}"
(spawns that mush, {SPECIES} is 'mushroom1', number between 1-24)

"/gimme {SPECIES}"
(spawns that bug, {SPECIES} is 'critter1', number between 1-21)

"/gimme {OID}"
(spawns an item, {OID} is the item oid from the dictionary - game/resources/re_dictionary)

"/world {WORLD}"
(forces you into that world, {WORLD} is either 'awake' or 'dream')

"/weather"
(toggle weather on/off)

"/time {TIME}"
(sets time to day, {TIME} can be either 'day', 'dawn', 'dusk' or 'night')

"/frogspawn {SPECIES}"
(gives you a frogspawn for that species, common green if no {SPECIES} given)

"/tadpoles {SPECIES}"
(gives you a bucket of tadpoles for that species, common green if no {SPECIES} given)

"/quest {QUEST}"
(where {QUEST} is the quest index in the book scroll panel starting from 1, marks all chapters except last as completed)

"/ghost"
(to toggle collision on/off)

"/layer {LAYER}"
(to set layer, {LAYER} is either 0 or 1, inside rooms are always layer 0)

"/tp {X} {Y}"
(teleport to an x/y position, in tiles - the whole game is 600x600 tiles)