VCMI 随机地图模板（Random Map Template）JSON 格式完全指南：从模板结构到区域配置的实战详解

游戏开发【免费下载链接】vcmiOpen-source engine for Heroes of Might and Magic III项目地址https://gitcode.com/gh_mirrors/vc/vcmi点击查看免费下载导读本文以 VCMI 开源引擎的 Random Map Template 文档 为核心系统讲解随机地图模板Random Map Template的 JSON 定义格式——包括模板顶层结构与区域Zone两级配置的全部字段、取值范围与语义。你将掌握如何编写一份能被 VCMI 随机地图生成器RMGRandom Map Generator正确解析的模板文件从地图尺寸、玩家数量、禁用法术/宝物/英雄到区域的类型、地形、怪物、城镇、矿产、宝藏与自定义对象并了解模板在 CRmgTemplate.cpp 中的加载与继承机制最终能基于仓库内置模板如Mods/vcmi/Content/config/rmg/hdmod/aroundamarsh.json动手定制自己的随机地图。一、模板Template是什么在 VCMI 中随机地图模板是驱动随机地图生成器RMG的核心配置文件。它用 JSON 描述一张随机地图的设计蓝图地图多大、允许多少玩家、哪些内容被禁止、地图划分为哪些区域Zone、区域之间如何连接。RMG 引擎读取模板后结合玩家在新建地图界面选择的尺寸、玩家数等选项动态生成实际地图。模板文件存放在仓库的Mods/vcmi/Content/config/rmg/目录下例如hdmod/子目录中即有aroundamarsh.json、balance.json、cube.json等多个内置模板mod 开发者也可以在自己的 mod 中按相同格式提供rmg配置目录来扩展模板库。模板的加载与注册由 CRmgTemplateStorage 完成loadObject读取 JSON 并调用serializeJson解析afterLoadFinalization在加载完成后统一执行继承与校验逻辑。一份完整的模板 JSON 由两大结构组成模板顶层结构Template format和区域结构Zone format。下文分别详解。二、模板顶层结构Template format顶层结构描述整张地图的宏观属性。完整骨架如下{ Triangle : { name : Custom template name, description : Detailed info and recommended rules, minSize : m, maxSize : xlu, players : 2-4, humans : 1-4, allowedWaterContent : [none, normal, islands], settings : { heroes : { perPlayerOnMapCap : 1 } }, bannedSpells : [townPortal, modID:spellFromMod], enabledSpells : [ ], bannedArtifacts : [armageddonsBlade, modID:artifactFromMod], enabledArtifacts : [ ], bannedSkills : [diplomacy, modID:secondarySkillFromMod], enabledSkills : [ ], bannedHeroes : [lordHaart, modID:heroFromMod], enabledHeroes : [ ], zones : { zoneA : { ... }, zoneB : { ... }, zoneC : { ... } }, connections : [ { a : zoneA, b : zoneB, guard : 5000, road : false }, { a : zoneA, b : zoneC, guard : 5000, road : random }, { a : zoneB, b : zoneC, type : wide } ] } }逐字段说明如下。2.1 标识字段name 与 descriptionname可选字符串模板的显示名称。当多个模板共享同一个文件键名如多个变体时用name区分展示。参见 CRmgTemplate.cpp 的序列化逻辑。description可选字符串显示在随机地图菜单中的详细描述可包含推荐规则等信息。从源码看非空描述会注册为翻译文本键getDescriptionTextID生成template.modScope.templateName.description形式的文本标识因此也支持多语言翻译见 CRmgTemplate.cpp。2.2 地图尺寸minSize 与 maxSize定义模板适用的地图尺寸区间RMG 会在此区间内匹配合适模板。支持两种写法尺寸代码s小、m中、l大、xl特大、h、xh、g可选后缀u表示带地下层depth2。数字尺寸宽 x 高 x 层数格式如120x120x1。注意当前实现中层数depth只能是0或1即单层或双层。从源码 CRmgTemplate.cpp 的serializeSize可以看出完整映射表s/m/l/xl/h/xh/g分别对应小到巨型的标准地图尺寸u变体把深度从 1 提升到 2。若尺寸字符串不在映射表中则按x拆分解析为width x height x depth数字三元组。模板匹配采用面积比较而非逐边比较matchesSize计算width × height × depth的乘积只要用户选择的地图总面积落在模板minSize与maxSize的乘积之间即视为匹配CRmgTemplate.cpp。当玩家选择模板后若当前地图尺寸不匹配CMapGenOptions::setMapTemplate会自动把宽、高、层数调整为模板的最小尺寸CMapGenOptions.cpp。2.3 玩家数量players 与 humansplayers地图上出现的玩家总数人类 AI支持范围语法如2-4表示 2 到 4 人也支持逗号分隔的多个区间如1,3-4。解析逻辑见 CRmgTemplate.cpp 的fromString按逗号拆分区间再按连字符拆分上下界。humans自 VCMI 1.4.0 起新增可选仅人类玩家的数量格式与players相同对应原版模板中的人类玩家数概念。源码中该字段序列化为humanPlayersCRmgTemplate.cpp 注释提示未来可能重命名此参数。当用户选择的玩家数量与模板范围完全冲突时setMapTemplate会将玩家数重置为随机RANDOM_SIZE见 CMapGenOptions.cpp。2.4 水域模式allowedWaterContent可选参数限制模板允许的水域模式。若缺省则允许所有模式。可取值为值含义none无水域纯陆地normal正常水域islands岛屿模式加载时afterLoad若该字段为空或包含RANDOM会自动补齐none、normal、islands三种模式CRmgTemplate.cpp。isWaterContentAllowed判定用户所选水域模式是否被模板允许其中用户选择随机RANDOM时恒为允许CRmgTemplate.cpp随机模式会在模板允许的集合中随机抽取CMapGenOptions.cpp。若用户选择的水域模式不被模板允许setMapTemplate会自动重置为随机水域CMapGenOptions.cpp。2.5 游戏设置覆盖settings可选字段用于覆盖本模板下的游戏设置结构对应 VCMI 安装目录下config/gameConfig.json中的设置树。模板中定义的设置永远覆盖 vcmi 自身或任何 mod 的同名设置。例如settings : { heroes : { perPlayerOnMapCap : 1 } }表示该模板强制每位玩家在地图上的英雄数量上限为 1。模板的settings以原始 JSON 节点形式保留std::unique_ptrJsonNode mapSettings见 CRmgTemplate.cpp生成地图时通过m.overrideGameSettings(mapGenOptions.getMapTemplate()-getMapSettings())写入地图CMapGenerator.cpp。2.6 禁用/启用清单banned 与 enabled 系列模板可以控制本局地图中哪些法术、宝物、技能、英雄可用或不可用。每组都有对应的banned禁用与enabled启用两个字段bannedSpells/enabledSpellsbannedArtifacts/enabledArtifactsbannedSkills/enabledSkillsbannedHeroes/enabledHeroes标识符Identifier规则对上述所有清单及后文 Zone 中的同类清单均适用不带 modID 前缀的标识符如townPortal、armageddonsBlade、diplomacy、lordHaart必须存在于基础游戏或某个依赖 mod 中否则加载会出错。带显式 modID 前缀的标识符如modID:spellFromMod在对应 mod未加载时会被静默跳过不会报错。生成地图时CMapGenerator依次处理这些集合CMapGenerator.cpp把banned项从地图的allowedSpells/allowedArtifact/allowedAbilities/allowedHeroes集合中erase掉把enabled项insert进去——从而既能在模板层面封印某些强力内容如禁掉townPortal传送门、禁掉末日之刃也能反向解除基础游戏对某些内容的默认限制。三、区域结构Zone format区域Zone是地图生成的最小布局单元每个区域有独立的尺寸、类型、地形、怪物强度、城镇配置、矿产与宝藏以及精细的对象放置规则。模板的zones字段是一个以区域名如1、zoneA为键的对象。区域的序列化实现在 CRmgTemplate.cpp。一个区域的完整字段示例{ type : playerStart, size : 2, owner : 1, forcedLevel : automatic, playerTowns : { castles : 1, towns : 1 }, neutralTowns : { towns : 1 }, townsAreSameType : true, townHints : [ { likeZone : 1 }, { relatedToZoneTerrain : 4 }, { notLikeZone : [1, 2, 3, 4] } ], monsters : normal, terrainTypes : [ sand ], bannedTerrains : [lava, asphalt], matchTerrainToTown : false, minesLikeZone : 1, treasureLikeZone : 1, terrainTypeLikeZone : 3, customObjectsLikeZone : 1, townsLikeZone : 1, allowedMonsters : [inferno, necropolis], bannedMonsters : [fortress, stronghold, conflux], allowedTowns : [castle, tower, rampart], bannedTowns : [necropolis], mines : { wood : 1, ore : 1 }, treasure : [ { min : 2100, max : 3000, density : 5 } ], customObjects : { bannedCategories : [all, dwelling, creatureBank, other], bannedObjects : { randomArtifactRelic : true, hota.mapobjects:townGate : true, cartographer : { cartographerLand : true } }, commonObjects : [ { type : cartographer, subtype : cartographerWater, rmg : { value : 9000, rarity : 500, zoneLimit : 2 } } ], requiredObjects : { refugeeCamp : 5, warMachineFactory : 5, creatureGeneratorCommon : { unicornGlade : { count : 3, guard : 10000 } }, artifact : { headOfLegion : 1, armsOfLegion : 1 }, hota.mapobjects:townGate : { count : 1, guard : 100000 } } } }3.1 类型type区域类型决定其在地图中的角色对应源码中的枚举ETemplateZoneTypeCRmgTemplate.hJSON 字符串与枚举的映射见 CRmgTemplate.cppJSON 值枚举含义playerStartPLAYER_START人类或 AI 玩家的出生区域cpuStartCPU_START仅 AI 玩家的出生区域treasureTREASURE通用中立区域宝藏区junctionJUNCTION中立枢纽区仅保留狭窄通道其余面积填充障碍物waterWATER水域区域文档未列出但源码枚举支持sealedSEALED装饰性不可通行区域完全被障碍物填满3.2 尺寸与归属size、owner、forcedLevelsize区域的相对大小整数。该值是相对量实际面积由 RMG 根据地图总尺寸按比例计算。内置模板中常见取值为2到15之间的相对值如 aroundamarsh.json 中所有区域size均为 15。owner拥有该区域的玩家索引1 开始通常playerStart区域必须指定。forcedLevel可选强制区域放置的层。对应枚举EZoneLevelCRmgTemplate.hautomatic默认根据阵营地形偏好自动决定层。surface强制放在地表层level 0。underground强制放在地下层level 1。3.3 城镇配置playerTowns、neutralTowns、townsAreSameType、townHintsplayerTowns本区域中属于玩家owner的城堡与城镇数量。对象包含castles城堡数与towns城镇数两个键。底层结构是ZoneOptions::CTownInfo除数量外还持有密度与城镇类型相关字段CRmgTemplate.h。neutralTowns开局时处于中立状态的城堡与城镇数量格式与playerTowns相同。townsAreSameType若为true本区域生成的所有城镇属于同一阵营种族。townHints每个城镇的类型提示列表按放置顺序生效先出现的可用提示优先用于每个城镇。提示有三种形式对应ZoneOptions::CTownHintsCRmgTemplate.h{ likeZone : 1 }主城类型与区域 1 的主城类型相同。{ relatedToZoneTerrain : 4 }该城镇类型匹配区域 4 的地形类型。{ notLikeZone : [1, 2, 3, 4] }该城镇类型不得与这些区域匹配值可为单个整数或整数数组。3.4 怪物强度monsters控制区域内的怪物守卫强度序列化映射见 CRmgTemplate.cpp默认值为normalJSON 值枚举含义noneZONE_NONE所有宝藏无守卫无怪物weakZONE_WEAK弱怪物normalZONE_NORMAL正常强度默认strongZONE_STRONG强怪物3.5 地形terrainTypes、bannedTerrains、matchTerrainToTownterrainTypes可选允许的地形类型数组如[sand]。不指定时所有地形均可用。标识符规则同 2.6 节不带 modID 的必须存在带 modID 的缺失时静默跳过。bannedTerrains可选显式禁止的地形类型数组如[lava, asphalt]。matchTerrainToTown若为true区域地形将匹配玩家阵营的本族地形native terrain。仅对拥有者区域owned zones生效即playerStart/cpuStart区域。源码细节当区域设置了terrainTypeLikeZone继承时terrainTypes与bannedTerrains字段本身不会被序列化CRmgTemplate.cpp地形完全由继承来源区域决定。3.6 继承机制minesLikeZone、treasureLikeZone、terrainTypeLikeZone、customObjectsLikeZone、townsLikeZone这是模板编写中极具 VCMI 特色的机制——区域属性继承。当某个*LikeZone字段指向另一区域取值为该区域的 ID时本区域的对应配置会从来源区域递归继承。支持的继承字段minesLikeZone矿产配置与关联区域相同。treasureLikeZone宝藏配置与关联区域相同。terrainTypeLikeZone地形配置与关联区域相同。customObjectsLikeZone自定义对象配置与关联区域相同。townsLikeZone全部城镇相关属性玩家城镇、中立城镇、matchTerrainToTown、townHints、允许/禁止城镇类型与关联区域相同CRmgTemplate.cpp。实现上由模板加载后的afterLoad()统一处理CRmgTemplate.cpp通过inheritZoneProperty模板方法递归地从来源区域取值并写回本区域。递归深度上限为 50 次超出会记录Infinite recursion ... detected in template错误日志并返回空值防止循环继承导致死循环。内置模板大量使用该机制精简配置例如 aroundamarsh.json 中区域 2/3/4 都只写minesLikeZone : 1, treasureLikeZone : 1就复用了区域 1 的矿产与宝藏配置区域 10/11/12 则通过terrainTypeLikeZone : 9, minesLikeZone : 9, treasureLikeZone : 9一键继承区域 9 的全部布局特征。3.7 怪物与城镇阵营过滤allowedMonsters、bannedMonsters、allowedTowns、bannedTownsallowedMonsters允许出现在本区域的怪物阵营列表如[inferno, necropolis]。若未指定afterLoad会默认填充为全部可用阵营LIBRARY-townh-getAllowedFactions(false)见 CRmgTemplate.cpp。bannedMonsters本区域永不出现的怪物阵营列表如[fortress, stronghold, conflux]。allowedTowns允许在本区域生成匹配地形的城镇类型如[castle, tower, rampart]。bannedTowns永不在此区域生成的城镇类型如[necropolis]。以上标识符同样遵循 2.6 节的 modID 规则。3.8 矿产minesmines是本区域必生成矿产的映射表键为资源类型wood、ore、mercury、crystal、sulfur、gems、gold值为数量mines : { wood : 1, ore : 1, gold : 2 }注意当指定了minesLikeZone时本字段不序列化CRmgTemplate.cpp矿产配置完全继承。仓库中config/schemas下对资源 ID 有完整定义可对照。3.9 宝藏treasuretreasure数组定义本区域的宝藏财宝分布档位每项包含三个数字treasure : [ { min : 2100, max : 3000, density : 5 } ]字段含义min该档位宝藏的最小价值max该档位宝藏的最大价值density密度系数越大则该档位在区域内分布越密集对应源码中的CTreasureInfo结构ui32 min; ui32 max; ui16 density;见 CRmgTemplate.h。加载时会调用recalculateMaxTreasureValue()汇总区域最大宝藏价值CRmgTemplate.cpp供 RMG 的资源分配逻辑参考。真实示例aroundamarsh.jsontreasure : [ { min : 9000, max : 9500, density : 1 }, { min : 3500, max : 5500, density : 3 }, { min : 350, max : 2000, density : 5 } ]三档分别对应高级/中级/低级宝藏密度递增形成越普通的宝藏越常见的资源梯度。3.10 自定义对象customObjectscustomObjects是对区域内对象放置的精细控制包含四个子字段序列化实现在 ObjectConfig.cpp1bannedCategories —— 按类别批量禁用从区域中移除整个对象类别可取值见源码枚举ObjectConfig::EObjectCategoryObjectConfig.h与 JSON 字符串映射ObjectConfig.cpp取值含义all所有对象none无不禁止任何类别creatureBank生物银行如龙之国bonus奖励类对象dwelling生物巢穴resource资源类对象resourceGenerator资源生产建筑spellScroll法术卷轴randomArtifact随机宝物pandorasBox潘多拉魔盒questArtifact任务宝物seerHut先知小屋other其他杂项对象示例bannedCategories : [all, dwelling, creatureBank, other]。2bannedObjects —— 按具体对象禁用精确禁止某个对象类型或子类型布尔true形式randomArtifactRelic : true表示禁止该对象ID 必须存在于基础游戏或依赖 mod。带 modID 的形式hota.mapobjects:townGate : true表示禁止来自 modhota.mapobjects的townGate对象mod 未加载时该条目被忽略、无副作用mod 可被隐式依赖使用。子类型嵌套形式cartographer : { cartographerLand : true }只禁止陆地版制图师水上版cartographerWater与地下版cartographerSubterra仍可能出现在地图上。从源码看加载时通过LIBRARY-identifiers()-requestIdentifierIfFound(...)按名称解析对象 ID布尔值true表示禁止整个对象类型secondaryID -1结构体则逐子类型解析ObjectConfig.cpp。3commonObjects —— 调整常规对象属性列表中的对象会被排除出常规放置规则类似 bannedObjects 的效果但可以重新配置其 RMG 放置参数rmg子结构commonObjects : [ { type : cartographer, subtype : cartographerWater, rmg : { value : 9000, rarity : 500, zoneLimit : 2 } } ]rmg参数含义对应ObjectInfo的序列化见 ObjectConfig.cpp参数含义value对象的基础价值影响守卫强度与生成优先级rarity稀有度概率权重越大越常见zoneLimit单个区域内的放置上限0表示无限制注意zoneLimit为0时在内部映射为maxPerZone INT_MAXObjectConfig.cpp。文档特别提示存在多个同名scholar对象时行为未定义应避免。带 modID 的对象如hota.mapobjects:townGate在对应 mod 未启用时条目不生效。4requiredObjects —— 必生成对象在区域中强制生成的对象及其数量按rmg.value决定守卫强度requiredObjects : { refugeeCamp : 5, warMachineFactory : 5, creatureGeneratorCommon : { unicornGlade : { count : 3, guard : 10000 } }, artifact : { headOfLegion : 1, armsOfLegion : 1, torsoOfLegion : 1, loinsOfLegion : 1, legsOfLegion : 1 }, hota.mapobjects:townGate : { count : 1, guard : 100000 } }支持四种写法纯数字refugeeCamp : 5表示必生成 5 个。带 count/guard 结构{ count : 3, guard : 10000 }表示生成 3 个、守卫强度 10000。子类型 数字creatureGeneratorCommon : { unicornGlade : 3 }指定具体子类型。子类型 count/guard 结构{ unicornGlade : { count : 3, guard : 10000 } }。mod 对象hota.mapobjects:townGate : { count : 1, guard : 100000 }。对于存在多个版本的对象如标准战争机器工厂与炮塔版cannonYard系统会随机选择一个版本。源码加载逻辑见 ObjectConfig.cpp数字直接作为数量含count键时读取数量与可选guard嵌套子对象时递归解析次 ID其中artifact/core:artifact有专门的 ID 解析分支。四、连接connections区域之间的通道设计connections数组定义区域之间的拓扑关系每条连接用a、b两个区域 ID 指向两端。序列化实现见 CRmgTemplate.cpp每条连接字段字段含义a/b连接两端的区域 ID字符串形式的区域名guard通道守卫强度兵力值默认0road道路选项random默认随机、true必有路、false无路type连接类型见下表默认guarded连接类型type对应枚举rmg::EConnectionTypeCRmgTemplate.hJSON 值枚举含义guardedGUARDED默认有守卫的普通通道wideWIDE宽连接无边界、无守卫fictiveFICTIVE虚拟连接不产生实际路径仅用于让两区域互相吸引靠近repulsiveREPULSIVE虚拟连接不产生实际路径仅用于让两区域互相排斥远离forcePortalFORCE_PORTAL强制以传送门形式连接从needsPassage()的实现CRmgTemplate.cpp可以看到关键语义repulsive连接与forcePortal连接不产生实际通道前者本就是虚拟的后者自带传送门而自连接a b是有意为之的传送门设计。加载完成后afterLoad()会把每条连接同时登记到两端区域的连接列表中CRmgTemplate.cpp供区域布局阶段使用。真实模板示例aroundamarsh.json4 个玩家区与 4 个宝藏区用guard : 5000的守卫通道相连宝藏区之间用guard : 25000~35000的高守卫通道隔离而区域 9~12 之间用guard : 0的自由通道连通形成网状的沼泽宝藏集群。五、模板的加载、校验与生命周期了解模板如何被引擎消费有助于编写无懈可击的配置注册CRmgTemplateStorage::loadObject读取 JSON 文件中的每个模板条目构造CRmgTemplate实例、设置 IDscope:name形式并调用serializeJson反序列化解析失败会记录Template %s has errors错误日志CRmgTemplateStorage.cpp。后处理所有模板加载完成后执行afterLoadFinalization逐模板调用afterLoad()完成区域继承*LikeZone解析、连接双向登记、水域模式补齐与默认怪物阵营填充。选择与适配玩家在随机地图界面选定模板后CMapGenOptions::setMapTemplate校验尺寸、玩家数、水域模式并在不匹配时自动调整为模板默认值CMapGenOptions.cpp。生成应用CMapGenerator生成地图时应用模板的settings覆盖与 banned/enabled 清单CMapGenerator.cpp随后由CZonePlacer、ObjectDistributor、TerrainPainter、TownPlacer、TreasurePlacer、ConnectionsPlacer等 modificators 按区域配置逐项生成内容。仓库中还有配套的测试用例可参考test/rmg/目录下的测试文件覆盖了 RMG 相关逻辑test/map/下的测试包含地图生成校验是验证模板行为的有力工具。六、实战建议与常见陷阱区域 ID 字符串zones的键与connections的a/b必须一致源码中ZoneConnection序列化时用std::stoi将字符串转为整数 ID见 CRmgTemplate.cpp因此区域键建议使用纯数字字符串如1、2。善用继承减少重复多个同构区域如 4 个对称玩家区应使用minesLikeZone、treasureLikeZone、terrainTypeLikeZone、customObjectsLikeZone、townsLikeZone复用基准区域配置既降低维护成本也保证对称性但需警惕继承环导致递归超过 50 次上限。mod 标识符的两面性带modID:前缀的条目在 mod 未加载时静默跳过——这既是兼容性保障也可能让你的模板在纯净环境下悄然缺失某些对象编写时应明确依赖关系。水域模式若不希望模板被用于岛屿地图务必显式写allowedWaterContent : [none, normal]缺省则三种模式全部允许。连接类型语义fictive/repulsive是纯布局引力/斥力不会产生通路wide无守卫无边界适合做大型开放战场forcePortal自带传送门通路。尺寸数值数字尺寸的深度第三维当前只能为0或1写其他值将无法匹配任何地图。七、延伸阅读随机地图模板原始规范docs/modders/Random_Map_Template.md模板数据模型与序列化lib/rmg/CRmgTemplate.h、lib/rmg/CRmgTemplate.cpp对象配置解析bannedCategories/commonObjects/requiredObjectslib/rmg/ObjectConfig.cpp模板存储与加载lib/rmg/CRmgTemplateStorage.cpp模板选择适配与水域随机lib/rmg/CMapGenOptions.cpp地图生成与设置应用lib/rmg/CMapGenerator.cpp内置模板实战范例Mods/vcmi/Content/config/rmg/hdmod/aroundamarsh.json生成修饰器区域放置、地形、道路、宝藏等lib/rmg/modificators赞分享游戏开发【免费下载链接】vcmiOpen-source engine for Heroes of Might and Magic III项目地址https://gitcode.com/gh_mirrors/vc/vcmi点击查看免费下载相关推荐VCMI 地图对象格式Map Object Format完全指南Group / Type / Template 三级结构与 JSON 配置详解VCMI 地图对象格式Map Object Format完全指南Group / Type / Template 三级结构与 JSON 配置详解 导读 本文游戏开发VCMI 随机地图 Biome 配置详解用 ObstacleSet 让每个区域的障碍风格统一VCMI 随机地图 Biome 配置详解用 ObstacleSet 让每个区域的障碍风格统一 Biome生物群系是 VCMI 1.5.0 引入的新实体类型游戏开发Nginx UI 配置模板完全指南文件格式、模板语法与内置模板实战详解Nginx UI 配置模板完全指南文件格式、模板语法与内置模板实战详解 Nginx UI 内置了一套开箱即用的 配置模板Config Template 体后端前端运维MCP 服务上一篇ggplot2扩展开发终极指南如何创建自定义几何对象和统计变换下一篇Keras 3.12.0重磅发布大模型训练效率革命与核心特性解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考