Improve documentation with examples

README.md

@@ -9,16 +9,23 @@ You should download the latest release and extract it to the Gamecraft folder.
 To patch, drag `Gamecraft.exe` onto `IPA.exe`. You will need to redo this step whenever Gamecraft is updated.
 2. Extract the ExtraCommands zip into Gamecraft's `Plugins\` folder (GCIPA should have created this automatically in the previous step). You should see `0Harmony.dll` and `ExtraCommands.dll` in the `Plugins\` folder. If those files are in another folder in `Plugins\` it will not work.
 3. Launch Gamecraft.
-You can check the log file `%APPDATA%\..\LocalLow\FreeJam\RobocraftX\Player.log` to confirm.
+You can check the log file `%APPDATA%\..\LocalLow\FreeJam\Gamecraft\Player.log` to confirm.
 You should be able to see a message near the top showing how many plugins have been loaded and their names.
 
 ## Development
 
-Interested in making your own mod?
-Clone this repository and modify the C# classes in `extracommands\`.
-Patch Gamecraft with [GCIPA](#installation)
-Build the solution and copy `bin\Debug\net45\extracommands.dll` and `bin\Debug\net45\0Harmony.dll` into Gamecraft's `Plugins\` folder.
+Interested in adding your own commands?
+Clone this repository and create a C# class file in `extracommands\`.
+A template command is provided in `ExampleCommandEngine.cs` which you can copy to get started.
+It's recommended that you create a symbolic link named `ref` in the root directory of this project linked to the folder containing Gamecraft `.dll` files.
 
+### Testing
+Patch Gamecraft with [GCIPA](#installation).
+Create a symbolic link named `ref` in the root directory of this project linked to the folder containing Gamecraft `.dll` files (to resolve dependencies).
+Build the solution and copy `bin\Debug\net45\extracommands.dll` and `bin\Debug\net45\0Harmony.dll` into Gamecraft's `Plugins\` folder.
+Load a game and try out your command in the command line interface in Gamecraft.
+
+### External Documentation
 More information about the IPlugin and IEnhancedPlugin interface can be found [on the IPA repository](https://github.com/Eusth/IPA).
 
 More information about Harmony can be found [on the Harmony wiki](https://github.com/pardeike/Harmony/wiki).

extracommands/ExampleCommandEngine.cs

@@ -0,0 +1,63 @@
+using System;
+using RobocraftX.GUI.CommandLine;
+using RobocraftX.Multiplayer;
+using RobocraftX.StateSync;
+using RobocraftX.Character;
+using Svelto.ECS;
+using Unity.Entities;
+using UnityEngine;
+using uREPL;
+using Svelto.Context;
+using RobocraftX;
+
+// checklist of things to rename to make this command your own:
+// [ ] namespace ExtraCommands.Example -> namespace ExtraCommands.[your command's namespace]
+// [ ] class ExampleCommandEngine : CustomCommandEngine -> class [your command name]CommandEngine : CustomCommandEngine
+// [ ] public ExampleCommandEngine(UnityContext<... -> public [your command name]CommandEngine(UnityContext<...
+// [ ] CustomCommandUtility.Register("[your command name]", [your command name]Command, "[your command description]")
+// [ ] private void ExampleCommand() -> private void [your command name]Command()
+// [ ] CustomCommandUtility.Unregister("[your command name]")
+//
+// For aesthetics, I'd recommend using PascalCase (first letter in every word is uppercase; spaces are illegal*)
+// * You can use spaces in your command description, but nowhere else. The description should be written like a normal English sentence.
+
+namespace ExtraCommands.Example
+{
+    // !!! Uncomment the line below this !!!
+    // [CustomCommand("Example")]
+    class ExampleCommandEngine : CustomCommandEngine
+    {
+        // This class is a custom implementation of CustomCommandEngine specific to this command
+        // You can use Svelto.ECS.IEntityDB entitiesDB to query game entities or one of the protected variables for other things
+        // More documentation on Svelto.ECS: https://github.com/sebas77/Svelto.ECS
+        // Unfortunately the documentation is severely lacking and out of date; you may have better luck decompiling Svelto.ECS.dll
+        // See CustomCommandEngine.cs for more information on the super class
+
+        public ExampleCommandEngine(UnityContext<FullGameCompositionRoot> ctxHolder, EnginesRoot enginesRoot, World physW, Action reloadGame, MultiplayerInitParameters mpParams) : base(ctxHolder, enginesRoot, physW, reloadGame, mpParams)
+        {
+        }
+
+        // Ready() is called when the command is registered in-game (this happens whenever you load a game)
+        public override void Ready()
+        {
+            // CustomCommandUtility.Register has multiple overloads depending on how many parameters you want to pass to your command
+            // See CustomCommandUtility.cs for more information
+            CustomCommandUtility.Register("Example", ExampleCommand, "This is an example command which does nothing!");
+        }
+
+        // ExampleCommand() is called whenever the command is executed. This can accept up to three parameters
+        // Please rename this, but don't forget to change the name in CustomCommandUtility.Register as well
+        private void ExampleCommand()
+        {
+            // command operations go here
+        }
+
+        // Dispose() is called when the command is unregistered in-game (this happens whenever you leave a game)
+        public override void Dispose()
+        {
+            // You must unregister the command so it doesn't waste memory and so
+            // it can be re-registered next time
+            CustomCommandUtility.Unregister("Example");
+        }
+    }
+}