Codefarts

Legacy Console is a unity project that provides in a game console that you can exectute commands either in game or in the unity editor. 

Table of Contents

Introduction [ Top ]

The legacy console project is both a console system for unity and other platforms that allows users to type in commands on a command line to perform various actions.

The history of the console is a fairly long and complicated one going back to 2004 with a blog post made by Jason Olson on the geek with blogs website located here http://geekswithblogs.net/jolson/archive/2004/02/16/2174.aspx. (Archive.org link here)

I first started out by converting the C# code over to VB.NET and from there I began to add additional functionality. The problem was that not to long after converting the code Microsoft released Xna and unfortunatley VB.NET was not an officially supported language. You could cirtianly reference the Xna assemblies in your VB.NET projects and use them that way but you lacked the ability to setup Xna content projects etc. Begrudgengly after converting the original code from C# to VB.NET and adding features I ended up converting it back again from VB.net to C#.

Repositories

Legacy Console is availible as separate git repositories and can be forked from the fallowing BitBucket locations

Default Command Parser [ Top ]

The default command parser that comes bundled with the console allows simple command expressions to be invoked.

For example using the command "echo This is a test " consists of the first word "echo " representing the name of the command to be executed. and every subsequent word separated by a space to be treated as an argument "This ", "is ", "a ", "test ".

Using Functions [ Top ]

Every command that is loaded into the console can be used to return a result. Example one demonstrates how to use the echo command that prints the output result of the help command. Notice that "help commands" is surrounded by [ and ] characters. These characters define the beginning and end of a function.

Example 1: echo [ help commands ]

In example two we use two function calls that results in the text "First, second." being written to the console.

Example 2: echo [ echo First ] [ echo , second. ]

In example three we use two function calls, and in the second function call we embed a third function call that results in the text "First, second, and third." being written to the console.

Example 3: echo [ echo First ] [ echo , second [ echo , and third. ] ]

As you can see by using function calls the console provides the user with a much more powerful command system for interacting with and debugging your games.

Creating Commands [ Top ]

Step  1: Create a new class that inherits from the BaseCommands class and call it CustomCommands.
Step  2: Create an override for the OnConnect method that also calls the base objects OnConnect method.

public override void OnConnect(Codefarts.LegacyConsole.CommandManager Manager, 
                Codefarts.LegacyConsole.CommandExtenderManager ExtenderManager)
{
    // be sure to call the base OnConnect method
    base.OnConnect(Manager, ExtenderManager);
}

Step 3: Add a "quit" command after the base.OnConnect statement 

// add a quit command
DoAddCommand("quit", new Codefarts.LegacyConsole.CommandCallback(this.DoQuit));

Step 4: Create a new method in the class called DoQuit

private string DoQuit(string[] args, bool usedAsFunction)
{
    // exit the app.
    this.game.Exit(); 

    // return an empty string
    return string.Empty;
}

The DoQuit method will be called when the user types “quit” into the console. The only thing the DoQuit method does is call the Game.Exit method that will intern quit the game.

Your code should look something like this…

public class CustomCommands : Codefarts.LegacyConsole.BaseCommands
{
    private Game1 game; 

    public CustomCommands(Game1 g, Codefarts.LegacyConsole.Console console) 
        : base(console)
    {
        this.game = g;
    } 

    #region " Commands ... "

    [Category("Example"), Description("Quits the applicaion/game.")]
    private string DoQuit(string[] args, bool usedAsFunction)
    {
        // exit the app.
        this.game.Exit();
 
        // return an empty string
        return string.Empty;
    } 

    #endregion 

    public override void OnConnect(Codefarts.LegacyConsole.CommandManager Manager, 
                Codefarts.LegacyConsole.CommandExtenderManager ExtenderManager)
    {
        // be sure to call the base OnConnect method
        base.OnConnect(Manager, ExtenderManager);    

        // add a quit command
        DoAddCommand("quit", new Codefarts.LegacyConsole.CommandCallback(this.DoQuit));
    }
}

Command methods require two parameters. The first is an array or arguments passed to the command and the second is a boolean flag indicating how this command is being invoked. If the usedAsFunction argument is true then the command should be expected to return a response value. If usedAsFunction is false the command is being executed on it's own or is the primary command that is being executed.

Primary commands are top level parent commands where some of there arguments are themselves commands.

For example "echo [ isfullscreen  ]" consists of a primary command "echo" and a child/nested command "isfullscreen". Note that the "isfullscreen" command is encapsulated by "[" & "]" characters. This instructs the default command parser to execute the "isfullscreen" command with the usedAsFunction parameter set to true.

In this simple example the isfullscreen command will return either "true" or "false" as a response value. Once the isfullscreen has returned it's value the "echo" command is invoked with the args parameter containing one array element with the value "true" or "false" and the usedAsFunction parameter set to false.