ExMods
/
html-site

<!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" />
    <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" />
    <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>, 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).
    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 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 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 (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 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 (or uncomment) "Debug.Log("Print this to log every frame");" (without quotes) and then save and build the project.
    Once again, copy TestMod (TestMod.dll) into Gamecraft's Plugins folder. Now start Gamecraft.
    When 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 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.
    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://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>