地图

旧音乐接口与读档兼容（ver-23）

ver-23 修复 ver-20/ver-22 在部分运行环境载入地图时调用缺失的 debug.getmetatable 导致 FATAL。地图音量接入现在使用引擎内部保存的原元表，保留地图对象身份和元表保护；不要求前端提供调试 API。未配置地图音乐、仅使用旧音乐对象的项目也可照常载图、读档。

旧的 引擎.创建音乐(...)、设置 循环/音量、停止() → 修改 音乐 → 播放() 调用继续可用。地图两个音量属性仅控制自动配乐及环境声，不会接管手动创建的音乐对象；缺少地图音乐字段时不创建自动播放对象。接入完成后才标记，重复加载不会叠加包装。

验证：在主动缺少 debug.getmetatable 的环境，ver-22 真实引擎读档复现旧错误，ver-23 通过相同用例、加密存读档、旧引用身份及音量保留验证。属于本机 App.exe 独立测试，尚未取得同事客户端的复测结论。

地图音频音量（ver-20）

当前地图提供两个可读写属性：

引擎.地图.音乐音效音量 = 40

引擎.地图.环境音效音量 = 25

-- 只静音环境声，音乐保持原值；环境声播放位置继续前进。

引擎.地图.环境音效音量 = 0

两项均限制为 0～100、向下取整，非数值或 NaN 忽略。它们属于当前引擎实例的统一设置，通过地图对象访问；跨图保留，保存的旧地图引用读写也作用于这两个统一值。尚无当前地图时引擎.地图为 nil，需在地图载入后设置。引擎不自动写入角色存档或本地文件。

两路资源从地图配置读取，分别比较资源标识。切到同一标识继续播放；缺少/false/空串停止该路；注册错误仅使该路失败，不影响另一条音频或地图载入。地图暂停/隐藏不会自动暂停音乐；地图重置本身不重播同曲。单独创建音乐的登录曲不受这两个属性控制，进入游戏时应停止登录曲。

配套前端使用audio_settings.dat独立保存普通音效、音乐、环境音量，旧文件环境音量默认 40；登录期间将地图两路静音，首次正式进入地图后停止登录曲并恢复本地选择。读档不会覆盖本地音量。候选字节码隔离与真实 App.exe 独立静音测试通过，完整游戏听感和设置窗口操作待用户复测。

提前取目标地图空位（ver-18）

使用全局引擎接口引擎.取地图随机空位(地图名称, 配置)，可在当前地图提前选取另一张已注册地图的非障碍格，不需要切图或执行目标地图创建事件。支持模板障碍与配置地图格子，可选格子矩形范围和地图边距。

local x,y,错误 = 引擎.取地图随机空位('祖玛寺庙', {边距=2})

if x >= 0 then

    调试输出('目标格子',x,y) -- 保存到你的藏宝目标数据，不是像素坐标

else

    调试输出(错误)

end

它不是地图对象新增方法，也不是刷怪接口。现有地图对象.取出空位仍用于已加载地图，行为不变。非障碍不保证入口可达，也不排除角色占位；实际刷怪前需复查。完整参数、-1 失败语义和同步读取/扫描预算见引擎接口。

天气方法（ver-34，兼容既有基础调用）

ver-34修正飘灰和低雾可见度，并允许低雾区域="当前视野"随镜头显示；原固定矩形数组仍支持。需要新增HeimeiWeather34两张纹理，参见地图天气。

ver-33新增类型="飘灰"/"落叶"/"低雾"；落叶支持落地停留，低雾必须指定世界像素矩形数组区域。落地叶片与低雾使用地表层，三类仍互斥切换；新增HeimeiWeather33两张图集，详细调用、数量和验证边界见地图天气。

ver-24 兼容发布器将天气图片标识和文件统一转换为 PNGZ；优先原注册标识，未注册时查询同名 PNG/PNGZ 替代注册，不改内置图集切片。四种天气新增 画质='极高'：雨雪沙粒子、雾团、水花预算和地面池容量按高档取整后翻倍，沙幕/雾噪声/雪幕噪声由 2 层增至 4 层。低、中、高行为及默认中档保持；速度、脚印步距、闪电频率与配置亮度沿用原值。全部 8 张图片继续使用 HeimeiWeather17。隔离回归及真实 App.exe 的 PNG、PNGZ、别名映射共 24 场景通过，完整游戏视觉和帧率待用户复测，详见地图天气。

