地图修改与地块添加完全指南

本文档旨在为开发者提供一份详尽的指南，用于在现有项目结构下手动添加新的地块（Location）。本指南涵盖了从地图绘制到游戏内逻辑配置的全过程。这份文档是AI生成内容，请谨慎使用。

1. 准备工作与工具

在开始之前，请确保你拥有以下工具：

文本编辑器: 推荐使用 VS Code 或 Notepad++，以确保编码格式正确（通常为 UTF-8 with BOM 或 UTF-8）。
图像处理软件: Photoshop, GIMP 或 Paint.net。
- 关键设置: 必须使用 铅笔工具 (Pencil Tool)。
- 绝对禁止: 使用画笔、羽化、抗锯齿或任何会产生过渡色的工具。地图文件中的每一个像素都必须是纯色。
调试模式: 启动游戏时请添加启动参数 -debug_mode，以便使用控制台和查看报错信息。

2. 核心文件详解

修改地图主要涉及 in_game/map_data 和 main_menu 两个目录。

2.1 地图几何与定义 (`in_game/map_data/`)

1. `locations.png` (地图底图)

路径: in_game/map_data/locations.png
规格: 8位 RGB 图像，无透明通道。默认分辨率通常为 16384 x 8192（具体取决于 00_defines.txt 中的 WORLD_EXTENTS）。
作用: 游戏读取每个像素的 RGB 颜色值来确定地块的形状和边界。
操作: 在地图上用一种全局唯一的颜色绘制新地块。
警告: 即使是一个像素的过渡色（Anti-aliasing）也会被游戏识别为一个全新的、未定义的颜色，导致崩溃或产生数千个微型地块。

2. `named_locations/00_default.txt` (颜色映射)

路径: in_game/map_data/named_locations/00_default.txt
作用: 将 locations.png 中的 RGB 颜色与代码（Key）绑定。
格式: <地块代码> = <十六进制颜色>

示例:

1 2	stockholm = dda910 # 对应 RGB(221, 169, 16) new_location_x = FF00AA

注意: 十六进制颜色码不区分大小写。

3. `definitions.txt` (层级结构)

路径: in_game/map_data/definitions.txt
作用: 定义地块的行政归属层级。层级结构严格如下：
Continent (洲) -> Subcontinent (次洲) -> Region (地区) -> Area (区域) -> Province (省份) -> Location (地块)
重要概念:
- Province: 在本作中，Province 是地块的集合（类似 P社其他游戏的 State），而 Location 才是最小的操作单位（Barony/County）。
- 修改: 你必须将新地块放入某个现有的 Province 中，或者创建一个新的 Province。

示例:

europe = {
    western_europe = {
        scandinavian_region = {
            svealand_area = {
                uppland_province = {
                    stockholm
                    new_location_x  # 新增地块
                }
            }
        }
    }
}

4. `location_templates.txt` (地理属性)

路径: in_game/map_data/location_templates.txt
作用: 定义地块的物理性质。不同类型的地块（陆地、沿海、湖泊）包含的字段有所不同。
字段说明:
- topography (地形):
  - 陆地: flatland (平原), hills (丘陵), mountains (山地), plateau (高原), wetlands (湿地).
  - 水域: lakes (湖泊), coastal_ocean (沿海), ocean (海洋), deep_ocean (深海), inland_sea (内海), narrows (海峡).
  - 荒地: mountain_wasteland, plateau_wasteland, hills_wasteland, ocean_wasteland.
- vegetation (植被): grasslands (草原), woods (疏林), forest (森林), farmland (农田), sparse (稀疏), desert (沙漠).
- climate (气候): continental (大陆性), oceanic (海洋性), arctic (极地), arid (干旱), tropical (热带).
- raw_material (特产资源):
  - 农业: wheat (小麦), millet (小米), legumes (豆类), fiber_crops (纤维作物), fruit (水果), wine (葡萄酒).
  - 畜牧: livestock (牲畜), horses (马), wool (羊毛), beeswax (蜂蜡).
  - 矿产: stone (石材), clay (粘土), sand (沙子), lumber (木材), iron (铁), copper (铜), tin (锡), lead (铅), coal (煤), salt (盐), alum (明矾), saltpeter (硝石), marble (大理石), silver (银), goods_gold (金), gems (宝石), mercury (水银).
  - 狩猎/采集: wild_game (野味), fur (毛皮), fish (鱼), amber (琥珀), medicaments (药材), ivory (象牙), pearls (珍珠).
