地图

地图音乐与环境音乐（ver-20）

在地图配置中直接声明两个资源标识：

local 地图配置 = {

    类型 = "地图",

    名称 = "封神陵",

    地图模板 = "封神陵模版",

    地图音乐 = "P失乐园",

    环境音乐 = false, -- 设置为已注册的环境音乐资源标识后自动播放

}

return 地图配置

引擎实际载入地图成功后处理两路音频，包括默认首地图和已缓存地图的再次进入。两路默认循环，各自与上一次资源标识比较：同标识保持当前位置，变化时先停止旧曲并加载新曲。nil/false/空串关闭对应路；无效类型按关闭处理。未注册标识/缺失文件使该路失败，不能沿用上一张地图的声音。载入地图失败时继续保留原地图及音频。只查询未进入地图的配置或空位不会触发播放。

通过引擎.地图.音乐音效音量与引擎.地图.环境音效音量分别调节。默认 100，0 静音且保持播放进度，跨地图继承。音量持久化由项目自行保存；配置中不支持每图覆盖这两个统一音量。环境音乐适合持续风声、水声等背景循环；原有技能、攻击、界面和天气雷声仍使用普通音效路径。

配套前端 22 张地图已将既有配乐写入game/map/map.lua。新库以这里的字段为准；L地图数据.音乐仅供尚未替换库时的过渡代码，修改它不会影响 ver-20 自动播放。当前未提供环境声素材，22 张地图的环境音乐均为 false；请先注册自己的资源，再填写标识。

验证：真实 Game_Map 注册器已确认保留这两个字段，原生独立静音项目验证自动循环、同文件双路、切图、空配置停播及音量继承。远程资源下载及完整用户游戏听感未实测。

介绍

地图是一个指定宽高和行列的矩形网格，可以配置项制作也可以直接使用地图模板。

local 地图配置 = {

    类型 = "地图",

    名称 = "新手地图",

    格子宽度 = 64,

    格子高度 = 32,

    格子列数 = 24,

    格子行数 = 48,

    默认地图 = true,

    初始位置 = {x=12,y=24}

}



return 地图配置 

local 地图配置 = {

	类型 = "地图",

	名称 = "泡点图",

	默认地图 = true,

	初始位置 = {x=22,y=19},

	地图模板 = "泡点图",

	资源表 = {

		{标识="泡点图",文件="dmstore_JD36KaqD2UCbEDOuDt0A"}, 

	}

}

return 地图配置 

配置项

环境色

• 颜色值为RGBA，当地图中的组件有光影效果时，A会影响所有光影亮度，
• ver-31：空光影表或缺少颜色的对象不产生灯光，开启环境色不会因此调用 GET_A(nil)；完整光影配置的行为不变。

环境色 = RGBA(255,255,255,255),  -- 正常

环境色 = RGBA(40,40,40,255),  -- 黑灯瞎火

环境色 = RGBA(153,204,230,255), -- 雪山青 雪地、冰川、寒冷环境



环境色 = RGBA(30,30,30,128), -- 当地图中有光影组件的时候，所有光影的亮度降低50%

地图物件

> 地图物件可以是图片,动画,显示在地表或是参与物件排序。

资源表 = {

    {标识="门点动画",文件="100/地表特效/atlas.json"},

    {标识="美女图",文件="100/美女.jpg"},

    {标识="路牌",文件="100/路牌.png"},

    {标识="小树",文件="100/小树.png"},

    

},



地图物件 = {

    {0,986,619,"美女图",0,0},{1,1529,780,"路牌",60,105},{1,1410,860,"小树",118,112},{0,1410,860,"门点动画,default",118,112}

},

地图格子

> 设置障碍格子,透明格子信息。

地图格子 = {

    {25,19,1},{17,22,2},{18,22,2}

},

地图角色

> 设置地图角色刷新。

地图角色 = {

    {名称="将军",阵营="中立",格子x=22,格子y=10,范围=0,数量=1},

    {名称="稻草人",阵营="敌方",格子x=22,格子y=10,范围=0,数量=4},



    {

        名称="稻草人BOSS",

        阵营="敌方",

        格子x=22,

        格子y=10,

        范围=0,

        数量=1,

        角色大小=1.0,

        重生间隔=300000,

        附加={boss=true},

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

        状态={

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

            {"BOSS增强",{}}

        }

    },

},

地图门点

> 设置地图自动传送的格子。

地图门点 = {

    {29,17,"暗殿密室2",24,18,2}

},

地图光源

> 设置地图光源

地图光源 = {

    {3650,2888,0.5,0.5,1,1,RGBA(255, 255, 0,255)},

    {2474,2665,0.5,0.5,2,2,RGBA(255, 255, 255,255)},



},

屏幕位置

• 设置地图在屏幕上的显示区域
• 默认镜头显示在屏幕中心,可以通过镜头微调中心位置。

屏幕位置 = {400,0,400,280,-96,0},

藏宝图提前选点（ver-18）

地图通过现有配置注册后，可调用引擎.取地图随机空位('地图名称', {边距=2, 范围={20,30,80,60}})，范围可省略。返回 0 起始的格子 x、y，失败返回 -1、-1、错误文本；不是像素坐标。

未进入地图时读取模板障碍并叠加本配置的地图格子，不调用场景加载/创建事件；无模板地图按行列和手工障碍取点。模板资源须已在正常资源表中声明。地图创建回调中临时设置的障碍无法提前预知，加载后调用则使用当前静态障碍数组。

没有新增地图根配置字段。不会自动刷新 BOSS、预留坐标或保证入口连通，应保存取点结果并在业务真正刷怪时重新校验。范围/边距/失败条件与性能限制见引擎接口。

