Merge pull request #41 from cmwedin/Development-Branch

1.0.0 Release

Author: cmwedin

Documentation~/CommandPatternDocumentation.pdf

@@ -3,6 +3,7 @@ This package contains a collection of classes and interfaces to allow for quick
 
 ## Installation
 ### Through GitHub (Recommended)
+#### Stable Installation
 To install this package in your Unity project, select the "window/Package Manager" entry in the Unity Inspector toolbar. Then, select the "+" icon in the upper left corner of the opened window, and select "Add package from git url." Paste the following:
 
     https://github.com/cmwedin/CommandPattern.git
@@ -11,22 +12,29 @@ Once you see this package show up in the Package Manager window, it has been suc
 
 You can automatically update the package by clicking the "update," button in the bottom right corner of the package manager window. This will retrieve any changes on main branch on this repository since installation or your last update.
 
-#### Advanced installation (Not Recommended) 
+#### Bleeding-Edge Installation
 You can install the experimental version of this package instead by adding #Development-Branch to the end of the Github url above. This will make your installation use the most up to date version possible, even before changes are merged onto the main branch. 
 
 ### Through Itch.io
-**This package will be available on Itch.io after 1.0.0 is released in the coming days, this section is currently a placeholder**
+When installing this package through Itch.io you will need to update the package manually. There are two methods to download the package through Itch, you can either install it with the rest of your packages, leaving your asset folder less cluttered, but preventing modifications to the packages files; or you can install it as an asset, placing all of the scripts within your asset folder and allowing you to modify them. Modifications to this packages scripts are recommended only for user very confident in what they are doing.   
 
-Download this package's archive from its Itch.io page [here](https://github.com/cmwedin/CommandPattern) **(link currently a placeholder)**. Once downloaded, extract the folder contained within to your desired installation location for the package. Note that deleting this folder will break your package installation, even after adding the package to a unity project.
+#### Installing as a Package
+Download this package's archive from its <a href="https://sadsapphic.itch.io/command-pattern" target="_blank">Itch.io page</a>. Once downloaded, extract the "CommandPattern" folder contained within to your desired installation location. Note that deleting this folder will break your package installation, even after adding the package to a Unity project.
 
 After you have downloaded and unzipped the package, open the Unity project you wish to add this package too. Open the package manager window, and select the "+" icon in the upper left corner. Then, select the "Add package from disk" option. Navigate to your installation location and select the "package.json" file. Once you see this package show up in the Package Manager window, it has been successfully installed.
 
-**Note that installing the package through this method will require you to update it manually**
+#### Installing as an Asset
+Download the .unitypackage file from this packages <a href="https://sadsapphic.itch.io/command-pattern" target="_blank">Itch.io page</a>. Once downloaded, open the Unity project you wish to add this package to. Select "Assets" from the Unity Editor's toolbar, an  from the "Import Package" menu select "Custom Package". In the window that pops up navigate to the .unitypackage file you downloaded and select it. The package will be added to your assets folder in the "/Packages/CommandPattern/" directory. 
 
-**The above process is a placeholder and may be changed before the release of version 1.0.0 and upload to Itch.io**
+### Updating the Package
+If you installed the package through GitHub, you can automatically update it to its newest version by clicking the "update" button in the bottom right corner of its entry in the package manager window. If not, you will need to update it manually. In addition, there may be steps needed to migrate your code to the newer version of the package. If there are, these will be added to this section when the update has been released.
+#### Manual Updating as a package
+If you installed the package using the local package installation through the Unity package manager to update it you will need to download the archive for the updated version from the packages Itch.io page. Once you've done this, remove the old package in the package manager, delete the old installation and extract the inner folder from the new archive. If you plan to install the updated package with the same path, you may be able to skip removing the old package, but it is recommended you do so regardless. Once you have completed this, add the updated version of the package through the same installation progress you followed above.
+#### Manual Updating as an Asset
+If you installed the package as an asset using the .unitypackage file, simply download the updated .unitypackage file, delete you old installation in your assets folder, and follow the installation process above using the new .unitypackage file.  
 
 ### Installing the Package Demo
