From 9678c109e0be5c63e04a7b8dbf55e5689fb6d04f Mon Sep 17 00:00:00 2001 From: "NGnius (Graham)" Date: Wed, 3 Jun 2020 14:34:19 -0400 Subject: [PATCH] Add footer and fix lots of text --- site/blog/001-intro.html | 3 + site/blog/index.html | 3 + site/guides/first.html | 173 ++++++++++++++++++++------------------- site/guides/index.html | 3 + site/guides/install.html | 57 +++++++------ site/static/style.css | 13 +++ 6 files changed, 142 insertions(+), 110 deletions(-) diff --git a/site/blog/001-intro.html b/site/blog/001-intro.html index 1446594..d7e2aea 100644 --- a/site/blog/001-intro.html +++ b/site/blog/001-intro.html @@ -140,5 +140,8 @@

Welcome to the Exmods blog!

+ diff --git a/site/blog/index.html b/site/blog/index.html index 2a5102e..f38fda0 100644 --- a/site/blog/index.html +++ b/site/blog/index.html @@ -42,5 +42,8 @@ + diff --git a/site/guides/first.html b/site/guides/first.html index 2a3909d..f66382c 100644 --- a/site/guides/first.html +++ b/site/guides/first.html @@ -9,12 +9,12 @@ - + - - - + + + Exmods Getting Started @@ -23,85 +23,90 @@
-

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 release for this guide (and for Gamecraft modding). - To any smart devs who don't use Windows; monodevelop 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.

-

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 HelloModdingWorld git repository into a folder (NOT into Gamecraft's install location) and switch to the "no-api" branch. - If you'd like to try out the GamecraftModdingAPI you can use the "master" (default) branch, but you'll have to install the GamecraftModdingAPI 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 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 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.

-

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 create a symlink to Gamecraft's main folder. - 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 README 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.

-

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 MyPlugin.cs and take a look at it. - This is the main Plugin file, which is the 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 "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!

-

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 HelloModdingWorld base configuration; see HelloModdingWorld.csproj) 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. - 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.

-

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.

-

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. - Either way, rest assured that modding does get easier with a bit of practice; the start of the learning curve is the steepest.

-

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.

-

- GamecraftModdingAPI, for an easier way to modify the behaviour of some parts of Gamecraft.

-

- 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.

+
+

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 release for this guide (and for Gamecraft modding). + To any smart devs who don't use Windows; monodevelop 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.

+

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 HelloModdingWorld git repository into a folder (NOT into Gamecraft's install location) and switch to the "no-api" branch. + If you'd like to try out the GamecraftModdingAPI you can use the "master" (default) branch, but you'll have to install the GamecraftModdingAPI 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 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 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.

+

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 create a symlink to Gamecraft's main folder. + 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 README 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.

+

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 MyPlugin.cs and take a look at it. + This is the main Plugin file, which is the 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 "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!

+

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 HelloModdingWorld base configuration; see HelloModdingWorld.csproj) 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. + 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.

+

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.

+

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. + Either way, rest assured that modding does get easier with a bit of practice; the start of the learning curve is the steepest.

+

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.

+

- GamecraftModdingAPI, for an easier way to modify the behaviour of some parts of Gamecraft.

+

- 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 index 3d730a6..66eafa4 100644 --- a/site/guides/index.html +++ b/site/guides/index.html @@ -36,5 +36,8 @@ - Adding mods

+ diff --git a/site/guides/install.html b/site/guides/install.html index 11e8f99..eb8aac1 100644 --- a/site/guides/install.html +++ b/site/guides/install.html @@ -9,12 +9,12 @@ - + - - - + + + Exmods Installing Mods @@ -23,27 +23,32 @@
-

Patching The Game

-
Gamecraft: I'm getting hacked
-

The first step towards installing mods in Gamecraft is patching the game with the latest release of GCIPA. - If you've already done this for another Gamecraft mod, you can skip this step. - To install GCIPA, download the latest release and unzip it to where you installed Gamecraft. - You can find where Gamecraft is installed through your Steam Library by right-clicking Gamecraft and selecting "Properties...". - A properties window should open, with a tab called "Local Files". - From that tab, click on "Browse Local Files..." and a file explorer menu should open. - When you've extracted the files, you should see three new files, one called IPA (aka IPA.exe), and a new folder called IPA. - Drag and drop Gamecraft (aka Gamecraft.exe) onto the IPA file (IPA.exe) to patch the game. - To confirm that it's successful, an empty folder called "Plugins" should have been created as a result. - If the Plugins folder is there, the game has been successfully patched and you can move on to the next step. - (NOTE: you will need to re-patch the game everytime Steam updates Gamecraft)

-

Adding Mods

-
Because multiplying mods is too hard
-

For this step, you'll need the "Plugins" folder that IPA created for you. - Navigate into that "Plugins" folder and unzip the mod there. - You should now see a file called something similar to "[name of mod].dll". - Depending on the mod, there may be some other file or folders as well, but you don't need to worry about those provided there's one similar to "[name of mod].dll". - If you accidentally extract a mod into it's own folder within the Plugins folder, the mod will not work. - Your mod is now installed. The next time you launch Gamecraft, the mod will be ready to go. - If you open Player.log (found in the %APPDATA%/../LocalLow/FreeJam/Gamecraft/ folder), you should now see the mod's name.

+
+

Patching The Game

+
Gamecraft: I'm getting hacked
+

The first step towards installing mods in Gamecraft is patching the game with the latest release of GCIPA. + If you've already done this for another Gamecraft mod, you can skip this step. + To install GCIPA, download the latest release and unzip it to where you installed Gamecraft. + You can find where Gamecraft is installed through your Steam Library by right-clicking Gamecraft and selecting "Properties...". + A properties window should open, with a tab called "Local Files". + From that tab, click on "Browse Local Files..." and a file explorer menu should open. + When you've extracted the files, you should see three new files, one called IPA (aka IPA.exe), and a new folder called IPA. + Drag and drop Gamecraft (aka Gamecraft.exe) onto the IPA file (IPA.exe) to patch the game. + To confirm that it's successful, an empty folder called "Plugins" should have been created as a result. + If the Plugins folder is there, the game has been successfully patched and you can move on to the next step. + (NOTE: you will need to re-patch the game everytime Steam updates Gamecraft)

+

Adding Mods

+
Because multiplying mods is too hard
+

For this step, you'll need the "Plugins" folder that IPA created for you. + Navigate into that "Plugins" folder and unzip the mod there. + You should now see a file called something similar to "[name of mod].dll". + Depending on the mod, there may be some other file or folders as well, but you don't need to worry about those provided there's one similar to "[name of mod].dll". + If you accidentally extract a mod into it's own folder within the Plugins folder, the mod will not work. + Your mod is now installed. The next time you launch Gamecraft, the mod will be ready to go. + If you open Player.log (found in the %APPDATA%/../LocalLow/FreeJam/Gamecraft/ folder), you should now see the mod's name.

+
+ diff --git a/site/static/style.css b/site/static/style.css index e9386d6..6f3ecc5 100644 --- a/site/static/style.css +++ b/site/static/style.css @@ -73,6 +73,19 @@ iframe.iframe-player { .tab { margin-left: 40px; } +footer { + width: 92%; + background-color: #D8DFD8; + padding: 0.5%; + margin: 0; + margin-left: 4%; + margin-right: 4%; + text-align: right; + border: 4px; + border-style: solid; + border-color: #208020; +} + /* leaderboard style */ .board { font-size: 200%;