From 95e2e554e7c05a5571c33358faf98c6a8a109f9a Mon Sep 17 00:00:00 2001 From: NGnius Date: Mon, 25 Nov 2019 16:49:02 -0500 Subject: [PATCH] Add guides and standard style --- site/guides/first.html | 97 ++++++++++++++++++++++++++++++++++++++++++ site/guides/index.html | 33 ++++++++++++++ site/static/style.css | 40 +++++++++++++++++ site/template.html | 24 +++++++++++ 4 files changed, 194 insertions(+) create mode 100644 site/guides/first.html create mode 100644 site/guides/index.html create mode 100644 site/static/style.css create mode 100644 site/template.html 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 @@ + + + + + + + + + + + + + + + + + Exmods Getting Started + + +

Getting Started with Gamecraft Modding

+
by NGniusness
+

The First Step

+
The first cut is the deepest
+

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.

+

Modifying Your Mod

+
Blood in the cut
+

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 Architecture

+

Do I wanna know
+

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.

+

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.

+

- 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 @@ + + + + + + + + + + + + + + + + + Exmods Guides + + +

Modding Guides

+

Welcome to a collection of guides about modifying Gamecraft.

+ + + diff --git a/site/static/style.css b/site/static/style.css new file mode 100644 index 0000000..4fdf79b --- /dev/null +++ b/site/static/style.css @@ -0,0 +1,40 @@ +body { + background-color: #404040; + color: #20c420; + padding: 5%; +} + +head { + display: none; +} + +h1 { + text-align: center; + padding-top: 2%; + color: #20c420; +} + +h2, h3, h4, h5 { + text-align: center; + color: #20c420; +} + +.title { + font-size: 120%; + font-weight: bold; + color: #20c420; +} + +a { + text-decoration:none; + color: #208020; +} + +ul { + text-align: left; + padding-left: 5%; +} + +li { + text-align: left; +} diff --git a/site/template.html b/site/template.html new file mode 100644 index 0000000..acaaada --- /dev/null +++ b/site/template.html @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + Exmods + + +

Welcome to the Exmods mod site

+

This domain is under construction, please check back (much) later

+
View our code site or build this site with us.
+ +