The First Step
The first cut is the deepest
-Modding Gamecraft is quite easy, once you get past the initial setup and learning. +
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 Gamecraft modding. + 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 Gamecraft modding). +
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 Gamecraft (and Steam) 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 Gamecraft.
-The latest release of GCIPA that you just downloaded is for patching Gamecraft. - GCIPA stands for Gamecraft Illusion Plugin Architecture, which is based on Eusth's IPA for patching games built on the Unity game engine (eg Gamecraft, Kerbal Space Program, Robocraft). - To get started with patching Gamecraft, unzip GCIPA's latest release directly into Gamecraft's install folder. + 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 Gamecraft onto 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 Steam updates Gamecraft)
+ (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 (NOT into Gamecraft's install location) and switch to the "no-api" branch. - If you'd like to try out the GamecraftModdingAPI you can use the "master" (default) branch, but you'll have to install the GamecraftModdingAPI as well. + 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 Gamecraft players. + 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 Gamecraft is.
-To point the Visual Studio project to the right Gamecraft dependencies, you've got two options: - copy the contents of your Gamecraft install location into a new folder called "ref" in MyFirstMod, or create a symlink to Gamecraft's main folder. - The disadvantage to the former option is that you'll have to re-copy the files everytime there's a Gamecraft update. + 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 Build > Build Solution). - In MyFirstMod's HelloModdingWorld/bin/net48 folder copy HelloModdingWorld (HelloModdingWorld.dll) into Gamecraft's new Plugins folder and your first mod is installed.
+ 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. @@ -67,14 +67,16 @@ 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 Gamecraft's Plugins folder. Now start Gamecraft. - If you open Gamecraft's Player.log file (found in something like %appdata%/../LocalLow/FreeJam/Gamecraft), you should see some wonderful spam of "Print this to log every frame". + 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 Gamecraft code and figure out what you need to modify. +
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
-
Do I wanna know
-Gamecraft modding uses a few new ideas in game development which can be quite different from common software engineering practices. +
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. @@ -95,15 +97,15 @@
Further Reading
Some of these resources have already been mentioned, but I'll mention them again to have a complete list of resources for quick reference.
-- Seba's Lab, for articles and examples about Svelto.ECS, Gamecraft's entity handler.
-- GamecraftModdingAPI, for an easier way to modify the behaviour of some parts of Gamecraft.
-- Unity Scripting API, for interfacing with Gamecraft's game engine.
-- Harmony, for patching existing methods in Gamecraft's code.
+- Seba's Lab, for articles and examples about Svelto.ECS, Techblox's entity handler.
+- TechbloxModdingAPI, for an easier way to modify the behaviour of some parts of Techblox.
+- Unity Scripting API, for interfacing with Techblox's game engine.
+- Harmony, for patching existing methods in Techblox's code.
- Eusth's Illusion Plugin Architecture (Reloaded), for injecting plugins into Unity games.
- Exmods Discord, for modding help and discussions.
- Exmods Git server, for other mods and custom tools.
-- uREPL, the command-line interface in Gamecraft.
-- Rewired, the input handling library in Gamecraft.
+- uREPL, the command-line interface in Techblox.
+- Rewired, the input handling library in Techblox.