- natural_harbor_suitability: (可选) 天然良港适性（-1.0 - 1.0），影响港口等级上限。正值表示适合建港，负值表示不适合（如 viborg 为 -0.25）。
- modifier: (可选) 地块修正（如 falun_base）。
- culture / religion: 占位符。如果 06_pops.txt 中未定义人口，游戏会用此处的设定生成一个默认人口。

示例:

# 普通陆地
new_land_location = {
    topography = flatland
    vegetation = woods
    climate = continental
    religion = catholic
    culture = swedish
    raw_material = lumber
}

# 沿海地块 (带良港适性)
new_coastal_location = {
    topography = flatland
    vegetation = farmland
    climate = oceanic
    religion = catholic
    culture = danish
    raw_material = fish
    natural_harbor_suitability = 0.50
}

# 湖泊/荒地 (字段较少)
new_lake_location = {
    topography = lakes
    climate = continental
}

5. `ports.csv` (港口坐标)

路径: in_game/map_data/ports.csv
作用: 定义沿海地块的港口位置。非沿海地块不需要此项。
格式: 陆地地块Key;海域地块Key;X坐标;Y坐标;x
坐标换算公式:
- 游戏内 Y 轴原点在左下角，而图像软件（PS/GIMP）原点在左上角。
- CSV_X = 图像软件_X
- CSV_Y = 地图总高度 (8192) - 图像软件_Y
位置规则: 坐标点必须落在海域地块的像素上，且该像素必须紧邻陆地地块。

6. `default.map` (特殊类型)

路径: in_game/map_data/default.map
作用: 注册特殊类型的地块。
分类:
- sea_zones: 所有海域地块必须在此列出。
- lakes: 所有湖泊地块必须在此列出。
- impassable_mountains: 所有不可通行的荒地（包括沙漠、深林等）必须在此列出。
- non_ownable: 走廊地块（不可拥有）。
注意: 如果你添加的是普通陆地，则无需修改此文件。

2.2 游戏逻辑与内容 (`main_menu/`)

1. 本地化文件

路径: main_menu/localization/simp_chinese/location_names/location_names_l_simp_chinese.yml
作用: 显示地块名称。
格式: YAML。注意冒号后必须有一个空格。
1
2
l_simp_chinese:
new_location_x: "新地块名"

2. `06_pops.txt` (人口配置)

路径: main_menu/setup/start/06_pops.txt
作用: 覆盖模板中的默认人口，定义详细的人群结构。
人群类型 (type):
- nobles: 贵族
- clergy: 教士
- burghers: 市民
- peasants: 农民
- tribesmen: 部落民
- slaves: 奴隶
参数说明:
- size: 人口数量。
- culture: 文化代码。
- religion: 宗教代码。

示例:

new_location_x = {
    define_pop = { type = peasants size = 12.5 culture = swedish religion = catholic }
    define_pop = { type = nobles size = 0.5 culture = swedish religion = catholic }
    define_pop = { type = clergy size = 0.2 culture = swedish religion = catholic }
}

3. `10_countries.txt` (领土归属)

路径: main_menu/setup/start/10_countries.txt
作用: 将地块分配给国家。
所有权类型:
- own_control_core: 拥有、控制并拥有核心（最常见）。
- own_control_colony: 殖民地。

示例:

SWE = {
    own_control_core = {
        # ...
        new_location_x
    }
}

3. 实战操作流程

假设我们要添加一个名为 solna 的地块。

规划: 确定地块位置、地形、归属。
绘图:
- 打开 locations.png。
- 选定一个未使用的颜色（例如 Hex: 123456）。
- 使用铅笔工具在斯德哥尔摩旁画出形状。
- 保存图片。
注册颜色:
- 打开 named_locations/00_default.txt。
- 添加一行: solna = 123456。
定义层级:
- 打开 definitions.txt。
- 搜索 uppland_province。
- 在花括号内添加 solna。
设置属性:
- 打开 location_templates.txt。
- 复制一个现有地块的格式，修改 Key 为 solna，调整地形参数。
特殊处理 (可选):
- 如果是沿海：计算坐标，修改 ports.csv。
- 如果是湖泊/荒地：修改 default.map。
添加名称:
- 修改 location_names_l_simp_chinese.yml，添加 solna: "索尔纳"。
添加人口:
- 修改 06_pops.txt，为 solna 添加人口条目。
分配国家:
- 修改 10_countries.txt，在 SWE (瑞典) 下添加 solna。
启动测试:
- 运行游戏，检查地块是否出现，颜色是否正确。
生成样条网络 (Splines):
- 见下文。

4. 样条网络重生成

