App.lua

介绍

App.lua是每个项目的入口文件，游戏的启动配置项在这里填写。

配置项

名称 类型 必填 说明
游戏标题 文本falsewindows窗口标题
屏幕宽度 整数false屏幕宽度
屏幕高度 整数false屏幕高度
屏幕帧率 整数false屏幕刷新帧率 默认:60
垂直同步 逻辑false是否开启垂直同步 默认:false 开启后屏幕帧率将按显示器刷新率为准
背景颜色 RGBAfalse默认：0, 屏幕适配模式[3]时作为透明关键色
屏幕适配 整数false
重复按键 逻辑false当键盘按键被按住时,是否允许连续收到按下事件。默认：false
资源表 tablefalse{ {标识="",文件=""}, {标识="",文件=""}, }
默认字体 tabletrue
信息框 tablefalse
技能气泡 tablefalse
道具气泡 tablefalse
状态气泡 tablefalse
掉落物 tablefalse
状态图标 tablefalse
道具格子 tablefalse
控件皮肤 tablefalse
扩展属性 tablefalse
扩展组件 table {}false
扩展脚本 table {}false
装备套装 table {}false
菜单 table {}false
系统事件 tablefalse

屏幕适配

  • 0：无适配
  • 1：窗口可以拉伸 画面缩放
  • 2：窗口可以拉伸 画面同步屏幕宽高
  • 3：无边框透明窗口 通过背景颜色设置透明关键色 例如：背景颜色 = RGBA(0,32,0,255)

基础属性

  • 引擎内置了10个基础属性：hp mp maxhp maxmp 命中 躲避 暴击 暴伤 移动速度 攻击速度
  • 命中：命中几率 = 攻击者命中 / (攻击者命中 + 被攻击者躲避) * 100
  • 暴击：暴击几率 = 取随机数(1,100) <= 攻击者暴击 。
  • 暴伤：暴击伤害,默认值: 150 表示触发暴击后产生 1.5倍伤害。
  • 移动速度：百分比属性 正值表示加速,负值表示减速。设置-10 表示移动速度-10%
  • 攻击速度：百分比属性 正值表示加速,负值表示减速。设置50 表示攻击速度+50%

扩展属性

  • 除基础属性之外你可以自己扩展需要的属性，扩展属性只能为数值型。
扩展属性 = {攻击=0,防御=0}, -- 游戏中有了 攻击，防御

提示

扩展属性会自动应用于整个游戏系统，道具，角色，技能 等等各种组件中都自动扩展拥有了这些属性。

扩展组件

  • DM3是一个组件化的引擎，通过即插即用的各种组件积木式产生游戏。
  • 目前的组件种类有 角色 地图 道具 技能 状态 窗口 ...
  • 组件是一个个配置项文件，后缀名为.lua，需要保存到工程目录下，然后加入到扩展组件。
扩展组件 = {

    "UI/底部UI.lua",

    "UI/角色窗口.lua",

    "DB/Npc/主角.lua",

    "DB/Npc/稻草人.lua",

    "DB/Map/泡点图.lua",

    "DB/Item/八荒刀.lua",

    ...

    ...

},

提示

阅读文档，编写各种类型的组件。

扩展脚本

  • 自定义的Lua脚本，没有格式要求。DM3使用Lua5.4，没有特殊限制，你可以用来封装自己的系统或者常用的公共函数。
  • 扩展脚本会在游戏组件初始化之前载入执行。依次执行完成后触发 系统事件 🔹 启动
扩展脚本 = {

    "DB/系统.lua",

    ...

    ...

},

掉落物

  • 掉落物是指在游戏中物品掉落地面时的显示效果。
  • 默认按住Alt键显示物品名,可以通过系统设置设置持续可见。
名称类型说明
影子底图文本静态图片资源标识,物品阴影细节
闪烁动画文本物品掉落时的按频率间隔闪烁的动画,动作名固定为 default
字体文本地面显示名字体 默认：默认字体
间距整数字体间距
行距整数字体行距
背景色颜色标题的背景颜色 默认：RGBA(0,0,0,100)

状态图标

名称类型说明
x整数状态图标在屏幕上的起始坐标x
y整数状态图标在屏幕上的起始坐标y
宽度整数状态图标的显示宽度
高度整数状态图标的显示高度
列数整数一行显示多少个图标,超过后换行显示
间距整数状态图标之间的间距
行距整数状态图标每行之间的行距
左对齐逻辑从左到右还是从右到左顺序显示
字体逻辑状态图标标题字体
字体间距整数标题字体的间距
置顶逻辑状态图标显示是否在屏幕最顶层
标题偏移整数状态标题坐标y偏移 默认:0

道具格子

  • 设置默认道具格子效果
  • 例：道具格子 = {底图 = "默认皮肤|格子底图3",数量标签={字体="宋体14粗",间距=1,边距=2,模式=0}},
名称类型说明
底图文本静态图片资源标识,格子的背景图
数量标签table默认的数量标签显示设置
字体：系统默认字体
间距：系统默认间距
边距：默认2
模式：0 右下对齐 1 左上对齐 2 不显示 默认0

装备套装

  • 一个套装配置数组,部件中道具对象可以在属性中可以取出[套装]属性。
名称类型说明
名称文本套装的唯一名称
部件table {}道具名称数组
效果table {}数组索引对应激活几个部件的效果
装备套装 = {

  {

    名称 = "全村的希望",

    部件 = {"黄金手镯","黄金戒指","黄金项链"},

    效果 = {

      {},	-- 1件

      {{"maxhp",20},{"maxmp",20}},	-- 2件

      {{"移动速度",20},{"攻击速度",20}}	-- 3件

    }

  },

  {

    名称 = "圣战套",

    ...

    ..

  }

},

菜单

  • 配合引擎中的弹出菜单方法,引擎中的菜单属性使用。
  • 菜单点击事件会触发到系统事件🔹菜单中。
  • 菜单永远在屏幕最顶层显示。
名称类型说明
名称文本菜单项的唯一名称
-: 画一条分割线
标题文本屏幕显示的内容
可视逻辑
选中逻辑
禁用逻辑
子菜单table允许嵌套
菜单 = {

  物件菜单 = {

    {名称="复制",标题="复制",可视=true,选中=false,禁用=false},

    {名称="网格对齐",标题="网格对齐",可视=true,选中=false,禁用=false},

    {名称="保存配置",标题="保存配置",可视=true,选中=false,禁用=false},

    {名称="测试子菜单",标题="测试子菜单",可视=true,选中=false,禁用=false,

      子菜单 = {

        {名称="子菜单1",标题="子菜单1",可视=true,选中=false,禁用=false},

        {名称="子菜单2",标题="子菜单2",可视=true,选中=false,禁用=false},

        {名称="子菜单3",标题="子菜单3",可视=true,选中=false,禁用=false,

          子菜单 = {

            {名称="平铺地面",标题="平铺地面",可视=true,选中=false,禁用=false},

          }

        },

        {名称="子菜单4",标题="子菜单4",可视=true,选中=false,禁用=false},

        {名称="子菜单5",标题="子菜单5",可视=true,选中=false,禁用=false},

      }

    }, 

    {名称="删除",标题="删除",可视=true,选中=false,禁用=false},

  },

  地表菜单 = {

    {名称="平铺地面",标题="平铺地面",可视=true,选中=false,禁用=false},

  },



},

系统事件

🔹 启动

  • 游戏启动后,系统载入所有扩展脚本后最先触发的回调。 通常用于游戏开始前的各种准备
  • 通过 -g -c 启动游戏可以传递命令行参数，参数间按空格分隔。
  • 返回 false 可以立即结束程序。

示例

系统事件 = {

  启动 = function(arg)	

    Log(arg)

  end,

}

🔹 游戏开始

游戏组件载入完成后激活此事件。

