Exmods Getting Started

The First Step

The first cut is the deepest

Modding Techblox is quite easy, once you get past the initial setup and learning. This guide was made to cover all of that in enough detail for anyone with coding experience. If you don't have experience with programming C#, I'd suggest you learn the basics before tackling Techblox modding. I've tried to make the setup as easy as possible, so that you can get straight to the interesting part: modding. But before we get started, you've got some waiting around to do; time to install some software and download some stuff.

To get the ball rolling, you'll need to download Visual Studio Community Edition, the .NET 4.8 Developper pack and GCIPA's latest release for this guide (and for Techblox modding). To any smart devs who don't use Windows; monodevelop does work, but you'll need to use .NET 4.7.* when building. The process is quite similar for every IDE, but I'll focus on VS because it's popular. You'll also need Techblox installed on your computer, unless you're magic or something. Since Visual Studio is a Microsoft product, it'll take a while to install, so while you're waiting for that to do it's thing, let's patch Techblox.

The latest release of GCIPA that you just downloaded is for patching Techblox. GCIPA stands for Gamecraft Illusion Plugin Architecture, which is based on Eusth's IPA for patching games built on the Unity game engine (eg Techblox, Kerbal Space Program, Robocraft <- EAC will stop you with that one). To get started with patching Techblox, unzip GCIPA's latest release directly into Techblox's install folder. You'll know it worked because you'll see some new files and folders, including an executable called IPA. Now for the real hackerman move: drag Techblox onto IPA. You'll know this worked because a folder called "Plugins" will be created (we'll need this later). Congratulations! Here's your certificate: (Certification of hacking that I stole off the internet). (NOTE: you'll need to re-patch the game everytime Techblox is updated)

I'm willing to bet Visual Studio is still downloading (thanks MS), so wait until that's done and then continue. Using Visual Studio, clone the HelloModdingWorld git repository into a folder. If you'll need the TechbloxModdingAPI installed as well, which you can do by following these instructions. The base branch of HelloModdingWorld provides a starter project for creating your own GCIPA-based mod (called a "plugin"). Before you make any changes, though, you'll want to create your own git repository to store your mod (unless you're that one guy in my office who dislikes open-source). Feel free to use Exmods' Git server (hosted by me!) to make your mod accessible to other modders and Techblox players. For the purpose of this guide the git repository name I'm using is "MyFirstMod". Clone your new git repository using Visual Studio, then copy the files (except the .git folder, if you can see it) from HelloModdingWorld into MyFirstMod's folder. Now you've got your first mod ready to go. It won't build though, since the project has no idea where Techblox is.

To point the Visual Studio project to the right Techblox dependencies, you've got two options: copy the contents of your Techblox install location into a new folder called "ref" in MyFirstMod, or create a symlink to Techblox's main folder. The disadvantage to the former option is that you'll have to re-copy the files everytime there's a Techblox update. This step is explained in HelloModdingWorld's README as well. No matter which you choose, if you've done everything correctly the project should now build successfully (CTRL+SHIFT+B or [top menu]Build > Build Solution). In MyFirstMod's HelloModdingWorld/bin/net48 folder copy HelloModdingWorld (HelloModdingWorld.dll) into Techblox's new Plugins folder and your first mod is installed.

Modifying Your Mod

Blood in the cut

Your mod is installed, but it doesn't do anything yet. Let's fix that. In Visual Studio, open MyPlugin.cs and take a look at it. This is the main Plugin file, which is the interface between Unity and IPA. It's very similar to a Unity MonoBehaviour, but with some sprinkles. As the first modification, let's do something simple: In the OnUpdate() method, add "Debug.Log("Print this to log every frame");" (without quotes) and then save and build the project. Once again, copy HelloModdingWorld (HelloModdingWorld.dll) into Techblox's Plugins folder. Now start Techblox. If you open Techblox's Player.log file (found in something like %appdata%/../LocalLow/FreeJam/Techblox), you should see some wonderful spam of "Print this to log every frame". You did that! You've modified your first mod!

For more advanced stuff, I'd recommend using a C# decompiler like dnSpy to read Techblox code and figure out what you need to modify. Also read about Harmony (included in the HelloModdingWorld base configuration; see HelloModdingWorld.csproj) for patching existing methods.

Gamecraft Architecture

Do I wanna know

Techblox is Gamecraft. It's also RobocraftX. This is quite obvious when you start decompiling things and you look at all of the names in the codebase. To make things easier, let's call the game Gamecraft in this section. Gamecraft modding uses a few new ideas in game development which can be quite different from common software engineering practices. The most notable paradigm shifts are the Entity Component System (ECS) and lack of documentation. To add insult to injury, code comments aren't included in C# DLLs. Please note that I won't extensively cover Gamecraft's codebase because I don't understand all of it and I don't want to get sued for "exposing trade secrets" or copyright violations. You can learn all of this yourself by searching on the Internet and by using dnSpy, so nothing in Gamecraft is really secret.

In traditional object-oriented programs, object relationships (eg One-to-many, One-to-one, Many-to-many) are stored in both objects which makes object traversal very easy. With ECS, an entity, which is similar to an object, simply describes what components it has relationships with; usually one-to-one. Those components are created and then stored in an entity database, where they can be accessed and modified. The entity itself is never really created, so there is no easy entity traversal. ECS does offer other advantages though, like performance-friendly operations on a set of components and much better dependency decoupling between objects.

In Gamecraft, a custom-desgned ECS is used called Svelto.ECS (made by FreeJam's superstar coder Seb). Gamecraft tends to use the most recent version of Svelto.ECS, or even a version newer than what is publicly available. Svelto.ECS does have some documentation (but nothing extensive) in the form of articles on Seb's website, but I find using dnSpy to read Svelto.ECS.dll to be much more helpful. Seb also has a Discord server if you have Svelto.ECS questions. Please don't bother him with non-ECS questions; Gamecraft doesn't officially support modding and we wouldn't want them to try to actively prevent it.

In between third-party code, compiled-out code comments and the lack of official modding documentation, the hardest part of modding right now is figuring out how to do what you want to do. Using a combination of dnSpy and some of the resources mentioned in Further Reading, I hope it isn't too hard for you. Either way, rest assured that modding does get easier with a bit of practice; the start of the learning curve is the steepest.

Getting Started with Modding