How to learn - How to mod ITB.

Discuss and distribute tools and methods for modding.
Lemonymous
Posts: 94
Joined: Fri Mar 09, 2018 3:29 am

How to learn - How to mod ITB.

Postby Lemonymous » Mon Nov 04, 2019 11:27 pm

Do you want to mod Into the Breach (ITB), but have no idea where to start?
In this guide I will try to list everything you need to start out as an ITB modder. I will not go in-depth on how to do specific things, but instead focus on giving you tools to help you find the information you need yourself. I will also try to include as much information into this as possible, so don't feel bad you cannot consume this in one bite. Instead use it as a lookup resource.

Setting up:
  1. Make sure ITB is up to date.
  2. Find your ITB directory. If you are playing ITB under Steam, this directory can be found via Steam Library -> Right Click Into the Breach -> Properties -> Local Files -> Browse Local Files.
  3. Scroll down to Readme.md here, and follow these instructions to install the mod loader.
  4. Download these tutorial mods and place them within the mods folder inside your ITB directory.
  5. Open up your favorite internet search engine. When you don't know something, search for it. I am going to assume you have this, since you did find this page.
  6. Open up your favorite text editor. If you have none, I recommend Notepad++. It is lightweight and very easy to use.
  7. Open up your favorite drawing tool. The best tool is the one you are familiar with. If you have none, here are some of the tools used by members of the community: Paint.net, Gimp, Graphics Gale, Paint Tool SAI, Pyxel, Aseprite.
  8. Join the ITB Discord. When something is unclear, it can be useful to ask someone for help. No question is too small. Everyone who has modded ITB has asked many questions, so don't be shy.
  9. Enable the ITB debug console. The console can be opened with tilde (the key next to 1 on your keyboard). If it does not work, search the net for how to change keyboard language to one that has this key. When you have opened the console, write debug and hit enter. With Debug Mode ON, press TAB - this enables the lua console, allowing you to write and test code at runtime - more on this later.
  10. Extract the game's assets - you can find out how to unpack the assets in one of the pins in #modding-creation on the discord.
  11. You should now be set up to edit mods and eventually create your own.

Acquiring knowledge:
ITB modding is done in the coding language lua. There are many online resources with information on how to write in this language. Use your seach engine, and look up information when you are stuck, or ask questions on the discord when you can't find the information yourself.
As lua is not compiled code, the text editor will not tell you when some piece of code is written incorrectly. For this, you will need to launch ITB, open up your console, and see if the mod was successfully initialized.
When it is not, you can find information on what piece of code failed in modloader.log, located in your ITB root directory.
Sometimes code can be written correctly, but crashes the game because the logic failed. When this happens, you can often find a clue about where the error occured in error.txt, also located in your ITB root directory.

In addition to common lua syntax, ITB has many functions that does specific things in-game. A list of many of them can be found here:
To find out the signatures of these functions, you can write them into the lua console without any parameters - (or incorrect parameters) - and an error will be created telling you of all the valid signatures for that function.
Another method is to use the Find in Files function of Notepad++ to search ITB/scripts for your function. This will give you a list of all the places the base game uses this function, and will often provide you with a good example of how to use it. If it is never used, try to expand your search to other people's mods.

Sometimes you need to know the output of a function, or to know what a variable contains - for this you have the function LOG. You can feed this function just about anything, and it will try to write down it's text form content in modloader.log (found in your ITB root directory).
Not all variable types converts directly to text in LOG, so you may have to help it along a bit.

Some examples you can try:
For a Point p: LOG(p:GetString())
For an unknown variable v: LOG(tostring(v))
For a table t: LOG(save_table(t))

The mod loader adds several useful functions on top of the base game. Go here for a quick rundown of the mod loader api.

The Process:
When creating a mod, you will cycle inbetween your tools, make edits, ask questions, and test your changes in ITB. It is an iterative process, that requires a lot of trial and error.
If you need to find out how something works, write out a small bit of code in a temporary file, and paste it into the lua console - fix any errors until it works, and then use the knowledge you acquired to write better code for your mod.

Acknowledgements
kartoFlane - maintainer of the mod loader.
Tarmean - compiled the ITB function and variable list.


Let me know if anything is unclear, or if I missed something, and I will try to update this post.
tosx
Posts: 161
Joined: Wed Mar 13, 2019 3:11 am

Re: How to learn - How to mod ITB.

Postby tosx » Tue Nov 05, 2019 12:32 am

Awesome to see this, hope it encourages many more mods!

In case it's useful, here is a list of URL's I found helpful to keep handy while working on my own mods: