21 KiB
地图系统
**本文档引用的文件** - [GameMap.ts](file://assets/script/game/map/GameMap.ts) - [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts) - *在最近提交中更新* - [Mon.ts](file://assets/script/game/hero/Mon.ts) - *在最近提交中更新* - [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts) - [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts) - [map.json](file://assets/resources/config/map/map.json) - [map_delivery.json](file://assets/resources/config/map/map_delivery.json) - [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts) - *在最近提交中更新* - [heroSet.ts](file://assets/script/game/common/config/heroSet.ts) - [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts) - [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.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) - [HeroAttrsComp.ts](file://assets/script/game/hero/HeroAttrsComp.ts) - *在最近提交中更新* - [MonMove.ts](file://assets/script/game/hero/MonMove.ts) - *在最近提交中更新* - [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts) - *在最近提交中更新*更新摘要
已更新内容
- 更新了“怪物实体设计模式分析”章节，反映使用
HeroAttrsComp和MonMoveComp的重构 - 更新了“依赖分析”图表，反映
Mon.ts和MissionMonComp.ts的变更 - 新增了“怪物属性与移动系统重构”章节，详细说明
HeroAttrsComp和MonMoveComp的使用 - 所有受影响的代码示例和序列图均已更新
目录
引言
本文档详尽描述了基于Cocos引擎的《英雄》游戏项目中地图系统的整体架构与运行机制。系统涵盖关卡设计、怪物生成、战斗区域管理及视图渲染等核心功能。通过分析GameMap.ts中的地图主控制器职责，结合RogueConfig.ts解释随机关卡生成逻辑，深入剖析Mon.ts中怪物实体的设计模式及其与英雄的交互方式。同时，阐述MapModelComp.ts与MapViewComp.ts如何实现数据与表现层的分离，并结合map.json和map_delivery.json配置文件说明地图数据结构与关卡参数定义。最后，提供实例说明如何添加新关卡、配置怪物波次及实现战斗区域判定。
项目结构
graph TD
subgraph "Assets"
subgraph "resources"
subgraph "config"
subgraph "map"
map_json["map.json"]
map_delivery_json["map_delivery.json"]
end
end
end
subgraph "script"
subgraph "game"
subgraph "map"
GameMap_ts["GameMap.ts"]
RogueConfig_ts["RogueConfig.ts"]
MissionMonComp_ts["MissionMonComp.ts"]
subgraph "model"
MapModelComp_ts["MapModelComp.ts"]
end
subgraph "view"
MapViewComp_ts["MapViewComp.ts"]
MapViewScene_ts["MapViewScene.ts"]
subgraph "layer"
MapLayer_ts["MapLayer.ts"]
EntityLayer_ts["EntityLayer.ts"]
SkillLayer_ts["SkillLayer.ts"]
end
end
end
subgraph "hero"
Mon_ts["Mon.ts"]
MonMove_ts["MonMove.ts"]
HeroAttrsComp_ts["HeroAttrsComp.ts"]
HeroViewComp_ts["HeroViewComp.ts"]
end
subgraph "common"
subgraph "config"
heroSet_ts["heroSet.ts"]
end
end
end
end
end
图示来源
- map.json
- map_delivery.json
- GameMap.ts
- MapModelComp.ts
- MapViewComp.ts
- MapViewScene.ts
- MapLayer.ts
- EntityLayer.ts
- SkillLayer.ts
本节来源
核心组件
地图系统的核心由多个组件构成，实现了数据与逻辑的分离。GameMap作为地图主控制器，负责协调地图模型与视图。MapModelComp封装了地图的静态数据，如初始地图ID和资源路径。MapViewComp则负责地图的显示逻辑，通过MapViewScene管理地图层、实体层和技能层。RogueConfig.ts定义了随机关卡的生成规则，包括怪物类型、数量和强度的动态调整。Mon.ts实现了怪物实体的加载与初始化，支持根据关卡进度调整属性强度。
本节来源
架构概述
classDiagram
class GameMap {
+MapModel : MapModelComp
+MapView : MapViewComp
+init() : void
+load() : void
}
class MapModelComp {
+id : number
+resPrefab : string
+reset() : void
}
class MapViewComp {
+scene : MapViewScene
+game_timer : Timer
+onLoad() : void
+start() : void
+reset() : void
+update(dt : number) : void
}
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 MapLayer {
+bgImg : Sprite
+init() : void
+clear() : void
+bgImage : Sprite
+width : number
+height : number
}
class EntityLayer {
+timer : Timer
+update(dt : number) : void
+start() : void
+clear() : void
}
class SkillLayer {
+timer : Timer
+light : Prefab
+onLoad() : void
+doSkill() : void
+update(dt : number) : void
+start() : void
+clear() : void
}
GameMap --> MapModelComp : "包含"
GameMap --> MapViewComp : "包含"
MapViewComp --> MapViewScene : "引用"
MapViewScene --> MapLayer : "引用"
MapViewScene --> EntityLayer : "引用"
MapViewScene --> SkillLayer : "引用"
图示来源
详细组件分析
地图主控制器分析
GameMap类是地图系统的主控制器，使用ECS（实体-组件-系统）架构模式。它继承自ecs.Entity，并注册为GameMap实体。该类包含两个核心组件：MapModel（数据模型）和MapView（视图组件）。init方法在实体初始化时被调用，用于添加MapModelComp组件。load方法负责加载地图的显示资源，通过资源管理器异步加载地图预制件，并将其挂载到游戏根节点下，最后将地图视图组件添加到当前实体。
对象导向组件
classDiagram
class GameMap {
+MapModel : MapModelComp
+MapView : MapViewComp
+init() : void
+load() : void
}
class MapModelComp {
+id : number
+resPrefab : string
+reset() : void
}
GameMap --> MapModelComp : "包含"
图示来源
本节来源
怪物属性与移动系统重构
根据最近的代码重构，怪物系统已进行重大更新。Mon.ts不再使用专用的MonAttrsComp和MonViewComp，而是统一使用英雄系统的HeroAttrsComp和HeroViewComp，实现了代码复用和逻辑一致性。同时，为怪物创建了专属的MonMoveComp移动组件，与英雄系统分离。
重构后组件关系
classDiagram
class Monster {
+HeroModel : HeroAttrsComp
+HeroView : HeroViewComp
+HeroSkills : HeroSkillsComp
+MonMove : MonMoveComp
}
class HeroAttrsComp {
+hero_uuid : number
+lv : number
+hp : number
+mp : number
+Attrs : Array
}
class HeroViewComp {
+scale : number
+box_group : number
}
class MonMoveComp {
+direction : number
+targetX : number
+moving : boolean
}
Monster --> HeroAttrsComp : "使用"
Monster --> HeroViewComp : "使用"
Monster --> MonMoveComp : "使用"
图示来源
本节来源
怪物类型与属性计算
RogueConfig.ts文件引入了MonType枚举来定义怪物类型，取代了原有的布尔标记。MonType包含NORMAL（普通）、ELITE（精英）和BOSS（首领）三种类型。系统通过MonAttrSet配置表为不同类型的怪物设置属性倍率。getMonAttr函数根据怪物等级、UUID和类型计算最终属性值，确保精英和Boss怪物具有更高的生命值、攻击力和防御力。
属性计算逻辑
flowchart TD
Start([计算怪物属性]) --> GetBase["获取基础属性 (来自HeroInfo)"]
GetBase --> ApplyLevel["应用等级倍率 (lv)"]
ApplyLevel --> ApplyType["应用类型倍率 (MonAttrSet[MonType])"]
ApplyType --> Calculate["计算最终属性: HP, MP, AP, DEF等"]
Calculate --> Return["返回属性对象"]
Return --> End([属性计算完成])
图示来源
- RogueConfig.ts - MonType枚举定义
- RogueConfig.ts - getMonAttr函数实现
- Mon.ts - load方法调用getMonAttr
本节来源
随机关卡生成逻辑分析
RogueConfig.ts文件重构了随机关卡的生成规则。系统通过getStageMonConfigs函数根据关卡号生成怪物配置。该函数首先判断当前关卡是否为精英关卡（EliteStage数组中包含）或Boss关卡（BossStage数组中包含）。如果是Boss关卡，则从BossMons列表中随机选择一个Boss怪物加入配置，并减少普通怪物数量。如果是精英关卡，则添加1-2个精英怪物。最后，根据StageRule中的extraMonsterRate概率决定是否生成额外的普通怪物。
API/服务组件
sequenceDiagram
participant Game as "游戏逻辑"
participant RogueConfig as "RogueConfig"
participant MissionMonComp as "MissionMonComp"
Game->>RogueConfig : getStageMonConfigs(stageNumber)
RogueConfig-->>Game : 返回IMonsConfig[]数组
Game->>MissionMonComp : generateMonsters(monsConf)
MissionMonComp->>MissionMonComp : addToStageSpawnQueue()
loop 每个怪物配置
MissionMonComp->>MissionMonComp : spawnNextMonster()
MissionMonComp->>Monster : load(uuid, pos, monType, level, buffs)
end
图示来源
- RogueConfig.ts - getStageMonConfigs函数实现
- MissionMonComp.ts - MonQueue使用MonType
- MissionMonComp.ts - addMonster方法
本节来源
怪物实体设计模式分析
Mon.ts文件定义了Monster类，代表游戏中的怪物实体。该类基于ECS架构，包含HeroModel（模型组件）、HeroView（视图组件）和MonMove（专属移动组件）。load方法的签名已更新，增加了monType和buffs参数。该方法调用getMonAttr函数根据关卡等级和怪物类型计算属性，并将这些属性传递给hero_init方法进行初始化。怪物的技能、属性和状态均在此方法中初始化。
复杂逻辑组件
flowchart TD
Start([怪物加载]) --> Load["load(pos, scale, uuid, lv, monType, buffs)"]
Load --> GetPrefab["获取预制件路径"]
GetPrefab --> Instantiate["实例化预制件"]
Instantiate --> SetParent["设置父节点为entityLayer"]
SetParent --> Init["调用hero_init初始化"]
Init --> GetHeroInfo["从HeroInfo获取基础属性"]
GetHeroInfo --> CalculateAttrs["调用getMonAttr计算最终属性"]
CalculateAttrs --> ApplyBuffs["应用buffs数组"]
ApplyBuffs --> InitSkills["初始化技能数组"]
InitSkills --> AddComponent["将HeroViewComp添加到实体"]
AddComponent --> SetMove["设置MonMove参数"]
SetMove --> Dispatch["派发monster_load事件"]
Dispatch --> End([怪物加载完成])
图示来源
- Mon.ts - load方法实现
- Mon.ts - hero_init方法实现
- RogueConfig.ts - getMonAttr函数
本节来源
数据与表现层分离分析
地图系统严格遵循MVC（模型-视图-控制器）设计模式，实现了数据与表现的分离。MapModelComp作为模型层，仅负责存储地图的静态数据，如地图ID和资源路径。MapViewComp作为视图层，负责地图的显示和用户交互。MapViewScene作为视图的具体实现，管理地图的各个显示层（背景层、实体层、技能层）。这种分离使得数据逻辑与显示逻辑解耦，提高了代码的可维护性和可测试性。
classDiagram
class MapModelComp {
+id : number
+resPrefab : string
}
class MapViewComp {
+scene : MapViewScene
}
class MapViewScene {
+mapLayer : MapLayer
+entityLayer : EntityLayer
+SkillLayer : SkillLayer
}
MapModelComp --> MapViewComp : "数据驱动"
MapViewComp --> MapViewScene : "控制"
MapViewScene --> MapLayer : "显示"
MapViewScene --> EntityLayer : "显示"
MapViewScene --> SkillLayer : "显示"
图示来源
本节来源
地图数据结构与关卡参数分析
地图数据由两个JSON文件定义：map.json和map_delivery.json。map.json定义了地图的基本信息，包括地图ID、名称和转场点。map_delivery.json定义了地图转场的具体参数，包括转场点ID、所在地图ID、触发位置、目标地图ID和目标地图的起始位置。这种设计支持非线性关卡流程，玩家可以通过不同的转场点进入不同的地图。
erDiagram
MAP {
string id PK
string name
string delivery
}
MAP_DELIVERY {
string id PK
string mapId FK
string pos
string toMapId
string start
}
MAP ||--o{ MAP_DELIVERY : "包含"
图示来源
本节来源
依赖分析
graph TD
GameMap_ts --> MapModelComp_ts
GameMap_ts --> MapViewComp_ts
MapViewComp_ts --> MapViewScene_ts
MapViewScene_ts --> MapLayer_ts
MapViewScene_ts --> EntityLayer_ts
MapViewScene_ts --> SkillLayer_ts
MissionMonComp_ts --> RogueConfig_ts
MissionMonComp_ts --> Mon_ts
Mon_ts --> HeroAttrsComp_ts
Mon_ts --> HeroViewComp_ts
Mon_ts --> MonMove_ts
RogueConfig_ts --> heroSet_ts
图示来源
- GameMap.ts
- MapModelComp.ts
- MapViewComp.ts
- MapViewScene.ts
- MapLayer.ts
- EntityLayer.ts
- SkillLayer.ts
- MissionMonComp.ts
- RogueConfig.ts
- Mon.ts
- HeroAttrsComp.ts
- HeroViewComp.ts
- MonMove.ts
- heroSet.ts
本节来源
- GameMap.ts
- MapModelComp.ts
- MapViewComp.ts
- MapViewScene.ts
- MapLayer.ts
- EntityLayer.ts
- SkillLayer.ts
- MissionMonComp.ts
- RogueConfig.ts
- Mon.ts
- HeroAttrsComp.ts
- HeroViewComp.ts
- MonMove.ts
- heroSet.ts
性能考虑
地图系统在性能方面进行了合理的设计。视图层的更新通过update方法每帧执行，但关键的实体排序逻辑被注释，表明开发者意识到性能问题并考虑优化。怪物生成采用队列机制，通过spawnInterval控制生成频率，避免一次性生成过多怪物导致性能骤降。地图资源采用异步加载，防止主线程阻塞。建议进一步优化实体层的深度排序，考虑使用空间分区或仅在必要时排序。
故障排除指南
- 地图无法加载：检查
MapModelComp中的resPrefab路径是否正确，确保预制件存在于资源目录中。 - 怪物未生成：确认
MissionMonComp是否监听了FightReady事件，检查MonQueue是否正确填充。 - 属性未按倍率调整：确保
Mon.ts中的hero_init方法正确接收并应用monType参数，并调用getMonAttr函数。 - 转场无效：验证
map_delivery.json中的pos和start坐标格式是否正确，确保触发位置与玩家位置匹配。
本节来源
结论
本文档全面分析了Cocos游戏项目中的地图系统架构。系统采用ECS和MVC设计模式，实现了良好的代码分离和可扩展性。随机关卡生成逻辑经过重构，使用MonType枚举清晰地管理普通、精英和Boss怪物，支持动态调整怪物数量和强度。数据与表现层分离清晰，便于维护和迭代。通过合理使用配置文件，实现了关卡数据的外部化管理。整体架构设计合理，为游戏的长期发展奠定了坚实基础。