pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

19 KiB

Raw Blame History

地图基础图层

**本文档中引用的文件** - [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts) - [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts) - [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts) - [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts) - [GameMap.ts](file://assets/script/game/map/GameMap.ts) - [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts) - [SkillLayer.ts](file://assets/script/game/map/view/map/layer/SkillLayer.ts) - [MoveUV.ts](file://assets/script/game/map/view/MoveUV.ts) - [map.json](file://assets/resources/config/map/map.json) - [map_delivery.json](file://assets/resources/config/map/map_delivery.json)

简介

MapLayer类是Cocos Creator游戏引擎中地图系统的核心组件，作为地图背景图层的基础实现。该类继承自cc.Component，提供了地图纹理资源的动态加载、精灵帧初始化、尺寸适配以及节点锚点校准等关键功能。通过与MapViewComp的紧密协作，MapLayer确保了在不同分辨率设备下的正确渲染和高效的性能表现。

本文档将深入解析MapLayer的实现机制，包括其生命周期管理、纹理资源处理流程、尺寸适配策略以及在地图系统中的注册与更新机制。同时，我们将探讨如何扩展MapLayer以支持多段滚动背景和动态材质更新，并提供实用的性能优化建议。

项目结构

地图系统的文件组织采用了模块化的架构设计，主要分为视图层(view)和模型层(model)两个核心部分：

graph TB
subgraph "地图系统架构"
GameMap[GameMap 游戏地图实体]
MapModel[MapModelComp 地图模型组件]
MapView[MapViewComp 地图视图组件]
subgraph "视图层组件"
MapViewScene[MapViewScene 地图场景逻辑]
MapLayer[MapLayer 地图背景层]
EntityLayer[EntityLayer 实体层]
SkillLayer[SkillLayer 技能层]
end
subgraph "配置文件"
MapConfig[map.json 地图配置]
DeliveryConfig[map_delivery.json 传送点配置]
end
end
GameMap --> MapModel
GameMap --> MapView
MapView --> MapViewScene
MapViewScene --> MapLayer
MapViewScene --> EntityLayer
MapViewScene --> SkillLayer
MapModel --> MapConfig
MapModel --> DeliveryConfig

图表来源

章节来源

核心组件

MapLayer类设计

MapLayer作为地图背景图层的核心实现，具有以下关键特性：

属性/方法	类型	描述	默认值
bgImg	Sprite	背景图像精灵组件	null
width	number	图层宽度属性	动态计算
height	number	图层高度属性	动态计算
init()	void	初始化方法	-
clear()	void	清理方法	-
bgImage	Sprite	背景图像访问器	-

组件继承体系

classDiagram
class Component {
+onLoad() void
+start() void
+update(dt : number) void
+destroy() void
}
class MapLayer {
-bgImg : Sprite
+init() void
+clear() void
+bgImage : Sprite
+width : number
+height : number
}
class MapViewScene {
+camera : Camera
+layer : Node
+mapLayer : MapLayer
+floorLayer : Node
+entityLayer : EntityLayer
+SkillLayer : SkillLayer
+isFollowPlayer : boolean
+ratio : Vec2
+onLoad() void
+start() void
+reset() void
+init() void
+update(dt : number) void
}
class EntityLayer {
-timer : Timer
+update(dt : number) void
+clear() void
}
class SkillLayer {
-timer : Timer
+light : Prefab
+onLoad() void
+doSkill() void
+update(dt : number) void
+clear() void
}
Component <|-- MapLayer
Component <|-- EntityLayer
Component <|-- SkillLayer
MapViewScene --> MapLayer : "包含"
MapViewScene --> EntityLayer : "包含"
MapViewScene --> SkillLayer : "包含"

图表来源

章节来源

架构概览

地图系统采用ECS（Entity-Component-System）架构模式，通过组件化设计实现了高度的灵活性和可扩展性：

sequenceDiagram
participant GM as GameMap
participant MM as MapModel
participant MVC as MapViewComp
participant MVS as MapViewScene
participant ML as MapLayer
participant BG as Background Sprite
GM->>MM : 创建地图模型
GM->>MVC : 加载地图视图
MVC->>MVS : 初始化场景逻辑
MVS->>ML : 注册地图层
ML->>BG : 初始化背景精灵
BG->>ML : 设置纹理资源
ML->>MVS : 完成初始化
MVS->>MVC : 场景就绪
MVC->>GM : 视图组件激活
Note over GM,BG : 地图初始化完成

图表来源

详细组件分析

MapLayer生命周期管理

MapLayer的生命周期管理遵循Cocos Creator的标准组件生命周期，通过init()方法进行初始化配置：

flowchart TD
Start([组件加载]) --> OnInit["调用init()方法"]
OnInit --> GetTransform["获取UITransform组件"]
GetTransform --> CalcSize["计算宽度和高度"]
CalcSize --> SetSize["设置节点尺寸"]
SetSize --> Ready([初始化完成])
Ready --> UpdateLoop{"游戏循环"}
UpdateLoop --> UpdateLoop
Ready --> ClearCall["调用clear()方法"]
ClearCall --> ResetSprite["重置精灵帧"]
ResetSprite --> Cleanup([清理完成])

图表来源

MapLayer.ts

初始化流程详解

MapLayer的init()方法负责设置图层的基本属性，主要包括：

尺寸适配：通过UITransform组件动态调整节点尺寸
锚点校准：确保在不同分辨率下的正确对齐
纹理绑定：建立与背景精灵的关联关系

清理机制

clear()方法提供了优雅的资源清理机制：

释放当前绑定的精灵帧资源
防止内存泄漏
支持动态切换地图内容

章节来源

MapLayer.ts

纹理资源动态加载

地图系统通过MapModelComp管理资源配置，支持动态加载不同地图的纹理资源：

flowchart LR
subgraph "资源配置"
Config[map.json<br/>地图配置文件]
Delivery[map_delivery.json<br/>传送点配置]
end
subgraph "资源加载"
Model[MapModelComp<br/>模型组件]
Loader[Oops资源管理器<br/>oops.res.load]
Prefab[地图预制件<br/>resPrefab]
end
subgraph "实例化"
Instantiate[实例化地图节点]
AddToScene[添加到场景]
RegisterLayers[注册图层组件]
end
Config --> Model
Delivery --> Model
Model --> Loader
Loader --> Prefab
Prefab --> Instantiate
Instantiate --> AddToScene
AddToScene --> RegisterLayers

图表来源

资源加载策略

资源类型	加载方式	缓存策略	释放时机
地图预制件	异步加载	自动缓存	场景切换时
纹理资源	按需加载	批量管理	地图销毁时
配置文件	同步加载	内存常驻	应用退出时

章节来源

尺寸适配与节点锚点校准

MapLayer通过UITransform组件实现智能的尺寸适配：

flowchart TD
subgraph "尺寸计算"
GetSprite["获取背景精灵"]
GetTransform["读取UITransform"]
CalcWidth["计算宽度"]
CalcHeight["计算高度"]
end
subgraph "锚点校准"
SetAnchor["设置锚点"]
AdjustPosition["调整位置"]
ValidateBounds["验证边界"]
end
subgraph "渲染优化"
BatchRender["批处理渲染"]
ReduceDrawCalls["减少绘制调用"]
OptimizeMemory["优化内存使用"]
end
GetSprite --> GetTransform
GetTransform --> CalcWidth
GetTransform --> CalcHeight
CalcWidth --> SetAnchor
CalcHeight --> SetAnchor
SetAnchor --> AdjustPosition
AdjustPosition --> ValidateBounds
ValidateBounds --> BatchRender
BatchRender --> ReduceDrawCalls
ReduceDrawCalls --> OptimizeMemory

图表来源

MapLayer.ts

适配算法实现

MapLayer采用以下策略确保在不同设备上的正确显示：

动态尺寸计算：基于背景精灵的实际纹理尺寸
锚点智能定位：自动调整节点锚点以适应不同的显示需求
边界验证：确保渲染边界不会超出屏幕范围

章节来源

MapLayer.ts

MapViewComp中的注册与更新策略

MapViewComp作为地图系统的协调中心，负责管理所有子图层的生命周期：

sequenceDiagram
participant MVC as MapViewComp
participant MVS as MapViewScene
participant ML as MapLayer
participant EL as EntityLayer
participant SL as SkillLayer
MVC->>MVS : 创建场景实例
MVS->>ML : 注册地图层
MVS->>EL : 注册实体层
MVS->>SL : 注册技能层
loop 游戏循环
MVS->>ML : 更新背景
MVS->>EL : 更新实体
MVS->>SL : 更新技能
ML->>ML : 处理纹理动画
EL->>EL : 处理深度排序
SL->>SL : 处理特效渲染
end
Note over MVC,SL : 地图系统运行中

图表来源

图层初始化顺序

地图系统按照以下优先级顺序初始化各图层：

背景层(MapLayer)：最先初始化，确保基础渲染环境
实体层(EntityLayer)：紧随其后，处理游戏对象渲染
技能层(SkillLayer)：最后初始化，处理特效和技能动画

渲染层级基础设定

图层类型	渲染层级	Z-Index范围	主要职责
背景层	最底层	0-10	地图背景渲染
地面层	中间层	11-50	地面装饰物
实体层	中间层	51-100	游戏实体对象
技能层	最顶层	101+	技能特效动画

章节来源

MapViewScene.ts

扩展MapLayer支持多段滚动背景

为了支持更复杂的游戏场景，可以扩展MapLayer以实现多段滚动背景：

classDiagram
class MapLayer {
+bgImg : Sprite
+scrollSpeed : number
+repeatMode : RepeatMode
+init() void
+update(dt : number) void
+setScrollSpeed(speed : number) void
+enableParallax(parallax : boolean) void
}
class MultiScrollLayer {
-layers : MapLayer[]
-parallaxFactor : number
+addBackground(layer : MapLayer) void
+removeBackground(layer : MapLayer) void
+update(dt : number) void
+setParallaxFactor(factor : number) void
}
class ParallaxEffect {
+depth : number
+speedMultiplier : number
+offset : Vec2
+applyEffect(sprite : Sprite) void
}
MapLayer <|-- MultiScrollLayer
MultiScrollLayer --> ParallaxEffect : "使用"
MultiScrollLayer --> MapLayer : "管理多个"

图表来源

动态材质更新机制

通过MoveUV组件可以实现动态UV动画效果：

flowchart TD
Start([开始UV动画]) --> GetSprite["获取Sprite组件"]
GetSprite --> InitRect["初始化矩形区域"]
InitRect --> SetPackable["禁用打包优化"]
SetPackable --> UpdateLoop{"更新循环"}
UpdateLoop --> CheckWrapMode{"检查包装模式"}
CheckWrapMode --> |变更| UpdateWrapMode["更新纹理包装模式"]
CheckWrapMode --> |未变| CalculateOffset["计算偏移量"]
UpdateWrapMode --> CalculateOffset
CalculateOffset --> ApplyOffset["应用UV偏移"]
ApplyOffset --> MarkDirty["标记渲染数据更新"]
MarkDirty --> UpdateLoop
UpdateLoop --> Stop([停止动画])

图表来源

MoveUV.ts

章节来源

MoveUV.ts

依赖关系分析

地图系统的依赖关系体现了清晰的分层架构：

graph TB
subgraph "外部依赖"
Cocos[Cocos Creator Engine]
Oops[Oops Plugin Framework]
ECS[ECS Framework]
end
subgraph "核心组件"
MapLayer[MapLayer]
MapViewComp[MapViewComp]
MapViewScene[MapViewScene]
MapModel[MapModelComp]
end
subgraph "辅助组件"
EntityLayer[EntityLayer]
SkillLayer[SkillLayer]
MoveUV[MoveUV]
end
subgraph "配置系统"
MapConfig[地图配置]
DeliveryConfig[传送点配置]
end
Cocos --> MapLayer
Cocos --> MapViewComp
Cocos --> MapViewScene
Cocos --> MapModel
Cocos --> EntityLayer
Cocos --> SkillLayer
Cocos --> MoveUV
Oops --> MapLayer
Oops --> MapViewComp
Oops --> MapViewScene
Oops --> MapModel
ECS --> MapLayer
ECS --> MapViewComp
ECS --> MapViewScene
ECS --> MapModel
MapConfig --> MapModel
DeliveryConfig --> MapModel
MapViewScene --> MapLayer
MapViewScene --> EntityLayer
MapViewScene --> SkillLayer
MapLayer --> MoveUV

图表来源

组件耦合度分析

组件对	耦合类型	耦合强度	优化建议
MapLayer ↔ MoveUV	功能耦合	中等	提取通用接口
MapViewScene ↔ MapLayer	依赖耦合	高	使用事件解耦
GameMap ↔ MapModel	实体耦合	低	添加中间管理层

章节来源

性能优化策略

图集合并优化

通过合理组织纹理资源，可以显著提升渲染性能：

flowchart LR
subgraph "原始资源"
T1[纹理1]
T2[纹理2]
T3[纹理3]
T4[纹理4]
end
subgraph "图集合并"
Atlas[纹理图集]
Pack[打包算法]
end
subgraph "优化效果"
Batch[批处理渲染]
DrawCalls[减少绘制调用]
Memory[优化内存使用]
end
T1 --> Pack
T2 --> Pack
T3 --> Pack
T4 --> Pack
Pack --> Atlas
Atlas --> Batch
Batch --> DrawCalls
DrawCalls --> Memory

性能优化建议

纹理打包策略
- 将频繁一起使用的纹理合并到同一图集中
- 使用合理的图集大小（建议1024x1024或2048x2048）
- 避免过度填充导致的内存浪费
绘制批次优化
- 相同材质的精灵自动合并到同一绘制批次
- 减少状态切换开销
- 优化渲染顺序以提高缓存命中率
内存管理
- 及时释放不再使用的纹理资源
- 使用对象池管理临时对象
- 监控内存使用情况，避免内存泄漏

动态加载优化

对于大型地图场景，建议采用分块加载策略：

flowchart TD
Start([地图加载开始]) --> LoadCore["加载核心图层"]
LoadCore --> LoadVisible["加载可见区域"]
LoadVisible --> PreloadNearby["预加载邻近区域"]
PreloadNearby --> Monitor["监控玩家位置"]
Monitor --> PlayerMoved{"玩家移动？"}
PlayerMoved --> |是| UnloadOld["卸载远离区域"]
PlayerMoved --> |否| Monitor
UnloadOld --> LoadNew["加载新区域"]
LoadNew --> PreloadNearby
Monitor --> End([加载完成])

章节来源

故障排除指南

常见问题及解决方案

问题类型	症状描述	可能原因	解决方案
纹理加载失败	背景显示为空白	资源路径错误	检查resPrefab配置
尺寸适配异常	图层显示变形	锚点设置不当	验证UITransform配置
性能下降	帧率降低	绘制批次过多	优化纹理打包策略
内存泄漏	内存持续增长	资源未正确释放	检查clear()方法调用

调试技巧

资源监控
- 使用Cocos Creator的Profiler监控渲染性能
- 检查纹理内存使用情况
- 监控绘制调用次数
日志记录
- 在关键方法添加调试日志
- 记录资源加载状态
- 跟踪组件生命周期
可视化调试
- 显示图层边界框
- 标记关键节点位置
- 可视化渲染顺序

章节来源

结论

MapLayer作为地图系统的核心组件，通过精心设计的架构实现了高效的地图渲染功能。其继承自cc.Component的生命周期管理确保了组件的正确初始化和清理，而动态纹理加载和精灵帧初始化流程则保证了资源的灵活使用。

通过与MapViewComp的紧密协作，MapLayer不仅实现了基本的地图背景渲染，还为扩展功能如多段滚动背景和动态材质更新奠定了坚实基础。合理的性能优化策略，包括图集合并和绘制批次减少，使得地图系统能够在各种设备上保持良好的性能表现。

未来的发展方向包括：

进一步优化多段滚动背景的实现
增强动态材质更新的功能
实现更智能的资源加载策略
提供更丰富的视觉效果支持

这些改进将使地图系统更加灵活和强大，为游戏开发提供更好的技术支持。

19 KiB Raw Blame History Unescape Escape

地图基础图层

目录

简介

项目结构

核心组件

MapLayer类设计

组件继承体系

架构概览

详细组件分析

MapLayer生命周期管理

初始化流程详解

清理机制

纹理资源动态加载

资源加载策略

尺寸适配与节点锚点校准

适配算法实现

MapViewComp中的注册与更新策略

图层初始化顺序

渲染层级基础设定

扩展MapLayer支持多段滚动背景

动态材质更新机制

依赖关系分析

组件耦合度分析

性能优化策略

图集合并优化

性能优化建议

动态加载优化

故障排除指南

常见问题及解决方案

调试技巧

结论

19 KiB

Raw Blame History