🔹 游戏关闭

点击游戏屏幕关闭按钮时,触发此事件。返回 false 可以拦截

示例

系统事件 = {

  游戏关闭 = function()	

    local 结果 = 引擎.信息框("#z(240,0,1)\n#md你确定要退出吗？",1)

    return 结果

  end,

}

🔹 焦点变化

游戏窗口焦点变化时触发

回调参数 类型 说明描述
屏幕焦点 逻辑 获得焦点：true 丢失焦点：false

示例

系统事件 = {

  焦点变化 = function (屏幕焦点)

    调试输出(屏幕焦点)

  end,

}

🔹 状态变化

游戏窗口状态变化时触发

回调参数 类型 说明描述
状态 整数 1 最小化2 最大化3 还原4 老板键隐藏

示例

系统事件 = {

  状态变化 = function (状态)

    调试输出(状态)

  end,

}

🔹 宽高变化

屏幕适配 = 2时,游戏窗口宽高改变时触发

回调参数 类型 说明描述
宽度 整数
高度 整数

示例

系统事件 = {

		宽高变化 = function (宽度,高度)

			local 底部UI = 引擎.窗口.底部UI

			底部UI.x = (宽度 - 底部UI.宽度) * 0.5 // 1

			底部UI.y = 高度 - 底部UI.高度

		end,

}

🔹 键盘按下

按键按下触发

回调参数 类型 说明描述
按键信息 table
成员 类型 说明
code 整数键值
alt 逻辑alt键状态
shift 逻辑shift键状态
control 逻辑ctrl键状态

示例

系统事件 = {

    键盘按下 = function (按键信息)

        调试输出(按键信息)

    end,

}

🔹 键盘弹起

按键弹起时触发

回调参数 类型 说明描述
按键信息 table
成员 类型 说明
code 整数键值
alt 逻辑alt键状态
shift 逻辑shift键状态
control 逻辑ctrl键状态

示例

系统事件 = {

    键盘弹起 = function (按键信息)

        调试输出(按键信息)

    end,

}

🔹 菜单

菜单关闭和点击事件会触发到此处。

回调参数 类型 说明描述
菜单名称 文本菜单名称
项目 table/nil 子菜单对象 nil：菜单关闭
附加 通用 弹出菜单中传递的附加信息

示例

系统事件 = {

	菜单 = function(菜单名称,项目,附加) 

		调试输出(菜单名称,项目)

		if (项目 == nil) then

			调试输出("菜单关闭")

			return 

		end

		if (菜单名称 == "物件菜单") then

			if (项目.名称 == "网格对齐") then

				项目.选中 = not 项目.选中

			end

		end

	end,

}

🔹 超链接

丰富文本的超链接事件会统一回调到此处。

回调参数 类型 说明描述
事件 文本 热点 点击
链接 文本 / table {} #@中的 触发标识
x 数值 链接屏幕坐标x
y 数值 链接屏幕坐标y
文本框对象 文本框 这个事件从哪里来

示例

系统事件 = {

    超链接 = function (事件,链接,x,y,文本框)	

        if (事件 == "点击") then

            调试输出(链接)

        end

    end,

}

🔹 道具气泡提示

道具气泡弹出时触发,通常用户动态修改气泡内容

回调参数 类型 说明描述
道具对象 道具对象
格子对象 格子对象 道具所在的格子组件
装备对比 逻辑 是否有装备对比行为

提示

Heimei-EG-lua ver-2 起，由引擎.富文本道具生成的热点也复用本事件。此时道具对象是传入信息创建的道具快照，装备对比固定为 false；格子对象是虚拟上下文 table，包含类型='富文本道具'、名称、道具和附加字段，不是可拖放的实体道具格子。 Heimei-EG-lua ver-3 修复动态热点进入绘制/悬停阶段后再次解析道具对象时可能得到 nil 的问题。调用参数和虚拟格子结构不变；ver-2 实机测试中出现的DrawPopuNode局部道具对象为 nil 报错，应改用 ver-3 或后续版本复测。

