From 181597cd2fa295cb0fd01af35152b685aee7d983 Mon Sep 17 00:00:00 2001 From: NGnius Date: Tue, 5 Nov 2019 16:32:52 -0500 Subject: [PATCH] Improve documentation with examples --- README.md | 15 +++++-- extracommands/ExampleCommandEngine.cs | 63 +++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 extracommands/ExampleCommandEngine.cs diff --git a/README.md b/README.md index 432f654..f8a571b 100644 --- a/README.md +++ b/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) +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). diff --git a/extracommands/ExampleCommandEngine.cs b/extracommands/ExampleCommandEngine.cs new file mode 100644 index 0000000..2e27db0 --- /dev/null +++ b/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 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"); + } + } +}