From 7519bc37ae76702bbe65da60fb95617e73cf3114 Mon Sep 17 00:00:00 2001 From: NGnius Date: Tue, 25 Feb 2020 18:05:13 -0500 Subject: [PATCH] Improve documentation --- GamecraftModdingAPI/Blocks/Movement.cs | 12 +++++++++--- GamecraftModdingAPI/Blocks/Placement.cs | 6 ++++-- GamecraftModdingAPI/Blocks/Rotation.cs | 10 +++++++--- GamecraftModdingAPI/Blocks/RotationEngine.cs | 1 + GamecraftModdingAPI/Blocks/Signals.cs | 3 ++- GamecraftModdingAPI/Tasks/Once.cs | 3 ++- GamecraftModdingAPI/Tasks/Repeatable.cs | 3 ++- GamecraftModdingAPI/Tasks/Scheduler.cs | 12 ++++++++++++ 8 files changed, 39 insertions(+), 11 deletions(-) diff --git a/GamecraftModdingAPI/Blocks/Movement.cs b/GamecraftModdingAPI/Blocks/Movement.cs index 4f4a8ec..132fedf 100644 --- a/GamecraftModdingAPI/Blocks/Movement.cs +++ b/GamecraftModdingAPI/Blocks/Movement.cs @@ -9,14 +9,17 @@ using Unity.Mathematics; namespace GamecraftModdingAPI.Blocks { /// - /// Common block movement operations + /// Common block movement operations. + /// The functionality of this class only works in build mode. /// public static class Movement { private static MovementEngine movementEngine = new MovementEngine(); /// - /// Move a single block by a specific (x,y,z) amount + /// Move a single block by a specific (x,y,z) amount (offset). + /// The moved block will remain connected to the blocks it was touching before it was moved. + /// The block's placement grid and collision box are also moved. /// /// The block's id /// The movement amount (x,y,z) @@ -32,7 +35,10 @@ namespace GamecraftModdingAPI.Blocks } /// - /// Move all connected blocks by a specific (x,y,z) amount + /// Move all connected blocks by a specific (x,y,z) amount (offset). + /// The moved blocks will remain connected to the block they're touching. + /// All of the block's placement grids and collision boxes are also moved. + /// This is equivalent to calling MoveBlock() for every connected block. /// /// The starting block's id /// The movement amount (x,y,z) diff --git a/GamecraftModdingAPI/Blocks/Placement.cs b/GamecraftModdingAPI/Blocks/Placement.cs index 4e3083b..11c11eb 100644 --- a/GamecraftModdingAPI/Blocks/Placement.cs +++ b/GamecraftModdingAPI/Blocks/Placement.cs @@ -7,15 +7,17 @@ using GamecraftModdingAPI.Utility; namespace GamecraftModdingAPI.Blocks { /// - /// Common block placement operations + /// Common block placement operations. + /// The functionality in this class is for build mode. /// public static class Placement { private static PlacementEngine placementEngine = new PlacementEngine(); /// - /// Place a block at the given position. If scaled, position means the center of the block. The default block size is 0.2 in terms of position. + /// Place a new block at the given position. If scaled, position means the center of the block. The default block size is 0.2 in terms of position. /// Place blocks next to each other to connect them. + /// The placed block will be a complete block with a placement grid and collision which will be saved along with the game. /// /// The block's type /// The block's color diff --git a/GamecraftModdingAPI/Blocks/Rotation.cs b/GamecraftModdingAPI/Blocks/Rotation.cs index a8ccd5a..a0b6785 100644 --- a/GamecraftModdingAPI/Blocks/Rotation.cs +++ b/GamecraftModdingAPI/Blocks/Rotation.cs @@ -9,14 +9,17 @@ using Unity.Mathematics; namespace GamecraftModdingAPI.Blocks { /// - /// Common block movement operations + /// Common block rotation operations. + /// The functionality in this class is not completely implemented and will only work in build mode. /// public static class Rotation { private static RotationEngine rotationEngine = new RotationEngine(); /// - /// Rotate a single block by a specific amount in degrees + /// Rotate a single block by a specific amount in degrees. + /// This not destroy inter-block connections, so neighbouring blocks will remain attached despite appearances. + /// The cube placement grid and collision are also rotated. /// /// The block's id /// The rotation amount around the x,y,z-axis @@ -32,7 +35,8 @@ namespace GamecraftModdingAPI.Blocks } /// - /// Rotate all connected blocks by a specific amount in degrees + /// Rotate all connected blocks by a specific amount in degrees. + /// This does not do anything because it has not been implemented. /// /// The starting block's id /// The rotation around the x,y,z-axis diff --git a/GamecraftModdingAPI/Blocks/RotationEngine.cs b/GamecraftModdingAPI/Blocks/RotationEngine.cs index 7827e33..c605bf1 100644 --- a/GamecraftModdingAPI/Blocks/RotationEngine.cs +++ b/GamecraftModdingAPI/Blocks/RotationEngine.cs @@ -75,6 +75,7 @@ namespace GamecraftModdingAPI.Blocks public float3 RotateConnectedBlocks(uint blockID, Vector3 vector) { + // TODO: Implement and figure out the math throw new NotImplementedException(); } diff --git a/GamecraftModdingAPI/Blocks/Signals.cs b/GamecraftModdingAPI/Blocks/Signals.cs index 3895dbe..6b6d779 100644 --- a/GamecraftModdingAPI/Blocks/Signals.cs +++ b/GamecraftModdingAPI/Blocks/Signals.cs @@ -12,6 +12,7 @@ namespace GamecraftModdingAPI.Blocks { /// /// [EXPERIMENTAL] Common block signal operations + /// The functionality in this class only works when in a game. /// public static class Signals { @@ -48,7 +49,7 @@ namespace GamecraftModdingAPI.Blocks } /// - /// Set a signal's value. + /// Set the signal's value. /// /// The channel cluster's id. /// The signal value (-1 to 1; not enforced). diff --git a/GamecraftModdingAPI/Tasks/Once.cs b/GamecraftModdingAPI/Tasks/Once.cs index a3dc20f..52651e6 100644 --- a/GamecraftModdingAPI/Tasks/Once.cs +++ b/GamecraftModdingAPI/Tasks/Once.cs @@ -10,7 +10,8 @@ using Svelto.Tasks.Enumerators; namespace GamecraftModdingAPI.Tasks { /// - /// An asynchronous task to be performed once + /// An asynchronous task to be performed once. + /// Once constructed, this can be run by scheduling it with Scheduler.Schedule() /// public class Once : ISchedulable { diff --git a/GamecraftModdingAPI/Tasks/Repeatable.cs b/GamecraftModdingAPI/Tasks/Repeatable.cs index 60d3026..0b9982e 100644 --- a/GamecraftModdingAPI/Tasks/Repeatable.cs +++ b/GamecraftModdingAPI/Tasks/Repeatable.cs @@ -10,7 +10,8 @@ using Svelto.Tasks.Enumerators; namespace GamecraftModdingAPI.Tasks { /// - /// An asynchronous repeating task + /// An asynchronous repeating task. + /// Once constructed, this can be run by scheduling it with Scheduler.Schedule() /// public class Repeatable : ISchedulable { diff --git a/GamecraftModdingAPI/Tasks/Scheduler.cs b/GamecraftModdingAPI/Tasks/Scheduler.cs index fbc5e2d..803bd2f 100644 --- a/GamecraftModdingAPI/Tasks/Scheduler.cs +++ b/GamecraftModdingAPI/Tasks/Scheduler.cs @@ -9,6 +9,11 @@ using Svelto.Tasks.ExtraLean; namespace GamecraftModdingAPI.Tasks { + /// + /// Asynchronous task scheduling for ISchedulables. + /// Asynchronous tasks will not freeze the main program, which makes them ideal for slow or blocking operations which don't need to be completed post-haste. + /// The functionality of this class works in any state. + /// public static class Scheduler { public static Svelto.Tasks.Lean.Unity.UpdateMonoRunner leanRunnerUI @@ -31,6 +36,13 @@ namespace GamecraftModdingAPI.Tasks public static readonly Svelto.Tasks.Lean.Unity.UpdateMonoRunner leanRunner = new Svelto.Tasks.Lean.Unity.UpdateMonoRunner("GamecraftModdingAPILean"); + /// + /// Schedule a task to run asynchronously. + /// This uses custom task runners (by default) to not interfere with the game. + /// + /// The task to run + /// Schedule toRun on an extra lean runner? + /// Schedule toRun on Gamecraft's built-in UI task runner? public static void Schedule(ISchedulable toRun, bool extraLean = false, bool ui = false) { if (extraLean)