GFConsoleUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/debug/gf_console_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
运行时开发者控制台。 提供命令注册、解析与执行能力，并在初始化时构建覆盖全屏的调试 GUI。 默认通过快捷键呼出，同时会消费 GFLogUtility 的日志信号进行彩色输出。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | CommandTier |
enum CommandTier |
| 常量 | DANGER_CONFIRMATION_ARGUMENT |
const DANGER_CONFIRMATION_ARGUMENT: String = "--confirm" |
| 属性 | toggle_key |
var toggle_key: Key = KEY_F1 |
| 属性 | max_output_lines |
var max_output_lines: int = 1000: |
| 属性 | max_history_size |
var max_history_size: int = 100: |
| 属性 | background_alpha |
var background_alpha: float = 0.85: |
| 属性 | windowed |
var windowed: bool = false: |
| 属性 | initial_window_size_ratio |
var initial_window_size_ratio: Vector2 = Vector2(0.72, 0.55): |
| 属性 | minimum_window_size |
var minimum_window_size: Vector2 = Vector2(360.0, 220.0): |
| 属性 | keep_topmost |
var keep_topmost: bool = true: |
| 属性 | debug_only |
var debug_only: bool = true |
| 属性 | max_command_tier |
var max_command_tier: CommandTier = CommandTier.CONTROL |
| 属性 | require_danger_confirmation |
var require_danger_confirmation: bool = true |
| 方法 | init |
func init() -> void: |
| 方法 | ready |
func ready() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | register_command |
func register_command(cmd_name: String, callback: Callable, description: String, metadata: Dictionary = {}) -> void: |
| 方法 | register_command_definition |
func register_command_definition(definition: GFConsoleCommandDefinition, callback: Callable) -> void: |
| 方法 | unregister_command |
func unregister_command(cmd_name: String) -> void: |
| 方法 | has_command |
func has_command(cmd_name: String) -> bool: |
| 方法 | get_command_names |
func get_command_names() -> PackedStringArray: |
| 方法 | get_command_catalog |
func get_command_catalog() -> Dictionary: |
| 方法 | suggest_commands |
func suggest_commands(prefix: String) -> PackedStringArray: |
| 方法 | suggest_similar_commands |
func suggest_similar_commands(cmd_name: String, limit: int = 3, threshold: float = 0.5) -> PackedStringArray: |
| 方法 | execute_command |
func execute_command(raw_input: String) -> bool: |
| 方法 | append_output_line |
func append_output_line(bbcode_line: String) -> void: |
| 方法 | append_output_lines |
func append_output_lines(bbcode_lines: PackedStringArray) -> void: |
| 方法 | clear_output |
func clear_output() -> void: |
| 方法 | flush_output |
func flush_output() -> void: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
枚举¶
CommandTier¶
- API：
public
控制台命令风险等级。
常量¶
DANGER_CONFIRMATION_ARGUMENT¶
- API：
public
DANGER 命令的确认参数。
属性¶
toggle_key¶
- API：
public
呼出或隐藏控制台的快捷键；默认为 KEY_F1。
max_output_lines¶
- API：
public
控制台最多保留的输出行数，避免高频日志无限增长。
max_history_size¶
- API：
public
控制台最多保留的历史命令数量。
background_alpha¶
- API：
public
控制台背景透明度，范围 0 到 1。
windowed¶
- API：
public
是否使用可拖拽、可缩放的窗口模式。默认 false 保持全屏覆盖。
initial_window_size_ratio¶
- API：
public
窗口模式初始尺寸相对视口比例。
minimum_window_size¶
- API：
public
窗口模式最小尺寸。
keep_topmost¶
- API：
public
是否把控制台放在较高 CanvasLayer 层级。
debug_only¶
- API：
public
是否只在 debug 构建中创建控制台 GUI。发布构建需要显式关闭此项才会创建控制台。
max_command_tier¶
- API：
public
允许执行的最高命令风险等级。
require_danger_confirmation¶
- API：
public
执行 DANGER 命令时是否要求传入 --confirm 参数。
方法¶
init¶
- API：
public
初始化控制台命令表和运行时 GUI。
ready¶
- API：
public
连接日志工具信号。
dispose¶
- API：
public
释放 GUI 并断开日志信号。
register_command¶
- API：
public
func register_command(cmd_name: String, callback: Callable, description: String, metadata: Dictionary = {}) -> void:
注册控制台命令。
参数：
| 名称 | 说明 |
|---|---|
cmd_name |
指令名称。 |
callback |
指令回调，签名为 func(args: PackedStringArray) -> void。 |
description |
指令说明文本。 |
metadata |
项目自定义元数据。 |
结构：
metadata: Dictionary，支持 tier 等项目自定义命令元数据。
register_command_definition¶
- API：
public
func register_command_definition(definition: GFConsoleCommandDefinition, callback: Callable) -> void:
注册资源化控制台命令。
参数：
| 名称 | 说明 |
|---|---|
definition |
命令资源定义。 |
callback |
指令回调，签名为 func(args: PackedStringArray) -> void。 |
unregister_command¶
- API：
public
注销控制台命令。
参数：
| 名称 | 说明 |
|---|---|
cmd_name |
指令名称。 |
has_command¶
- API：
public
检查控制台命令是否已注册。
参数：
| 名称 | 说明 |
|---|---|
cmd_name |
指令名称。 |
返回：已注册返回 true。
get_command_names¶
- API：
public
获取当前已注册命令名称。
返回：排序后的命令名称数组。
get_command_catalog¶
- API：
public
获取控制台命令目录。
返回：命令元数据字典。
结构：
return: Dictionary[String, Dictionary]，每个值包含 description、metadata 和 tier。
suggest_commands¶
- API：
public
根据前缀获取命令补全候选。
参数：
| 名称 | 说明 |
|---|---|
prefix |
命令名前缀。 |
返回：排序后的候选命令名数组。
suggest_similar_commands¶
- API：
public
func suggest_similar_commands(cmd_name: String, limit: int = 3, threshold: float = 0.5) -> PackedStringArray:
根据字符串相似度获取可能的命令名，用于未知命令诊断。
参数：
| 名称 | 说明 |
|---|---|
cmd_name |
用户输入的命令名。 |
limit |
最多返回的候选数量。 |
threshold |
最低相似度，范围 0 到 1。 |
返回：按相似度降序排列的候选命令名。
execute_command¶
- API：
public
解析并执行一条原始输入。
参数：
| 名称 | 说明 |
|---|---|
raw_input |
用户输入的完整字符串。 |
返回：找到并成功执行命令时返回 true。
append_output_line¶
- API：
public
向控制台输出追加一行 BBCode 文本。
参数：
| 名称 | 说明 |
|---|---|
bbcode_line |
要追加的一行 BBCode 文本。 |
append_output_lines¶
- API：
public
向控制台输出追加多行 BBCode 文本。
参数：
| 名称 | 说明 |
|---|---|
bbcode_lines |
要追加的 BBCode 文本行列表。 |
clear_output¶
- API：
public
清空控制台输出。
flush_output¶
- API：
public
立即刷新待追加的控制台输出。
get_debug_snapshot¶
- API：
public
获取控制台调试快照。
返回：控制台命令、GUI 和配置状态。
结构：
return: Dictionary，包含 command_count、command_names、command_catalog、has_console_gui、gui、配置字段。