-This package includes a demo showcasing how to use the command pattern along with many scripts you may find helpful to reference when implementing your own commands. Once the package is installed, this demo can easily be added by opening the "Samples" dropdown, and clicking the "import" button next to the "Simple Demo" entry. Once this demo has been imported, you can open it by navigating to the newly created "Samples/CommandPattern/[Current Version]/SimpleDemo" folder and opening the "SimpleDemo.Unity" scene. You may need to enter play-mode and resize your game window for the scene's ui elements to display properly.
+This package includes a demo showcasing how to use the command pattern along with many scripts you may find helpful to reference when implementing your own commands. If you installed the package as an asset the demo will be included by default within the "Demos/SimpleDemo" directory. Once the package is installed, this demo can easily be added by opening the "Samples" dropdown, and clicking the "import" button next to the "Simple Demo" entry. Once this demo has been imported, you can open it by navigating to the newly created "Samples/CommandPattern/[Current Version]/SimpleDemo" folder and opening the "SimpleDemo.Unity" scene. You may need to enter play-mode and resize your game window for the scene's ui elements to display properly.
 
 ## Using this package
 Full documentation of this package can be found [here](https://cmwedin.github.io/CommandPatternDocumentation/annotated.html)

README.md

@@ -125,6 +125,11 @@ public CancellationTokenSource GetRunningTaskCTS(Task task) {
                 return null;
             }
         }
+        /// <summary>
+        /// Gets the CancellationTokenSource of a running AsyncCommand's task
+        /// </summary>
+        /// <param name="task">The AsyncCommand to get the CTS of</param>
+        /// <returns>The CTS of task if it is running, null if it is not</returns>
         public CancellationTokenSource GetRunningTaskCTS(IAsyncCommand asyncCommand) {
             return GetRunningTaskCTS(asyncCommand.CommandTask);
         }

Runtime/Commands/CommandStream.cs

@@ -1,6 +1,8 @@
+using System;
 using System.Collections;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
+using System.Threading;
 using System.Threading.Tasks;
 using UnityEngine;
 
@@ -32,6 +34,10 @@ public class SingletonCommandManager : MonoBehaviour
         /// </summary>
         private bool freezeCommandExecution = false;
         /// <summary>
+        /// Invoked when the inner CommandStream invokes its OnTaskFaulted event
+        /// </summary>
+        public event Action<Exception> OnTaskFaulted;
+        /// <summary>
         /// Turns command execution off if its on and on if its off
         /// </summary>
         public void ToggleCommandExecution()
@@ -61,6 +67,22 @@ public ReadOnlyCollection<Task> GetRunningCommandTasks() {
             return commandStream.GetRunningCommandTasks();
         }
         /// <summary>
+        /// Gets the CancellationTokenSource of a running AsyncCommand's task
+        /// </summary>
+        /// <param name="task">The task to get the CTS of</param>
+        /// <returns>The CTS of task if it is running, null if it is not</returns>
+        public CancellationTokenSource GetRunningTaskCTS(Task task){
+            return commandStream.GetRunningTaskCTS(task);
+        }
+        /// <summary>
+        /// Gets the CancellationTokenSource of a running AsyncCommand's task
+        /// </summary>
+        /// <param name="task">The AsyncCommand to get the CTS of</param>
+        /// <returns>The CTS of task if it is running, null if it is not</returns>
+        public CancellationTokenSource GetRunningTaskCTS(IAsyncCommand asyncCommand){
+            return commandStream.GetRunningTaskCTS(asyncCommand);
+        }
+        /// <summary>
         /// Cancels an AsyncCommand's running task through a reference to the task
         /// </summary>
         /// <param name="taskToCancel">the task of an AsyncCommand to cancel</param>
@@ -75,13 +97,27 @@ public void CancelRunningCommandTask(IAsyncCommand asyncCommand) {
             commandStream.CancelRunningCommandTask(asyncCommand);
         }
         /// <summary>
+        /// Get a dictionary of any faulted tasks and the exceptions that they threw
+        /// </summary>
+        /// <returns> A read only copy of the dictionary of faulted tasks and their exceptions </returns>
+        public ReadOnlyDictionary<Task, Exception> GetFaultedCommandTasks() {
+            return commandStream.GetFaultedCommandTasks();
+        }
+        /// <summary>
         /// Empties the history of the internal CommandStream and replaces it with an empty one.
         /// </summary>
         /// <returns> The old history of the internal CommandStream </returns>
