bigsnake
19th August 2017, 12:03 AM
As of the past few updates on the Patreon developer branch and the public beta branch (click here for info (http://steamcommunity.com/games/473770/announcements/detail/1437064718847735579)) BallisticNG has had official support for writing your own mods in C#. Right now the game officially supports writing your own gamemodes although you can basically do whatever you want (within some bounds of reason). Since there's no system in place for uploading or consuming scripts on the workshop, this thread can serve as a good hub in the meantime.
There isn't any proper documentation written yet, so hopefully the FAQ below can answer any initial questions and don't forget to check out the examples linked below. Also feel free to ask me anything if you have any questions!
There is also a channel on the game's discord server dedicated to writing scripts - check it out here (https://discord.gg/0136l5AIRn7eiT70A).
FAQ
How are mods loaded?
Mods are loaded from the UserData/Mods folder. Each subfolder in the mods folders is treated as a seperate mod. If you leave all of your .cs files in a subfolder then the game will compile the files for you and spit out a compiled DLL. Once this DLL is created, the cs files will be ignored. You can also compile your own DLL files and leave them in a subfolder, the game will loads these too.
Do you get any control over mod loading?
Right now an ini file is generated when mods are compiled which lets you change what happens when the game looks at the folder. Always Recompile will make the game always recompile the assembly when the menu loads and ignore assembly will make the game ignore the dll and not load it.
What can I use to write mods?
Anything that can edit text will be suitable, including notepad! However, it is reccomended you use one of the following; Notepad++, Sublime Text, Visual Studio Code, Atom, Visual Studio or MonoDevelop. Visual Studio or MonoDevelop are reccomended the most as they both support intelisense and can load signatures from dlls to help you out with accessing the currently not documented BnG code base.
I'm using an IDE, what DLLs should I reference?
You can find the files you want to reference in the BallisticNG_Data/Managed folder, the files you want to reference are; Assembly-CSharp.dll, BallisticModding.dll, BallisticSource.dll, BallisticUnityTools.dll, UnityEngine.dll and UnityEngine.UI.dll. You can also decompile these dll's with a tool like ILSpy to get a glimpse at a fairly accurate reconstruction of the code inside them.
How can I debug my scripts/compilations?
The ingame console will report any issues with compilations and if you enable Unity logging you can use Unity's log functions and have them show up ingame. The ingame console can be accessed by pressing Ctrl + Backspace, you can enabled Unity logging by using the command unitylog true
Getting started
This section is to quickly introduce you to how your mods are registered into the game. Mods are registered from a register class, this contains a function which is called when your mod is loaded. This is the one and only entry point to your mod, if you don't have this then your mod will not work.
A register class looks something like this:
using BallisticSource.Mods;
public class MyModRegister : ModRegister
{
public override void OnRegistered()
{
// do your stuff here
}
}
Examples
Here are some examples, I will be updating these as I go along. For the time being these are uploaded to pastebin. There is also an example gamemode available in the Modding/Scripting folder, read the readme for instructions.
Shield Customizer (https://pastebin.com/hvLubr9C) (compatible with Dev-18/08/2018-2 and above only)
Knockout Gamemode (https://pastebin.com/wV4eLfh1)
Eliminator Gamemode (https://pastebin.com/1Sjzg4dD)
Time Trial Gamemode (https://pastebin.com/e4XkUFu2)
Speedlap Gamemode (https://pastebin.com/qUw3Zb7h)
Race Gamemode (https://pastebin.com/wV4eLfh1)
There isn't any proper documentation written yet, so hopefully the FAQ below can answer any initial questions and don't forget to check out the examples linked below. Also feel free to ask me anything if you have any questions!
There is also a channel on the game's discord server dedicated to writing scripts - check it out here (https://discord.gg/0136l5AIRn7eiT70A).
FAQ
How are mods loaded?
Mods are loaded from the UserData/Mods folder. Each subfolder in the mods folders is treated as a seperate mod. If you leave all of your .cs files in a subfolder then the game will compile the files for you and spit out a compiled DLL. Once this DLL is created, the cs files will be ignored. You can also compile your own DLL files and leave them in a subfolder, the game will loads these too.
Do you get any control over mod loading?
Right now an ini file is generated when mods are compiled which lets you change what happens when the game looks at the folder. Always Recompile will make the game always recompile the assembly when the menu loads and ignore assembly will make the game ignore the dll and not load it.
What can I use to write mods?
Anything that can edit text will be suitable, including notepad! However, it is reccomended you use one of the following; Notepad++, Sublime Text, Visual Studio Code, Atom, Visual Studio or MonoDevelop. Visual Studio or MonoDevelop are reccomended the most as they both support intelisense and can load signatures from dlls to help you out with accessing the currently not documented BnG code base.
I'm using an IDE, what DLLs should I reference?
You can find the files you want to reference in the BallisticNG_Data/Managed folder, the files you want to reference are; Assembly-CSharp.dll, BallisticModding.dll, BallisticSource.dll, BallisticUnityTools.dll, UnityEngine.dll and UnityEngine.UI.dll. You can also decompile these dll's with a tool like ILSpy to get a glimpse at a fairly accurate reconstruction of the code inside them.
How can I debug my scripts/compilations?
The ingame console will report any issues with compilations and if you enable Unity logging you can use Unity's log functions and have them show up ingame. The ingame console can be accessed by pressing Ctrl + Backspace, you can enabled Unity logging by using the command unitylog true
Getting started
This section is to quickly introduce you to how your mods are registered into the game. Mods are registered from a register class, this contains a function which is called when your mod is loaded. This is the one and only entry point to your mod, if you don't have this then your mod will not work.
A register class looks something like this:
using BallisticSource.Mods;
public class MyModRegister : ModRegister
{
public override void OnRegistered()
{
// do your stuff here
}
}
Examples
Here are some examples, I will be updating these as I go along. For the time being these are uploaded to pastebin. There is also an example gamemode available in the Modding/Scripting folder, read the readme for instructions.
Shield Customizer (https://pastebin.com/hvLubr9C) (compatible with Dev-18/08/2018-2 and above only)
Knockout Gamemode (https://pastebin.com/wV4eLfh1)
Eliminator Gamemode (https://pastebin.com/1Sjzg4dD)
Time Trial Gamemode (https://pastebin.com/e4XkUFu2)
Speedlap Gamemode (https://pastebin.com/qUw3Zb7h)
Race Gamemode (https://pastebin.com/wV4eLfh1)