ProfileService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [ProfileService]（6 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

ProfileService 提供 Print、Warn 与 Error 三种级别的运行时日志输出，用于记录诊断信息。

适用场景

脚本需要按普通、警告或错误级别输出运行状态，便于在控制台定位问题时使用。

使用要点

通过 game:GetService("ProfileService") 获取服务，并把待记录的值传给 Print、Warn 或 Error。

注意事项

当前公开契约只保证三个日志方法及其 Any 类型参数；未声明性能采样、日志持久化、字符串转换规则或仅限开发环境等额外行为。不要把控制台输出作为业务状态或错误恢复机制。

代码示例

日志输出与分段计时

-- @runtime client
local profile = game:GetService("ProfileService")
-- 开始一段代码性能计时，ProfileBegin/ProfileEnd 采用嵌套栈式管理
profile:ProfileBegin("出生点初始化")
profile:Print("开始加载出生点配置")
profile:Warn("检测到未设置的复活点参数")
profile:Error("复活点不存在，使用默认点")
-- 结束计时并获取耗时（毫秒）
local costMs = profile:ProfileEnd()
print("ProfileEnd 耗时(毫秒):", costMs)
-- 获取场景热力图数据（模型面数/帧率等），返回值为不透明表，读取前先做类型检查
local sceneData = profile:GetSceneProfileData()
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("场景热力图数据可用")
else
    print("场景热力图数据为空")
end

关联类型

• Unit

函数 (6)

Print

签名：Print(msg: Any) -> void

输出一条普通级别的日志消息。

参数	类型	说明
msg	Any	消息内容

返回值 void

示例代码

输出普通日志

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Print 方法输出普通信息
profileService:Print("玩家进入游戏，ID: 12345")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

Warn

签名：Warn(msg: Any) -> void

输出一条警告级别的日志消息。

参数	类型	说明
msg	Any	消息内容

返回值 void

示例代码

输出警告日志

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Warn 方法输出警告信息
profileService:Warn("内存使用率超过 80%，请注意性能")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

Error

签名：Error(msg: Any) -> void

输出一条错误级别的日志消息。

参数	类型	说明
msg	Any	消息内容

返回值 void

示例代码

输出错误日志

-- @runtime client
-- 获取 ProfileService 服务实例
local profileService = game:GetService("ProfileService")
-- 调用 Error 方法输出错误信息
profileService:Error("发生了一个严重错误：网络连接超时")
-- 验证服务实例可用
print("ProfileService 实例获取成功:", profileService)

GetSceneProfileData

签名：GetSceneProfileData() -> Table (热力图数据 {model_prim_num, model_dp_num, prim_num, dp_num, fx_dp_num, logic_rate, render_rate, ts}；仅客户端有数据，服务端无渲染数据返回空表)

无参数调用。返回当前场景的热力图数据表，表中包含 model_prim_num、model_dp_num、prim_num、dp_num、fx_dp_num、logic_rate、render_rate、ts 等字段。该数据仅在客户端有内容，服务端没有渲染数据，因此调用返回空表。

返回值 Table (热力图数据 {model_prim_num, model_dp_num, prim_num, dp_num, fx_dp_num, logic_rate, render_rate, ts}；仅客户端有数据，服务端无渲染数据返回空表)

示例代码

示例：客户端读取场景热力图数据

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先输出一行日志，便于确认服务已就绪
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启一段命名计时，把要统计的代码包在中间
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时并返回毫秒耗时，同时也能观察查询本身的开销
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 热力图数据仅在客户端可用，空表表示当前环境拿不到数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end

ProfileBegin

签名：ProfileBegin(name: String) -> void

接收一个字符串参数 name，用于开始一段以该名称标识的代码计时。调用后可以用 ProfileEnd 结束最近一段计时并取得耗时。

参数	类型	说明
name	String	计时标签名

返回值 void

示例代码

示例：用 ProfileBegin 开启一段耗时统计

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先用 Print 打一条日志，方便和后面的计时结果对照
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启一段命名计时，把要统计的代码包在中间
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时并返回毫秒耗时，同时也能观察查询本身的开销
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 场景热力图只在客户端有数据，空表表示当前环境拿不到数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end

ProfileEnd

签名：ProfileEnd() -> Float (最近一段计时耗时（毫秒），无匹配开始段返回 0)

无参数调用。结束最近一段由 ProfileBegin 开启的计时，并返回该段计时耗时，单位为毫秒；若没有匹配的开始段，则返回 0。

返回值 Float (最近一段计时耗时（毫秒），无匹配开始段返回 0)

示例代码

示例：用 ProfileEnd 取得计时结果

-- @runtime client
-- 获取 ProfileService：先取全局服务单例，后续调用都通过这个变量发起
local profileService = game:GetService("ProfileService")

-- 先输出一条日志，便于确认服务已就绪
profileService:Print("开始查看场景热力图")

-- ProfileBegin 开启命名计时，中间放置待统计的查询逻辑
profileService:ProfileBegin("场景热力统计")
local sceneData = profileService:GetSceneProfileData()

-- ProfileEnd 结束最近一段计时，返回值是耗时毫秒数；若没有匹配的开始段会返回 0
local elapsedMs = profileService:ProfileEnd()
print("计时耗时(ms):", elapsedMs)

-- 客户端下可以读到热力图字段；空表表示当前环境没有数据
if type(sceneData) == "table" and next(sceneData) ~= nil then
    print("模型Prim数:", sceneData.model_prim_num)
    print("DrawCall数:", sceneData.dp_num)
else
    print("当前环境无场景热力图数据")
end