Dream Mod 3.0Dream Mod 3.0
首页
快速开始
资源库
首页
快速开始
资源库
  • 进度

    • 更新日志
  • 指南

    • 快速上手
    • App.lua
    • Server.lua
    • 地图
    • 角色
    • 道具
    • 技能
    • 状态
    • 窗口
    • 成长
    • DmTcpClient
    • WebSocketClient
    • SqliteDB
    • 皮肤
    • 自定义组件
  • Api

    • 引擎
    • 地图
    • 角色
    • 道具
    • 技能
    • 状态
    • 窗口
    • 自定义组件
    • 音乐
    • 缓动
    • 全局
  • 控件

    • 标签
    • 按钮
    • 图片框
    • 动画框
    • 模型框
    • 文本框
    • 进度条
    • 技能格子
    • 快捷格子
    • 包裹格子
    • 道具格子
    • 角色框
    • 选择框
    • 选择夹
    • 容器
    • 地图框
    • 滑块条
    • 滚动条
    • 组合框
    • 输入框
    • 列表框
  • 组件

    • 文本
    • 艺术字
    • 精灵
    • 矩形
    • 圆形
    • 动画
    • 模型
  • 其他

    • 丰富文本
    • 模板变量
    • 资源格式
    • 游戏盒子
    • 资源列表
  • 自定义功能

    • 战斗血液效果
    • 地图天气
  • 引擎

    独立 ver-25 / ver-26 / ver-27 诊断库可自动记录战斗前后分阶段耗时和队列数量,ver-26 另有函数级计时及截断前帧间隔,ver-27 仅将输出降为每 10 秒一组、最多 180 组,详见卡顿诊断版。不需要新增接口调用,不是默认正式库行为。

    正式 ver-28 按用户要求以干净的 ver-24 为底座,不包含上述三版插桩和 HMP 日志;新增 系统信息.实时帧率。历史诊断使用与热点修复案例见诊断复用记录。

    更新记录

    日期适用版本变化
    2026-09-16ver-25 诊断专用主循环新增每约两秒一次、最多 900 次的性能诊断日志;保持原业务调用,不新增强制 GC。
    2026-09-16ver-26 精细诊断保留原主循环指令和 30 ms 逻辑 dt 上限,增加原生 dt 采集、30 项函数计时、NPC 实际列表计数与覆盖信息;停用时恢复诊断持有的函数入口。
    2026-09-16ver-27 低频诊断仅降低汇总输出为 10 秒/组、180 组上限,使用 HMP27;原计时和战斗逻辑保持。
    2026-09-16ver-28 正式库新增只读 系统信息.实时帧率,每帧转发原生 FPS;原 屏幕帧率 保持配置目标语义。以 ver-24 为底座,不继承三次诊断插桩。
    2026-09-16ver-29系统设置新增血液效果开关与四档预算;系统信息提供当前血液状态及视觉异常信息。沿用 ver-28 无诊断底座。

    属性

    系统信息

    • 类型:table
    • 读写:只读
    • 详情:当前系统信息。
    名称类型说明
    标题文本游戏窗口标题
    桌面宽度数值桌面分辨率宽度
    桌面高度数值桌面分辨率高度
    桌面鼠标x数值桌面上鼠标坐标x
    桌面鼠标y数值桌面上鼠标坐标y
    屏幕坐标x数值游戏窗口在桌面上的坐标x
    屏幕坐标y数值游戏窗口在桌面上的坐标y
    屏幕宽度数值游戏窗口宽度
    屏幕高度数值游戏窗口高度
    屏幕帧率数值启动配置的目标帧率,来自 App 配置,缺省 60;不是实际测得的 FPS,垂直同步/后台状态也可能影响实际帧率
    实时帧率数值/nilver-28 起提供原生主循环传入的实际 FPS,每次主循环刷新;不依赖调试窗口。首帧更新前或旧库可能为 nil,原生尚无有效样本时可能为 0
    血液效果文本/nilver-29;当前低/中/高/极高或“关闭”,未配置时可能为 nil,详见战斗血液效果
    血液效果错误文本/nilver-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),
    
      数据源 = 引擎.系统信息,
    
    },
    
    

    实时 FPS 使用说明(ver-28)

    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忙碌状态光标
    3I型文本输入光标
    4手形指针光标
    5水平双向调整光标
    6垂直双向调整光标
    7左上-右下双向调整光标
    8左下-右上双向调整光标
    9左向箭头光标
    10右向箭头光标
    11上向箭头光标
    12下向箭头光标
    13左上箭头光标
    14右下箭头光标
    15左下箭头光标
    16右上箭头光标
    17全向调整光标
    18十字准星光标
    19帮助问号光标
    20禁止操作光标

    方法

    系统设置

    系统设置
    说明:动态修改系统配置。
    参数名称 值的类型 是否必填 说明描述
    配置项 tablefalse
    参数名称 值的类型 是否必填 说明描述
    x 整数false窗口坐标x
    y 整数false窗口坐标y
    宽度 整数false窗口宽度
    高度 整数false窗口高度
    标题 文本false窗口标题
    垂直同步 逻辑false是否启用垂直同步
    掉血数字 整数false范围0-100,控制默认掉血效果出现的几率
    血液效果逻辑值或 tablefalsever-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
    角色血条 整数false0:不显示
    1:合并显示 (默认)
    2:独立显示
    角色名称 整数false0:不显示
    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支持丰富文本
    属性表 tablefalse
    参数名称 值的类型 是否必填 说明描述
    x 整数false显示坐标x
    y 整数false显示坐标y
    行距 整数false两次提示间的间隔距离 默认:2
    气泡皮肤 文本false气泡皮肤名称
    对齐方式 整数false0 左对齐 1 居中对齐 2 右对齐
    动画效果 整数false0 直接显示 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 整数truex坐标偏移
    y 整数truey坐标偏移
    内容 文本true
    艺术字 文本true资源标识
    目标对象 对象false显示在哪? 如果不填表示屏幕最顶层
    属性表 tablefalse
    参数名称 值的类型 是否必填 说明描述
    颜色 RGBAfalse
    间距 整数false
    缩放 数值false缩放比例
    平滑 逻辑false缩放时是否启用平滑效果 默认:false
    动效 整数false0-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 随机像素溶解
    回调函数 functionfalse 转场后触发函数
    地图转场 逻辑false是否只针对地图场景转场 默认:false
    半场模式 逻辑false是否只显示后半场过渡 默认:false

    示例

    引擎.转场动画(1000,0) 
    
    
    
    引擎.转场动画(1000,0,nil,false,true) -- 仅显示后半段过渡效果
    
    

    播放特效

    播放特效
    说明:在指定位置播放一个特效。
    参数名称 值的类型 是否必填 说明描述
    x 整数truex坐标偏移
    y 整数truey坐标偏移
    特效配置 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支持丰富文本
    按钮类型 整数true0 确定 1 确定取消 2 输入框+确定取消
    额外配置 tablefalse
    名称 类型 说明描述
    确定按钮标题 文本默认:确定
    取消按钮标题 文本默认:取消
    确定按钮宽度 整数默认: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 整数/niltrue对话窗口坐标x,nil表示关闭对话窗口
    y 整数true对话窗口坐标y
    标题 文本true对话窗口有标题时有效
    内容 文本true对话框中的内容,支持丰富文本
    数据源 tablefalse会传递到事件函数中

    示例

    {
    
    
    
      名称 = "测试按钮",
    
      类型 = "按钮",
    
      宽度 = 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
    附加 tablefalse如果填写会传递到道具的 创建 事件中

    示例

    引擎.增加物品("八荒刀",1,{攻击=20})
    
    引擎.增加物品("粗布衣",1,{给白装=true})
    
    引擎.增加物品("金创药小",6)
    
    引擎.增加物品("魔法药小",6)
    
    引擎.增加物品("金创药中",6)
    
    引擎.增加物品("魔法药中",26)
    
    引擎.增加物品("雷电术")
    
    

    注意事项
    1、可以用 引擎.取包裹空位() 进行前置判断。

    取包裹空位

    取包裹空位
    说明:取所有包裹类控件剩余的空位数量。
    参数名称 值的类型 是否必填 说明描述
    包裹名称 文本falsenil表示取所有包裹空位

    示例

    local 剩余空位 = 引擎.取包裹空位()
    
    调试输出(剩余空位)
    
    
    返回值 值的类型 说明描述
    数量 整数

    取物品数量

    取物品数量
    说明:取包裹中指定物品的总数量。
    参数名称 值的类型 是否必填 说明描述
    道具名称 文本true

    示例

    local 物品数量 = 引擎.取物品数量("金创药小")
    
    调试输出(物品数量)
    
    
    返回值 值的类型 说明描述
    数量 整数

    减少物品

    减少物品
    说明:从包裹格子里面减少物品。
    参数名称 值的类型 是否必填 说明描述
    道具名称 文本true
    数量 整数true

    示例

    引擎.减少物品("金创药小",2)
    
    

    注意事项
    1、可以用 引擎.取物品数量() 进行前置判断。

    创建音乐

    创建音乐

    说明:创建一个音乐对象。
    ver-20:资源标识可省略以先创建空对象;创建后需调用播放。标识未注册时返回 nil;标识已注册但文件加载失败时返回对象,可查询加载状态/加载错误。不同对象使用同文件时各自独立,显式重试不再被累计失败次数永久阻断。地图背景请优先使用地图配置的地图音乐/环境音乐。

    参数名称 值的类型 是否必填 说明描述
    音乐素材 文本/nilfalse音乐资源素材标识;省略时创建空对象

    示例

    local 背景音乐 = 引擎.创建音乐("一直很安静")
    
    背景音乐.音量 = 50
    
    背景音乐.循环 = true
    
    背景音乐.播放()
    
    
    返回值 值的类型 说明描述
    对象 音乐对象

    创建缓动

    创建缓动

    说明:创建一个缓动对象。

    参数名称 值的类型 是否必填 说明描述
    自动销毁 逻辑false默认:true

    示例

    引擎.创建缓动()
    
    .by(按钮对象.父窗口.地图按钮,{y=-100,x=100},500)
    
    .by(按钮对象.父窗口.地图按钮,{y=100,x=-100},500)
    
    
    返回值 值的类型 说明描述
    对象 缓动对象支持链式调用

    添加指针

    添加指针

    说明:使用组件自定义指针样式,通过引擎.鼠标指针动态显示。

    参数名称 值的类型 是否必填 说明描述
    组件配置 tabletrue精灵,动画...等基石组件

    示例

    引擎.添加指针(
    
      {
    
        名称 = "指针默认",
    
        类型 = "精灵",
    
        图片 = "鼠标指针_默认"
    
      }
    
    )
    
    
    
    引擎.鼠标指针 = "指针默认"
    
    

    注意事项
    1、相同名称的指针组件添加一次即可,之后通过鼠标指针设置名称显示。

    弹出菜单

    弹出菜单

    说明:在鼠标位置弹出指定 菜单 项目。

    参数名称 值的类型 是否必填 说明描述
    菜单名称 文本false
    附加 通用false会传递到菜单点击事件中
    屏幕坐标x 整数false
    屏幕坐标y 整数false

    示例

    引擎.弹出菜单("物件菜单")
    
    

    注意事项
    1、未指定弹出坐标的情况下,默认会在鼠标坐标处弹出。

    存档

    存档
    说明:存档。
    参数名称 值的类型 是否必填 说明描述
    存档文件名 文本/niltrue存档到指定文件,如果为nil表示存档到table
    附加 tablefalse需要保存的自定义数据
    密钥 文本false不填表示不加密

    示例

    local 结果 = 引擎.存档("save.dat",{金币=20,技能点=30},"ttttt")
    
    调试输出(结果)
    
    
    
    
    
    local 结果 = 引擎.存档(nil,{金币=20,技能点=30},"ttttt")
    
    调试输出(结果)
    
    
    返回值 值的类型 说明描述
    结果 逻辑/table存档到文件失败返回false,存档到table格式为{ver,dat}

    提示

    默认存读档的内容:包裹格子,道具格子,技能格子,快捷格子,主角所在的地图,位置,方向,等级,经验。

    读档

    ver-23 兼容修复:读档切换地图时,地图音量接入不再依赖 debug.getmetatable。旧的手动音乐调用可保留;地图两个音量值在同一引擎实例内保持当前设置,不从角色存档恢复。本机真实引擎已验证合成存档和加密存读档,同事客户端待复测。

    读档
    说明:读档。
    参数名称 值的类型 是否必填 说明描述
    存档文件名/存档信息 文本/tabletrue存档保存的位置或者存档table信息
    密钥 文本false不填表示不加密
    配置 tablefalse
    成员 类型 说明
    跳转地图 逻辑是否跳转到存档时的地图 默认: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
    区域tabletrue{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|*.*|"。

    取地图随机空位(ver-18)

    引擎.取地图随机空位(地图名称, 配置):无需进入目标地图,提前随机选取一个非障碍格子。使用点号调用,不是引擎.地图的方法。适合藏宝图提前确定目标地图和坐标;本接口不负责提示、扣道具、刷 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触发的事件名称
    附加信息 tablefalse事件触发时可以取出
    延迟时间 数值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标签。
    格子大小数值falsever-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-10Heimei-EG-lua ver-2新增引擎.富文本道具,支持用 table/道具对象生成动态#item显示快照并复用标准道具气泡。
    2026-09-10Heimei-EG-lua ver-3修复动态道具热点的对象二次解析,并让返回标签复用快照的格子效果配置。
    2026-09-10Heimei-EG-lua ver-4定点修复格子效果代理未捕获引擎内部SystemDat导致的实机绘制报错;接口和渲染规则不变。
    2026-09-10Heimei-EG-lua ver-5富文本道具新增可选格子大小,统一虚拟格子布局/热点,隔离效果动画及裁剪状态;混合显示未修改,实机待测。
    2026-09-10Heimei-EG-lua ver-6定点修复第六参数路径的原生绘制整数类型约束,保留参数格式、尺寸及气泡行为。
    2026-09-10Heimei-EG-lua ver-7对齐原生道具格的缩放与图层所有权,修复系统底图误作尺寸基准和主图标重复绘制。
    2026-09-13ver-18新增引擎.取地图随机空位,无需进入目标地图;支持范围/边距、模板及配置障碍、失败返回和有限扫描,说明不刷怪及可达性边界。
    2026-09-14ver-20创建音乐保持显式播放;同文件不同实例独立,失败计数不再永久阻止显式重试。
    2026-09-15ver-23修复读档切图时地图音乐接入的调试 API 依赖;旧音乐写法及当前音量保持。

    删除事件

    删除事件
    说明:删除指定自定义事件。
    参数名称 值的类型 是否必填 说明描述
    事件名称 文本true

    示例

    系统事件 = {
    
    
    
        游戏开始 = function()
    
           引擎.加入事件("系统时钟",{},1000,false)
    
        end,
    
    
    
        系统时钟 = function (tbl,dt,time)
    
          调试输出(dt,time)
    
          引擎.删除事件("系统时钟")
    
        end,
    
    
    
    }