示例

系统事件 = {

  道具气泡提示 = function (道具对象,格子对象,装备对比)

		local 主角对象 = 引擎.地图.主角



		local 需要等级 = 道具对象.等级

		local 等级颜色 = "#W"

		if (需要等级 > 主角对象.等级 ) then

			等级颜色 = "#R"

		end

		

		local 富文本 = "#z(140,0,1)\n#z(2,-12)#f(宋体14粗)#c(".. 道具对象.颜色 ..")".. 道具对象.显示名

		if (装备对比) then

			-- 显示一个已装备图标

			富文本 = 富文本 .. "\n#p(已装备图标,98,-16)\n#z(0,-8)"

		else 

			富文本 = 富文本 .. "#z(0,10,1)\n"

		end



		富文本 = 富文本 .. "#p(默认皮肤|格子底图)#p(".. 道具对象.图标 ..",-44,0,42,42)#f(宋体12)#W#z(4,-42)\n"

		富文本 = 富文本 .. "类型：" .. 道具对象.子类 .. "\n" .. 等级颜色 .. "等级：" .. 需要等级 .. "\n#W限制：无\n#z(0,0)"



		if (道具对象.分类 == "装备") then

				



			local 附加属性 = 道具对象.附加



			if(道具对象.攻击 > 0 ) then

				富文本 = 富文本 .. "\n".. (附加属性.攻击 > 0 and "#c(0x66CC00FF)" or "#W") .. "攻击 " .. 道具对象.攻击 

			end



			if(道具对象.防御 > 0) then

				富文本 = 富文本 .. "\n".. (附加属性.防御 > 0 and "#c(0x66CC00FF)" or "#W") .. "防御 " .. 道具对象.防御

			end



			if(道具对象.maxhp > 0) then

				富文本 = 富文本 .. "\n".. (附加属性.maxhp > 0 and "#c(0x66CC00FF)" or "#W") .. "生命 " .. 道具对象.maxhp 

			end



			if(道具对象.maxmp > 0) then

				富文本 = 富文本 .. "\n".. (附加属性.maxmp > 0 and "#c(0x66CC00FF)" or "#W") .. "法力 " .. 道具对象.maxmp 

			end



			if(道具对象.攻击_百分比 > 0 ) then

				富文本 = 富文本 .. "\n".. (附加属性.攻击_百分比 > 0 and "#G" or "#W") .. "攻击 +" .. 道具对象.攻击_百分比   .. "%"

			end



			if(道具对象.防御_百分比 > 0 ) then

				富文本 = 富文本 .. "\n".. (附加属性.防御_百分比 > 0 and "#G" or "#W") .. "防御 +" .. 道具对象.防御_百分比  .. "%"

			end



			if(道具对象.maxhp_百分比 > 0) then

				富文本 = 富文本 .. "\n".. (附加属性.maxhp_百分比 > 0 and "#G" or "#W") .. "生命 +" .. 道具对象.maxhp_百分比  .. "%"

			end



			if(道具对象.maxmp_百分比 > 0) then

				富文本 = 富文本 .. "\n".. (附加属性.maxmp_百分比 > 0 and "#G" or "#W") .. "法力 +" .. 道具对象.maxmp_百分比  .. "%"

			end





			-- 有套装属性

			if(道具对象.套装) then



				local 套装名称 = 道具对象.套装.名称

				local 套装部件 = 道具对象.套装.部件

				local 套装效果 = 道具对象.套装.效果

				local 激活数量 = 道具对象.套装.激活数量

				local 部件数量 = #套装部件

				富文本 = 富文本 .. "\n\n#Y" .. 套装名称  .. " (" .. 激活数量 .. "/" .. 部件数量 .. ")"



				for n=1,#套装部件 do

					富文本 = 富文本 .. "\n".. (套装部件[n].数量 > 0 and "#c(255,200,0,255)" or "#H") .. 套装部件[n].名称

				end



				for n=1,#套装效果 do

					

					if(#套装效果[n] > 0) then



						富文本 = 富文本 .. "\n\n#z(0,0)" .. (激活数量 >= n and "#c(255,200,0,255)" or "#H")  .. "[" .. n .. "]:#z(4,-14)"



						for i=1,#套装效果[n] do

							local 属性名称 = 套装效果[n][i][1]

							local 属性值 = 套装效果[n][i][2]

							if (属性名称 == "maxhp") then

								属性名称 = "生命"

							elseif (属性名称 == "maxmp") then

								属性名称 = "法力"

							end

							富文本 = 富文本 .. "\n".. 属性名称 .. " +".. 属性值

						end

						

					end

				end



			end



		elseif (道具对象.分类 == "道具") then



			if (道具对象.子类 == "消耗") then

				if(道具对象.hp > 0 ) then

					富文本 = 富文本 .. "\n".. "#GHP + " .. 道具对象.hp 

				end

				if(道具对象.mp > 0 ) then

					富文本 = 富文本 .. "\n".. "#GMP + " .. 道具对象.mp 

				end

			end



		end



		富文本 = 富文本 .. "\n\n#z(0,0)#br(140)#H普普通通的".. 道具对象.显示名 .. "#z(0,2,1)"



		道具对象.气泡提示 = 富文本

  end,

}

🔹 技能气泡提示

技能气泡弹出时触发,通常用户动态修改气泡内容

回调参数 类型 说明描述
技能对象 技能对象
格子对象 格子对象 技能格子或是快捷格子

示例

系统事件 = {

  技能气泡提示 = function (技能对象,格子对象)



    if (格子对象.绑定角色 == -1) then

      if (格子对象.名称 == "雷电术技能") then

        技能对象.气泡提示 = "这是一个雷电术技能,你要掌握吗？"

      else 

        技能对象.气泡提示 = "你还不能使用这个技能"

      end

      return 

    end



    -- 只有已经添加的技能才有进度这个属性 通过判断进度可以区分是否是已经学习的技能

    if (技能对象.进度 == nil) then

      技能对象.气泡提示 = "#H#f(宋体14粗)".. 技能对象.显示名 .."\n#f(宋体12)\n未掌握"

      return

    end



    local 富文本 = "#G#f(宋体14粗)" .. 技能对象.显示名 .. "\n#W#f(宋体12)\nMP:" .. 技能对象.mp .. "\nCD:" .. math.round(技能对象.间隔 / 1000,1) .. "秒\n\n#W等级:" .. 技能对象.等级

    技能对象.气泡提示 = 富文本



  end,

}

🔹 系统提示

用于拦截捕获系统默认提示

回调参数 类型 说明描述
编号 整数1：使用技能时，技能冷却中
2：使用物品时，道具冷却中！
3：使用物品时，等级不足！
4：拾取物品时，包裹已满！
提示内容 文本默认内容

示例

系统事件 = {

  系统提示 = function (编号,提示内容)

    调试输出(编号,提示内容)

    return true -- 拦截

  end

}

🔹 自定义事件

是指通过Api 加入事件 创建的事件。

回调参数 类型 说明描述
事件附加 table 是指通过Api [加入事件]中传递进来的 附加信息
dt 数值 事件执行的实际间隔时间
time 数值 事件执行的总时间

示例

系统事件 = {



  游戏开始 = function()

    引擎.加入事件("系统时钟",{},1000,false)

  end,



  系统时钟 = function (tbl,dt,time)
    调试输出(dt,time)
  end,

}

更新记录

日期版本简易记录
2026-09-10Heimei-EG-lua ver-2记录动态富文本道具热点复用道具气泡提示事件，以及虚拟格子上下文和默认不进行装备对比的规则。
2026-09-10Heimei-EG-lua ver-3修复动态富文本道具热点二次解析为 nil 导致的DrawPopuNode报错；事件参数规则不变。