Saltbox.Terminal

A CommandLine Terminal for Unity Games

Installing from OpenUPM

You can easily install this package using OpenUPM CLI

openupm add com.saltboxgames.saltbox.terminal

Note: this method requires Node 12 and you can install OpenUPM using

npm install -g openupm-cli

Usage

Assets and scripts are available under the saltbox.terminal namespace.

The default Terminal is available under the Window dropdown. The first time you open the terminal it will create two scriptable objects Commands and TerminalSettings in your project root.

TerminalSettings

TerminalSettings is used to store information about the terminal editor window. it can't be moved, it's only used by the editor so it won't be compiled into your game.

CommandRunner

Commands is and instance of CommandRunner used to handle any terminal controls and commands you wish to write. It will be regenerated if the runner field in TerminalSettings is null.

Creating New Commands

Adding a new command can be done by implementing the ICommand interface. and adding it to the command runner. Option attributes will automatically be populated during execution.

    //Ex; clear --all
    class ClearCommand : ICommand
    {
        [Option('a', "all", HelpText="Clear All Terminals")]
        public bool clearAll { get; set; }

        public bool Invoke(ITerminalControl sender, CommandRunner runner)
        {
            if (clearAll)
            {
                runner.Clear();
                return true;
            }
            sender.Clear();
            return true;
        }
    }

    runner.AddCommand('clear', new ClearCommand());

Alternatively any commands that require Unity Assets can be created by inheriting from ScriptableCommand.

    //Ex; spawn-block -c 10
    [CreateAssetMenu(fileName = "Spawner", menuName = "Terminal/Commands/Spawner")]
    public class SpawnPrefab : ScriptableCommand
    {
        [SerializeField]
        private GameObject prefab;

        [Option('c', "count", Required = true, HelpText = "number of prefabs to spawn")]
        public int count { get; set; }

        public override string Name => "spawn-" + prefab.Name;

        public override bool Invoke(ITerminalControl sender, CommandRunner runner)
        {
            for (int i = 0; i < count; i++)
            {
                GameObject.Instantiate(prefab);
            }
            return true;
        }
    }

you can then add an instance of your command to either the Runtime or Editor Commands list in your command runner.

Creating New Terminal

New Terminal windows can be created by implementing the ITerminalControl interface and adding a reference to your CommandRunner

    public class InGameTerminal : MonoBehaviour, ITerminalControl
    {
        public event TerminalEvent OnInputSubmit;

        public string Name => "Game";

        [SerializeField]
        private CommandRunner runner;

        [SerializeField]
        private TextMeshPro text;

        private void OnEnable()
        {
            runner.AddControl(this);
        }

        private void OnDisable()
        {
            runner.RemoveControl(this);
        }

        public void Clear()
        {
            text.text = "";
        }

        public void Write(string content, Color color)
        {
            string hex = ColorUtility.ToHtmlStringRGB(color);
            text.text += $"<{hex}>" + content + "</color>";
        }

        public void WriteLine(string content, Color color)
        {
            text.text += "\n";
            Write(content, color);
        }

        public void Submit(string content)
        {
            OnInputSubmit?.Invoke(this, new TerminalEventArgs()
            {
                content = content
            });
        }
    }