GDKonsole

A simple Quake-style developer console for Godot 4. Drop it into any project to get an in-game terminal for debugging, running commands, and building developer tools — without touching your game logic.

---

Features

• Lightweight — no dependencies, pure GDScript
• Print messages, allow code execution directly from the console
• Register custom commands with typed arguments, and default values
• Register CVars — named runtime variables you can read and set from the console
• Autocomplete based on registered commands.
• Error handling, and Godot debugger redirection
• Commands history

---

Installation

1. Clone repository or Download the lastest release
2. Copy the addons/gdkonsole/ folder into your project's addons/ directory.
3. Enable the plugin in Project → Project Settings → Plugins.
4. GDKonsole will register itself as an autoload — no scene setup required.
5. Set the desired toggle key in Actions

NOTE: Plugin injects an action called "gdkonsole_toggle" when enabled. Sometimes, it requires to restart Godot to appear. (or reload project)

---

Usage

Opening the console

Press the toggle key (not bound by default) during runtime to open or close the console.

Writing to the console

You can write text to the console using the following API calls: Console uses Godot RichTextLabel BBCode (reference manual)

GDKonsole.write("Hello, world!");
GDKonsole.write("Hello, yellow world!", Color.Yellow); # Console supports color

GDKonsole.write_line("This gets its own line.");

GDKonsole.write_line("[bgcolor=green]Let's touch some grass![/bgcolor]"); # Write BBCode

Registering commands

Commands map a string to an object and method name.

The most basic command creation will be

GDKonsole.add_command("test", self, "test_something");

You can add descriptions to your commands

GDKonsole.add_command("kill_anything", actor_manager, "kill_any") \
    .set_description("Randomly kills an actor in scene");

Add arguments, that can be of any type supported by Variant.Type Godot enum. Internally, GDKonsole uses Godot str_to_var to convert types.

GDKonsole.add_command("kill_player", actor_manager, "kill_player") \
    .add_argument("player_id", TYPE_INT) \
    .set_description("Kill player identified by player_id");

Bools will be parsed from ints (0=false, any other value=true) or true/false strings.

The third parameter of "add_argument" sets default value

GDKonsole.add_command("enable_cheats", game_manager, "enable_cheats") \
    .add_argument("enable", TYPE_BOOL, false) \
    .set_description("Allow use of cheats");

Commands are called when the user types their name and presses Enter.

Registering CVars

CVars (Console Variables) are named variables bound to properties on your objects.

Bind any property on any object:

GDKonsole.add_cvar("sv_gravity", physics_manager, "gravity") \
    .set_description("World gravity value");

To read a CVar value, just type it, and autocomplete will show the current value. NOTE: autocomplete shown value is captured at time of writing, and not kept up to date.

To set a CVar value, enter it, and give the value like so:

sv_gravity 500.0

Interacting with GDKonsole

The console binds signals to Commands, you can connect them and perform actions when signal triggers

var my_cmd = GDKonsole.add_command("destroy_world", world_manager, "destroy");

await my_cmd.called;
print("The command was called!");

CVars also provide signals:

var my_cvar = GDKonsole.add_cvar("sv_gravity", physics_manager, "gravity");

var value = await my_cvar.value_set;
print("Value was set to %d via console!" % value);

Customizing GDKonsole

The console comes with a default theme. There are two ways to customize it:

Change only colors

Colors can be changed by overriding them directly on GDKonsole object

GDKonsole.colors.background = Color.Red;
GDKonsole.colors.default = Color("#ffffff");

Change console theme

If you want the console to match your theme, simply override its theme using

GDKonsole.override_theme(my_theme); # my_theme is a Resource of type Theme

Configure features

A file config.gd exists at root folder of theme implementing all variables used by GDKonsole. Any config variable can be overriden, directly on GDKonsole object

GDKonsole.config.enable_log_to_file = true;
GDKonsole.config.max_lines = 800;

Builtins

echo text:String Prints text to console commands Shows all existing commands cvars Shows all registered CVars exec path:String Executes a file containing commands from given path (line by line) eval gdscript:String Evaluates a snippet of GDScript and prints result inspect <node_path:String> Inspects node at node_path

---

Requirements

• Godot 4.x

---

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repository
2. Create a branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push: git push origin feature/my-feature
5. Open a Pull Request Please keep PRs focused — one feature or fix per PR makes review easier.

---

License

This project is licensed under the MIT License.