ver-19 修复天气精灵复用后错误显示界面图集：每批绘制绑定当前天气纹理。沿用 Res/HeimeiWeather17/ 和原 设置天气 参数；安装新库并重启生效。旧版故障对照、隔离回归与真实 App.exe 离线验证通过，用户完整游戏画面待复测；详见地图天气。

地图对象提供设置天气(配置)、清除天气(淡出毫秒)、暂停天气(逻辑值)和取天气()，支持雨、雪、雾、黄沙，默认关闭、按地图隔离。ver-17 修复快速移动缺雪和公共边缘裁剪，积雪按地图共享进度并有界预生成，增加角色前景雪幕、雾图集保护边和可选 2D 氛围景深。需安装 Res/HeimeiWeather17/ 的 8 张 PNG 和 1 个 WAV，新增 atmosphere.png，不能混用旧 fog/ground 图集。

引擎.地图.设置天气 {类型='下雨', 雨量='中雨', 密度=0.7, 画质='中', 淡入=1000, 雷暴=false}

引擎.地图.清除天气(1000)

新增积雪.预生成距离、雪幕浓度、雪幕颜色与氛围景深。根配置颜色=0x5F9641D2可将底雾和团雾一起染成绿色，只产生视觉效果，不实现中毒。氛围景深用远景染色/近景压暗/暗角模拟远近感，不是真实深度或景深模糊，也不改地图环境色和黑白画面。

取天气()新增地图积雪进度、雪幕浓度和氛围景深开关；保留积雪覆盖/积雪网格尺寸，落雪数表示当前准备范围内的有效覆盖格数。新区域和视距换级继承本天气的地图进度，不重新积累；雪面图形缓存仍有上限，不是永久全图存档。完整参数、返回值、资源、暂停和层级见地图天气。

普通地面默认等待积雪覆盖达到 0.2 后留印；雪地=true仅跳过覆盖判定，不负责铺雪。地面雪先于角色，前景雪幕/雾/氛围在角色之后、普通 UI 之前；不能自动给宝箱顶面或屋顶积雪。仅主角生成脚印，可用地面区域限制。清除/切换/重新设置天气释放旧状态；地图重置先清除，再执行原重置与创建回调。

战斗血液效果（ver-29）

通过系统设置开启，不新增地图方法。实际扣血后在当前地图生成原生上层血滴和下层血迹，使用有界复用池；切换当前地图、地图清空/重置时释放，暂停/隐藏冻结视觉计时。地面血迹不是永久存档，空中血滴不提供逐角色/墙体深度遮挡；配置、PNGZ 资源和验证边界见战斗血液效果。

更新记录

属性

名称

• 类型：文本
• 读写：只读
• 说明：地图对象的名称。

显示名

• 类型：文本
• 读写：只读
• 说明：地图对象的显示名。

地图信息

• 类型：table
• 读写：读写
• 详情：当前地图信息。

调试输出(引擎.地图.地图信息.宽度)

镜头平滑移动

• 类型：逻辑
• 读写：读写
• 说明：用于配合镜头位置变化时使用,将镜头缓动到新的目标点。

环境色

• 类型：RGBA/nil
• 读写：读写
• 说明：动态读写地图当前环境色。 nil表示取消环境色。
• ver-31：角色等对象的 光影效果 = {} 或缺少 颜色 时，不提交该对象灯光；不影响环境色及对象本身绘制。合法 RGBA（包括 0）仍按原亮度规则绘制。

黑白画面

• 类型：逻辑
• 读写：读写
• 说明：地图是否显示为黑白效果。

暂停

• 类型：逻辑
• 读写：读写
• 说明：暂停继续地图游戏状态。

鼠标事件

• 类型：逻辑
• 读写：读写
• 说明：是否触发系统事件中的鼠标事件。

主角

• 类型：角色对象
• 读写：只读
• 说明：你可以在脚本中使用 引擎.地图.主角 快捷获得当前的主角对象。

镜头对象

• 类型：包含属性{x,y}的table
• 读写：只写
• 说明：更改当前地图的镜头绑定。

引擎.地图.镜头对象 = 引擎.地图.主角

引擎.地图.镜头对象 = 其他角色.....



引擎.地图.镜头对象 = {x=100,y=100} -- 固定镜头位置



动态镜头 = {x=100,y=100}

引擎.地图.镜头对象 = 动态镜头 -- 绑定一个自己的镜头位置对象

动态镜头.x = 动态镜头.x + 10  -- 改变x,y值镜头也会随之移动

动态镜头.y = 动态镜头.y + 10

视距