天气（ver-24）

ver-24 的天气支持发布后统一 PNGZ 文件及标识，继续使用已注册的 HeimeiWeather17 资源。可在下方调用中加入 画质='极高'；四天气的粒子、雾团、相关地面容量及流动层在高档基础上翻倍。未指定仍为中档。此选项不改变天气速度、脚印步距或雷暴时序；图集布局、关闭开关和绘制层级沿用原行为。真实 App.exe 独立 24 场景通过，用户完整游戏视觉和帧率仍待复测。

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

通过地图创建事件开启天气，先安装 Res/HeimeiWeather17/ 的 8 张图片与 1 个雷声资源，并在资源表声明。新增 atmosphere.png，fog/ground 图集布局已改变。不要每帧重复设置，每次成功设置会替换原天气并清空其积雪进度。

系统事件 = {

    创建 = function(地图对象)

        地图对象.设置天气 {

            类型='下雪', 雪量='大雪', 画质='极高', 密度=0.85, 淡入=1000,

            积雪={强度=0.82, 积累速度=1, 停留=15000, 预生成距离=256},

            雪幕浓度=0.12, 雪地=false,

            脚印={停留=6000}, 阵风=true,

        }

    end,

}

未新增地图根配置天气字段。参数、资源、画质和验证状态详见地图天气。天气只推进当前可视地图，适配屏幕位置宽高。地表 → 水花/雪面/脚印 → 角色 → 雪幕/底雾/氛围景深 → 团雾/天空天气/闪电 → 普通窗口/UI；天气也可能覆盖地图内部气泡。地面效果固定世界坐标并跟随视距，前景雪幕不是物体顶面积雪。

示例用于普通地面，积雪覆盖达到 0.2 才留印。已有雪地素材时可设雪地=true跳过覆盖判定，但它不负责铺雪。ver-17 的地图共享积雪进度由当前天气持续推进，新区域/瞬移/视距换级继承已有进度；有界网格缓存提前准备视野周围及运动前方，不维护永久全图雪面。清除/切换/重新设置会释放；非当前地图和暂停时进度冻结。

大雾支持根配置颜色=0x5F9641D2表现绿色瘴气，仍需项目另做毒伤逻辑；四种天气都可选氛围景深={远景颜色=0x376F94FF, 远景浓度=0.55, 近景压暗=0.16, 边缘压暗=0.18, 清晰范围=0.7}。这是 2D 气氛叠层，不读取真实深度、不改环境色或黑白状态、不识别屋顶/宝箱轮廓。

当前脚印只跟踪主角，不自动识别屋顶、室内或地面材质，可用最多 32 个世界像素矩形组成的地面区域限制地面效果，不能限制天空天气。

更新记录

系统事件

🔹 创建

地图创建后触发

系统事件 = {

    创建 = function (地图对象)

        调试输出(地图对象.名称, 地图对象.格子行数,地图对象.格子列数)

    end

}

🔹 鼠标事件

• 地图上发生鼠标事件时触发。需要开启配置项中的 鼠标事件。
• 按下 事件时 返回 true 可以阻止主角移动。

系统事件 = {



	鼠标事件 = function (地图对象,事件,信息)

		

		if(地图对象.附加.镜头 == nil) then

			地图对象.附加.镜头 = {x=地图对象.主角.x,y=地图对象.主角.y,_x=信息.屏幕坐标.x,_y=信息.屏幕坐标.y}

			引擎.地图.镜头对象 = 地图对象.附加.镜头

		end



		local 镜头信息 = 地图对象.附加.镜头





		if (事件 == "按下") then



			if (信息.键值 == 1) then	-- 右键

				镜头信息.开始移动 = true

				镜头信息._x = 信息.屏幕坐标.x

				镜头信息._y = 信息.屏幕坐标.y



			elseif (信息.键值 == 0) then	-- 左键



				local 格子状态 = 地图对象.地图格子(信息.地图格子.x,信息.地图格子.y)

				格子状态 = 格子状态 == 1 and 0 or 1 



				地图对象.地图格子(信息.地图格子.x,信息.地图格子.y,格子状态)



			end



		

			local 焦点角色 = 信息.焦点



			if (焦点角色) then

				调试输出("焦点角色",焦点角色.名称)

			--	焦点角色.自动战斗 = false

			--	焦点角色.主动攻击 = false

			--	焦点角色.移动控制 = true

			end





			return true	-- 拦截事件



		elseif (事件 == "弹起") then

			镜头信息.开始移动 = false





		elseif (事件 == "移动") then



			if (镜头信息.开始移动) then



				local px = 信息.屏幕坐标.x - 镜头信息._x 

				local py = 信息.屏幕坐标.y - 镜头信息._y 



				镜头信息.x = 镜头信息.x - px * 地图对象.视距 

				镜头信息.y = 镜头信息.y - py * 地图对象.视距 

				镜头信息._x = 信息.屏幕坐标.x

				镜头信息._y = 信息.屏幕坐标.y



                地图对象.镜头平滑移动 = true

			

			end



		elseif (事件 == "滚轮") then 



			if (信息.键值 > 0) then -- 上滚动

				地图对象.视距 = math.max(0.5,地图对象.视距 - 0.2)

			else 

				地图对象.视距 = math.min(6,地图对象.视距 + 0.2)

			end



            地图对象.镜头平滑移动 = false



		end



	end



}

🔹 自定义事件

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

系统事件 = {



    创建 = function(地图对象)

        地图对象.加入事件("自动刷怪",{名称="稻草人",数量=1},500,false)

    end,



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

        地图对象.创建角色(附加.名称,20,20,"敌方",6,附加.数量); 

    end,



}

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