DebugService

Debug 调试信息服务，提供单位模型面数/物理面数、碰撞体信息、空间区域统计与全场景统计等调试信息查询。

Overview

SE 编辑器专属的调试信息服务，用于在开发阶段查询单位的渲染模型面数与物理碰撞面数、碰撞体体积及包围盒范围等指标，也支持按世界坐标区域（AABB）检索该区域内的单位及面数统计。针对单位或场景的层级明细查询结果会以 JSON 形式写入用户工程目录下的 debug_info 文件夹并返回绝对路径，方便排查模型与碰撞体结构。

Get by:

-- @runtime client
local service = editor:GetService("Debug")

Public

GetUnitModelFaceCount

获取单位模型的整体面数，返回整型数值；可通过可选参数控制是否包含子级。

参数

参数	类型	说明
unit	Unit	要查询的单位对象
includeChildren	Bool	是否包含子组件；默认 true

返回值

类型	说明
Int	模型面数

查询场景首个单位的模型面数

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
print(debugService:GetUnitModelFaceCount(unit, true))

GetUnitPhysicsFaceCount

获取单位物理碰撞体的面数，返回整型数值；可通过可选参数控制是否包含子级。

参数

参数	类型	说明
unit	Unit	要查询的单位对象
includeChildren	Bool	是否包含子组件；默认 true

返回值

类型	说明
Int	物理碰撞体面数

查询场景首个单位的物理面数

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
print(debugService:GetUnitPhysicsFaceCount(unit, true))

GetUnitDebugInfo

获取指定单位的调试信息并写入 JSON 文件；可通过参数控制是否包含子级以及输出文件名，返回 JSON 文件的绝对路径。

注意： 该方法会在用户 Lua 工程的 debug_info 目录写入 JSON 文件。

参数

参数	类型	说明
unit	Unit	要查询的单位对象
includeChildren	Bool	是否按父子层级展开子组件；默认 true
fileName	String	输出文件名；默认 unit_face_info_<时间戳>.json

返回值

类型	说明
String	JSON 文件绝对路径；写入失败返回空字符串

导出场景首个单位的调试信息

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
local path = debugService:GetUnitDebugInfo(unit, true, "documentation_unit_debug.json")
print("调试信息文件:", path)

GetUnitCollisionFaceCount

获取指定单位碰撞体的面数，返回整型数值。

参数

参数	类型	说明
unit	Unit	要查询的单位对象

返回值

类型	说明
Int	碰撞体面数

查询场景首个单位的碰撞体面数

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
print(debugService:GetUnitCollisionFaceCount(unit))

GetUnitCollisionVolume

获取单位碰撞体包围盒的体积，返回数值结果。

参数

参数	类型	说明
unit	Unit	要查询的单位对象

返回值

类型	说明
Number	碰撞体包围盒体积

查询场景首个单位的碰撞体体积

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
print(debugService:GetUnitCollisionVolume(unit))

GetUnitCollisionExtent

获取单位碰撞体的包围盒尺寸，返回格式为 [x, y, z] 的数组。

参数

参数	类型	说明
unit	Unit	要查询的单位对象

返回值

类型	说明
Array	包围盒尺寸 [x, y, z]

查询场景首个单位的碰撞体尺寸

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
local extent = debugService:GetUnitCollisionExtent(unit)
print(extent[1], extent[2], extent[3])

GetUnitCollisionWorldPosition

获取单位碰撞体在场景世界坐标系中的位置，返回格式为 [x, y, z] 的数组。

参数

参数	类型	说明
unit	Unit	要查询的单位对象

返回值

类型	说明
Array	碰撞体世界坐标 [x, y, z]

查询场景首个单位的碰撞体世界坐标

-- @runtime client
local units = editor:GetService("World"):GetDescendants()
local unit = units[1]
if unit == nil then return end
local debugService = editor:GetService("Debug")
local position = debugService:GetUnitCollisionWorldPosition(unit)
print(position[1], position[2], position[3])

GetRegionFaceInfo

统计指定区域内的模型面数、物理面数和单位数，并以表的形式返回这三项调试信息。

参数

参数	类型	说明
minPos	Array	区域最小角点 [x, y, z]；也接受 Vector3
maxPos	Array	区域最大角点 [x, y, z]；也接受 Vector3

返回值

类型	说明
Table	区域调试信息 {模型面数, 物理面数, 单位数}

统计原点附近区域的调试信息

-- @runtime client
local debugService = editor:GetService("Debug")
local info = debugService:GetRegionFaceInfo({-100, -100, -100}, {100, 100, 100})
print("区域单位数:", info["单位数"])

GetRegionUnits

获取指定坐标范围内的单位对象列表，返回一个单位数组。

参数

参数	类型	说明
minPos	Array	区域最小角点 [x, y, z]；也接受 Vector3
maxPos	Array	区域最大角点 [x, y, z]；也接受 Vector3

返回值

类型	说明
Array	区域内的单位对象列表

获取原点附近区域的单位

-- @runtime client
local debugService = editor:GetService("Debug")
local units = debugService:GetRegionUnits({-100, -100, -100}, {100, 100, 100})
print("区域单位数:", #units)

GetSceneFaceInfo

获取整个场景的面数统计等调试信息，并写入指定名称的 JSON 文件中；返回该 JSON 文件的绝对路径，写入失败时返回空字符串。

注意： 该方法会在用户 Lua 工程的 debug_info 目录写入 JSON 文件。

参数

参数	类型	说明
fileName	String	输出文件名；默认 scene_face_info_<时间戳>.json

返回值

类型	说明
String	JSON 文件绝对路径；写入失败返回空字符串

导出全场景调试信息

-- @runtime client
local debugService = editor:GetService("Debug")
local path = debugService:GetSceneFaceInfo("documentation_scene_debug.json")
print("调试信息文件:", path)