• 类型：小数
• 读写：读写
• 说明：镜头的视野缩放倍数，默认：1.0。

加速

• 类型：小数
• 读写：读写
• 说明：地图逻辑加速倍数，默认：1.0。

初始位置

• 类型：{x,y}
• 读写：只读
• 说明：地图配置项中的初始位置。

方法

创建角色

地图对象.创建角色("稻草人",20,20,"敌方",20,6); 



local 附加配置 = 

{

  角色大小=1.0,

  重生间隔=300000,

  附加={boss=true},

  掉落={"木剑 1/1","金币100 4/1"},

  状态={

    {"通用增强",{maxhp_百分比=100,攻击_百分比=30,防御_百分比=30}},

    {"BOSS增强",{}}

  }

}



地图对象.创建角色("稻草人BOSS",20,20,"敌方",20,1,附加配置); 

取出角色

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

local 角色组 = 主角对象.地图.取出角色(主角对象.格子x,主角对象.格子y,5,-主角对象.阵营)

调试输出("附近敌方数量：" ,#角色组)

查找角色

local 角色对象

if (self.客户端.cid == tbl.cid) then

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

else 

    角色对象 = 引擎.地图.查找角色(tbl.id)

end

  if (角色对象 == nil) then

    调试输出("角色不存在")

    return

end



引擎.屏幕提示(tbl.msg,{

  停留时间=12000,动画效果=0,气泡皮肤="透明气泡",限制宽度=6*20,

  x=0,y=-角色对象.角色高度 - 24,

  分组="_msg_" .. tbl.cid, 清空分组=true}

,角色对象) 

地图格子

调试输出(地图对象.地图格子(20,20)) -- 取出



地图对象.地图格子(20,20,1) -- 设置成障碍

地图光源

引擎.地图.地图光源("光源1",true)

掉落物品

local 损失金币 = 99999

local 道具对象 = 引擎.地图.掉落物品(引擎.地图.主角.格子x,引擎.地图.主角.格子y,"死亡金币",true)

if (道具对象) then

  道具对象.显示名 = "金币("  .. 损失金币 .. ")"

end





引擎.地图.掉落物品(引擎.地图.主角.格子x,引擎.地图.主角.格子y,"棉布衣",true,{系统任务=true})

设置主角

引擎.地图.设置主角(self.主控角色) 

显示气泡

引擎.加入事件("系统时钟",{},0,false) -- 持久显示的气泡 需要一个帧事件保持持续显示

-----------------------------------------------------

系统时钟 = function (tbl,dt,time)

  local 鼠标角色 = 引擎.鼠标角色

  if (鼠标角色) then

    local 丰富文本 = "Lv" .. 鼠标角色.等级 .. " " .. 鼠标角色.显示名 

    引擎.地图.显示气泡(鼠标角色.x,鼠标角色.y - 鼠标角色.角色高度 * 0.5,丰富文本)

  end

end,

重置

引擎.地图.重置();

抖动

引擎.地图.抖动(2000,10);

坐标转换

local 地图坐标x,地图坐标y = 引擎.地图.坐标转换(50,50,3)

调试输出(地图坐标x,地图坐标y)

取出空位

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

local 格子x,格子y = 引擎.地图.取出空位(主角对象.格子x,主角对象.格子y)

调试输出(格子x,格子y )

添加节点

local 选中脚底动画 = {

  名称 = "脚底动画",

  类型 = "动画",

  x = 0,

  y = 0,

  动画 = "脚底动画",

  动作 = "default",

  默认可视 = false,

}



self.脚底动画 = 引擎.地图.添加节点(选中脚底动画,0) -- 0地表  1顶层

取出节点

local 脚底动画 = 引擎.地图.取出节点("脚底动画")

脚底动画.可视 = false

清除节点

引擎.地图.清除节点(L系统.脚底动画)

加入事件

系统事件 = {



    创建 = function(地图对象)

        地图对象.加入事件("自动刷怪",{},500,false)

    end,



    自动刷怪 = function (地图对象,tbl,dt,time)

        调试输出(tbl,dt,time)

    end,



}

删除事件

系统事件 = {



    创建 = function(地图对象)

        地图对象.加入事件("自动刷怪",{},500,false)

    end,



    自动刷怪 = function (地图对象,tbl,dt,time)

        地图对象.删除事件("自动刷怪")

    end,



}

• 2026-09-19，ver-31：地图绘制跳过缺少颜色的光影配置，修复开启环境色后的 GET_A(nil)；1,078 项定点隔离检查通过，用户前端复测待确认。