Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Performance

继承: Object

公开与性能相关的数据。

描述

该类提供对许多与性能相关的不同监视器的访问,例如内存使用情况、绘制调用、和 FPS。这些值与编辑器的调试器面板中的监视选项卡中显示的值相同。通过使用该类的 get_monitor 方法,你可以从代码中访问该数据。

可以使用 add_custom_monitor 方法添加自定义监视器。在编辑器的调试器面板的监视选项卡中,自定义监视器可以与内置监视器一起使用。

注意:某些内置监视器仅在调试模式下可用,并且在以发布模式导出的项目中使用时,将始终返回 0

注意:出于性能原因,某些内置监视器不会实时更新,所以在更改之间可能会有长达 1 秒的延迟。

注意:自定义监视器不支持负值。负值被钳制为 0。

方法

void

add_custom_monitor ( StringName id, Callable callable, Array arguments=[] )

Variant

get_custom_monitor ( StringName id )

StringName[]

get_custom_monitor_names ( )

float

get_monitor ( Monitor monitor ) const

int

get_monitor_modification_time ( )

bool

has_custom_monitor ( StringName id )

void

remove_custom_monitor ( StringName id )


枚举

enum Monitor:

Monitor TIME_FPS = 0

上一秒渲染的帧数。该指标每秒仅更新一次,与查询频率无关。越高越好。

Monitor TIME_PROCESS = 1

完成一帧所需的时间,单位为秒。越低越好。

Monitor TIME_PHYSICS_PROCESS = 2

完成一个物理帧所需的时间,单位为秒。越低越好。

Monitor TIME_NAVIGATION_PROCESS = 3

完成一个导航步骤的时间,单位为秒。包括导航地图的更新以及代理避障的计算。越低越好。

Monitor MEMORY_STATIC = 4

当前使用的静态内存,单位为字节。在发布版本中不可用。越低越好。

Monitor MEMORY_STATIC_MAX = 5

可用的静态内存。在发布版本中不可用。越低越好。

Monitor MEMORY_MESSAGE_BUFFER_MAX = 6

消息队列缓冲区已使用的最大内存量,单位为字节。消息队列用于延迟函数调用和通知。越低越好。

Monitor OBJECT_COUNT = 7

当前实例化的对象数(包括节点)。越低越好。

Monitor OBJECT_RESOURCE_COUNT = 8

当前使用的资源数。越低越好。

Monitor OBJECT_NODE_COUNT = 9

当前在场景树中实例化的节点数。也包括根节点。越低越好。

Monitor OBJECT_ORPHAN_NODE_COUNT = 10

孤立节点的数量,即父节点不是场景树节点的节点。越低越好。

Monitor RENDER_TOTAL_OBJECTS_IN_FRAME = 11

在上一个渲染帧中的对象总数。该指标不包括剔除的对象(通过隐藏节点、视锥剔除、或遮挡剔除)。越低越好。

Monitor RENDER_TOTAL_PRIMITIVES_IN_FRAME = 12

在上一个渲染帧中渲染的顶点或索引的总数。该指标不包括来自被剔除对象的图元(通过隐藏节点、视锥剔除、或遮挡剔除)。由于预深度阶段和阴影阶段,图元的数量总是高于场景中的实际顶点数量(通常是原始顶点数量的两倍或三倍)。越低越好。

Monitor RENDER_TOTAL_DRAW_CALLS_IN_FRAME = 13

在上一个渲染帧中执行的绘制调用的总数。该指标不包括剔除对象(通过隐藏节点、视锥剔除、或遮挡剔除),因为它们不会导致绘制调用。越低越好。

Monitor RENDER_VIDEO_MEM_USED = 14

显存的使用量(纹理和顶点内存之和,单位为字节)。由于该指标还包括其他杂项分配,因此该值始终大于 RENDER_TEXTURE_MEM_USEDRENDER_BUFFER_MEM_USED 的总和。越低越好。

Monitor RENDER_TEXTURE_MEM_USED = 15

纹理内存的使用量(单位为字节)。越低越好。

Monitor RENDER_BUFFER_MEM_USED = 16

渲染缓冲区内存的使用量(单位为字节)。越低越好。

Monitor PHYSICS_2D_ACTIVE_OBJECTS = 17

游戏中活跃的 RigidBody2D 节点数。越低越好。

Monitor PHYSICS_2D_COLLISION_PAIRS = 18

2D 物理引擎中碰撞对的数量。越低越好。

Monitor PHYSICS_2D_ISLAND_COUNT = 19

2D 物理引擎中孤岛的数量。越低越好。

