|
|
|
@@ -9,12 +9,12 @@ |
|
|
|
<meta name="og:title" content="Exmods" /> |
|
|
|
<meta name="og:description" content="Gamecraft modding website" /> |
|
|
|
<meta name="description" content="Gamecraft modding website" /> |
|
|
|
<meta name="og:image" content="/static/favicon.png" /> |
|
|
|
<meta name="og:image" content="../static/favicon.png" /> |
|
|
|
<meta name="og:url" content="https://www.exmods.org" /> |
|
|
|
<meta charset="UTF-8" /> |
|
|
|
<link rel="icon" href="/static/favicon.png" type="image/x-icon"/> |
|
|
|
<link rel="shortcut icon" href="/static/favicon.png" type="image/x-icon"/> |
|
|
|
<link rel="stylesheet" href="/static/style.css" type="text/css" /> |
|
|
|
<link rel="icon" href="../static/favicon.png" type="image/x-icon"/> |
|
|
|
<link rel="shortcut icon" href="../static/favicon.png" type="image/x-icon"/> |
|
|
|
<link rel="stylesheet" href="../static/style.css" type="text/css" /> |
|
|
|
<title>Exmods Getting Started</title> |
|
|
|
</head> |
|
|
|
<body> |
|
|
|
@@ -23,85 +23,90 @@ |
|
|
|
<div> |
|
|
|
<iframe width="850" height="480" sandbox="allow-same-origin allow-scripts" src="https://peertube.co.uk/videos/embed/b41abd31-fa16-42c8-be37-df10072c1c29?title=0&warningTitle=0" frameborder="0" allowfullscreen class="iframe-player"></iframe> |
|
|
|
</div> |
|
|
|
<h3>The First Step</h3> |
|
|
|
<h5>The first cut is the deepest</h5> |
|
|
|
<p>Modding Gamecraft 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. |
|
|
|
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.</p> |
|
|
|
<p>To get the ball rolling, you'll need to download <a href="https://visualstudio.microsoft.com/vs/community/">Visual Studio Community Edition</a>, the <a href="https://dotnet.microsoft.com/download/dotnet-framework/net48">.NET 4.8 Developper pack</a> and <a href="https://git.exmods.org/modtainers/GCIPA/releases">GCIPA's latest release</a> for this guide (and for Gamecraft modding). |
|
|
|
To any smart devs who don't use Windows; <a href="https://www.monodevelop.com/">monodevelop</a> 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.</p> |
|
|
|
<p>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 <a href="https://github.com/Eusth/IPA">IPA</a> 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 <b>directly</b> into Gamecraft'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. |
|
|
|
You'll know this worked because a folder called "Plugins" will be created (we'll need this later). |
|
|
|
Congratulations! Here's your certificate: <a href="http://pre06.deviantart.net/23ca/th/pre/f/2016/306/0/9/hackerman_by_shiiftyshift-dan31sc.png">(Certification of hacking that I stole off the internet)</a>. |
|
|
|
(NOTE: you'll need to re-patch the game everytime Steam updates Gamecraft)</p> |
|
|
|
<p>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 <a href="https://git.exmods.org/modtainers/HelloModdingWorld">HelloModdingWorld git repository</a> into a folder (NOT into Gamecraft's install location) and switch to the "no-api" branch. |
|
|
|
If you'd like to try out the <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI">GamecraftModdingAPI</a> you can use the "master" (default) branch, but you'll have to <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI/src/branch/master/README.md#installation">install the GamecraftModdingAPI</a> as well. |
|
|
|
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 <a href="https://git.exmods.org/">Exmods' Git server</a> (hosted by me!) to make your mod accessible to other modders and Gamecraft 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.</p> |
|
|
|
<p>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 <a href="https://www.howtogeek.com/howto/16226/complete-guide-to-symbolic-links-symlinks-on-windows-or-linux/">create a symlink to Gamecraft's main folder</a>. |
|
|
|
The disadvantage to the former option is that you'll have to re-copy the files everytime there's a Gamecraft update. |
|
|
|
This step is explained in HelloModdingWorld's <a href="https://git.exmods.org/modtainers/HelloModdingWorld/src/branch/no-api/README.md">README</a> 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.</p> |
|
|
|
<h3>Modifying Your Mod</h3> |
|
|
|
<h5>Blood in the cut</h5> |
|
|
|
<p>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 <a href="https://git.exmods.org/modtainers/GCIPA">Plugin</a> file, which is the interface between Unity and IPA. |
|
|
|
It's very similar to a <a href="https://docs.unity3d.com/ScriptReference/MonoBehaviour.html">Unity MonoBehaviour</a>, 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". |
|
|
|
You did that! You've modified your first mod!</p> |
|
|
|
<p>For more advanced stuff, I'd recommend using a C# decompiler like <a href="https://github.com/0xd4d/dnSpy/releases">dnSpy</a> to read Gamecraft code and figure out what you need to modify. |
|
|
|
Also read about <a href="https://github.com/pardeike/Harmony/wiki">Harmony</a> (included in the HelloModdingWorld base configuration; see HelloModdingWorld.csproj) for patching existing methods.</p> |
|
|
|
<h3>Gamecraft Architecture<h3> |
|
|
|
<h5>Do I wanna know</h5> |
|
|
|
<p>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 <a href="https://en.wikipedia.org/wiki/Entity_component_system">Entity Component System (ECS)</a> 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.</p> |
|
|
|
<p>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.</p> |
|
|
|
<p>In Gamecraft, a custom-desgned ECS is used called <a href="https://github.com/sebas77/Svelto.ECS">Svelto.ECS</a> (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 <a href="http://www.sebaslab.com/">Seb's website</a>, 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.</p> |
|
|
|
<p>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.</p> |
|
|
|
<h3>Further Reading</h3> |
|
|
|
<h5></h5> |
|
|
|
<p>Some of these resources have already been mentioned, but I'll mention them again to have a complete list of resources for quick reference.</p> |
|
|
|
<p>- <a href="http://www.sebaslab.com/">Seba's Lab</a>, for articles and examples about Svelto.ECS, Gamecraft's entity handler.</p> |
|
|
|
<p>- <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI">GamecraftModdingAPI</a>, for an easier way to modify the behaviour of some parts of Gamecraft.</p> |
|
|
|
<p>- <a href="https://docs.unity3d.com/ScriptReference/">Unity Scripting API</a>, for interfacing with Gamecraft's game engine.</p> |
|
|
|
<p>- <a href="https://github.com/pardeike/Harmony/wiki">Harmony</a>, for patching existing methods in Gamecraft's code.</p> |
|
|
|
<p>- <a href="https://github.com/Eusth/IPA">Eusth's Illusion Plugin Architecture (Reloaded)</a>, for injecting plugins into Unity games.</p> |
|
|
|
<p>- <a href="https://discord.gg/xjnFxQV">Exmods Discord</a>, for modding help and discussions.</p> |
|
|
|
<p>- <a href="https://git.exmods.org">Exmods Git server</a>, for other mods and custom tools.</p> |
|
|
|
<p>- <a href="https://github.com/hecomi/uREPL">uREPL</a>, the command-line interface in Gamecraft.</p> |
|
|
|
<p>- <a href="https://assetstore.unity.com/packages/tools/utilities/rewired-21676">Rewired</a>, the input handling library in Gamecraft.</p> |
|
|
|
<div class="text-content"> |
|
|
|
<h3>The First Step</h3> |
|
|
|
<h5>The first cut is the deepest</h5> |
|
|
|
<p>Modding Gamecraft 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. |
|
|
|
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.</p> |
|
|
|
<p>To get the ball rolling, you'll need to download <a href="https://visualstudio.microsoft.com/vs/community/">Visual Studio Community Edition</a>, the <a href="https://dotnet.microsoft.com/download/dotnet-framework/net48">.NET 4.8 Developper pack</a> and <a href="https://git.exmods.org/modtainers/GCIPA/releases">GCIPA's latest release</a> for this guide (and for Gamecraft modding). |
|
|
|
To any smart devs who don't use Windows; <a href="https://www.monodevelop.com/">monodevelop</a> 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.</p> |
|
|
|
<p>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 <a href="https://github.com/Eusth/IPA">IPA</a> 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 <b>directly</b> into Gamecraft'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. |
|
|
|
You'll know this worked because a folder called "Plugins" will be created (we'll need this later). |
|
|
|
Congratulations! Here's your certificate: <a href="http://pre06.deviantart.net/23ca/th/pre/f/2016/306/0/9/hackerman_by_shiiftyshift-dan31sc.png">(Certification of hacking that I stole off the internet)</a>. |
|
|
|
(NOTE: you'll need to re-patch the game everytime Steam updates Gamecraft)</p> |
|
|
|
<p>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 <a href="https://git.exmods.org/modtainers/HelloModdingWorld">HelloModdingWorld git repository</a> into a folder (NOT into Gamecraft's install location) and switch to the "no-api" branch. |
|
|
|
If you'd like to try out the <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI">GamecraftModdingAPI</a> you can use the "master" (default) branch, but you'll have to <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI/src/branch/master/README.md#installation">install the GamecraftModdingAPI</a> as well. |
|
|
|
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 <a href="https://git.exmods.org/">Exmods' Git server</a> (hosted by me!) to make your mod accessible to other modders and Gamecraft 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.</p> |
|
|
|
<p>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 <a href="https://www.howtogeek.com/howto/16226/complete-guide-to-symbolic-links-symlinks-on-windows-or-linux/">create a symlink to Gamecraft's main folder</a>. |
|
|
|
The disadvantage to the former option is that you'll have to re-copy the files everytime there's a Gamecraft update. |
|
|
|
This step is explained in HelloModdingWorld's <a href="https://git.exmods.org/modtainers/HelloModdingWorld/src/branch/no-api/README.md">README</a> 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.</p> |
|
|
|
<h3>Modifying Your Mod</h3> |
|
|
|
<h5>Blood in the cut</h5> |
|
|
|
<p>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 <a href="https://git.exmods.org/modtainers/GCIPA">Plugin</a> file, which is the interface between Unity and IPA. |
|
|
|
It's very similar to a <a href="https://docs.unity3d.com/ScriptReference/MonoBehaviour.html">Unity MonoBehaviour</a>, 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". |
|
|
|
You did that! You've modified your first mod!</p> |
|
|
|
<p>For more advanced stuff, I'd recommend using a C# decompiler like <a href="https://github.com/0xd4d/dnSpy/releases">dnSpy</a> to read Gamecraft code and figure out what you need to modify. |
|
|
|
Also read about <a href="https://github.com/pardeike/Harmony/wiki">Harmony</a> (included in the HelloModdingWorld base configuration; see HelloModdingWorld.csproj) for patching existing methods.</p> |
|
|
|
<h3>Gamecraft Architecture<h3> |
|
|
|
<h5>Do I wanna know</h5> |
|
|
|
<p>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 <a href="https://en.wikipedia.org/wiki/Entity_component_system">Entity Component System (ECS)</a> 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.</p> |
|
|
|
<p>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.</p> |
|
|
|
<p>In Gamecraft, a custom-desgned ECS is used called <a href="https://github.com/sebas77/Svelto.ECS">Svelto.ECS</a> (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 <a href="http://www.sebaslab.com/">Seb's website</a>, 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.</p> |
|
|
|
<p>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.</p> |
|
|
|
<h3>Further Reading</h3> |
|
|
|
<h5></h5> |
|
|
|
<p>Some of these resources have already been mentioned, but I'll mention them again to have a complete list of resources for quick reference.</p> |
|
|
|
<p>- <a href="http://www.sebaslab.com/">Seba's Lab</a>, for articles and examples about Svelto.ECS, Gamecraft's entity handler.</p> |
|
|
|
<p>- <a href="https://git.exmods.org/modtainers/GamecraftModdingAPI">GamecraftModdingAPI</a>, for an easier way to modify the behaviour of some parts of Gamecraft.</p> |
|
|
|
<p>- <a href="https://docs.unity3d.com/ScriptReference/">Unity Scripting API</a>, for interfacing with Gamecraft's game engine.</p> |
|
|
|
<p>- <a href="https://github.com/pardeike/Harmony/wiki">Harmony</a>, for patching existing methods in Gamecraft's code.</p> |
|
|
|
<p>- <a href="https://github.com/Eusth/IPA">Eusth's Illusion Plugin Architecture (Reloaded)</a>, for injecting plugins into Unity games.</p> |
|
|
|
<p>- <a href="https://discord.gg/xjnFxQV">Exmods Discord</a>, for modding help and discussions.</p> |
|
|
|
<p>- <a href="https://git.exmods.org">Exmods Git server</a>, for other mods and custom tools.</p> |
|
|
|
<p>- <a href="https://github.com/hecomi/uREPL">uREPL</a>, the command-line interface in Gamecraft.</p> |
|
|
|
<p>- <a href="https://assetstore.unity.com/packages/tools/utilities/rewired-21676">Rewired</a>, the input handling library in Gamecraft.</p> |
|
|
|
</div> |
|
|
|
<footer> |
|
|
|
exmods.org|<a href="https://git.exmods.org/ExMods/html-site">Site Repository</a>|<a href="https://exmods.org">Home</a>|<a href="https://discord.gg/xjnFxQV">Discord</a>|<a href="https://twitter.com/GamecraftMods">Twitter</a> |
|
|
|
</footer> |
|
|
|
</body> |
|
|
|
</html> |