-        public ReadOnlyCollection<ICommand> DropCommandHistory() {
+        public ReadOnlyCollection<ICommand> DropHistory() {
             return commandStream.DropHistory();
         }
-
+        /// <summary>
+        /// This will remove all commands from the CommandStream's queue and replace it with a new empty queue.
+        /// </summary>
+        /// <remark> This can be useful to rearrange the commands in a queue. Simple preform the needed changes on the returned list and re-queue it </remark>
+        /// <returns> The commands in the previous queue, in case this information is needed.</returns>
+        public List<ICommand> DropQueue() {
+            return commandStream.DropQueue();
+        }
         /// <summary>
         /// The number of Commands recorded by the CommandManager's CommandStream
         /// </summary>
@@ -137,6 +173,50 @@ public void ForceQueueUndoCommand(IUndoable commandToUndo) {
             commandStream.ForceQueueUndoCommand(commandToUndo);
         }
         /// <summary>
+        /// Examine the next command in the CommandStream's commandQueue with out executing it
+        /// </summary>
+        /// <param name="nextCommand">The next command in the queue, null if empty</param>
+        /// <returns>Wether there was a command in queue or not</returns>
+        public bool TryPeekNext(out ICommand nextCommand) {
+            return commandStream.TryPeekNext(out nextCommand);
+        }
+        /// <summary>
+        /// Removes the next command in the CommandStream's queue, if it has one, and adds it back to the end of the queue.
+        /// </summary>
+        public void RequeueNextCommand() {
+            commandStream.RequeueNextCommand();
+        }
+        /// <summary>
+        /// Removes the next command from the CommandStream's queue without executing it
+        /// </summary>
+        public void SkipNextCommand(){
+            commandStream.SkipNextCommand();
+        }
+        /// <summary>
+        /// Bypass the CommandStream's queue and immediately attempt to execute a command
+        /// </summary>
+        /// <param name="command">The command to immediately be executed</param>
+        /// <returns>The ExecuteCode for the attempt to execute the command</returns>
+        public ExecuteCode TryExecuteImmediate(ICommand command) {
+            return commandStream.TryExecuteImmediate(command);
+        }
+        /// <summary>
+        /// Bypass the CommandStream's queue and immediately attempt to execute an IUndoable's undo command if the IUndoable is in the CommandStream's history
+        /// </summary>
+        /// <param name="undoable">the IUndoable to execute the undo command of</param>
+        /// <returns>The ExecuteCode of the attempt to execute the undo command of the IUndoable, Execute.Failure if the IUndoable was not in the CommandStream's history </returns>
+        public ExecuteCode TryUndoImmediate(IUndoable undoable) {
+            return commandStream.TryUndoImmediate(undoable);
+        }
+        /// <summary>
+        /// Bypass the command queue and immediately attempt to execute an IUndoable's undo command, regardless of wether the IUndoable is in the CommandStream's history
+        /// </summary>
+        /// <param name="undoable">the IUndoable to execute the undo command of</param>
+        /// <returns>The ExecuteCode of the attempt to execute the undo command of the IUndoable</returns>
+        public ExecuteCode ForceTryUndoImmediate(IUndoable undoable) {
+            return commandStream.ForceTryUndoImmediate(undoable);
+        }
+        /// <summary>
         /// sets the singleton instance of this object
         /// </summary>
         private void Awake() {
@@ -155,8 +235,8 @@ void Start() {
             } else {
                 commandStream = new CommandStream();
             }
+            commandStream.OnTaskFaulted += (ex) => OnTaskFaulted.Invoke(ex);
         }
-
         /// <summary>
         /// Executes the next command in queue if it isn't empty and command execution isn't frozen
         /// </summary>

Runtime/Monobehaviours/SingletonCommandManager.cs

@@ -10,27 +10,16 @@ namespace SadSapphicGames.CommandPattern.SimpleDemo
     public class LinearProj : ProjSO
     {
         /// <summary>
-        /// the maximum y value the projectile can reach before being destroyed
-        /// </summary>
-        private float yMax;
-        /// <summary>
-        /// a property to set yMax based on the bounds of a RectTransform
-        /// </summary>
-        public override RectTransform BoundingBox { set {
-                Vector3[] corners = new Vector3[4];
-                value.GetWorldCorners(corners);
-                yMax = corners[1].y;
-            }}
-        /// <summary>
         /// Updates the y value of the position to be a distance above the current position's y value based on this scriptable objects set speed
         /// </summary>
         /// <remark> unused parameters exclude </remark>
         /// <param name="currentPos">the current position of the projectile</param>
         /// <returns>The new position of the projectile</returns>
-        public override Vector3 UpdatePosition(Vector3 currentPos, Vector3 origin,  Vector3 prevDirection, out Vector3 nextDirection) {
+        public override Vector3 UpdatePosition(Vector3 currentPos, Vector3 origin,  RectTransform boundsRect, Vector3 prevDirection, out Vector3 nextDirection) {
+            ProjBounds bounds = new ProjBounds(boundsRect);
             float targetY = currentPos.y + speed * Time.fixedDeltaTime;
             nextDirection = Vector3.up;
-            if (targetY <= yMax) {
+            if (targetY <= bounds.yMax) {
                 return new Vector3(currentPos.x, targetY, currentPos.z);
             } else {
                 return Vector3.zero;

Samples~/SimpleDemo/DemoScripts/InputPanel/LinearProj.cs

@@ -91,11 +91,6 @@ void Update()
                 ) {
                     inputCommandStream.QueueCommand(new SpawnProjectileCommand(this, altProjType,projMaxLifespan));
                 }
-
-                if (Input.GetKey(inputCommandStream.InputKeybinds[InputType.Undo]))
-                {
-                    inputCommandStream.Undo();
-                }
             }
         }
         /// <summary>
@@ -111,6 +106,10 @@ private void FixedUpdate() {
                         inputCommandStream.QueueCommand(new MovePlayerCommand(this, movementVector, baseSpeed));
                     }
                 }
+                if (Input.GetKey(inputCommandStream.InputKeybinds[InputType.Undo]))
+                {
+                    inputCommandStream.Undo();
+                }
             }
 
         }

