diff --git a/site/guides/first.html b/site/guides/first.html new file mode 100644 index 0000000..2bc305d --- /dev/null +++ b/site/guides/first.html @@ -0,0 +1,97 @@ + + + +
+ + + + + + + + + + + + +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.
+To get the ball rolling, you'll need to download Visual Studio Community Edition, the .NET 4.8 Developper pack and GCIPA's latest releasefor this guide (and for Gamecraft modding). + I'm sorry in advance to the smart devs who don't use Windows; monodevelop 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.
+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 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: (Certification of hacking that I stole off the internet). + (NOTE: you'll need to re-patch the game everytime Steam updates Gamecraft)
+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 TestMod git repository 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 Exmods' Git server (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.
+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 create a symlink to Managed called ref. + 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.
+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 Plugin file, which is 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 (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 dnSpy to read Gamecraft code and figure out what you need to modify. + Also read about Harmony (included in the TestMod base configuration; see TestPatch.cs) for patching existing methods.
+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 (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.
+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.
+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.
+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.
+- Unity Scripting API, for interfacing with Gamecraft's game engine.
+- Harmony, for patching existing methods in Gamecraft'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.
+ + diff --git a/site/guides/index.html b/site/guides/index.html new file mode 100644 index 0000000..3a6a8ec --- /dev/null +++ b/site/guides/index.html @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + +This guide lays the groundwork for modding Gamecraft. Subjects covered include:
+ - Setting up your development environment
+ - Making your first mod in Visual Studio
+ - Overview of Gamecraft's design
+ - Best practices