An easy-to-use Source Engine inspired game console for Godot with history, autocomplete, and the ability to manipulate any Godot Node
s.
- Examples
- Adding to a Godot Project
- Usage
- Adding Custom Commands
- Command Argument Types
- Default Commands
- Future
- LICENSE
NB: These Examples are from a stylistically-lowres game! The font will not be pixelated or fuzzy under normal use. The font used is a standard true type font (Inconsolata, similar to Microsoft's Consolas).
-
If you don't already have an
addon
folder in your Godot project create one (res://addons/
) -
Submodule this repository into
res://addons/godot_console
, fromres://
(project root) run:git submodule add https://github.com/bpharris/godot-console.git addons/godot_console/
NB: The addon folder must be
godot_console
verbatim or Godot will not correctly register the plugin. -
For the
Console
to work you will also need to create anautoload
script calledGlobals
and add to it the following:var console_commands := {}
I would recommend having a
Globals.gd
autoload regardless of the use of theConsole
as it allows one to track values across scenes (such as a player inventory, etc), though one should obviously be conservative about what one puts in the global autoload. -
In your Godot project go to
Project > Project Settings... > Plugins
and set the console to active. -
To add the console to a scene click create a new child node (as you would with a native Godot node such as
KinematicBody2D
, not an instanced scene) and search for console. Select the listedConsole
node and click 'Create'. NB: TheConsole
node should be underNode > CanvasItem > Control > Console
.NB: It is recommended you add it to your Player UI/HUD so that a singular console is accessible in all scences. For example:
Player (Type: KinematicBody) ├─ Mesh ├─ AnimationPlayer ├─ ... └── UI (Type: Control) ├─ ... ├─ ... └─ Console
Image example from a game of mine:
-
Select the newly created
Console
node and, in the editor, set the layout to 'Full Rect' (Layout > Full Rect
). -
Ensure that your Godot project has a key assigned to 'dev_toggle_console' (
Project > Project Settings... > Input Map
) -
Enjoy!
To use the console, simply press the 'dev_toggle_console' key to open the console,
type a command, and press 'ui_enter'. The console comes with a help
command built-in for help with commands, for example:
> help echo
echo <output : Variant> - echo the given argument
> help help
help <command_name : String> - display the given command's help message
but with prettier colours!
Simply call $console.add_command(
args)
where $console
is a reference to the
console node. The method implementing the command must return a CommandResponse instance. Below are the exact rules, but they may be a bit confusing at first -- if so take a look at the example and you will see it is quite simple really!
Custom command arguments:
-
name
: The name the command will registered as -
command_arguments
: The names and types of the command/method arguments (default =[]
) (type:Array[Array[argument_name : String, argument_type : Type]]
) -
parent_node
: A refence the node that stores the method that implements the command (usuallyself
) -
method_name
: The name of the method that implements the command (default =name
) -
description
: A description of the commands function, displayed by thehelp
command (default ='no description given'
) -
help
: A help string for the command, usually a usage style string (default = automatically derived).Unless you want to specifically override the automatically generated help string (which is quite good and have highlighting, see the examples in Usage) you should omit this argument.
Type hints omitted in examples for better syntax highlighting on GitHub (though most people don't use them anyways).
Example (given that console
is a reference to a Console
node):
func _ready():
console.add_command(
'my_command', # Command name
[['x', TYPE_INT], ['s', TYPE_STRING]], # Command args, [] for no args
self, # Object containing method
'_my_command', # Method implementing command
'this is my custom command' # Command description
# Help string omitted (autogenerated)
)
func _my_command(x, s):
# Your command logic here
...
# If command with no output
if no_ouput:
# Can use static method "return GDConsole.response_empty()" as shorthand
return CommandResponse.new(CommandResponse.ResponseType.EMPTY)
# On error
if error:
# Can use static method "return GDConsole.response_error('desc. of err')" as shorthand
return CommandResponse.new(CommandResponse.ResponseType.ERROR, 'description of error')
# Can use static method "return GDConsole.response_result('result string')" as shorthand
return CommandResponse.new(CommandResponse.ResponseType.RESULT, 'result/response as string')
For info on the command argument types see the 'Command Argument Types' section below.
Worked example of the echo
command:
func _ready():
add_command('echo', [['output', TYPE_NIL]], self, '_command_echo', 'echo the given argument')
func _command_echo(output):
"""Echo the output string."""
return GDConsole.response_result(str(output))
It's that simple! For more example see add_default_commands
and _command_*
in ./Console.gd
.
In use:
> help echo
echo <output : Variant> - echo the given argument
> echo 4
4
> echo test
test
> echo "a long string"
a long string
See ./Command/Types.gd
for even more info and implementation.
Argument Types:
- TYPE_NIL (GDScript
Variant
, i.e. dynamicly typed) - TYPE_BOOL (GDScript
bool
, e.g.true
) - TYPE_INT (GDScript
int
, e.g.4
) - TYPE_REAL (GDScript
float
, e.g.3.2
) - TYPE_STRING (GDScript
String
, e.g.'a sring'
) - TYPE_NODE_PATH (GDScript
NodePath
, i.e. aNodePath()
instance)
The identifiers TYPE_NIL, TYPE_INT, etc are provided by GDScript (as part of @GlobalScope
) in the enum Variant.Type
.
Current:
clear
: clears the console outputhelp
: prints the help message to the consoleexit
: closes the consolequit
: quits the gameecho
: takes a string and prints it to the consoleprint_tree
: print the full scene tree to the consoleprint_children
: print the given node's children (i.e. print the subtree for which the given node is the root)list
: list the registered commands
Comming soon:
info
/debug
/warn
/error
?bind
/unbind
Todo:
- Remove need for autoload script?
- Implement command history
- Add aliases?
See the LICENSE file (MIT License)
Feel free to suggest improvements, contribute code, etc!
If you use the console in your game please let me know! I would love to hear about it. :)