Monitor PHYSICS_3D_ACTIVE_OBJECTS = 20

游戏中活跃的 RigidBody3DVehicleBody3D 节点数。越低越好。

Monitor PHYSICS_3D_COLLISION_PAIRS = 21

3D 物理引擎中碰撞对的数量。越低越好。

Monitor PHYSICS_3D_ISLAND_COUNT = 22

3D 物理引擎中孤岛的数量。越低越好。

Monitor AUDIO_OUTPUT_LATENCY = 23

AudioServer 的输出延迟。相当于调用 AudioServer.get_output_latency,不建议每帧都调用该方法。

Monitor NAVIGATION_ACTIVE_MAPS = 24

NavigationServer3D 中活动导航地图的数量。也包含 World2D 和 World3D 所创建的两张默认导航地图。

Monitor NAVIGATION_REGION_COUNT = 25

NavigationServer3D 中活动导航地区的数量。

Monitor NAVIGATION_AGENT_COUNT = 26

NavigationServer3D 中正在处理避障的活动导航代理的数量。

NavigationServer3D 中活动导航链接的数量。

Monitor NAVIGATION_POLYGON_COUNT = 28

NavigationServer3D 中导航网格多边形的数量。

Monitor NAVIGATION_EDGE_COUNT = 29

NavigationServer3D 中导航网格多边形边缘的数量。

Monitor NAVIGATION_EDGE_MERGE_COUNT = 30

NavigationServer3D 中由于边键重叠而被合并的导航网格多边形的边的数量。

Monitor NAVIGATION_EDGE_CONNECTION_COUNT = 31

NavigationServer3D 中由边缘接近而被认为已连接的多边形的边的数量。

Monitor NAVIGATION_EDGE_FREE_COUNT = 32

NavigationServer3D 中无法合并的导航网格多边形的边的数量。这些边仍然可以通过边缘接近或使用链接而被连接。

Monitor MONITOR_MAX = 33

代表 Monitor 枚举的大小。


方法说明

void add_custom_monitor ( StringName id, Callable callable, Array arguments=[] )

添加一个名为 id 的自定义监视器。可以在 id 中使用斜线分隔符指定监视器的类别(例如:"Game/NumberOfNPCs")。如果有多个斜线分隔符,则使用默认的类别。默认类别是 "Custom"。如果给定的 id 已经存在,则打印一个错误。

func _ready():
    var monitor_value = Callable(self, "get_monitor_value")

    # 将名称为“MyName”的监视器添加到类别“MyCategory”。
    Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value)

    # 将名称为“MyName”的监视器添加到类别“Custom”。
    # 注意:“MyCategory/MyMonitor”和“MyMonitor”同名但不同 ID,所以代码有效。
    Performance.add_custom_monitor("MyMonitor", monitor_value)

    # 将名称为“MyName”的监视器添加到类别“Custom”。
    # 注意:“MyMonitor”和“Custom/MyMonitor”名称相同,类别相同,但 ID 不同,所以代码有效。
    Performance.add_custom_monitor("Custom/MyMonitor", monitor_value)

    # 将名称为“MyCategoryOne/MyCategoryTwo/MyMonitor”的监视器添加到类别“Custom”。
    Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitor_value)

func get_monitor_value():
    return randi() % 25

调试器调用可调用对象来获取自定义监视器的值。可调用对象必须返回一个零或正整数或浮点数。

使用参数数组中提供的参数来调用可调用对象。


Variant get_custom_monitor ( StringName id )

返回具有给定 id 的自定义监视器的值。调用这个可调用对象以获取自定义监视器的值。另请参阅 has_custom_monitor。如果给定的 id 不存在,则打印一个错误。


StringName[] get_custom_monitor_names ( )

以一个 Array,返回活动自定义监视器的名称。


float get_monitor ( Monitor monitor ) const

返回任一可用的内置监视器的值。应该提供任一 Monitor 常量作为参数,如下所示:

print(Performance.get_monitor(Performance.TIME_FPS)) # 将 FPS 打印到控制台。

请参阅 get_custom_monitor,以查询自定义性能监视器的值。


int get_monitor_modification_time ( )

返回自定义监视器被添加/删除时的最后一个刻度(自引擎启动以来的微秒数)。当该监视器更新时,它被设置为 Time.get_ticks_usec


bool has_custom_monitor ( StringName id )

如果存在具有给定 id 的自定义监视器,则返回 true,否则返回 false


void remove_custom_monitor ( StringName id )

移除具有给定 id 的自定义监视器。如果给定的 id 已经不存在,则打印一个错误。