这是极其重要的一步。 凡是修改了 locations.png（改变了地块形状、边界、位置），都必须执行此操作。否则会导致道路断裂、边界线渲染错误，甚至游戏崩溃。

进入游戏: 启动游戏并加载地图。
打开控制台: 按 ` 键（或 ~ 键）。
清除旧数据: 输入 SplineNetwork.ClearAssets 并回车。
生成新数据: 输入 SplineNetwork.AppendAssets 并回车。
- 提示: 此时游戏可能会卡顿约 1 分钟，请耐心等待直到控制台显示完成。
应用文件:
- 切出游戏，打开文件资源管理器。
- 前往: Documents/Paradox Interactive/Europa Universalis V/gfx/map/spline_network/ (在你的“文档”文件夹中)。
- 找到生成的 .splnet 文件。
- 移动 (剪切/粘贴) 该文件到你的 Mod 或项目目录: .../game/in_game/gfx/map/spline_network/。
- 注意: 必须移动，不要保留副本在“文档”目录，否则游戏会优先读取“文档”中的旧文件，导致你下次修改无效。

5. 地标与定位点 (Locators)

除了地块本身的形状和属性，你还需要定义游戏元素在地图上的具体显示位置（如城市模型、军队模型、战斗动画位置等）。

5.1 什么是 Locators

Locators 是 3D 空间中的坐标点，用于告诉游戏在哪里渲染特定的对象。主要类型包括：

City Locators: 城市模型和建筑的位置。
Unit Locators: 军队站立的位置。
Combat Locators: 两军交战时战斗动画的位置。
Text Locators: 地块名称显示的位置。

5.2 如何修改

与 locations.png 不同，Locators 通常不建议手动编辑文本文件，而是使用游戏内地图编辑器 (In-Game Map Editor)。

7启动编辑器: 使用 -debug_mode 启动游戏，在主界面或控制台进入地图编辑器。
选择工具: 在编辑器工具栏中找到 Locators 或 Map Objects 选项卡。
编辑位置:
- 选择你要编辑的类型（如 city_locators, unit_stack_locators）。
- 在地图上点击你的新地块，拖动定位点到合适的位置（例如平坦的中心区域）。
- 注意: 确保定位点在陆地上，不要放在水中或山上。
保存: 点击编辑器的保存按钮。
文件迁移:
- 编辑器生成的 Locator 文件通常位于 Documents/Paradox Interactive/Europa Universalis V/generated/ 或类似路径。
- 你需要将生成的 .txt 文件（通常在 gfx/map/map_object_data/ 下）移动到你的 Mod 目录中对应的位置。

6. 常见问题与故障排查 (Troubleshooting)

问题现象	可能原因	解决方案
游戏启动时崩溃 (CTD)	`locations.png` 中存在未定义的颜色。	检查是否使用了抗锯齿笔刷；检查 `00_default.txt` 是否漏加了颜色定义。
地块显示为黑色/无纹理	`location_templates.txt` 中缺少地形定义。	检查该地块是否有 `topography` 和 `climate` 定义。
鼠标悬停地块显示为 “Mare Incognitum” 或海域	陆地地块被错误地放入了包含海域的 Province/Area 中。	检查 `definitions.txt`，确保陆地和海域在 Area 层级上是分开的（除非特定设计）。
地块有人口但无国家控制	`10_countries.txt` 未添加该地块。	在对应国家的列表中添加地块 Key。
道路显示在水中或穿模	样条网络未更新。	执行“样条网络重生成”步骤。
报错: Could not find spline network strip…	样条网络未更新。	执行“样条网络重生成”步骤。
港口无法使用或位置错误	`ports.csv` 坐标计算错误。	记住 Y 轴翻转公式：`8192 - Y`。确保坐标点落在海里。

6. 参考

本指南的编写参考了 Paradox Wiki 上的多篇技术文档。关于 Mod 制作的基础知识，请参阅 Modding 页面。涉及地图绘制、颜色映射及层级定义的详细规范，主要依据 Map Modding 指南。此外，关于地标、城市模型及军队位置的调整，参考了 Settlement Position Modding Guide 中的说明。

地图修改与地块添加完全指南

1. 准备工作与工具

2. 核心文件详解

2.1 地图几何与定义 (in_game/map_data/)

1. locations.png (地图底图)

2. named_locations/00_default.txt (颜色映射)

3. definitions.txt (层级结构)

4. location_templates.txt (地理属性)

5. ports.csv (港口坐标)

6. default.map (特殊类型)

2.2 游戏逻辑与内容 (main_menu/)