Command Pattern Toolkit

Description

This package contains a collection of classes and interfaces to allow for quick implementation of the command pattern across projects with ground-up support for commands that are optionally undo-able, fail-able, composite, or asynchronous. For more information, see the project readme file located on its Github page, or in the packages root folder after downloading it. A demo is included with the package as a showcase of how it can be used.

Features

Features of this package include:

• An invoker object designed to work with any project
• Support for using the invoker object as a queue for commands our for using it to execute commands immediately
• Support for recording the history of executed commands to a depth of your choosing
• And out-of-the-box singleton wrapper of an invoker to get the package up and running with ease
• Support for undoable commands
• Support for failable commands
• Support for composite commands
• Support for asynchronous commands with built in debug messages to indicate faulted tasks

You can use this package to create architecture to respond to player inputs, rebind controls, preform tween-ing animations, and much more! This package is free and open-source; however, donations are greatly appreciated to enable me to continue developing software such as this.

Using the Package

More detailed instructions on using the package are included in its readme found on its Github repository or in the root directory of your installation, but we will go over the basics here. The first step to using this package is to define the command objects you need for your package. You can do this by defining an object inheriting from the "Command" abstract class and implementing its "Execute" method. Once you have done this, you can send instances of this command to the invoker, or "CommandStream" object. It is recommended that you do this through a seperate object wrapping the invoker. You can use the the out-of-the-box "SingletonCommandManager" component for a quick implementation of this, but for more advanced usage it may be prudent to create your own wrapper object tailored to the needs of your project.

You can send commands to a CommandStream either by using its "QueueCommand" method followed by the "TryExecuteNext" method to execute commands in the order they are sent to the CommandStream, or by using the "TryExecuteImmediate" method to execute commands as soon as they are sent. Both of these methods will record the executed Command to the CommandStream's history if the desired HistoryDepth is greater than zero.

Advanced Topics

These topics are discussed in more detail in the full readme; however we will briefly mention them here as well. You can extend the functionality of your commands using the "IUndoable" and "IFailable" interfaces. These interfaces indicate that a Command can be undone, or that the CommandStream should verify it will succeed before invoking its execute method respectively. You can also create more advanced Commands by inheriting from the CompositeCommand abstract class, or the AsyncCommand abstract class. A CompositeCommand is a type of command that uses its own internal invoker to encapsulate multiple child Commands into a single object. An AsyncCommand is a command that uses an asynchronous method returning a Task to implement its logic, rather than the standard synchronous method returning void.

Installation

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 source code; 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.  

Installing as a Package

Download this package's archive from this page. 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.

Installing as an Asset

Download the .unitypackage file from this page.  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.

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