Documentation - hibzzgames/com.hibzz.console GitHub Wiki

Getting Started

The hibzz.console package is a tool and framework used to add an in-game console for games made in Unity. This package can be installed in the Unity Package Manager using the following git URL.

https://github.com/Hibzz-Games/com.hibzz.console.git

Or, a better way to add it is using a scoped registry since the package is also published to NPM. To do so, from the package manager, go to advanced project settings where you can add new scoped registries. Here use https://registry.npmjs.org as the URL and add com.hibzz.console as a scope. Now under the package manager, you'll be able to view and install this package under "My Registries". By adding it as a scoped registry, you'll be able to choose the version you want to install as well as get updates directly from the package manager.

Once the package is installed, go to the hierarchy window and right-click to add a new gameobject under Custom > Hibzz.Console. Note that only one instance of the console can exist at a time and any added instances will be removed automatically when entering play mode. Just to be safe, press the "Scan for Commands" button from the unity inspector so that the console is up to date on all commands.

By default, the Slash button (/) is used as the prefix and activates the keyboard console. This can be modified easily in the prefab. You may also change the default log color from here.

Creating custom commands

Creating custom commands is a two-step process: Creating the custom console command script, then creating the console command asset. Below is a template on how to format a custom command script while using the hibzz.console framework.

using UnityEngine;
using Hibzz.Console;

[CommandTooltip("Tooltip for what this console command does goes here")]        // optional
[CreateAssetMenu(fileName = "exampleCmd", menuName = "Console/Custom/Example")] // creates an asset menu from which the console command asset can be created
public class CustomCommandExample : ConsoleCommand
{
	// default constructor is used to set the default values when creating the console command asset
	public CustomCommandExample()
	{
		CommandWord = "example";    // by default /example is used to execute the command
		RequiresAdminAccess = true; // by default this command can only be executed when the player has admin access
		IncludeInScan = true;       // by default this command gets included in automatic command scan
	}

	// whenever the player enters the command, this function is called with a list of space-separated strings as args
	public override bool Process(string[] args)
	{
		Console.Log("example message with first args = " + args[0]); // Prints the message with the first args in default color
		Console.Log("Yellow Message", Color.yellow);                 // Prints the message in yellow color
		return true;                                                 // if the command executes successfully return true, else false
	}

	// [OPTIONAL] This is used to handle secure input, if the console commands wants to use the Console.RequestSecureInput API
	public override void HandleSecureInput(string secureInput)
	{
		// Handle the secure input here
	}
}

The next step is to create the console command asset. To do so, go to the asset browser and right-click and navigate to the create menu. From there you can navigate through the dropdown lists as specified in the menuName in the script above. Here is a reference image that represents how to navigate and create the example console command asset scripted above.

After creating the console command asset, the asset lets the users modify the commands how they want. By default, the users can change the Command Word, choose if they want to mark the asset as an admin-only command, or if they want to mark the asset to be ignored in the automatic scan. While writing the custom command scripts, the users can also specify additional properties like the password field in the built-in console command called AdminPassword.

API Functions

Console.Log(string message); - Prints the message

Console.Log(string message, Color color); - Prints the message with the given color

Console.Clear(); - Clears the console log

Console.RequestAdminAccess(); - Grants console admin access

Console.RevokeAdminAccess(); - Revokes console admin access

Console.PostError(string message) - Display an error message

Console.PostWarning(string message) - Display a warning message

Console.PostInfo(string message) - Display an info message

Console.PostSuccess(string message) - Display a success message

Console.Width(float width) - Sets the width of the console

Console.Height(float height) - Sets the height of the console

Console.RequestSecureInput(ConsoleCommand command, string placeholder = "SECURE INPUT") - Used to request a secure input where the input can be handled by the ConsoleCommand's HandleSecureInput function.

API Properties

bool Console.IsHovered - Is the mouse hovering the console UI? (Helpful in preventing input bleeding)

bool Console.IsTextboxFocused - Is the console textbox focused at the moment? (Helpful in preventing input bleeding)

Dictionary<string, Object> Console.CacheDictionary - A dictionary to store cache results and intermediary values that can be used in the next process

Hibzz.DefineManager

This package supports Hibzz.DefineManager to enable optional features. The optional features include:

Pre-built Commands - When enabled, this package provides optional pre-built scripts that can give quick access to certain useful commands.
Cache Dictionary - Cache Dictionary is a tool provided by the Console that let's commands cache and store data to communicate with each other.

Built-in console commands

Here is a list of built-in commands available with hibzz.console:

/clear - clears the console logs
/version - prints the version of the game
/console.help - prints a link to the hibzz.console github repository
/admin - opens a secure input field that can be used to enter passwords, and when it matches, grants admin access
/admin -r - revokes admin access to the console commands