|
|
|
@@ -0,0 +1,97 @@ |
|
|
|
<!DOCTYPE html> |
|
|
|
|
|
|
|
<html lang="en"> |
|
|
|
<head> |
|
|
|
<meta name="theme-color" content="#20c420" /> |
|
|
|
<meta name="author" content="Exmods community" /> |
|
|
|
<meta name="keywords" content="exmods,gamecraft,modding,mod" /> |
|
|
|
<meta name="og:type" content="website" /> |
|
|
|
<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:url" content="https://www.exmods.org" /> |
|
|
|
<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> |
|
|
|
<h1>Getting Started with Gamecraft Modding</h1> |
|
|
|
<h5>by NGniusness</h5> |
|
|
|
<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>, <a href="https://dotnet.microsoft.com/download/dotnet-framework/net48">the .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). |
|
|
|
I'm sorry in advance to the smart devs who don't use Windows; <a href="https://www.monodevelop.com/">monodevelop</a> may work, but I haven't had any success. |
|
|
|
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/TestMod">TestMod git repository</a> into a folder (NOT into Gamecraft's install location) and switch to the "base" branch. |
|
|
|
The base branch of TestMod provides a starter project for creating your own IPA 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 TestMod 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 [Gamecraft install location]/Gamecraft_Data/Managed 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 Managed called ref</a>. |
|
|
|
The disadvantage to the former option is that you'll have to re-copy the files everytime there's a Gamecraft update. |
|
|
|
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 TestMod/bin/net48 folder copy TestMod.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 TestPlugin.cs and take a look at it. |
|
|
|
This is the main <a href="https://github.com/Eusth/IPA">Plugin</a> file, which is 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 (or uncomment) "Debug.Log("Print this to log every frame");" and then save and build the project. |
|
|
|
Once again, copy TestMod.dll into Gamecraft's Plugins folder. Now start Gamecraft. |
|
|
|
When you open Gamecraft's Player.log file (in something like %appdata%/../LocalLow/FreeJame/Gamecraft), 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 <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 TestMod base configuration; see TestPatch.cs) 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 (and code comments aren't included in 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 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, 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 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.</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.</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://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> |
|
|
|
</body> |
|
|
|
</html> |
