Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

输出面板

输出面板位于屏幕底部。点击 Output 即可打开它。

../../../_images/overview_output.webp

输出面板提供了多项功能,使查看项目(以及编辑器)输出的文本更加方便。

备注

默认情况下,运行项目时输出面板会自动打开。你可以通过修改 Run > Bottom Panel > Action on Play 编辑器设置来控制这一行为。

消息分类

消息分四种:

  • 日志:项目打印的标准信息。显示为白色或黑色(取决于编辑器主题)。

  • Error(错误) : 由项目或编辑器打印出的、表明出现了某种故障或问题的消息。在输出面板中会以红色显示。

  • Warning: 项目或编辑器输出的消息,用于报告重要信息,但并不表示发生了错误。显示为黄色。

  • 编辑器:编辑器打印的消息,通常用于跟踪撤销/重做操作。显示为灰色。

筛选消息

通过点击右侧的按钮,你可以隐藏某些消息类别。这样可以更方便地找到你正在寻找的特定消息。

你也可以利用输出(Output)面板底部的 Filter Messages (过滤消息)输入框,根据消息的文本内容来进行筛选。

清空消息

运行项目时,现有消息默认会被自动清除。该行为由 Run > Output > Always Clear Output on Play 编辑器设置控制。此外,你还可以点击输出面板右上角的“清洁刷”图标来手动清除消息。

打印消息

打印消息分以下几种方法:

  • print():打印一条消息。该方法接受多个参数,这些参数在打印时会被连接在一起。该方法还有会分别使用制表符和空格分隔参数的变体:printt()prints()

  • print_rich():和 print() 一样,但可以使用 BBCode 来格式化输出的文本(具体用法见下文)。

  • push_error(): 打印一条错误消息。当在一个正在运行的项目中打印错误时,它会显示在 Debugger > Errors (调试器 > 错误)标签页里,而不是普通的输出面板。

  • push_warning(): 打印一条警告消息。当在一个正在运行的项目中打印警告时,它会显示在 Debugger > Errors (调试器 > 错误)标签页里。

对于更复杂的用例,可以使用这些(方法/函数):

  • print_verbose():与 print() 相同,但仅在项目设置中启用了详细模式或使用 --verbose 命令行参数运行项目时才会打印。

  • printerr():与 print() 相同,但打印到标准错误流而不是标准输出字符串。在大多数情况下应该优先使用 push_error()

  • printraw():功能与 print() 相同,但输出末尾不附加空行。这是唯一不在编辑器输出面板中显示的方法,输出到标准输出流,因此仍会被包含在文件日志中。

  • print_debug() :功能与 print() 相同,但在末尾的新行上添加当前的调用栈帧(stack frame)。仅在从编辑器运行时,或项目以调试模式导出时才支持。

  • print_stack():从当前位置打印堆栈跟踪信息。仅在从编辑器运行时,或项目以调试模式导出时才支持。

  • print_tree():打印相对于当前节点的场景树结构,适用于调试运行时动态创建的节点结构。

  • print_tree_pretty():功能与 print_tree() 相同,但使用 Unicode 字符以呈现更接近树状结构的视觉效果。该功能依赖于 制表符(框线绘制字符),因此在某些字体下可能无法正确显示。

如果想要获得更高级的格式化能力,可以考虑配合使用 GDScript 格式字符串 以及上述的打印函数。

参见

引擎的日志功能在日志文档中有详细说明。

打印富文本

通过使用 print_rich(),你可以在编辑器的输出(Output)面板以及标准输出(即用户从终端/命令行运行项目时可见的窗口)中打印富文本。其原理是将 BBCode 转换成终端能够识别的 ANSI escape codes

在编辑器的输出面板中,所有的 BBCode 标签都会照常被识别。而在终端输出中,只有一部分 BBCode 标签能够生效,具体支持哪些标签,请参考上文链接中的 print_rich() 方法说明。另外,在终端里,颜色看起来会是什么样,取决于用户系统终端的主题设置;而在编辑器里,颜色则会使用与项目内部完全一致的显示效果。

备注

不同的终端模拟器对 ANSI 转义码的支持程度各不相同。另外,终端输出中显示的具体颜色,也取决于用户自己所选择的终端主题。