Samples~/SimpleDemo/DemoScripts/InputPanel/Player.cs

@@ -8,6 +8,40 @@ namespace SadSapphicGames.CommandPattern.SimpleDemo
     /// The base scriptable object for the data of projectile behavior
     /// </summary>
     public abstract class ProjSO : ScriptableObject {
+        /// <summary>
+        /// The bounds of a projectile
+        /// </summary>
+        protected struct ProjBounds {
+            /// <summary>
+            /// The max x position
+            /// </summary>
+            public float xMax;
+            /// <summary>
+            /// The max y position
+            /// </summary>
+            public float yMax;
+            /// <summary>
+            /// The min x position
+            /// </summary>
+            public float xMin;
+            /// <summary>
+            /// The min y position
+            /// </summary>
+            public float yMin;
+
+            /// <summary>
+            /// Constructs a ProjBounds struct from a rect transform
+            /// </summary>
+            /// <param name="rectTransform"></param>
+            public ProjBounds(RectTransform rectTransform)
+            {
+                var corners = rectTransform.GetWorldCorners();
+                xMax = corners[2].x;
+                yMax = corners[2].y;
+                xMin = corners[0].x;
+                yMin = corners[0].y;
+            }
+        }
         /// <summary>
         /// The prefab object to instantiate as the visual base for the projectile
         /// </summary>
@@ -18,11 +52,6 @@ public abstract class ProjSO : ScriptableObject {
         /// </summary>
         [SerializeField] protected float speed;
 
-        /// <summary>
-        /// The box that should bound the projectiles movement
-        /// </summary>
-        public abstract RectTransform BoundingBox { set; }
-
         /// <summary>
         /// Invoked in the projectile FixedUpdate method to determine where it should move to next based on where it currently is, where it started, and what direction it was last moving in 
         /// Some projectile types may not use all of this information
@@ -32,7 +61,7 @@ public abstract class ProjSO : ScriptableObject {
         /// <param name="prevDirection">the previous direction the projectile moved in</param>
         /// <param name="newDirection">the direction the projectile is moving in now</param>
         /// <returns> The new position of the projectile </returns>
-        public abstract Vector3 UpdatePosition(Vector3 currentPos, Vector3 origin, Vector3 prevDirection, out Vector3 newDirection);
+        public abstract Vector3 UpdatePosition(Vector3 currentPos, Vector3 origin, RectTransform rectBounds, Vector3 prevDirection, out Vector3 newDirection);
 
     }
 }

Samples~/SimpleDemo/DemoScripts/InputPanel/ProjSO.cs

@@ -18,6 +18,10 @@ public class Projectile : MonoBehaviour
         /// </summary>
         private ProjSO data;
         /// <summary>
+        /// The RectTransform the projectile can move within
+        /// </summary>
+        public RectTransform rectBounds { get; set; }
+        /// <summary>
         /// The starting position of the projectile, relevant for some projectile types
         /// </summary>
         public Vector3 Origin { get; set; }
@@ -55,7 +59,7 @@ void FixedUpdate()
             {
                 if (data == null) { Destroy(gameObject); }
                 Destroy(gameObject, Lifespan);
-                Vector3 target = data.UpdatePosition(transform.position, Origin, prevDirection, out prevDirection);
+                Vector3 target = data.UpdatePosition(transform.position, Origin, rectBounds,prevDirection, out prevDirection);
                 if (target == Vector3.zero)
                 {
                     Destroy(gameObject);