独立 ver-25 / ver-26 / ver-27 诊断库可自动记录战斗前后分阶段耗时和队列数量,ver-26 另有函数级计时及截断前帧间隔,ver-27 仅将输出降为每 10 秒一组、最多 180 组,详见卡顿诊断版。不需要新增接口调用,不是默认正式库行为。
正式 ver-28 按用户要求以干净的 ver-24 为底座,不包含上述三版插桩和 HMP 日志;新增 系统信息.实时帧率。历史诊断使用与热点修复案例见诊断复用记录。
| 日期 | 适用版本 | 变化 |
| 2026-09-16 | ver-25 诊断专用 | 主循环新增每约两秒一次、最多 900 次的性能诊断日志;保持原业务调用,不新增强制 GC。 |
| 2026-09-16 | ver-26 精细诊断 | 保留原主循环指令和 30 ms 逻辑 dt 上限,增加原生 dt 采集、30 项函数计时、NPC 实际列表计数与覆盖信息;停用时恢复诊断持有的函数入口。 |
| 2026-09-16 | ver-27 低频诊断 | 仅降低汇总输出为 10 秒/组、180 组上限,使用 HMP27;原计时和战斗逻辑保持。 |
| 2026-09-16 | ver-28 正式库 | 新增只读 系统信息.实时帧率,每帧转发原生 FPS;原 屏幕帧率 保持配置目标语义。以 ver-24 为底座,不继承三次诊断插桩。 |
| 2026-09-16 | ver-29 | 系统设置新增血液效果开关与四档预算;系统信息提供当前血液状态及视觉异常信息。沿用 ver-28 无诊断底座。 |
| 名称 | 类型 | 说明 | |
标题 | 文本 | 游戏窗口标题 | |
桌面宽度 | 数值 | 桌面分辨率宽度 | |
桌面高度 | 数值 | 桌面分辨率高度 | |
桌面鼠标x | 数值 | 桌面上鼠标坐标x | |
桌面鼠标y | 数值 | 桌面上鼠标坐标y | |
屏幕坐标x | 数值 | 游戏窗口在桌面上的坐标x | |
屏幕坐标y | 数值 | 游戏窗口在桌面上的坐标y | |
屏幕宽度 | 数值 | 游戏窗口宽度 | |
屏幕高度 | 数值 | 游戏窗口高度 | |
屏幕帧率 | 数值 | 启动配置的目标帧率,来自 App 配置,缺省 60;不是实际测得的 FPS,垂直同步/后台状态也可能影响实际帧率 |
实时帧率 | 数值/nil | ver-28 起提供原生主循环传入的实际 FPS,每次主循环刷新;不依赖调试窗口。首帧更新前或旧库可能为 nil,原生尚无有效样本时可能为 0 |
血液效果 | 文本/nil | ver-29;当前低/中/高/极高或“关闭”,未配置时可能为 nil,详见战斗血液效果 |
血液效果错误 | 文本/nil | ver-29;血液视觉异常会自动停用并保留错误,不追加逐帧日志;有效开启配置清除错误,单独关闭保留错误 |
垂直同步 | 逻辑 | 是否启用垂直同步 | |
屏幕鼠标x | 数值 | 游戏窗口上鼠标坐标x | |
屏幕鼠标y | 数值 | 游戏窗口上鼠标坐标y | |
运行模式 | 数值 | 0调试模式 1打包模式 2盒子模式 | |
运行时间 | 整数 | 本次游戏启动后运行的时长,单位:毫秒 | |
调试输出(引擎.系统信息)
{
名称 = "调试标签",
类型 = "标签",
x = 40,
y = 40,
宽度 = 600,
高度 = 30,
水平对齐 = 0,
垂直对齐 = 1,
字体 = "宋体12",
标题 = "桌面:&桌面宽度&x&桌面高度& &桌面鼠标x&,&桌面鼠标y& 屏幕:&屏幕宽度&x&屏幕高度& (&屏幕坐标x&x&屏幕坐标y&) &屏幕鼠标x&,&屏幕鼠标y& ",
边框宽度 = 1,
边框色 = RGBA(255,255,0,255),
文本色 = RGBA(255,255,255,255),
描边色 = RGBA(0,0,200,200),
背景色 = RGBA(0,200,0,200),
数据源 = 引擎.系统信息,
},
local 帧率 = 引擎.系统信息.实时帧率
if type(帧率) == "number" and 帧率 > 0 then
-- 建议在现有约 1 秒 UI 时钟中刷新,标题不变时不重复写入。
引擎.窗口.小地图窗口.标签_右上_FPS.标题 = "FPS " .. math.floor(帧率 + 0.5)
end
字段直接转发原生 FPS,不是 1000 / dt(游戏逻辑 dt 原有 30 ms 上限保持不变),也不是固定设置值或诊断窗口均值。原生自身的采样窗口和舍入精度未新增约定;每帧读取不代表有逐帧 GPU 耗时或精确帧时间。卡死期间 Lua 与 UI 不能继续更新,不能把最后显示值理解为卡死期间仍在出帧。未知值应显示 --,不得回退成配置的 60。
2026-09-16 独立真实 App.exe 离线夹具通过:正常约 59.87 FPS、人为慢阶段约 20.02、恢复约 58.66,三阶段配置帧率均为 60;没有开启调试窗口或加入 HMP 日志。属于机器验证,完整前端实机显示待用户复测。
- 类型:
table - 详情:登录微信,从游戏盒子进入游戏后,可以取出账号相关信息。
| 名称 | 类型 | 权限 | 说明 | |
玩家账号 | 文本/nil | 只读 | 玩家盒子标识 未登录:nil | |
玩家昵称 | 文本/nil | 只读 | 玩家游戏盒子里的昵称 未登录:nil | |
玩家头像 | 文本/nil | 只读 | 玩家游戏盒子里的头像 未登录:nil | |
今日签到 | 整数 | 只读 | 0:未签到 1:签到 | |
连续签到 | 整数 | 只读 | 连续签到次数 | |
今日投币 | 整数 | 只读 | 今日为当前游戏投币数量 | |
累计投币 | 整数 | 只读 | 累计为当前游戏投币总数 | |
剩余金币 | 整数 | 只读 | 当前玩家剩余多少金币 | |
今日发电 | 整数 | 只读 | 今日为当前游戏发电数量 | |
累计发电 | 整数 | 只读 | 累计为当前游戏发电总数 | |
附加 | table {整数} | 读写 | 每个账号可以储存5个整数型变量,变动后会自动同步到平台 后台设置排行策略,在盒子页面的排行榜显示 | |
调试输出(引擎.平台信息)
引擎.平台信息.附加[1] = 66; -- 平台会自动储存 后台可见
- 类型:
地图对象 - 读写:
只读 - 详情:地图是常用组件,你可以在脚本中使用
引擎.地图 获得当前的地图对象
- 类型:
道具对象 - 读写:
读写 - 详情:你可以在脚本中使用 引擎.道具.xxxx 快速读写指定道具项目默认配置项。
| 属性 | 类型 | 权限 | |
名称 | 文本 | 只读 | |
显示名 | 文本 | 只读 | |
颜色 | RGBA | 只读 | |
等级 | 整数 | 只读 | |
分类 | 文本 | 只读 | |
子类 | 文本 | 只读 | |
图标 | 文本 | 只读 | |
最大叠加 | 整数 | 只读 | |
hp,mp,自定义属性... | 整数 | 只读 | |
附加 | table | 读写 | |
气泡提示 | table | 读写 | |
local 道具信息 = 引擎.道具["新装备武器"]
if (道具信息 == nil) then
调试输出("没有这件装备")
return
end
道具信息 = 引擎.道具["短剑"]
调试输出(道具信息.名称,道具信息.显示名,道具信息.等级,道具信息.maxhp,道具信息.暴击)
道具信息.气泡提示 = "#Y一把超级大短剑" -- 修改默认气泡
- 类型:
菜单对象 - 读写:
读写 - 详情:菜单是常用组件,你可以在脚本中使用
引擎.菜单.xxxx 快速读写指定菜单项目属性,[标题][可视][选中][禁用] - 菜单拥有
重置方法,可以动态改变菜单内容。
调试输出(引擎.菜单.物件菜单)
引擎.菜单.物件菜单.网格对齐.选中 = true -- 允许直接修改子菜单属性
引擎.菜单.测试菜单.重置({
{名称="复制",标题="复制",可视=true,选中=false,禁用=false},
{名称="删除",标题="删除",可视=true,选中=false,禁用=false}
})
- 类型:
道具对象 - 读写:
只读 - 详情:当前鼠标上拿起的道具对象,如果没有道具,则为nil
点击 = function(角色对象,键值,功能键)
local 鼠标道具 = 引擎.鼠标道具
if (鼠标道具) then
if (鼠标道具.名称 == "木剑") then
鼠标道具.数量 = 0
引擎.屏幕提示("#Y" .. 鼠标道具.显示名 .. "很好吃!我的攻击力变得更强了!" ,{x =0,y=-60,弹簧效果=false},角色对象)
else
引擎.屏幕提示("我不吃 " .. 鼠标道具.显示名 ,{x =0,y=-60,弹簧效果=false},角色对象)
end
end
return true
end,
- 类型:
文本 - 读写:
只读 - 详情:当前鼠标上拿起的技能名称,如果没有技能,则为nil
- 类型:
角色对象 - 读写:
只读 - 详情:在地图上当前鼠标位置是否有角色对象,如果没有角色,则为nil
- 类型:
整数/文本 - 读写:
读写 - 详情:设置鼠标指针样式,文本型时填写组件名称添加指针。
| 样式值 | 说明 | |
| -1 | 隐藏鼠标指针 | |
| 0 | 箭头光标(默认) | |
| 1 | 忙碌箭头光标 | |
| 2 | 忙碌状态光标 | |
| 3 | I型文本输入光标 | |
| 4 | 手形指针光标 | |
| 5 | 水平双向调整光标 | |
| 6 | 垂直双向调整光标 | |
| 7 | 左上-右下双向调整光标 | |
| 8 | 左下-右上双向调整光标 | |
| 9 | 左向箭头光标 | |
| 10 | 右向箭头光标 | |
| 11 | 上向箭头光标 | |
| 12 | 下向箭头光标 | |
| 13 | 左上箭头光标 | |
| 14 | 右下箭头光标 | |
| 15 | 左下箭头光标 | |
| 16 | 右上箭头光标 | |
| 17 | 全向调整光标 | |
| 18 | 十字准星光标 | |
| 19 | 帮助问号光标 | |
| 20 | 禁止操作光标 | |
| 系统设置 |
| 说明:动态修改系统配置。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 配置项 | table | false |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| x | 整数 | false | 窗口坐标x |
| y | 整数 | false | 窗口坐标y |
| 宽度 | 整数 | false | 窗口宽度 |
| 高度 | 整数 | false | 窗口高度 |
| 标题 | 文本 | false | 窗口标题 |
| 垂直同步 | 逻辑 | false | 是否启用垂直同步 |
| 掉血数字 | 整数 | false | 范围0-100,控制默认掉血效果出现的几率 |
| 血液效果 | 逻辑值或 table | false | ver-29:false 关闭;true 开启;配置表支持开启、画质、血迹时间、受击间隔。首次默认高/8000ms/120ms;非法配置返回 false,错误文本。详见 战斗血液效果,需注册配套资源。 |
| 位置 | 整数 | false | -1:桌面置底 1:桌面置顶 2:最小化 |
| 音量 | 整数 | false | 范围:0-100 整体控制游戏中的音效音量 不包含音乐,音乐对象的音量需要自己单独控制 |
| 调试键 | {键值,功能键} | false | 默认:{96,0} 功能键:0:无 1:Alt 2:Ctrl 4:Shift 键值:-1表示不启用 |
| 老板键 | {键值,功能键} | false | 默认:{-1,0} 功能键:0:无 1:Alt 2:Ctrl 4:Shift 键值:-1表示不启用 |
| 键盘控制 | {启用=false,上=22,下=18,左=0,右=3} | false | 键盘控制角色移动,上下左右为四个键值,默认不启用 |
| 物品名可视 | 逻辑 | false | 地面物品名称是否持续可见 默认:false |
| 角色血条 | 整数 | false | 0:不显示
1:合并显示 (默认)
2:独立显示 |
| 角色名称 | 整数 | false | 0:不显示
1:合并显示 (默认)
2:独立显示 |
|
示例
引擎.系统设置({宽度 = 800,高度 = 600,标题 = "我的游戏"})
引擎.系统设置({标题 = os.date("%Y-%m-%d %H:%M:%S",os.time())}) -- 只修改标题
引擎.系统设置({老板键 = {64,0},调试键={-1,0}}) -- 设置 Home 老板键 取消默认的F12调试键
引擎.系统设置({ 键盘控制 = {启用=true,上=22,下=18,左=0,右=3} }) -- WASD
| 返回值 |
值的类型 |
说明描述 |
| 是否成功 | 逻辑 | 设置老板键时有可能设置失败 |
注意事项
1、配置项均为可选项,按需修改。
2、改变分辨率后,游戏窗口会自动居中。
|
| 屏幕提示 |
| 说明:在屏幕上显示一个提示。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 内容 | 文本 | true | 支持丰富文本 |
| 属性表 | table | false |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| x | 整数 | false | 显示坐标x |
| y | 整数 | false | 显示坐标y |
| 行距 | 整数 | false | 两次提示间的间隔距离 默认:2 |
| 气泡皮肤 | 文本 | false | 气泡皮肤名称 |
| 对齐方式 | 整数 | false | 0 左对齐 1 居中对齐 2 右对齐 |
| 动画效果 | 整数 | false | 0 直接显示 1 渐入 2 弹簧 3 弹幕 默认:1 |
| 停留时间 | 整数 | false | 单位:毫秒 默认:1000 |
| 移动速度 | 整数 | false | 弹幕模式下有效。默认:100 |
| 限制宽度 | 整数 | false | 自动换行的宽度 默认:-1 不自动换行 |
| 打字间隔 | 整数 | false | 是否使用打字效果,越大越慢, 默认:0,无打字效果。 |
| 分组 | 文本 | false | 不同分组的提示会显示在一起 |
| 清空分组 | 逻辑 | false | 是否清空分组内的所有提示 默认:false |
|
| 目标对象 | 对象 | false | 显示在哪? 如果不填表示屏幕最顶层 |
示例
引擎.屏幕提示("#Y游戏开始了")
引擎.屏幕提示("+123",{分组 = "法力恢复", x = 740,y = 652, 气泡皮肤="道具气泡",对齐方式=1})
引擎.屏幕提示("+123",{分组 = "生命恢复", x = 280,y = 652, 气泡皮肤="道具气泡",对齐方式=1})
注意事项
1、缺省显示位置为屏幕中心。
2、如果绑定目标对象,坐标是以目标的坐标点相对偏移。
|
| 弹出文字 |
| 说明:弹出一个动感艺术字。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| x | 整数 | true | x坐标偏移 |
| y | 整数 | true | y坐标偏移 |
| 内容 | 文本 | true | |
| 艺术字 | 文本 | true | 资源标识 |
| 目标对象 | 对象 | false | 显示在哪? 如果不填表示屏幕最顶层 |
| 属性表 | table | false |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 颜色 | RGBA | false | |
| 间距 | 整数 | false | |
| 缩放 | 数值 | false | 缩放比例 |
| 平滑 | 逻辑 | false | 缩放时是否启用平滑效果 默认:false |
| 动效 | 整数 | false | 0-3 内置4种模式 |
| 延迟 | 整数 | false | 延迟时间 |
|
示例
引擎.弹出文字(512,300,tostring(math.random(111,999)) ,"艺术字1");
引擎.弹出文字(0,-70,tostring(math.random(111,999)) ,"艺术字1",引擎.地图.主角,{颜色=RGBA(0,255,0,255),动效=3});
注意事项
1、如果绑定目标对象,坐标是以目标的坐标点相对偏移。
|
| 转场动画 |
| 说明:显示一个转场过渡效果。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 花费时间 | 整数 | true | 多少毫秒内完成 |
| 转场效果 | 整数 | false | 缺省值:1
- 0 圆形过渡
- 1 淡入淡出
- 2 横向擦除
- 3 菱形过渡
- 4 随机像素溶解
|
| 回调函数 | function | false | 转场后触发函数 |
| 地图转场 | 逻辑 | false | 是否只针对地图场景转场 默认:false |
| 半场模式 | 逻辑 | false | 是否只显示后半场过渡 默认:false |
示例
引擎.转场动画(1000,0)
引擎.转场动画(1000,0,nil,false,true) -- 仅显示后半段过渡效果
|
| 播放特效 |
| 说明:在指定位置播放一个特效。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| x | 整数 | true | x坐标偏移 |
| y | 整数 | true | y坐标偏移 |
| 特效配置 | table {} | true |
| 特效类型 |
例子 |
说明描述 |
| 音效 | {延迟=200,音效={"雷电术_结束"}}| 名称 | 类型 | 说明描述 | | 音效 | table{} | 一个由音效资源名组成的数组,随机播放其中一个 | | 音量 | 整数 | 音量大小:0-100 默认:100。可选 | | 音高 | 小数 | 越大声音越尖锐,默认:1.0。可选 |
| 播放音效 |
| 动画 | {延迟=200,动画="雷电术,命中,0.5"}, | 名称 | 类型 | 说明描述 | | 动画 | 文本 | 动画写法:动画,动作,缩放,速度,位置 | | x | 整数 | 可选 | | y | 整数 | 可选 |
| 如果配置x,y会覆盖掉接口参数中坐标 |
| Call | {延迟=200,Call=function(tbl) 调试输出("触发了",tbl) end,附加={1,2,3}}, | 名称 | 类型 | 说明描述 | | Call | function | | | 附加 | 通用 | 触发时候,会做为Call的回调参数进行传递 |
| 触发一个自定义函数 |
| 破碎 | {延迟=200,破碎={图片="半兽人",数量= 20,缩放= 0.8,力量 = 1.6,效果=1}},
| 名称 |
类型 |
说明描述 |
| 效果 | 整数 | 0:向上抛出 1:中心炸开 2:角度冲击 |
| 数量 | 整数 | 碎片数量 默认:20 |
| 缩放 | 小数 | 缩放比例 默认:0.8 |
| 力量 | 小数 | 破碎爆出力度 范围:0.3-2.0 默认:0.6 |
| 地平线 | 数值 | 效果1时有效,设置碎片落地的y轴坐标 |
| 地平线偏移 | 数值 | 效果1时有效,碎片落地的y坐标是否具有随机性 |
| 发力点x | 数值 | 效果2时有效,设置发力点坐标 |
| 发力点y | 数值 | 效果2时有效,设置发力点坐标 |
| 同步消失 | 逻辑 | 是否全部碎片都停止后才开始消失 默认:false |
| 在目标点产生随机撕裂图片效果 |
| 抖动 | {延迟=0,抖动={时间=2000,幅度=10,对象=引擎.窗口.底部UI.动画框1}},
| 名称 |
类型 |
说明描述 |
| 对象 | 组件对象 | 要被抖动的对象 |
| 时间 | 整数 | 持续时间 单位:毫秒 |
| 幅度 | 整数 | 抖动幅度 |
| 指定对象发生抖动效果 |
| 闪电链 |
| 名称 |
类型 |
说明描述 |
| 起点x | 数值 | 起点坐标 |
| 起点y | 数值 | |
| 终点x | 数值 | 终点坐标 |
| 终点y | 数值 | |
| 持续时间 | 整数 | 单位:毫秒 默认:1000 |
| 节点数量 | 整数 | 默认:30 |
| 抖动幅度 | 整数 | 数值越大越剧烈 默认:100 |
| 宽度 | 数值 | 默认:2.5 |
| 颜色 | RGBA | 默认:RGBA(100, 180, 255,255) |
| 光晕色 | RGBA | 默认:RGBA(100, 180, 255,80) |
| 渐入 | 整数 | 默认:200 |
| 渐出 | 整数 | 默认:200 |
| 末端变细 | 逻辑 | |
| 在两点之间产生闪电链效果 |
| 图层 |
- 目标为角色时:
0身后 1身前 默认:1 - 目标为地图时:
0地表 1顶层 默认:1
| 动画时有效 |
|
| 目标对象 | 对象 | false | 显示在哪? 如果不填表示屏幕最顶层 |
示例
引擎.播放特效(512,100,{{延迟=200,音效={"雷电术_结束"}},{延迟=200,动画="雷电术,命中"}})
引擎.播放特效(200,200,{{延迟=200,音效={"雷电术_结束"}},{延迟=200,动画="雷电术,命中"}},引擎.窗口.技能窗口)
引擎.播放特效(0,0,{{延迟=200,音效={"升级光"}},{延迟=200,动画="__测试动画_,升级地,1,1",图层=0}},引擎.地图.主角)
引擎.播放特效(0,0,{{延迟=0,抖动={时间=2000,幅度=10,对象=引擎.窗口.底部UI.动画框1}}})
引擎.播放特效(0,0,{{延迟=0,音量=50,音效={"移动1","移动2"}}}
引擎.播放特效(200,200,
{
{延迟=0,闪电链={起点x = 50,起点y = 50,终点x = 250,终点y = 50,持续时间 = 2000,宽度 = 1,颜色 = RGBA(240, 240, 240,255),
光晕色 = RGBA(0, 0,255,255),渐入 = 100,渐出 = 100,节点数量 = 16,末端变细 = false}},
},按钮对象.父窗口)
{
名称 = "测试按钮",
类型 = "按钮",
x = 40,
y = 550,
宽度 = 80,
高度 = 40,
标题 = "测试",
系统事件 = {
点击 = function(按钮对象)
引擎.播放特效(400,300,{
{
延迟=0,
破碎={
图片="牌背面",
数量=20,
缩放=0.8,
力量 = 1.6,
效果=2,
发力点x = 300, -- 从坐标300,300位置产生力量撕碎图片抛出。
发力点y = 300,
}
}
})
end
}
},
注意事项
1、如果绑定目标对象,坐标是以目标的坐标点相对偏移。
|
| 信息框 |
| 说明:在屏幕上弹出一个信息框。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 内容 | 文本 | true | 支持丰富文本 |
| 按钮类型 | 整数 | true | 0 确定 1 确定取消 2 输入框+确定取消 |
| 额外配置 | table | false |
| 名称 |
类型 |
说明描述 |
| 确定按钮标题 | 文本 | 默认:确定 |
| 取消按钮标题 | 文本 | 默认:取消 |
| 确定按钮宽度 | 整数 | 默认:60 |
| 取消按钮宽度 | 整数 | 默认:60 |
| 确定按钮高度 | 整数 | 默认:30 |
| 取消按钮高度 | 整数 | 默认:30 |
| 背景遮罩透明度 | 整数 [0-255] | 默认:168 |
| 默认内容 | 文本 | 输入框模式下的默认内容 |
|
示例
if (引擎.信息框("确定要退出游戏吗?",1)) then
if(not 引擎.信息框("#Y你真的要退出?",1)) then
引擎.信息框("#H你还是放弃了")
end
end
local 结果,内容 = 引擎.信息框("输入动作名称",2,{默认内容="停止"})
if (结果) then
调试输出(内容)
end
| 返回值 |
值的类型 |
说明描述 |
| 是否确定 | 逻辑 | 确定返回true 取消返回false |
| 输入框内容 | 文本 | 输入框模式时返回内容 |
注意事项
1、同步模式,信息框返回结果后才会继续执行后面逻辑。
|
| 对话 |
说明:在屏幕上弹出一个对话框。
- 对话窗口使用App.lua中
对话框 皮肤。 - 对话链接触发的是当前对象中的
系统事件中的同名事件, 链接名称为 exit时,点击后关闭对话框。 - 事件函数会接收回调参数[信息],与
文本框控件相同和调用时传递的[数据源]。 - 事件函数返回值为逻辑型
true 时,表示关闭对话窗口。 - 事件函数返回值为文本型,表示更新当前对话窗口内容。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| x | 整数/nil | true | 对话窗口坐标x,nil表示关闭对话窗口 |
| y | 整数 | true | 对话窗口坐标y |
| 标题 | 文本 | true | 对话窗口有标题时有效 |
| 内容 | 文本 | true | 对话框中的内容,支持丰富文本 |
| 数据源 | table | false | 会传递到事件函数中 |
示例
{
名称 = "测试按钮",
类型 = "按钮",
宽度 = 80,
高度 = 30,
标题 = "测试对话",
x = 692,
y = 41,
系统事件 = {
点击 = function(按钮对象)
引擎.对话(0,0,"",
[[
你要干什么?
#Y#@查金币@我还有多少金币?@
#Y#@exit@没事@
]])
end,
查金币 = function (信息,数据源)
return
[[
你现在的金币数量:#Y999
#Y#@退出@谢谢你@
]]
end,
退出 = function ()
return true
end,
}
}
注意事项
1、同步模式,对话框返回结果后才会继续执行后面逻辑。
|
| 引导 |
| 说明:在屏幕上突出显示指定的控件。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 控件数组 | table{控件对象} | true | |
示例
local 窗口对象 = 引擎.窗口.底部UI
窗口对象.引导动画.可视 = true
窗口对象.引导动画.x = 150
引擎.引导({窗口对象.底部红血条,窗口对象.生命标签,窗口对象.引导动画})
窗口对象.引导动画.x = 505
引擎.引导({窗口对象.属性按钮,窗口对象.引导动画})
窗口对象.引导动画.x = 585
引擎.引导({窗口对象.技能按钮,窗口对象.引导动画})
窗口对象.引导动画.可视 = false
注意事项
1、同步模式,按次序依次引导。
2、点击屏幕结束。
|
| 增加物品 |
| 说明:增加物品道具到包裹格子中。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 道具名称 | 文本 | true | |
| 数量 | 整数 | false | |
| 附加 | table | false | 如果填写会传递到道具的 创建 事件中 |
示例
引擎.增加物品("八荒刀",1,{攻击=20})
引擎.增加物品("粗布衣",1,{给白装=true})
引擎.增加物品("金创药小",6)
引擎.增加物品("魔法药小",6)
引擎.增加物品("金创药中",6)
引擎.增加物品("魔法药中",26)
引擎.增加物品("雷电术")
注意事项
1、可以用 引擎.取包裹空位() 进行前置判断。
|
| 取包裹空位 |
| 说明:取所有包裹类控件剩余的空位数量。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 包裹名称 | 文本 | false | nil表示取所有包裹空位 |
示例
local 剩余空位 = 引擎.取包裹空位()
调试输出(剩余空位)
|
| 取物品数量 |
| 说明:取包裹中指定物品的总数量。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 道具名称 | 文本 | true | |
示例
local 物品数量 = 引擎.取物品数量("金创药小")
调试输出(物品数量)
|
| 减少物品 |
| 说明:从包裹格子里面减少物品。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 道具名称 | 文本 | true | |
| 数量 | 整数 | true | |
示例
注意事项
1、可以用 引擎.取物品数量() 进行前置判断。
|
| 创建音乐 |
|
说明:创建一个音乐对象。 ver-20:资源标识可省略以先创建空对象;创建后需调用播放。标识未注册时返回 nil;标识已注册但文件加载失败时返回对象,可查询加载状态/加载错误。不同对象使用同文件时各自独立,显式重试不再被累计失败次数永久阻断。地图背景请优先使用地图配置的地图音乐/环境音乐。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 音乐素材 | 文本/nil | false | 音乐资源素材标识;省略时创建空对象 |
示例
local 背景音乐 = 引擎.创建音乐("一直很安静")
背景音乐.音量 = 50
背景音乐.循环 = true
背景音乐.播放()
|
| 创建缓动 |
|
说明:创建一个缓动对象。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 自动销毁 | 逻辑 | false | 默认:true |
示例
引擎.创建缓动()
.by(按钮对象.父窗口.地图按钮,{y=-100,x=100},500)
.by(按钮对象.父窗口.地图按钮,{y=100,x=-100},500)
| 返回值 |
值的类型 |
说明描述 |
| 对象 | 缓动对象 | 支持链式调用 |
|
| 添加指针 |
|
说明:使用组件自定义指针样式,通过引擎.鼠标指针动态显示。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 组件配置 | table | true | 精灵,动画...等基石组件 |
示例
引擎.添加指针(
{
名称 = "指针默认",
类型 = "精灵",
图片 = "鼠标指针_默认"
}
)
引擎.鼠标指针 = "指针默认"
注意事项
1、相同名称的指针组件添加一次即可,之后通过鼠标指针设置名称显示。
|
| 弹出菜单 |
|
说明:在鼠标位置弹出指定 菜单 项目。
|
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 菜单名称 | 文本 | false | |
| 附加 | 通用 | false | 会传递到菜单点击事件中 |
| 屏幕坐标x | 整数 | false | |
| 屏幕坐标y | 整数 | false | |
示例
注意事项
1、未指定弹出坐标的情况下,默认会在鼠标坐标处弹出。
|
| 存档 |
| 说明:存档。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 存档文件名 | 文本/nil | true | 存档到指定文件,如果为nil表示存档到table |
| 附加 | table | false | 需要保存的自定义数据 |
| 密钥 | 文本 | false | 不填表示不加密 |
示例
local 结果 = 引擎.存档("save.dat",{金币=20,技能点=30},"ttttt")
调试输出(结果)
local 结果 = 引擎.存档(nil,{金币=20,技能点=30},"ttttt")
调试输出(结果)
| 返回值 |
值的类型 |
说明描述 |
| 结果 | 逻辑/table | 存档到文件失败返回false,存档到table格式为{ver,dat} |
提示 默认存读档的内容:包裹格子,道具格子,技能格子,快捷格子,主角所在的地图,位置,方向,等级,经验。
|
ver-23 兼容修复:读档切换地图时,地图音量接入不再依赖 debug.getmetatable。旧的手动音乐调用可保留;地图两个音量值在同一引擎实例内保持当前设置,不从角色存档恢复。本机真实引擎已验证合成存档和加密存读档,同事客户端待复测。
| 读档 |
| 说明:读档。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 存档文件名/存档信息 | 文本/table | true | 存档保存的位置或者存档table信息 |
| 密钥 | 文本 | false | 不填表示不加密 |
| 配置 | table | false |
| 成员 |
类型 |
说明 |
| 跳转地图 | 逻辑 | 是否跳转到存档时的地图 默认:true |
|
示例
local 附加 = 引擎.读档("save.dat","ttttt")
调试输出("读档",附加)
-- 从table中还原存档
local 结果 = 引擎.存档(nil,{金币=20,技能点=30},"ttttt")
附加 = 引擎.读档(结果,"ttttt")
调试输出("读档",附加)
| 返回值 |
值的类型 |
说明描述 |
| 附加 | table/nil | 读档成功返回存档时传递进去的数据,失败返回nil |
|
| 结束 |
说明:立即关闭游戏,不会触发游戏关闭事件。 |
示例
|
| 执行 |
| 说明:调用Windows系统通用接口。 |
| 命令名称 |
参数表 |
说明描述 |
| 打开文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 初始目录 | 文本 | false | 默认:程序运行目录 |
| 多选 | 逻辑 | false | 默认:false |
| 过滤器 | 文本 | false | 默认:"所有文件|*.*|" |
| 显示系统打开文件对话框,返回选中的所有文件名 |
| 保存文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 初始目录 | 文本 | false | 默认:程序运行目录 |
| 后缀名 | 文本 | false | 缺省情况下的后缀名例:"json" |
| 过滤器 | 文本 | false | 默认:"所有文件|*.*|" |
| 显示系统保存文件对话框,返回保存的文件名 |
| 查看文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 指定文件名或是目录 |
| 打开文件夹并且选中文件 |
| 删除文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 指定文件名或是目录 |
| 删除文件或者文件夹 |
| 寻找文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 支持通配符 |
| 寻找指定文件,返回文件名数组 |
| 复制文件 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 待复制文件名 |
| 目标 | 文本 | true | 目标文件名 |
| 复制指定文件到目标位置,自动创建目标目录 |
| 命令行 |
| 属性 |
类型 |
是否必填 |
说明 |
| 命令 | 文本 | true | 待指定的cmd命令 |
| 返回执行结果 |
| 屏幕截图 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 截图文件名支持.jpg .png |
| 区域 | table | true | {x,y,w,h} |
| 屏幕截图并保存到指定文件 |
| 图片切片 |
| 属性 |
类型 |
是否必填 |
说明 |
| 文件 | 文本 | true | 图片文件地址 |
| 目标 | 文本 | true | 保存的目录 |
| 宽度 | 整数 | true | 单片宽度 默认:256 |
| 高度 | 整数 | true | 单片高度 默认:256 |
| 格式 | 文本 | true | 保存什么格式 默认:"jpg" |
| 将一张图片按需求裁剪成小块 失败返回nil 成功返回:{原图宽度,原图高度,列数,行数} |
示例
local 结果 = 引擎.执行("打开文件",{初始目录="./",多选=true,过滤器="Lua脚本|*.lua|图片文件|*.jpg;*.png|所有文件|*.*|"})
调试输出(结果)
local 结果 = 引擎.执行("保存文件",{初始目录="E:/", 后缀名="dmp", 过滤器="Lua脚本|*.lua|图片文件|*.jpg;*.png|所有文件|*.*|"})
调试输出(结果)
引擎.执行("查看文件",{文件="C:/Users"})
引擎.执行("删除文件",{文件="D:/luamake"})
local 结果 = 引擎.执行("寻找文件",{文件 = "MapRes/高物件/*.png"})
for n=1,#结果 do
local info = string.fileinfo(结果[n])
调试输出(引擎.执行("复制文件",{文件 = 结果[n],目标 = "F:/dmstore/" .. info.文件名}))
end
引擎.执行("命令行",{命令="start http://dm3.2ddm.com/"})
引擎.执行("屏幕截图",{文件= "游戏截图.jpg",区域={0,0,引擎.系统信息.屏幕宽度,引擎.系统信息.屏幕高度}})
local 结果 = 引擎.执行("图片切片",{文件 = "gameMap.jpg",目标= "" ,宽度=256,高度=256,格式="jpg"})
调试输出(结果)
注意事项
1、过滤器格式:"Text Files|*.txt|Image Files|*.jpg;*.png|All Files|*.*|"。
|
引擎.取地图随机空位(地图名称, 配置):无需进入目标地图,提前随机选取一个非障碍格子。使用点号调用,不是引擎.地图的方法。适合藏宝图提前确定目标地图和坐标;本接口不负责提示、扣道具、刷 BOSS、切图或保存任务。
| 参数 | 类型 | 默认/含义 | |
| 地图名称 | 文本,必填 | 已注册地图配置的唯一名称,不是 Lua 文件名或地图模板资源标识 | |
| 配置 | table,可省略 | 可含下列字段;配置格式错误返回失败 | |
| 配置.范围 | {x,y,宽,高} | 可省略,表示全图;整数格子矩形,宽高为正数,自动与地图边界及边距取交集 | |
| 配置.边距 | 整数 | 默认 0,0~65535;排除地图最外侧指定格数,不是矩形范围内部的边距 | |
成功返回格子x, 格子y,两者都是 Lua integer,坐标从 0 开始;失败返回-1, -1, 错误文本。数学上为整数的 1.0 等输入会规范为整数;字符串数字、NaN、无穷和小数不被接受。行列数有效范围为 1~65536。范围内的 (0,0) 是合法点;不要把 -1 当成 false,Lua 中 -1 仍为真值。
local 目标地图 = '祖玛寺庙'
local 格子x, 格子y, 错误 = 引擎.取地图随机空位(目标地图, {
边距=2,
-- 范围={20,30,80,60}, -- 可选,只在这一片格子区域取点
})
if 格子x >= 0 then
local 藏宝目标 = {地图=目标地图, x=格子x, y=格子y}
调试输出(string.format('藏宝图指向:%s,%d,%d', 目标地图, 格子x, 格子y))
-- 将藏宝目标存入你的任务/道具数据,再调用项目自己的提示与刷怪流程。
else
调试输出('藏宝图取点失败:', 错误)
end
取点依据与副作用边界:
- 未加载的地图:读取已注册地图定义。模板地图复用原生 LoadJson 对 JSON/JSONZ/资源标识的解析和缓存,取模板行列数与障碍数组,再覆盖地图配置中的
地图格子(后项覆盖前项)。纯配置地图默认空地,再应用配置障碍。 - 已加载的地图:读取该地图现有障碍数组,包含通过
地图格子(x,y,类型)写入的当前静态障碍变化,不再用旧配置覆盖它。取点本身不写数组,不标记地图已加载,也不创建渲染或寻路对象。 - 与地图原始障碍判定一致,检查障碍位:0 和 2(透明)可选,1 和 3 不可选。缺失或非法障碍值按不可用处理,资源读取失败不会当成全图可走。
- 不调用目标地图的 Load、Init、Call,不改变当前地图、主角位置,不触发目标地图创建/刷怪事件。但首次读取模板会产生正常的 JSON 资源缓存和同步读取开销,不是“零加载成本”。
- 不排除角色当前占位、门点、安全区或玩法禁区,不判断入口连通性。非障碍格可能属于封闭区域。若藏宝图只能落在可达区域,应由项目提供已确认可达的范围;若需要自动连通性过滤,应另行实现。
- 查询时的有效格不等于稍后仍能刷怪。机关、动态阻挡、地图创建事件可能改变障碍;实际刷 BOSS 前需按当时地图状态重新检查,失败时由业务决定改点或提示。提前选点不会立即创建远处 BOSS。
- 不保证多次取点互不重复,也不预留或锁定格子。调用消耗原有 math.random 序列,但不重新设置随机种子。
随机与性能:
先从有效矩形均匀随机尝试最多 128 次。没有命中时,对不超过 1,048,576 格的范围使用完整扫描和蓄水池抽样,保证有有效格时可找到;全障碍返回失败。超过该规模且随机尝试未命中时,返回“范围过大,请缩小范围后重试”,不声称整张地图没有可行点。没有额外维护全地图空位 table,但模板自身仍由原资源缓存管理。
接口是同步调用,不要每帧调用。大地图首读和高度阻塞范围的兜底扫描可能产生停顿,建议藏宝图限制明确区域,或在业务允许时提前读取。隔离样本常规已备妥纯配置地图约 0.0015 ms/次,不包含首读、兜底扫描、真实项目负载或设备性能保证。
验证状态:ver-18 候选实际字节码通过 38,122 项隔离断言;真实 App.exe 独立项目通过未进入地图取点、原生 JSON 模板、范围/透明格/失败、加载后 500 个坐标逐格对照和运行时静态障碍变化等 8 个场景。该测试没有接入用户实际藏宝图或 BOSS 刷新逻辑。
| 资源解析 |
| 说明:用于查看图集,动画,地图模板资源内部信息。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 资源标识 | 文本 | true | |
示例
local 资源信息 = 引擎.资源解析(素材标识)
调试输出(资源信息)
| 返回值 |
值的类型 |
说明描述 |
| 结果 | table/nil | 失败返回nil
- {类型,数据={}}
- 图集数据 {帧名称,帧宽度,帧高度,帧偏移x,帧偏移y}
- 动画数据 {动作名称}
- 地图数据 {格子宽度,格子高度,格子列数,格子行数,障碍信息}
|
|
| 加入事件 |
| 说明:往游戏主循环中加入一个自定义事件。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 事件名称 | 文本 | true | 触发的事件名称 |
| 附加信息 | table | false | 事件触发时可以取出 |
| 延迟时间 | 数值 | false | 延迟执行 |
| 自动销毁 | 逻辑 | false | 是否只执行一次,默认:true |
示例
系统事件 = {
游戏开始 = function()
引擎.加入事件("系统时钟",{},1000,false)
end,
系统时钟 = function (tbl,dt,time)
调试输出(dt,time)
end,
}
|
Heimei-EG-lua ver-2 新增。根据道具组件模板和一份运行时道具信息,返回可拼接到富文本中的#item标签。
引擎.富文本道具(道具名称, 道具数量, x偏移, y偏移, 道具信息, 格子大小)
| 参数名称 | 类型 | 是否必填 | 说明 | |
| 道具名称 | 文本 | true | 已注册的道具组件名称,用作创建运行时道具的模板。 | |
| 道具数量 | 数值 | false | 默认 1;当道具信息.数量存在时,以道具信息中的数量为准。 | |
| x偏移 | 数值 | false | 标签显示的水平偏移;只传一个偏移时另一个按 0 处理。 | |
| y偏移 | 数值 | false | 标签显示的垂直偏移。 | |
| 道具信息 | table/道具对象 | false | 传 table 时按其顶层字段的浅拷贝创建显示快照;也可传已有道具对象并复制其属性。未传 table 且未指定有效格子大小时退回普通静态#item标签。 | |
| 格子大小 | 数值 | false | ver-5 新增。有效值为不小于 1 的有限数值,向下取整,例如 34 表示 34×34 的虚拟格子。未传、0、负数或非数值沿用自动尺寸;只传尺寸时从模板创建显示快照。 | |
local 道具信息 = {
数量 = 1,
图标 = '自定义钢手镯图标',
显示名 = '极品钢手镯',
攻击 = 12,
}
文本框.内容 = '获得道具:' .. 引擎.富文本道具('钢手镯', 1, nil, nil, 道具信息)
Heimei-EG-lua ver-3 起,如果道具快照带有格子效果,动态标签会按“底图 → 格子效果 → 图标 → 数量”绘制。资源格式沿用道具 - 格子效果,无需在标签外另行拼接品质底纹或动画。
Heimei-EG-lua ver-4 修复 ver-3 的格子效果代理在实机绘制时把引擎内部SystemDat误当成全局变量的问题。调用参数、返回标签、绘制层级和气泡规则均不变,原 ver-3 调用代码可直接换用 ver-4。
有效格子大小统一富文本测量、换行、绘制、数量位置与热点范围。ver-7 起,效果素材按原生道具格规则处理:小图不放大,超出格子的静态素材才等比缩小,偏移及动画配置缩放保留原值;常规无旋转、正缩放的精灵/帧动画裁剪超出部分。列表框仍保留原生留白和行高限制。
列表框.加入项目({
引擎.富文本道具(道具.名称, 道具.数量, nil, nil, 道具, 34),
})
ver-5 同时隔离动态标签的动画节点和播放状态,不再与背包、装备或其他表项共用公共动画节点。旧五参数调用也受益于位置串扰修复;动画混合显示不在本版调整范围。隔离字节码验证不等同于真实引擎视觉验证。
ver-6 修复有效格子大小触发的首帧裁剪绘制类型错误:内部纹理矩形按完整纹素向内取整为 Lua integer,同步调整绘制位置;不足一个纹素的片段跳过。用户参数及效果配置不变,无需将道具 table 转成字符串。真实 App.exe 的独立离线绘制对照通过,完整前端待用户复测。
ver-7 修复第六参数曾以系统底图纹理尺寸作为效果缩放基准的问题,并遵循项目道具构造规则:格子效果存在时,它已经包含主图标,富文本代理不再额外补画图标。第六参数只定义虚拟格子、裁剪、排版、数量与热点气泡范围。
警告
必须用点号调用引擎.富文本道具并把返回值拼入富文本。#item(钢手镯,1,nil,nil,道具信息)只是普通字符串,不能携带 Lua table。该对象仅用于富文本显示和气泡,不等同于包裹格子,不提供拖放、使用或装备操作。热点悬停会触发 App.lua 的道具气泡提示,装备对比参数固定为 false。
| 日期 | 版本 | 简易记录 | |
| 2026-09-10 | Heimei-EG-lua ver-2 | 新增引擎.富文本道具,支持用 table/道具对象生成动态#item显示快照并复用标准道具气泡。 | |
| 2026-09-10 | Heimei-EG-lua ver-3 | 修复动态道具热点的对象二次解析,并让返回标签复用快照的格子效果配置。 | |
| 2026-09-10 | Heimei-EG-lua ver-4 | 定点修复格子效果代理未捕获引擎内部SystemDat导致的实机绘制报错;接口和渲染规则不变。 | |
| 2026-09-10 | Heimei-EG-lua ver-5 | 富文本道具新增可选格子大小,统一虚拟格子布局/热点,隔离效果动画及裁剪状态;混合显示未修改,实机待测。 | |
| 2026-09-10 | Heimei-EG-lua ver-6 | 定点修复第六参数路径的原生绘制整数类型约束,保留参数格式、尺寸及气泡行为。 | |
| 2026-09-10 | Heimei-EG-lua ver-7 | 对齐原生道具格的缩放与图层所有权,修复系统底图误作尺寸基准和主图标重复绘制。 | |
| 2026-09-13 | ver-18 | 新增引擎.取地图随机空位,无需进入目标地图;支持范围/边距、模板及配置障碍、失败返回和有限扫描,说明不刷怪及可达性边界。 | |
| 2026-09-14 | ver-20 | 创建音乐保持显式播放;同文件不同实例独立,失败计数不再永久阻止显式重试。 | |
| 2026-09-15 | ver-23 | 修复读档切图时地图音乐接入的调试 API 依赖;旧音乐写法及当前音量保持。 | |
| 删除事件 |
| 说明:删除指定自定义事件。 |
| 参数名称 |
值的类型 |
是否必填 |
说明描述 |
| 事件名称 | 文本 | true | |
示例
系统事件 = {
游戏开始 = function()
引擎.加入事件("系统时钟",{},1000,false)
end,
系统时钟 = function (tbl,dt,time)
调试输出(dt,time)
引擎.删除事件("系统时钟")
end,
}
|