Debug Console

ui The game must have a debug console, to allow team members to test any part of the game efficiently.

Warning

If you can find a Unity plugin or framework that gets all of this done (and that we have the right to use), please use it. It’s not worth making this all from scratch if there’s a library that handles it already.

Functionality

The debug console must be accessible using the / key on the keyboard.

• While the console is open, it must capture ALL keyboard input, preventing any input from passing through and affecting the game while the user is typing.
• Mouse clicks on the console area should be captured and ignored in the same way.

The debug console is composed of:

• a command line, where the user enters and executes their commands.
• a log, where the results of executed commands are dumped.

The debug console MUST only be accessible in development/testing builds of the game. Any build created for commercial use MUST NOT allow the user to open the debug console.

Controls

While the debug console is open:

• Pressing ESC must close the console, discarding whatever was typed in the command line at that time.
  • This behavior is ignored while cycling through autocomplete.
• Pressing Left Arrow or Right Arrow must move the cursor like in a typical text editor

Syntax

Based on Minecraft Bedrock’s command syntax. Each term is separated by a space.

Syntax	Meaning
plaintext	A literal string entered exactly as shown. Always used as the first entry/entries to define the command.
key: type	An argument called key, which supports a value with a certain type.
entry|entry	One of the given values must be chosen.
<entry>	Required.
[entry]	Optional.

Example Command

Definition: give <unit: string> <id: string> [quantity: int] Input: give brawler focus_crystal 1

Subcommands

Multiple plaintext entries should be used to create subcommands. For example:

give item <id: string> [quantity: int] [location: hand|deck] give status <target: string> <id: string> [stacks] [duration]

Autocomplete

Where possible, the console should show the user a list of all possible values for a particular entry in the command.

The autocomplete dialog must appear anytime the cursor is in a position to type an entry. For example:

• If the user has typed nothing, autocomplete should suggest all possible first values.
• If the user has typed part of a command and then entered a space, autocomplete should suggest all possible values for the term that should follow.
• If the user has typed a portion of an entry, the console should only provide suggestions that would complete that entry.

While cycling through entries:

• If the user pressesESC or moves the cursor away from the end of the current entry, autocompletion shall be cancelled.
  • Pressing ESC to cancel autocompletion should NOT close the console.
• If the user presses Down Arrow or Tab, the highlighted suggestion should cycle down to the next one in the list. If the last suggestion was already highlighted, it should cycle to the first suggestion.
• If the user presses Up Arrow, the highlighted suggestion should cycle up to the previous one in the list. If the first suggestion was already highlighted, it should cycle to the last suggestion.
• If the user presses Enter, the highlighted suggestion should be entered into the command, along with a Space char (to allow the user to type the next entry straight away).
• If the user presses any other key, the keystroke should be entered into the command as normal, and autocompletion should re-evaluate.

For entries whose value is an asset ID, such as an item ID, status ID or similar, the autocomplete should provide all possible options.

For entries whose value is an element in the current game state, such as a unit ID or similar, autocomplete should provide all elements within the current game state (fetched once, at the time the autocompletion for that entry first began).

Autocomplete should also apply to subcommands. For example, typing give and then pressing space must provide the suggestions item and status.

Command History

The debug console must store every command entered, even if they weren’t successful. This will allow the user to use Up Arrow and Down Arrow to cycle through previous commands.

Commands

Info

All of these commands are expected to log their results in the console log after execution. We are not going to specify what to log for every single command, but please implement appropriate error and success messages that tell the user what went wrong with their command.

For example:

• Item "nonexistent-item" not found tells the user they probably typed the item name incorrectly.
• Failed to give "Focus Crystal" to unit "Brawler" tells the user that their command was parsed properly, but the actual command execution failed (and therefore wasn’t an input error).

give item

Give a unit an item. give item <unit: string> <id: string> [quantity: int]

• unit - the string ID of a unit on the field.
• id - the string ID of the item to give.
• quantity - the quantity to give. Default 1.

give status

Apply a status effect to a unit. give status <unit: string> <id: string> [quantity: int]

• unit - the string ID of a unit on the field.
• id - the string ID of the status to apply.
• quantity - the amount of stacks of the effect to apply. Default 1.

skip turn

Ends the player’s turn, skips the enemy’s next turn and immediately begins another turn for the player. Must only be callable while it’s the player’s turn. skip turn

skip room

Completes the current room and proceeds to the map screen.

• If the player was in the middle of a battle, this command should simply kill every enemy, therefore winning the battle immediately, granting rewards, and proceeding to the map naturally from there. skip room

clear

Clear the console’s log. Must not clear command history. clear

testarea

Opens the Test Battle Scene. testarea

newrun

Opens the scene for a new run. newrun

Presentation

The debug console must follow these visual specifications:

• Aligned to the left of the screen
• Fills 100% of the screen height and 50% of the screen width
• Black background with 90% transparency
• White text
• Monospaced font
• The command line has a fixed height, enough to show one line, and does not wrap its text. Overflown text is simply hidden
• The command line and console log are visually separated by a horizontal white line