Performance

继承： Object

公开与性能相关的数据。

描述

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

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

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

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

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

方法

void

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

Variant

get_custom_monitor(id: StringName)

Array[StringName]

get_custom_monitor_names()

float

get_monitor(monitor: Monitor) const

int

get_monitor_modification_time()

bool

has_custom_monitor(id: StringName)

void

remove_custom_monitor(id: StringName)

枚举

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_USED 和 RENDER_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

游戏中活跃的 RigidBody3D 和 VehicleBody3D 节点数。越低越好。

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 中正在处理避障的活动导航代理的数量。

Monitor NAVIGATION_LINK_COUNT = 27

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(id: StringName, callable: Callable, arguments: Array = []) 🔗

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

GDScriptC#

  1. func _ready():
  2.     var monitor_value = Callable(self, "get_monitor_value")
  4.     # 将名称为“MyName”的监视器添加到类别“MyCategory”。
  5.     Performance.add_custom_monitor("MyCategory/MyMonitor", monitor_value)
  7.     # 将名称为“MyName”的监视器添加到类别“Custom”。
  8.     # 注意：“MyCategory/MyMonitor”和“MyMonitor”同名但不同 ID，所以代码有效。
  9.     Performance.add_custom_monitor("MyMonitor", monitor_value)
  11.     # 将名称为“MyName”的监视器添加到类别“Custom”。
  12.     # 注意：“MyMonitor”和“Custom/MyMonitor”名称相同，类别相同，但 ID 不同，所以代码有效。
  13.     Performance.add_custom_monitor("Custom/MyMonitor", monitor_value)
  15.     # 将名称为“MyCategoryOne/MyCategoryTwo/MyMonitor”的监视器添加到类别“Custom”。
  16.     Performance.add_custom_monitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitor_value)
  18. func get_monitor_value():
  19.     return randi() % 25
  1. public override void _Ready()
  2. {
  3.     var monitorValue = new Callable(this, MethodName.GetMonitorValue);
  5.     // 将名称为“MyName”的监视器添加到类别“MyCategory”。
  6.     Performance.AddCustomMonitor("MyCategory/MyMonitor", monitorValue);
  7.     // 将名称为“MyName”的监视器添加到类别“Custom”。
  8.     // 注意：“MyCategory/MyMonitor”和“MyMonitor”同名但不同 ID，所以代码有效。
  9.     Performance.AddCustomMonitor("MyMonitor", monitorValue);
  11.     // 将名称为“MyName”的监视器添加到类别“Custom”。
  12.     // 注意：“MyMonitor”和“Custom/MyMonitor”名称相同，类别相同，但 ID 不同，所以代码有效。
  13.     Performance.AddCustomMonitor("Custom/MyMonitor", monitorValue);
  15.     // 将名称为“MyCategoryOne/MyCategoryTwo/MyMonitor”的监视器添加到类别“Custom”。
  16.     Performance.AddCustomMonitor("MyCategoryOne/MyCategoryTwo/MyMonitor", monitorValue);
  17. }
  19. public int GetMonitorValue()
  20. {
  21.     return GD.Randi() % 25;
  22. }

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

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

Variant get_custom_monitor(id: StringName) 🔗

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

Array[StringName] get_custom_monitor_names() 🔗

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

float get_monitor(monitor: Monitor) const 🔗

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

GDScriptC#

  1. print(Performance.get_monitor(Performance.TIME_FPS)) # 将 FPS 打印到控制台。
  1. GD.Print(Performance.GetMonitor(Performance.Monitor.TimeFps)); // 将 FPS 打印到控制台。

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

int get_monitor_modification_time() 🔗

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

bool has_custom_monitor(id: StringName) 🔗

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

void remove_custom_monitor(id: StringName) 🔗

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