RTS Terrain Studio

地图的构成

如果你用过经典 RTS 游戏的地图编辑器，会对其中大部分概念感到熟悉。地图是由正方形单元格组成的栅格（默认每格宽 2 m）。单元格的角点就是顶点，大部分数据按顶点存储，或者存储在覆盖整张地图的高分辨率纹理中。

在场景中，地图位于一个带有 RTSTerrain 组件的 GameObject 上。菜单 GameObject ▸ RTS Terrain Studio ▸ RTS Terrain 还会为它添加各个子系统组件（RTSVegetationRenderer、RTSWaterRenderer 和 RTSDecorManager）。地形从项目中的 .rtsmap 文件（即 RTSMapAsset）读取地图。它显示的区块网格、草和水体都由该文件生成，并且永远不会保存到场景中，因此你的场景始终保持精简。

上手五分钟

这是亲眼看到所有功能运行起来的最快方式。除了导入包之外，无需任何配置。

1. 打开 Tools ▸ RTS Terrain Studio ▸ Validate Project，然后单击 Fix All。这会配置 URP、战争迷雾渲染器功能、水体所用的摄像机纹理以及色彩空间。在实际修改之前，确认对话框会先说明具体的改动。
2. 运行 Tools ▸ RTS Terrain Studio ▸ Create Demo Content。生成纹理、模型、图块集、地图和场景期间会显示进度条。完成后，Project 窗口中会选中 RTS Terrain Studio - Gameplay Demo 场景。
3. 双击该场景将其打开，然后单击 Play。
4. 用鼠标左键选择你的单位（单击或拖出选框），然后右键单击地面让它们移动。用 WASD 或方向键平移视角，用鼠标滚轮缩放，按 F1 查看所有操作方式。
5. 退出 Play 模式并打开 RTS Terrain Studio - Editor Playground 场景。然后打开 Tools ▸ RTS Terrain Studio ▸ Editor Window，选择一个工具，在 Scene 视图中绘制。按住 Shift 可执行相反的操作（例如降低而不是升高）。按 Ctrl+Z 撤销。
6. 打开 RTS Terrain Studio - In-Game Editor Demo 场景并单击 Play。这就是你的玩家将会用到的编辑器。按 F5 带单位试玩地图，按 F2 显示或隐藏编辑器。

从哪里开始

功能特性

下面列出的每个编辑工具在 Unity 编辑器和游戏内编辑器中都可用，因为两者使用相同的工具类（RTSTool 的子类）。列表中的名称就是你在用户界面中看到的名称。

设计决策一览

下面是大家对 RTS 地形工具最常提出的问题，以及 RTS Terrain Studio 给出的答案。

初识 API

为了让程序员对 API 有个初步印象，下面给出一个完整的脚本。它会向地形查询你单击位置的信息，并用内置寻路器规划一条通往该位置的路径。它既不需要碰撞体，也不需要额外的组件：只需在包含 RTSTerrain 的场景中，把它挂到任意 GameObject 上即可。

using System.Collections.Generic;
using RTSTerrainStudio;
using UnityEngine;

/// <summary>Click on the ground: logs what the terrain knows about that point and plans a path to it.</summary>
public class ClickInfoExample : MonoBehaviour
{
    // Reused for every click, so no new list is allocated each time.
    readonly List<Vector3> path = new List<Vector3>();

    void Update()
    {
        // RTSInput works with the Input System package and with the old Input Manager.
        if (!RTSInput.GetMouseButtonDown(0) || Camera.main == null) return;

        Ray ray = Camera.main.ScreenPointToRay(RTSInput.PointerPosition);

        // Analytic ray cast against every RTSTerrain in the scene. Colliders are not needed.
        if (!RTSTerrain.RaycastAll(ray, out RTSTerrainHit hit)) return;
        RTSTerrain terrain = hit.terrain;

        // Gameplay questions, answered from the map data and the pathing map.
        int level = terrain.GetCliffLevel(hit.point);
        bool buildable = terrain.IsBuildable(hit.point);
        bool water = terrain.IsWater(hit.point, out float depth);
        Debug.Log($"Cell {hit.cell}: cliff level {level}, buildable {buildable}, water {water} ({depth:0.00} m)");

        // Built-in Burst A* on the pathing map, for a unit with a radius of 0.6 m.
        PathStatus status = RTSPathfinder.FindPath(terrain, transform.position, hit.point,
                                                   PathRequestOptions.ForUnit(0.6f), path);
        Debug.Log($"Path from {name}: {status}, {path.Count} waypoints");
    }
}

PathStatus 的取值为 Success、Partial（最近的可到达点）、NoPath 或 InvalidStart。完整的 API 说明参见“脚本编写”一章。

环境要求

文件夹结构

整个包位于一个文件夹中，默认是 Assets/RTSTerrainStudio。你可以移动或重命名该文件夹：编辑器通过 RTSTerrainStudio.Runtime.asmdef 的位置找到包的根目录，演示内容和文档也以它为基准按相对路径查找。

RTSTerrainStudio/
├── Runtime/                 Core, rendering, tools and runtime systems (RTSTerrainStudio.Runtime)
├── Editor/                  Editor window, Scene View, inspectors, setup, demo content (RTSTerrainStudio.Editor)
├── Shaders/                 URP shaders and HLSL includes
│   ├── Hidden/              Internal shaders (fog blur, minimap fog, gizmos, texture array blit)
│   └── Include/             Shared HLSL (fog of war, brush cursor, wind, terrain, vegetation, water)
├── Samples/
│   ├── Scripts/             Sample gameplay: camera, units, selection, orders, minimap, HUD (RTSTerrainStudio.Samples)
│   └── Scenes/              Demo scenes (created by Create Demo Content)
├── Integrations/
│   ├── Mirror/              Multiplayer (compiled only with Mirror)
│   ├── AStarPathfinding/    A* Pathfinding Project (compiled only with A* Pro 5.4.4+)
│   └── UnityNavMesh/        Unity AI Navigation (compiled only with com.unity.ai.navigation 2.0+)
├── Content/                 Generated demo content (empty until you run Create Demo Content)
├── Resources/
│   └── RTSTerrainStudio/    Runtime UI style sheets and theme, shader references, panel settings
├── Documentation/           This manual (index.html) and its images
└── Tests/
    └── Editor/              EditMode unit tests (RTSTerrainStudio.Tests.Editor)

包含内容

本包以源代码、着色器和本手册的形式发布。所有视觉内容（纹理、模型、图块集、地图和场景）都由脚本在你的电脑上生成。这样可以让下载体积保持很小，而且这些内容的许可方式与代码完全相同。

演示地图

三张地图均使用 2 m 的单元格尺寸、2 m 的悬崖层级高度和 Summer 图块集。

地图	尺寸	对称	说明
Two Rivers (1v1).rtsmap	128 × 128 个单元格	Rotate 2	两名玩家，两条河流。河上处处都有可供穿越的浅滩，中央的湖泊则是深水。坡道通往林木茂密的高地，高地上有废墟和废弃的营地。
Four Kingdoms (4p).rtsmap	192 × 192 个单元格	Rotate 4	四个王国，各自占据一片高地。坡道向下通往共享的低地，地图中央是一片腐化之地，其中有一座古老神庙的废墟。
Sandbox.rtsmap	96 × 96 个单元格	None	一张小型地图，地势大多平坦，适合试用各种工具。

图标

编辑器窗口、Inspector 窗口和游戏内编辑器中的所有图标都由 RTSIcons 以程序化方式绘制，因此在任何尺寸下都保持清晰，在构建版本中也无需纹理资源即可使用。

安装与配置

打开演示场景

演示场景位于 RTSTerrainStudio/Samples/Scenes 中。在 Project 窗口中双击即可打开，也可以在 Welcome 窗口的第 3 步中选择场景，然后单击 Open。

你的第一张地图

地图位于场景中的 RTS Terrain GameObject 上，并存储在项目中的 .rtsmap 文件里。场景只引用该文件；你的编辑会保存到该文件中。先新建一个场景，以便自由尝试：

1. 选择 File ▸ New Scene，然后选择一个 URP 场景模板（例如 Basic (URP)）。
2. 立即按 Ctrl+S 保存场景，例如保存为 Assets/MyMaps/FirstMap.unity。新的地图文件会创建在已保存场景的旁边，这样地图和场景就能放在一起。

打开编辑器窗口

打开 Tools ▸ RTS Terrain Studio ▸ Editor Window（向导和 Welcome 窗口也可以替你打开它，RTS Terrain 组件的 Inspector 中还有一个 Open RTS Terrain Studio 按钮）。将它停靠在 Inspector 窗口旁边，这样你可以同时看到 Scene 视图。

区域	显示内容
Header（标题栏）	地形选择器、地图名称（圆点表示有未保存的更改）、Save、Save As…、Open…、Reload、带步骤名称的 Undo / Redo、帮助按钮，以及 Editing On / Editing Off 开关。
Tab bar（选项卡栏）	八个工具类别（Height、Cliffs、Paint、Vegetation、Decor、Water、Pathing、Markers），之后是 Map 和 Settings。圆点标示当前工具所属的类别。
Tools page（工具页）	大号工具按钮、一张显示当前工具说明及其实时状态的卡片、Brush 和 Symmetry 卡片，以及该工具自身的设置和选择面板（图层、悬崖层级、玩家、树木、装饰物）。
Status bar（状态栏）	光标所在的单元格，鼠标下方的悬崖层级、高度和通行状态，以及撤销内存占用。

八个类别及其工具：

按键	类别	工具
1	Height	Raise / Lower、Smooth、Flatten、Set Height、Noise、Terrace、Erode
2	Cliffs	Raise / Lower Level、Set Level、Ramp、Cliff Type、Clean Cliffs
3	Paint	Paint Layer、Tile Paint、Fill / Replace、Smooth Paint、Auto Paint
4	Vegetation	Paint Details、Erase Details、Place Trees、Erase Trees
5	Decor	Place Decor、Erase Decor、Select Decor
6	Water	Paint Water、Erase Water、Flood Fill
7	Pathing	Paint Pathing、Clear Pathing
8	Markers	Start Locations、Regions、Markers

每个工具都在各自的章节中有详细说明（例如高度工具和悬崖工具）；窗口本身详见编辑器窗口。

你的第一次试玩

试玩地图有两种方式：在 Play 模式下使用 Demo Game，或者在运行中的游戏里使用游戏内编辑器及其 Play Test 按钮。

using RTSTerrainStudio;
using UnityEngine;

// Add this component to any GameObject in a scene with an RTS Terrain and an in-game editor.
public class PlaytestStartLogger : MonoBehaviour
{
    void OnEnable()
    {
        // Raised by the in-game editor when a play test starts (true) or stops (false).
        RTSRuntimeEditorEvents.PlaytestChanged += OnPlaytestChanged;
    }

    void OnDisable()
    {
        RTSRuntimeEditorEvents.PlaytestChanged -= OnPlaytestChanged;
    }

    void OnPlaytestChanged(bool playing)
    {
        if (!playing) return;

        // The first enabled terrain of the scene.
        RTSTerrain terrain = RTSTerrain.Main;
        if (terrain == null || terrain.Map == null) return;

        foreach (StartLocation start in terrain.Map.StartLocations)
        {
            // Start locations are stored in map-local coordinates: convert to world space
            // and move the point onto the ground.
            var local = new Vector3(start.position.x, start.position.y, start.position.z);
            Vector3 world = terrain.SnapToGround(terrain.LocalToWorld(local));
            Debug.Log($"Player {start.player + 1} starts at {world}, facing {start.yaw:0} degrees");
        }
    }
}

10 分钟教程：你的第一张 1v1 地图

在本教程中，你将为两名玩家制作一张小巧而公平的地图：每个玩家都在一块带坡道的高地上拥有一个基地，一条河流将地图分为两半，森林环绕在地图四周。对称绘制可以确保两侧完全相同，因此你只需制作一半。

后续步骤

• 编辑器窗口：详细介绍每个选项卡、卡片和设置项，包括 Map 选项卡（调整尺寸、地图生成器、高度图导入与导出、小地图、环境）。
• 各工具章节，每个类别一章：Height、Cliffs、Paint、Vegetation、Decor、Water、Pathing、Markers。
• 游戏内编辑器：随游戏一起发布编辑器，让玩家自己制作地图。
• 脚本编写：通过代码查询高度、悬崖层级和通行数据，在运行时加载地图，并响应编辑操作。
• 集成：使用 Mirror 实现多人联机，使用 A* Pathfinding Project 或 Unity NavMesh 实现寻路。
• 故障排除：材质显示为粉色、水面看起来很平、绘制位置偏移以及其他常见问题。

Project Validator（项目验证器）

打开 Tools ▸ RTS Terrain Studio ▸ Validate Project，或者在 Welcome 窗口中单击 Validate。窗口一打开，检查就会自动运行。所有检查分为五个类别：

每个检查结果都会显示以下四种状态之一：

Fix All 会应用所有可用的修复。对话框会先列出全部更改，在你单击 Apply Fixes 之前不会修改任何内容。依赖 URP 的修复（摄像机纹理和战争迷雾渲染器功能）会在渲染管线指定完成后自动运行，因此只需单击一次即可配置好一个全新的项目。Run Again 会重新运行所有检查。完整的检查列表及对应的修复按钮参见验证项目。

通过代码运行检查

RTSProjectValidator.RunChecks() 返回检查结果，不做任何更改；RTSProjectValidator.FixAll() 则会应用修复。你可以在构建脚本或持续集成作业中使用它们。下面的示例必须放在 Editor 文件夹中。

using UnityEditor;
using UnityEngine;
using RTSTerrainStudio.Editor;

// Command line: Unity -batchmode -projectPath <path> -executeMethod ProjectSetupCheck.Run -quit
public static class ProjectSetupCheck
{
    public static void Run()
    {
        // Runs every check. Nothing is modified.
        var results = RTSProjectValidator.RunChecks();

        // Applies every available fix without dialogs, then checks again.
        int applied = RTSProjectValidator.FixAll(results, interactive: false);
        if (applied > 0) results = RTSProjectValidator.RunChecks();

        // Logs warnings and errors ("[Status] Title: Message").
        foreach (var result in results)
            if (result.IsProblem) Debug.LogWarning(result.ToString());

        // Fails the job when a required setting is still missing.
        if (RTSProjectValidator.WorstStatus(results) == RTSValidationStatus.Error)
            EditorApplication.Exit(1);
    }
}

通用渲染管线（URP）

本包的所有着色器都是为 URP 编写的。没有 URP，地形、水体和植被会显示为粉色，甚至完全不显示。Use URP 修复会选用项目中的一个 URP 资源（或者创建带有渲染器的 Assets/Settings/RTS URP.asset），将其指定为默认渲染管线，并指定给所有使用其他渲染管线的质量级别。手动操作步骤如下：

1. 如果项目中还没有 URP 资源，在 Project 窗口中通过 Create ▸ Rendering ▸ URP Asset (with Universal Renderer) 创建一个。
2. 在 Edit ▸ Project Settings ▸ Graphics 中将其指定为 Default Render Pipeline。
3. 打开 Edit ▸ Project Settings ▸ Quality。对于每个设置了 Render Pipeline Asset 覆盖的质量级别，确认所指定的同样是 URP 资源。

Depth Texture 和 Opaque Texture

水体使用摄像机深度纹理，让水深颜色、泡沫和柔和的岸边能贴合立于水中的物体；使用不透明纹理实现折射。没有这两张纹理，水面效果会更简单。选中质量级别所用的每个 URP 资源，在其 Rendering 部分勾选 Depth Texture 和 Opaque Texture，或者在验证器中单击 Enable Both。

战争迷雾渲染器功能

RTS Fog Of War 渲染器功能（RTSFogOfWarRendererFeature）会在屏幕上的所有内容之上绘制迷雾，包括使用你自己材质的单位和道具。没有它，只有本包自带的着色器才会显示迷雾。Add Feature 会将它添加到每个正在使用的 URP 资源的默认渲染器中。要手动添加，选中 Universal Renderer Data 资源，单击 Add Renderer Feature，然后选择 RTS Fog Of War。详情参见渲染：渲染器功能与着色器回退。

色彩空间

本包是针对 Linear 色彩空间（URP 的默认设置）设计的。在 Gamma 色彩空间中，颜色、光照和水体与截图相比会显得发灰、褪色。将 Edit ▸ Project Settings ▸ Player ▸ Other Settings ▸ Color Space 设置为 Linear，或者在验证器中单击 Switch to Linear。

必需的包

运行时程序集的作业和数据模型使用了 Burst（com.unity.burst）、Collections（com.unity.collections）和 Mathematics（com.unity.mathematics）。只要缺少其中任何一个，本包的脚本就无法编译。你可以通过 Window ▸ Package Manager ▸ Unity Registry 安装它们，或者在验证器中单击 Install，它会通过一次 Package Manager 请求添加所有缺失的包。经过测试的版本列在必需的包中。

输入处理

所有运行时输入（游戏内编辑器、示例摄像机和单位）都经由静态类 RTSInput 处理。安装了 Input System 包（com.unity.inputsystem）后，运行时程序集会在编译时定义符号 RTS_INPUT_SYSTEM，并使用 Input System。否则，或者当项目只使用旧版 Input Manager 时，RTSInput 会回退到旧版 UnityEngine.Input API。

该设置位于 Edit ▸ Project Settings ▸ Player ▸ Other Settings ▸ Active Input Handling。更改此设置后，Unity 会要求重启编辑器。Input handling 检查从不会替你更改此设置，因为如何设置取决于你的游戏。另请参阅“环境要求”中的输入处理。

着色器与内容

• Package shaders compile. 如果某个包内着色器存在编译错误（受影响的对象显示为粉色），Reimport 会重新导入该着色器。如果着色器是在 URP 加载完成之前导入的，这样做通常能解决问题。如果必需的着色器完全缺失，请从 Asset Store 重新导入本包。参见故障排除。
• Shaders included in builds. 参见构建游戏。
• Tileset texture arrays built. 纹理数组未构建或已过期的图块集仍然可以使用，但在重新构建数组之前，编辑器会在加载地图时构建未压缩的数组，这会额外占用内存并延长加载时间。Build Arrays 会为每个已过期的图块集构建数组。Player 构建会自动重建已过期的数组；从未构建过数组的图块集在 Player 构建中同样会使用未压缩的数组。参见纹理数组和 Player 构建中的纹理数组。
• GPU instancing on instanced prototypes. 实例化树木、Mesh 模式细节和实例化装饰物的材质应勾选 Enable GPU Instancing。否则会改用临时副本进行绘制，而且其实例化变体可能会在 Player 构建中被剥离。Enable Instancing 会在列出的每个可编辑材质上勾选该选项。模型或包内的材质是只读的：请先将其提取出来。参见 GPU 实例化。
• Terrains have a tileset. 没有图块集的地形会显示为中性的占位外观。该修复会为每个没有图块集的地形指定项目中的一个图块集（可撤销）。参见图块集。

场景地形的地图文件

RTS Terrain 将地图保存在 .rtsmap 资源中（由其 Map Asset 字段引用）。没有此资源的地形，其地图只存在于内存中，关闭场景时你所做的编辑就会丢失。Terrains save to a map file 检查会列出这些地形。Create Map Files 会将列出的每个地形的当前地图保存为其场景所在文件夹中的一个新 .rtsmap 文件（如果场景尚未保存，则保存到 Assets/Maps），并将该文件指定给地形。

使用 New Map Wizard 创建的地形和演示内容中的地形已经带有地图文件。要了解地图资源、Save 和 Save As 的工作方式，请阅读地图资源与地图文件。

构建游戏

只有当构建中的某个材质使用了某个着色器时，Unity 才会将该着色器放入 Player 构建。RTS Terrain Studio 在运行时通过代码创建地形、水体和战争迷雾的材质，因此这些着色器由包文件夹内的资源 Resources/RTSTerrainStudio/RTSShaderReferences.asset 引用。该资源还引用了 DecorPlaceholder 材质，从而让 URP Lit 的实例化变体保留在构建中。每次脚本重新加载后、每次导入着色器时以及每次 Player 构建之前，系统都会自动检查并更新该资源。如果 Shaders included in builds 检查显示为红色，单击 Update。

构建之前，请逐项检查以下清单：

1. 运行 Tools ▸ RTS Terrain Studio ▸ Validate Project，修复所有错误和警告。
2. 检查目标平台的每个质量级别是否都使用了启用 Depth Texture 和 Opaque Texture 的 URP 资源；如果你使用战争迷雾，还要检查其渲染器是否添加了 RTS Fog Of War 功能。
3. 为图块集构建一次纹理数组（在验证器中单击 Build Arrays，或在图块集的 Inspector 窗口中单击 Build Texture Arrays），以免地形在加载时以未压缩形式构建它们。每次 Player 构建之前，已过期的数组都会自动重建（参见下文）。
4. 如果你的地图使用雾效，请确保 Fog kept in player builds 检查的状态为 OK（参见Player 构建中的雾效）。
5. 在 Map 选项卡上验证你的地图（参见地图验证）。
6. 将你的场景添加到构建配置文件的场景列表中。场景中指定给 RTS Terrain 的地图会和其他被引用的资源一样包含在构建中。
7. 如果你要随游戏发布游戏内编辑器，请阅读发布游戏内编辑器。玩家在运行时保存的地图会存放到 RTSMapSerializer.StorageRoot 中的 Maps 文件夹（即 Application.persistentDataPath；在 Web 构建中则是浏览器的存储空间）；参见运行时的地图文件。
8. 如果你将 Managed Stripping Level 调高到 Minimal 以上，并且编写了自己的编辑工具，请阅读代码剥离与自定义工具。
9. 对于 Web 构建，还请阅读Web（WebGL）构建。

Player 构建中的纹理数组

Player 会原样使用图块集已构建的纹理数组，因为只有编辑器才能将它们与源纹理比较。为了确保构建版本中不会带上旧的地面纹理，每次 Player 构建开始之前，系统都会检查每个曾经构建过数组的图块集：

• 如果数组与纹理、分辨率或压缩设置不再一致，或者是为其他平台或其他纹理压缩格式构建的，系统会以普通压缩质量重新构建它们。进度条会显示重建进度。
• 从未构建过数组的图块集不受影响。加载地图时，Player 会为它们构建未压缩的数组。
• 如果重建被取消或失败，并且纹理或设置已经更改，系统会弹出一个对话框，提供 Try Again、Cancel Build 和 Build Anyway 三个选项。仅格式不同的数组仍然能显示正确的纹理，因此只会记录一条警告。
• 在这种情况下，批处理模式下的构建会停止。在命令行中添加 -rtsAllowOutdatedTextureArrays 即可继续构建，每个图块集会记录一条警告。
• 没有图形设备的编辑器（-nographics，在构建服务器上很常见）无法构建数组。此时构建会继续进行，每个已过期的图块集记录一条警告，Player 会使用上一次构建的数组。进行此类构建之前，请先在编辑器中构建好数组。
• 只会为当前构建平台重建数组。如果你为其他平台构建，构建过程只会记录一条警告：请先切换到该平台。
• 单独构建的 AssetBundle 和 Addressables 内容不会运行此检查。请先构建好数组。

已构建的数组以可读形式存储在图块集资源中。Player 会在首次使用这些数组时释放这份 CPU 副本，在 512 px 下每个图块集约可节省 14 MB，在 1024 px 下约可节省 56 MB。

Player 构建中的雾效

游戏运行时，RTSEnvironment 会开启地图中存储的雾效。Unity 会剥离它认为未使用的雾效模式的着色器变体：当 Project Settings ▸ Graphics ▸ Shader Stripping ▸ Fog Modes 设置为 Automatic 时，它只会保留保存时开启了雾效的构建场景所用的雾效模式。RTS Environment 在每次保存前都会恢复场景自身的雾效设置，因此它所应用的雾效不会被计入，带雾效的地图在构建版本中便不会显示雾效。

Fog kept in player builds 检查会读取当前构建配置文件中的构建场景以及已打开的场景，并列出 RTS Environment 在其中使用的雾效模式。Keep Fog Modes（也包含在 Fix All 中）会将 Fog Modes 设置为 Custom，并恰好保留这些模式，外加之前已经保留的模式。每个保留的模式都会为构建增加着色器变体，因此未使用的模式不会被添加。如果当前构建配置文件覆盖了 Graphics 设置，请同样检查其中的 Fog Modes。

Web（WebGL）构建

RTS Terrain Studio 可以在网页浏览器中运行，包括地形、植被、水体、装饰物、战争迷雾、游戏内编辑器和示例。不过，浏览器的工作方式与桌面平台不同：玩家无法打开任何文件夹，部分按键归浏览器所有，所有代码都在一个线程上运行，而且整个游戏共享一个大小有限的内存堆。本节介绍本包如何应对这些差异，以及如何构建、测试和发布 Web 构建。

简要步骤：

1. 打开 File ▸ Build Profiles，选择 Web，然后单击 Switch Platform（或者将你的 Web 构建配置文件设为当前配置文件）。
2. 运行 Tools ▸ RTS Terrain Studio ▸ Validate Project，然后单击 Fix All。当 Web 为当前平台时，验证器还会安装全窗口模板，并检查 Web 构建的质量级别。
3. 如果你的地图使用雾效，请检查 Fog kept in player builds 的状态是否为 OK。
4. 单击 Build And Run。Unity 会构建游戏并在浏览器中打开它。

using RTSTerrainStudio;
using UnityEngine.Scripting;

// [Preserve] keeps the tool in builds with a high Managed Stripping Level.
[Preserve]
public sealed class CraterTool : RTSTool
{
    // ...
}

using System.IO;
using RTSTerrainStudio;

public static class MyGameFiles
{
    // Kept between sessions on every platform; in Web builds in the storage of the browser.
    static string SettingsPath => Path.Combine(RTSMapSerializer.StorageRoot, "settings.json");

    public static void SaveSettings(string json)
    {
        Directory.CreateDirectory(RTSMapSerializer.StorageRoot);
        File.WriteAllText(SettingsPath, json);

        // Web builds: write the change to the browser storage, so it survives a reload.
        // Does nothing on other platforms.
        RTSWebFileSystem.Flush();
    }

    /// <summary>Lets the player keep a copy of the current map on the computer (Web builds only).</summary>
    public static bool DownloadMap(RTSTerrain terrain)
    {
        if (!RTSWebFileSystem.IsSupported || terrain.Map == null) return false;
        byte[] bytes = RTSMapSerializer.Serialize(terrain.Map);
        return RTSWebFileSystem.DownloadFile("My Map" + RTSMapSerializer.FileExtension, bytes);
    }
}

地图模型

所有地图数据都存放在 MapData 类（命名空间 RTSTerrainStudio）的一个对象中。每个 RTSTerrain 组件拥有一个 MapData（terrain.Map），负责将其渲染为区块网格，持续更新由它派生出的通行图，并回答诸如“这里的地面有多高？”之类的查询。

单元格与顶点

地图是由 Width × Height 个单元格组成的栅格。每个单元格的四个角上各有一个顶点，相邻单元格共享这些角点。因此，一张 4 × 2 个单元格的地图有 5 × 3 个顶点：

 z
 2   v10 ---- v11 ---- v12 ---- v13 ---- v14
      |  cell  |  cell  |  cell  |  cell  |
      | (0,1)  | (1,1)  | (2,1)  | (3,1)  |
 1   v5 ----- v6 ----- v7 ----- v8 ----- v9
      |  cell  |  cell  |  cell  |  cell  |
      | (0,0)  | (1,0)  | (2,0)  | (3,0)  |
 0   v0 ----- v1 ----- v2 ----- v3 ----- v4
     x=0      1        2        3        4

 vertex index = z * VertexCountX + x      (VertexCountX = Width + 1)

• 顶点层（精细高度、悬崖层级、标记、悬崖类型、水面高度）包含 (Width + 1) × (Height + 1) 个条目，按行存储。用 map.VertexIndex(x, z) 获取索引。
• 单元格尺寸（map.CellSize，默认 2 m）是单个单元格在世界空间中的尺寸。一张 128 × 128、单元格尺寸为 2 m 的地图覆盖 256 × 256 m（map.WorldSize）。
• 一个位置所属的单元格为 floor(localXZ / CellSize)；map.LocalToCell(localXZ) 会完成这一计算，并将结果限制在地图范围内。
• 渲染时，单元格按区块分组（每边 16、32 或 64 个单元格，由 RTSTerrain 组件上的 Chunk Size 设置项决定，默认 32）。只有编辑涉及的区块才会重建。区块大小不影响地图数据。

地图尺寸

地图尺寸在创建地图时确定（通过 New Map Wizard、游戏内的 New Map 对话框，或在代码中通过 MapCreationSettings）。超出有效范围的值会由 MapCreationSettings.Validate() 修正。

地图包含的内容

每一项数据在 MapLayers 枚举中都有对应的标记。这些标记用于变更通知、撤销记录和序列化。

有两个组合标记很实用：MapLayers.Geometry（高度、层级、顶点标记、悬崖类型）和 MapLayers.PathingInputs（所有影响通行图的数据）。MapLayers.All 涵盖全部数据。

通行图（terrain.Pathing，类 PathingMap）是派生数据：它根据上述各层计算得出，从不保存。参见通行图。

悬崖层级、精细高度与悬崖类型

经典 RTS 地形有两种高度：大幅度的离散台阶（悬崖）和细小平滑的起伏（丘陵）。RTS Terrain Studio 在每个顶点上分别存储这两种高度。

悬崖层级

• 每个顶点都有一个悬崖层级，取值范围为 0 到 15（MapData.MaxCliffLevel = 15）。
• 每个层级高 CliffLevelHeight 米（默认 2 m）。
• 新地图从层级 2 开始，因此地面以下有两个层级可用于湖泊、河流和峡谷，地面以上有十三个层级可用于高地。
• 使用悬崖工具编辑层级：Raise / Lower Level、Set Level、Ramp、Cliff Type 和 Clean Cliffs。
• 战争迷雾使用悬崖层级判断视线：单位能看到自身所在层级及更低的层级，更高的地面会遮挡其视线。

精细高度

在层级之上，每个顶点还有一个以米为单位的精细高度（Heights），可正可负。高度工具（Raise / Lower、Smooth、Flatten、Set Height、Noise、Terrace、Erode）只改变精细高度，因此你可以在高地上堆出丘陵，而不会让它们变成悬崖。顶点的地面高度为：

vertex height = CliffLevels[i] × CliffLevelHeight + Heights[i]      (map-local Y, metres)

示例：层级为 3、层级高度为 2 m、精细高度为 0.4 m 时，顶点位于地图原点上方 6.4 m 处。map.GetVertexHeight(x, z) 和 map.GetVertexPosition(x, z) 可以替你完成这一计算。

悬崖类型

一个图块集最多可以包含 4 个悬崖图层（例如“Rock”和“Grassy Cliff”）。每个顶点都记录了要使用其中哪一个（CliffTypes，0–3，用 Cliff Type 工具绘制）。崖壁使用其所在单元格最高角点的悬崖类型。如果某个悬崖类型索引在图块集中没有对应的图层，崖壁会回退使用悬崖图层 0。

表面的构建方式（参考表面）

结构体 MapGeometryView 定义了地形唯一真实的表面。区块网格、游戏玩法查询（GetHeight、Raycast……）、通行图和战争迷雾都遵循同一套规则，因此你看到的表面就是单位实际行走的表面。每个单元格按其四个角点分类：

圆润的轮廓线。在悬崖单元格内，对于每个层级阈值 t，指示值“角点层级 ≥ t”（取 1 或 0）会在整个单元格范围内做双线性插值。一个点属于插值后指示值至少为 0.5 的最高层级（MapGeometryView.LevelAt）。这是一种 Marching Squares（移动方块）规则：单个抬高的角点会形成四分之一圆而不是对角线，长悬崖线则保持笔直。崖壁本身在轮廓线处是垂直的。精细高度始终以双线性方式插值并叠加在上面，在悬崖单元格内也是如此。

渲染出的崖壁外观可在 RTSTerrain 组件（Settings）上调整：

用 map.GetGeometryView() 获取视图。它是由原生数组组成的结构体，因此也可以传入 Burst 作业。所有成员都接受地图局部坐标：

坡道

坡道让单位可以从一个悬崖层级走到相邻的层级。规则很简单：

• 该标记是每个顶点上的 VertexFlags.Ramp。Ramp 工具（ID cliff.ramp）用于绘制此标记；按住 Shift 可将其移除。
• 坡道单元格是在其角点高度（层级加精细高度）之间的平滑双线性斜坡。
• 坡道最适合跨越恰好一个层级。更陡的坡道同样允许，但状态栏会对跨越多个层级的坡道单元格发出警告。
• 通行：对于有效的单层级坡道，只根据其精细高度形成的坡度检测是否可行走（它所跨越的层级高差不会让它被判定为“过陡”）。坡道永远不可建造。
• 在坡道上调用 GetCliffLevel 会返回插值后取整的层级：下半部分返回较低层级，上半部分返回较高层级。

1. 用 Raise / Lower Level 将一块高地抬高一个层级。
2. 选择 Ramp 工具，在需要坡道的位置横跨悬崖边缘绘制。笔刷至少要覆盖崖壁两侧的顶点，确保中间单元格的每个角点都带有标记。
3. 崖壁消失，出现一道斜坡。沿边缘绘制更多顶点即可加宽坡道。

地面图层与 Splat 贴图

地面纹理绘制在 Splat 贴图中：共四张 RGBA 纹理（MapData.SplatMapCount = 4），每张有 SplatWidth × SplatHeight 个纹素。16 个通道各自存储图块集中一个地面图层的权重：

• 图层 i 存储在贴图 i / 4 的通道 i % 4 中。这就是图块集恰好有 16 个地面图层的原因：4 张贴图 × 4 个通道。
• 同一纹素在全部 16 个通道上的权重之和始终为 255。所有绘制工具都会维持这一不变量；写入 Splat 数据的代码也必须维持它。
• Splat 分辨率是每个单元格边长上的纹素数（默认 4）。单元格尺寸为 2 m 时，即每 0.5 m 一个纹素。
• 纹素 (x, z) 的中心在地图局部 XZ 坐标中位于 ((x + 0.5), (z + 0.5)) × CellSize / SplatResolution。同一公式也适用于细节纹素和通行纹素，只需换用它们各自的分辨率。
• 辅助方法：map.SplatIndex(x, z)、map.GetSplatWeight(texelIndex, layer)、map.GetDominantLayer(texelIndex)、MapData.GetChannel / SetChannel 以及 map.FillSplat(layer)。

using RTSTerrainStudio;
using Unity.Mathematics;
using UnityEngine;

public static class SplatExample
{
    /// <summary>Paints one map cell 100 % with a ground layer (like the Tile Paint tool, without undo).</summary>
    public static void PaintCell(RTSTerrain terrain, int2 cell, int layer)
    {
        MapData map = terrain.Map;
        if (map == null || !map.IsValidCell(cell.x, cell.y)) return;
        layer = math.clamp(layer, 0, MapData.MaxGroundLayers - 1);

        int res = map.SplatResolution;
        for (int tz = cell.y * res; tz < (cell.y + 1) * res; tz++)
        {
            for (int tx = cell.x * res; tx < (cell.x + 1) * res; tx++)
            {
                int texel = map.SplatIndex(tx, tz);
                for (int m = 0; m < MapData.SplatMapCount; m++)
                {
                    // All channels 0, except the one of our layer: the sum stays exactly 255.
                    var c = new Color32(0, 0, 0, 0);
                    if (layer / 4 == m) MapData.SetChannel(ref c, layer % 4, 255);
                    map.SplatMaps[m][texel] = c;
                }
            }
        }

        // Tell the terrain which data changed and where (in cells). Textures and pathing update in LateUpdate.
        terrain.NotifyChanged(MapLayers.Splat, new RectInt(cell.x, cell.y, 1, 1));
    }
}

水体

• 带有 VertexFlags.Water 标记的顶点位于水下。其水面高度（地图局部 Y 坐标，单位为米）存储在 WaterHeights 中；该值仅在设置了此标记的位置才有意义。
• 如果某点所在单元格四个角点的水体标记经双线性插值后的覆盖率至少为 0.5，该点就被视为有水。有水单元格中不带水体标记的角点会使用该单元格内最高的水面高度，因此岸线保持水平。
• 水深 = 水面高度 − 地面高度。水深决定通行情况：水深超过图块集 Shallow Depth Limit（默认 0.9 m）的水为深水（不可行走），较浅的水为浅水（可行走，默认不可建造）。
• 水体工具包括 Paint Water、Erase Water 和 Flood Fill。水体编辑只会发出 MapLayers.Water 通知，因此绘制水体时不会重建地形区块。
• 查询方法：terrain.IsWater(world, out depth) 和 terrain.TryGetWaterHeight(world, out waterWorldY)。

水体外观（颜色、波浪、泡沫）来自图块集的水体配置；参见水体配置。

细节密度（草和小型植物）

• 细节不是单独的对象。地图上使用的每个细节原型在 map.DetailLayers 中都有一个 DetailLayer：每个细节纹素一个字节（DetailWidth × DetailHeight，默认每个单元格边长 2 个纹素）。
• 密度 0 表示空，255 表示每个纹素生成 Max Density 个实例（细节原型的一个字段，默认 6）。每个纹素生成 density / 255 × maxDensity 个实例；渲染器以确定性方式散布这些实例，因此同一张地图看起来总是一样的。
• 各层通过 prototypeId 与植被库匹配。map.GetOrAddDetailLayer(id) 按需创建细节层；当该原型未被使用时，map.FindDetailLayer(id) 返回 null。
• 用 Paint Details 绘制，用 Erase Details 擦除。

树木与装饰物实例

树木（TreeInstanceData）和装饰物（DecorInstanceData）以普通列表的形式存储。每个实例存储的不是原型名称，而是一个很小的原型索引（palette index），它指向地图上所存库 ID 列表中的某一项：

map.TreePrototypeIds = [ "a3f0…", "77c1…" ]        <- ids of TreePrototype entries in the vegetation library
map.Trees[n].prototype = 1                          <- this tree uses "77c1…"

• 使用 map.GetOrAddTreePrototype(id) / map.GetOrAddDecorPrototype(id) 获取某个库 ID 对应的原型索引（如果列表中还没有该 ID，会自动添加）。
• 由于地图通过 ID 引用原型，你可以放心地重命名、重新排序或扩展库。对于库中缺失的原型，植被渲染器会直接跳过，装饰物管理器则将其显示为品红色占位立方体；重新添加一个 ID 相同的原型即可让它恢复。通行方面：原型缺失的树木不会被绘制，但仍会阻挡一个半径为 PathingMapBuilder.DefaultTreeFootprintRadius（0.8 m）× 树木缩放的圆形区域。在原型恢复之前，装饰物占位符不会在通行图中写入占地范围。
• 每个实例在地图内都有一个唯一且稳定的 id。使用 map.AllocateInstanceId() 获取新 ID。
• 位置采用地图局部坐标。所有旋转都遵循同一约定：以度为单位，俯视时按顺时针方向计算，0 = +Z，90 = +X（与 Unity 的 Y 轴旋转一致）。

position.y 约定

切勿把原型的 yOffset 复制到 position.y 中，渲染时会再加上它。DecorMath.ComputeLocalPosition 和 DecorMath.ToStoredHeight 用于在存储位置与渲染位置之间转换。

using RTSTerrainStudio;
using Unity.Mathematics;
using UnityEngine;

public static class InstanceExample
{
    /// <summary>Adds a tree of the first tree prototype of the terrain's vegetation library at a world position.</summary>
    public static uint AddTree(RTSTerrain terrain, Vector3 worldPosition, float yawDegrees)
    {
        MapData map = terrain.Map;
        RTSVegetationLibrary library = terrain.VegetationLibrary;
        if (map == null || library == null || library.trees.Count == 0) return 0;

        Vector3 local = terrain.WorldToLocal(worldPosition);
        var tree = new TreeInstanceData
        {
            id = map.AllocateInstanceId(),
            prototype = map.GetOrAddTreePrototype(library.trees[0].id), // palette index of the library id
            position = new float3(local.x, 0f, local.z),                 // y = offset above the ground, normally 0
            yaw = yawDegrees,                                             // clockwise from above, 0 = +Z
            scale = 1f,
            tint = new Color32(255, 255, 255, 255)
        };
        map.Trees.Add(tree);

        // Notify the cell that changed: vegetation, pathing (tree footprint) and fog blockers update.
        int2 cell = map.LocalToCell(new float2(local.x, local.z));
        terrain.NotifyChanged(MapLayers.Trees, new RectInt(cell.x, cell.y, 1, 1));
        return tree.id;
    }

    /// <summary>Adds a decor object (by library id) standing upright on the ground.</summary>
    public static uint AddDecor(RTSTerrain terrain, string decorPrototypeId, Vector3 worldPosition, float yawDegrees)
    {
        MapData map = terrain.Map;
        if (map == null) return 0;

        Vector3 local = terrain.WorldToLocal(worldPosition);
        var decor = new DecorInstanceData
        {
            id = map.AllocateInstanceId(),
            prototype = map.GetOrAddDecorPrototype(decorPrototypeId),
            variant = 0,                                  // main prefab
            flags = DecorFlags.None,
            position = new float3(local.x, 0f, local.z),  // the prototype's yOffset is added at render time
            rotation = DecorMath.Yaw(yawDegrees),
            scale = new float3(1f, 1f, 1f),
            tint = new Color32(255, 255, 255, 255)
        };
        map.Decor.Add(decor);

        int2 cell = map.LocalToCell(new float2(local.x, local.z));
        terrain.NotifyChanged(MapLayers.Decor, new RectInt(cell.x, cell.y, 1, 1));
        return decor.id;
    }
}

通行图

通行图用于回答“单位能否在这里行走、建筑能否放在这里？”这类问题。它是由通行单元格组成的栅格（每个地图单元格每边 PathingResolution 个，默认为 2，因此在单元格尺寸为 2 m 的地图上，通行单元格的边长为 1 m），每个通行单元格对应一个 PathingFlags 字节。通行图由系统自动推导得出，只要任一输入发生变化（几何形状、水体、地面图层、树木、装饰物、通行覆盖），就会增量重建。通行图本身从不保存，保存的只有手动设置的通行覆盖。

标记的推导方式

1. 地形：崖壁（外加 Cliff Margin 范围）会设置 Cliff；坡度超过 Max Walkable Slope（默认 42°）时设置 Steep；水体根据水深设置 ShallowWater 或 DeepWater；所有位置都设置 Flyable；Buildable = 可行走、坡度 ≤ Max Buildable Slope（默认 18°）且没有水（开启 Shallow Water Buildable 时，浅水也可以）。之后再应用主导地面图层的 Pathing Effect（例如粗糙岩石图层上的“Unbuildable”）。
2. 占地范围：树木会阻挡一个圆形区域（半径 = Footprint Radius × 树木缩放 × Tree Footprint Scale）；装饰物会在圆形或旋转后的矩形区域内应用其 Footprint Effect，除非该实例带有 DecorFlags.IgnorePathing。
3. 手动覆盖（用 Paint Pathing / Clear Pathing 绘制）最后应用。

这些规则的设置项位于 RTSTerrain 组件上（RTSPathingSettings，属性 terrain.PathingSettings）。

地面图层的通行效果、装饰物的占地效果和绘制的通行覆盖都使用同一组 PathingOverride 标记。可以用 terrain.GetPathing(world)、terrain.IsWalkable(world) 和 terrain.IsBuildable(world) 查询结果，也可以直接读取 terrain.Pathing.Flags。

区域、出生点与标记点

这些是供游戏逻辑使用的轻量对象。它们不会在游戏中渲染，编辑器会将它们绘制为 Gizmo（辅助图标）。

对于出生点和标记点，工具会存储 position.y = 0，并像树木一样把它视为相对地面的偏移。

using RTSTerrainStudio;
using Unity.Mathematics;
using UnityEngine;

public static class RegionExample
{
    /// <summary>Returns the "gold" property of the first region that contains the world position, or 0.</summary>
    public static int GetGoldAt(RTSTerrain terrain, Vector3 worldPosition)
    {
        if (terrain.Map == null) return 0;
        Vector3 local = terrain.WorldToLocal(worldPosition);
        foreach (MapRegion region in terrain.Map.Regions)
        {
            // Regions are rectangles in map-local XZ.
            if (region.Contains(new float2(local.x, local.z)) &&
                int.TryParse(region.GetProperty("gold", "0"), out int gold))
                return gold;
        }
        return 0;
    }
}

地图信息与环境

EnvironmentSettings 存储地图的光照设置。它由 RTSEnvironment 组件（GameObject ▸ RTS Terrain Studio ▸ Environment）应用到场景中；如果没有该组件，这些值会被保存，但不会生效。

变更通知

通过代码修改 MapData 后，需要告诉地形改了什么、改在哪里（以单元格为单位）：

• terrain.NotifyChanged(MapLayers layers, RectInt cellRect) 会立即触发 MapChanged，并将重建加入队列。
• terrain.NotifyChangedAll(layers) 将整张地图标记为已更改（适用于运行生成器或导入之后）。
• 待处理的更改会在 LateUpdate 中处理（在 Play 模式之外，每次编辑器更新时也会处理），也可以调用 terrain.ProcessPendingChanges() 立即处理。之后会触发 ChangesProcessed，此时网格、纹理和通行数据均已更新。
• 一个顶点最多与四个单元格相接。可以用 BrushUtility.VertexRectToCellRect(map, vertexRect) 将顶点矩形转换为单元格矩形，用 BrushUtility.TexelRectToCellRect(map, texelRect, resolutionPerCell) 转换纹素矩形。

using RTSTerrainStudio;
using UnityEngine;

public static class CliffExample
{
    /// <summary>Raises a square plateau by one cliff level around a world position.</summary>
    public static void RaisePlateau(RTSTerrain terrain, Vector3 worldCenter, int radiusInVertices)
    {
        MapData map = terrain.Map;
        if (map == null) return;

        // Nearest vertex to the centre (vertices sit on multiples of the cell size).
        Vector3 local = terrain.WorldToLocal(worldCenter);
        int cx = Mathf.RoundToInt(local.x / map.CellSize);
        int cz = Mathf.RoundToInt(local.z / map.CellSize);

        int x0 = Mathf.Max(0, cx - radiusInVertices), x1 = Mathf.Min(map.Width, cx + radiusInVertices);
        int z0 = Mathf.Max(0, cz - radiusInVertices), z1 = Mathf.Min(map.Height, cz + radiusInVertices);
        for (int z = z0; z <= z1; z++)
        {
            for (int x = x0; x <= x1; x++)
            {
                int i = map.VertexIndex(x, z);
                // Levels are bytes from 0 to 15: always clamp.
                map.CliffLevels[i] = (byte)Mathf.Min(map.CliffLevels[i] + 1, MapData.MaxCliffLevel);
            }
        }

        // Convert the changed vertices to the cells around them and notify the terrain.
        var vertexRect = new RectInt(x0, z0, x1 - x0 + 1, z1 - z0 + 1);
        RectInt cells = BrushUtility.VertexRectToCellRect(map, vertexRect);
        terrain.NotifyChanged(MapLayers.CliffLevels, cells);
    }
}

坐标与多个地形

所有地图数据都存储在地图局部空间中。RTSTerrain GameObject 的 Transform 负责把该空间放置到世界中。

地图局部空间

• 原点是顶点 (0, 0)，即单元格 (0, 0) 的角点。X 和 Z 的范围是 0 到 map.WorldSize（单位为米），Y 轴朝上。
• 顶点 (x, z) 位于局部坐标 (x × CellSize, height, z × CellSize)；单元格 (x, z) 的中心位于 ((x + 0.5) × CellSize, …, (z + 0.5) × CellSize)。
• 局部 Y = 0 对应层级 0、精细高度为 0。如果新地图的基础层级为 2，每个层级高 2 m，那么它的地面位于局部 Y = 4 m。
• 区块 GameObject 都位于地形的隐藏子对象 RTS Chunks（RTSTerrain.ChunkRoot）之下。该根对象没有局部偏移或旋转，并会抵消地形的缩放，而每个区块的局部 Transform 都是单位变换，因此区块网格的对象空间就是地图局部空间。为地形编写着色器时，这一点很重要。

世界空间与地图空间的转换

using RTSTerrainStudio;
using Unity.Mathematics;
using UnityEngine;

/// <summary>Add to any GameObject and use the context menu to see the map data under it.</summary>
public class TerrainProbe : MonoBehaviour
{
    [ContextMenu("Probe Terrain")]
    void Probe()
    {
        // Several terrains can exist: find the one below this object.
        RTSTerrain terrain = RTSTerrain.FindAt(transform.position);
        if (terrain == null || terrain.Map == null) { Debug.Log("Not above an RTS Terrain."); return; }
        MapData map = terrain.Map;

        // World -> map-local (origin at vertex 0,0; position and Y rotation only).
        Vector3 local = terrain.WorldToLocal(transform.position);
        int2 cell = terrain.WorldToCell(transform.position);

        // Nearest vertex.
        int vx = Mathf.Clamp(Mathf.RoundToInt(local.x / map.CellSize), 0, map.Width);
        int vz = Mathf.Clamp(Mathf.RoundToInt(local.z / map.CellSize), 0, map.Height);
        int v = map.VertexIndex(vx, vz);

        // Splat texel below the object (SplatResolution texels per cell side).
        int tx = Mathf.Clamp((int)(local.x / map.CellSize * map.SplatResolution), 0, map.SplatWidth - 1);
        int tz = Mathf.Clamp((int)(local.z / map.CellSize * map.SplatResolution), 0, map.SplatHeight - 1);
        int dominantLayer = map.GetDominantLayer(map.SplatIndex(tx, tz));

        Debug.Log($"Cell {cell}, vertex ({vx},{vz}): level {map.CliffLevels[v]}, fine height {map.Heights[v]:0.00} m, " +
                  $"vertex height {map.GetVertexHeight(vx, vz):0.00} m. Ground at world Y {terrain.GetHeight(transform.position):0.00}, " +
                  $"cliff level {terrain.GetCliffLevel(transform.position)}, dominant ground layer {dominantLayer}, " +
                  $"pathing {terrain.GetPathing(transform.position)}.");
    }
}

位置、旋转与缩放规则

多个地形

一个场景可以包含任意数量的 RTSTerrain 组件。每个组件都有自己的地图、图块集、库、区块和通行图。

• RTSTerrain.All 列出所有已启用的地形；RTSTerrain.Main 返回第一个地形（适合单地图游戏；临时预览地形会被跳过）。
• RTSTerrain.FindAt(worldPosition) 返回 XZ 区域包含该位置的地形。
• RTSTerrain.RaycastAll(ray, out hit) 对所有地形执行射线检测，并返回最近的命中结果（hit.terrain 会指明命中的是哪个地形）。
• RTSTerrain.TerrainEnabled / TerrainDisabled 是静态事件，供需要跟踪地形的系统使用。
• 各个地形相互独立：地图在边界处不会拼接，寻路（RTSPathfinder.FindPath(terrain, …)）每次也只作用于一个地形。要让两张地图无缝衔接，需要让它们边界顶点的高度保持一致。

using RTSTerrainStudio;
using UnityEngine;

public static class TerrainLayout
{
    /// <summary>Places "east" directly next to "west" (along west's local +X), with the same rotation.</summary>
    public static void PlaceNextTo(RTSTerrain west, RTSTerrain east)
    {
        if (west.Map == null) return;
        float widthMetres = west.Map.WorldSize.x;   // map-local X extent in metres
        east.transform.SetPositionAndRotation(
            west.transform.position + west.transform.rotation * new Vector3(widthMetres, 0f, 0f),
            west.transform.rotation);
    }
}

地图资源与地图文件

地图保存为 .rtsmap 文件。Unity 编辑器（作为项目中的资源）和游戏内编辑器（作为磁盘上的文件）使用相同的二进制格式，因此玩家制作的地图可以在 Unity 中打开，反之亦然。

项目中的 .rtsmap 文件

当 Unity 在 Assets 文件夹中发现 .rtsmap 文件时，导入器 RTSMapImporter 会将其转换为 RTSMapAsset。该资源存储压缩后的文件字节、一个小型文件头（名称、作者、尺寸、玩家数、图块集 ID）以及一张小地图预览图，这张预览图也用作 Project 窗口中的缩略图。

创建地图资源

• Tools ▸ RTS Terrain Studio ▸ New Map Wizard...：引导式设置（基本信息、尺寸、外观、地形）；写入文件并为其创建地形，或将其指定给选中的地形。
• Assets ▸ Create ▸ RTS Terrain Studio ▸ Map (.rtsmap)：在选中的文件夹中创建一张使用默认设置、尺寸为 128 × 128 的平坦地图。
• RTS Terrain Studio 窗口中的 Save As…：将某个地形的当前地图写入新文件。
• 将游戏内编辑器制作的 .rtsmap 文件复制到 Assets 文件夹中，Unity 会像导入其他文件一样导入它。

地图资源的 Inspector 窗口

选中一个地图资源，即可查看其预览图、名称、作者、描述、尺寸、玩家数、图块集和格式版本，以及统计信息（单元格数、世界尺寸、单元格尺寸、层级高度、出生点、树木、装饰物、区域、标记点、细节图层、文件大小、内存占用、最后修改时间）。

当地图所记录的 ID 对应的图块集被添加、移除，或其小地图颜色发生变化时，预览图会自动重新烘焙。重建纹理数组不会重新导入地图。损坏的文件会作为带错误图标的空资源导入，同时 Console 窗口中会出现一条导入错误。

编辑、Save 与 Save As

将地图资源指定给 RTSTerrain 的 Map Asset 字段。地形启用时会将地图加载到内存中，所有编辑都在这份内存副本上进行。场景文件只存储对该资源的引用，从不存储地图数据本身。

• Save（位于 RTS Terrain Studio 窗口标题栏，或 Scene 视图中 RTS Terrain Studio 叠加层选项菜单里的 Save Map）会将地图写回其 .rtsmap 文件并重新导入。存在未保存的更改时，Save 会高亮显示。
• Save As… 会写入新文件并将其指定给地形，且不会重新加载地图，因此你的撤销历史会保留下来。
• Open… 加载另一个地图资源；Reload 从资源重新加载地图，并丢弃未保存的更改。
• 没有地图资源的地形会根据其 Default Map Settings 创建地图。在你使用 Save As 之前，这张地图只存在于内存中。
• 保存场景（Ctrl+S）时，也会保存该场景中各地形已编辑的地图，并为尚无文件的新地图提供 Save As 选项。这两种行为都可以在 Scene 视图叠加层的选项菜单中关闭（Save Maps When Saving the Scene、Offer Save As for New Maps）。
• 如果存在未保存的地图编辑，在进入 Play 模式、关闭场景或退出 Unity 之前，系统会询问你是否保存。在 Play 模式下所做的编辑（无论是通过 Scene 视图工具还是游戏内编辑器）也会在你退出 Play 模式时提示保存。

运行时的地图文件

在构建出的游戏中，地图就是磁盘上的普通文件：

• RTSMapSerializer.DefaultMapsFolder 是 RTSMapSerializer.StorageRoot 下的 Maps 文件夹。该存储根目录就是 Application.persistentDataPath，因此在 Windows 上，这个文件夹通常为 %USERPROFILE%\AppData\LocalLow\<Company>\<Product>\Maps。在 Web 构建中，StorageRoot 是浏览器存储空间中的一个文件夹（参见浏览器中的地图）。
• 游戏内编辑器（RTSRuntimeEditor）在其 Maps Folder 中保存和打开地图（留空 = 上述默认文件夹；相对路径以 RTSMapSerializer.StorageRoot 为基准）。开启 Write Preview Images 后，它会在每张已保存的地图旁写入一张小尺寸的小地图图像 Name.preview.png，供其地图浏览器使用。
• 要分享地图，可将 .rtsmap 文件复制到其他玩家的地图文件夹，或复制到 Unity 项目中。在网页浏览器中，则应改用游戏内编辑器的 Download Map 和 Import Map。
• 随游戏发布的地图可以直接作为地图资源，由地形或脚本引用；它们会和其他资源一样包含在构建版本中。

using System.IO;
using RTSTerrainStudio;
using UnityEngine;

public class SimpleMapList : MonoBehaviour
{
    [SerializeField] RTSTerrain terrain;

    /// <summary>Logs all maps in the default folder without loading them, then opens the first one.</summary>
    [ContextMenu("List And Open Maps")]
    void ListAndOpen()
    {
        string folder = RTSMapSerializer.DefaultMapsFolder;
        if (!Directory.Exists(folder)) { Debug.Log("No maps folder yet: " + folder); return; }

        string[] files = Directory.GetFiles(folder, "*" + RTSMapSerializer.FileExtension);
        foreach (string path in files)
        {
            // The header is stored uncompressed, so this is fast even for big maps.
            if (RTSMapSerializer.TryReadHeaderFromFile(path, out RTSMapHeader h))
                Debug.Log($"{h.name} by {h.author}: {h.width} x {h.height} cells, {h.maxPlayers} players, saved {h.Modified}");
        }

        if (files.Length > 0 && terrain != null)
        {
            try
            {
                terrain.LoadFromFile(files[0]);   // the terrain owns and disposes the loaded map
            }
            catch (InvalidDataException e)
            {
                Debug.LogError("The map file is damaged: " + e.Message);
            }
        }
    }
}

图块集

图块集（RTSTileset）定义地图的外观：最多 16 个地面图层、最多 4 个悬崖图层以及水体样式，类似于经典 RTS 地图编辑器中的夏季、冬季或沙漠图块集。你可以创建任意数量的图块集，并随时切换地形所用的图块集：已绘制的地图只存储图层索引，因此同一张地图既可以呈现夏季风貌，也可以呈现冬季风貌。

1. 通过 Assets ▸ Create ▸ RTS Terrain Studio ▸ Tileset 创建图块集。
2. 将地面纹理拖放到 Inspector 窗口的 Ground Layers 部分。每张反照率纹理会创建一个图层。匹配的法线贴图和高度贴图会根据文件名后缀自动识别（例如 _n、_normal、_nrm、_normalgl、_h、_height、_disp）；粗糙度、AO 和金属度贴图会被忽略，因此你可以直接拖入下载的整个纹理文件夹。
3. 以同样的方式在 Cliff Layers 中添加悬崖图层。
4. 将图块集指定给 RTSTerrain 的 Tileset 字段。
5. 在 Texture Arrays 部分中单击一次 Build Texture Arrays（参见纹理数组）。

图块集字段

地面图层字段

悬崖图层字段

崖壁在地图局部空间中使用三平面映射贴图，因此悬崖纹理不需要特殊的 UV 布局。

水体配置

水体配置是图块集的一部分，供水体渲染器、通行图和小地图使用。

通过代码编辑图块集

图块集是 ScriptableObject。通过代码修改字段后，调用 tileset.NotifyChanged()，让地形刷新其材质。对于未使用的槽位，tileset.GetGroundLayer(index) 和 GetCliffLayer(index) 返回 null。

纹理数组

地形着色器在单个 Pass 中绘制全部 20 个图层，因此所有图层纹理都打包进两个 GPU 纹理数组中。你无需亲自制作这些数组：只要提供任意尺寸和格式的普通 Unity 纹理，数组就会自动生成。

布局

• 第一个悬崖切片为 RTSTileset.CliffSliceOffset（16）；切片总数为 RTSTileset.TotalSlices（20）。
• 高度（alpha）取自图层的 Height Map（R 通道）；如果没有，且开启了 Height From Albedo Alpha，则取自反照率的 alpha；否则为常量 0.5。
• 法线会在构建过程中解包，因此你的法线贴图可以照常使用 Unity 的法线贴图导入方式（DXT5nm / BC5）。没有法线贴图的图层会得到平坦法线。
• 没有反照率纹理的图层会得到带有细微图案的中性灰色切片；着色器仍会应用色调。
• 每个切片都有完整的 Mip 链，并使用三线性过滤。任意尺寸的源纹理都会缩放到所选的 Resolution。

预构建数组与运行时回退

数组有两种生成方式：

Texture Arrays 部分会显示一个状态徽章：

• Not built：地形正在使用运行时数组。单击一次 Build Texture Arrays 即可。
• Up to date：显示格式、尺寸、Mip 数量和内存占用。
• Outdated：纹理、分辨率或压缩设置已更改，或者数组是为其他平台或其他纹理压缩格式构建的。重新构建即可，也可以交给下一次 Player 构建来完成。
• Building：构建正在进行或已排队等待。

该部分还会显示当前活动构建平台的目标格式、预计大小和构建时间；构建大小超过 256 MB 时，会先请求你确认。Clear 会移除预构建数组。

Player 构建

Player（构建出的游戏）会原样使用预构建数组，因为只有编辑器才能将它们与源纹理进行比较。因此，已过期的数组会在每次 Player 构建开始前自动重建，而从未构建过数组的图块集会继续使用运行时数组。详细信息（包括批处理模式和 -rtsAllowOutdatedTextureArrays）参见Player 构建中的纹理数组。Player 还会在首次使用预构建数组时释放它们在 CPU 端的副本，节省的内存大约与这些数组占用的 GPU 内存相当。

通过代码：tileset.HasValidBuiltArrays 表示是否会使用压缩数组。在编辑器中，数组必须存在且与 ComputeContentHash() 匹配。Player 会一直信任预构建数组，直到你的代码在运行时更改图层纹理、分辨率或压缩设置，随后回退到运行时数组。ComputeContentHash() 的值只能在编辑器内部或同一次 Player 会话内相互比较，因为编辑器计算哈希时使用的是纹理的导入状态。HasValidBuiltArrays 为 false 时，RTSTerrain 会构建未压缩的运行时数组（RTSTextureArrayBuilder.Acquire）。tileset.BuiltAlbedoArray / BuiltNormalArray 提供对预构建数组的访问。在你自己的运行时代码中，请使用 RTSShaderReferences.FindShader(name)（以及 FindMaterial(name)）代替 Shader.Find，这样查找在 Player 构建中也能正常工作。

Auto Build

开启 Auto Build（默认开启，这是一项适用于所有图块集的编辑器偏好设置）后，之前构建过的数组会在纹理、分辨率或压缩设置更改一秒后，使用快速压缩自动重建。首次构建始终需要手动启动。被取消或失败的自动构建在内容或目标格式发生变化之前不会重试。手动单击 Build Texture Arrays 按钮时使用正常的压缩质量，效果略好，因此请在发布前单击一次。

植被库

植被库（RTSVegetationLibrary）列出可用于绘制的草、植物和树木。通过 Assets ▸ Create ▸ RTS Terrain Studio ▸ Vegetation Library 创建植被库，并将其指定给 RTSTerrain 的 Vegetation Library 字段。地形还需要 RTSVegetationRenderer 组件才能显示植被（RTSTerrain 的 Inspector 窗口会提供添加该组件的选项）。

植被库的 Inspector 窗口有 Details 和 Trees 两个选项卡，各带一个缩略图列表。将预制件（树木）、纹理（草片）或网格（细节网格）拖放到列表上即可添加条目。每个条目都有一个供地图使用的稳定 id；复制出的条目会自动获得新的 ID。

细节原型

细节是按密度绘制、数量众多的小型植物（参见细节密度）。它们按 16 × 16 个单元格的块生成，并使用内部程序化着色器 Hidden/RTS Terrain Studio/Detail 绘制，该着色器负责处理风、战争迷雾和颜色变化。

树木原型

树木是通过 Place Trees 放置的独立实例（参见树木与装饰物实例）。

GPU 实例化

以 Instanced 模式生成的树木通过 GPU 实例化绘制，因此其材质应开启 Enable GPU Instancing。如果某个材质未开启该选项，渲染器会自动使用该材质的隐藏实例化副本（在你编辑时与原材质保持同步），同时植被库的 Inspector 窗口会显示一条信息提示，附带可直接修复材质本身的 Enable 按钮。细节的材质无需开启实例化，因为细节始终使用程序化细节着色器绘制。

通过代码：使用 RTSVegetationRenderer.RemoveTree(id) 移除树木实例（例如工人砍伐一棵树时），使用 TryFindNearestTree 查找树木，使用 GetTreeObject(id) 获取其 GameObject 或碰撞体代理。

通过代码编辑库

地图存储的是一张原型 ID 表，因此需要通过库解析原型索引：

• 树木：vegetationLibrary.FindTree(map.TreePrototypeIds[tree.prototype])。
• 细节图层：vegetationLibrary.FindDetail(layer.prototypeId)。
• 装饰物：decorLibrary.Find(map.DecorPrototypeIds[d.prototype])。使用 prototype.GetPrefab(d.variant) 获取变体预制件：0 表示主预制件，无效或空的变体会回退到主预制件。VariantCount 包含主预制件。
• decorLibrary.GetCategories() 按显示顺序列出各类别（没有类别的原型会列在 Misc 下）。
• vegetationLibrary.EnsureUniqueIds() 会为重复的条目分配新 ID。

通过代码修改库后，调用 library.NotifyChanged()（它会触发库的 Changed 事件），使 RTSTerrain 触发 LibrariesChanged，渲染器随之刷新。这与图块集的规则相同。

装饰物库

装饰物库（RTSDecorLibrary）列出了你可以放置的场景道具（doodad）：岩石、废墟、栅栏、箱子、建筑或任何其他预制件。通过 Assets ▸ Create ▸ RTS Terrain Studio ▸ Decor Library 创建一个装饰物库，并将其指定给 RTSTerrain 的 Decor Library 字段。地形上的 RTSDecorManager 组件负责让场景与已放置的实例保持同步。

Inspector 窗口以列表形式显示各个原型及其自动生成的缩略图，每个类别对应一个选项卡（另有一个 All 选项卡）。将预制件拖放到列表上，即可将其添加到当前类别；右键单击类别选项卡可以重命名该类别。没有类别的原型显示在 Misc 下。

装饰物原型字段

占地范围

• 圆形占地范围以 Footprint Size 的 X 值为半径，再乘以实例在水平方向上的最大缩放值。
• 矩形占地范围会跟随实例的旋转（将其 X 轴和 Z 轴投影到地面上）以及 X/Z 缩放，因此旋转后的墙壁恰好只阻挡自身所占的区域。
• 当形状为 None、效果为 None，或实例带有 DecorFlags.IgnorePathing 标记时，不会写入占地范围。
• 对于单位可以从上面走过的扁平装饰物（花朵、碎石），只使用 Unbuildable；对于实体对象，则使用 Unwalkable。

生成模式

Instanced 模式的装饰物与实例化树木具有相同的 GPU 实例化行为：未勾选 Enable GPU Instancing 的材质会通过一个隐藏的实例化副本进行绘制。生成的对象会放入对象池；RTSDecorManager.GetInstanceObject(id) 返回某个实例生成的对象，RTSDecorInstance.FromCollider(collider) 则将物理检测的命中结果映射回对应的实例。

.rtsmap 文件格式

本节面向需要用其他工具读取地图、编写转换器或添加自定义数据的程序员。如果只是使用本包，则无需了解这些内容：RTSMapSerializer 会处理好一切。

二进制布局

所有数值均采用小端序（little-endian）。字符串采用 .NET BinaryWriter 格式：先是以 7 位编码的长度，后跟 UTF-8 字节。

头部未经压缩，因此地图浏览器无需解压地图就能显示名称、作者、尺寸和玩家人数（RTSMapSerializer.TryReadHeader、TryReadHeaderFromFile、结构体 RTSMapHeader）。读取器根据头部长度直接跳到头部末尾，因此以后的版本可以追加头部字段。

文件段

每个段的结构为 [int32 tag][int32 length][payload]。标签是以小端序存储的 FourCC 代码，因此第一个字符位于最低字节（DIMS = 0x534D4944）。栅格数据数组的写法是：先写入 int32 元素数量，再写入原始元素。

“properties”（属性）的写法是：先写入 int32 数量，再写入若干键/值字符串对。派生出的通行图不会被存储，只存储手动通行覆盖。

未知段、损坏的文件与版本管理

• 读取器会根据长度跳过未知段。因此，旧版本的包也能读取带有额外段的新文件，你的自定义段也绝不会导致其他读取器出错。
• 如果文件的格式版本比读取器新，读取器会记录一条警告，但仍会读取该文件；未知数据会被跳过。
• 如果某个栅格层的元素数量与地图尺寸不符，会记录一条警告；能对应上的部分会被读取，其余部分则被跳过。
• 被截断或损坏的文件只会抛出一种异常类型：System.IO.InvalidDataException。魔数不正确的文件会被报告为“Not an RTS Terrain Studio map file”。
• RTSMapSerializer.SaveToFile 会先写入 <path>.tmp，然后再替换原文件，因此即使保存过程中发生崩溃，也绝不会留下写了一半的地图。
• 该格式的兼容性规则：新数据总是以新段或追加头部字段的形式加入，绝不通过修改现有段来实现。你自己的段也应遵循这一规则，并在负载数据中保存一个版本号。

自定义段

你可以在地图文件中存储自己的数据，例如游戏规则、触发器或任务数据。这要借助 RTSMapSerializer 上的两个静态钩子来实现：

• 选择不会与内置标签冲突的标签：让它们以 X 开头（例如 XGLD）。切勿使用 0，因为它标志着所有段的结束。
• 这两个钩子都是普通委托：用 += 添加处理程序，用 -= 移除处理程序，这样多个系统都可以添加各自的段。
• 在读取器中检查标签，忽略不属于你的段。
• MapData 中没有存放你自己数据的位置，因此需要把数据与地图关联起来单独存放（示例中使用了 ConditionalWeakTable）。以这种方式保存的数据不会被 MapData.Clone() 或 ResizeMap 复制，也不会被记录到撤销历史中。
• 在加载或保存任何地图之前注册钩子。在 Unity 编辑器中，导入器也会读取地图，Save 也会写入地图，因此还需要为编辑器注册（示例中使用了 InitializeOnLoadMethod）。

using System;
using System.IO;
using System.Runtime.CompilerServices;
using RTSTerrainStudio;
using UnityEngine;

/// <summary>Stores a "starting gold" value in every map file, in a custom section "XGLD".</summary>
public static class StartingGoldSection
{
    // FourCC, little-endian like the built-in tags: the first character is in the lowest byte.
    const int Tag = 'X' | ('G' << 8) | ('L' << 16) | ('D' << 24);
    const int PayloadVersion = 1;

    /// <summary>Our data for one map.</summary>
    public sealed class Data
    {
        public int startingGold = 500;
    }

    // One Data object per MapData. Entries disappear automatically together with their map.
    static readonly ConditionalWeakTable<MapData, Data> s_Data = new ConditionalWeakTable<MapData, Data>();

    /// <summary>Returns the data of a map (created with defaults when the map has none).</summary>
    public static Data Get(MapData map) => s_Data.GetOrCreateValue(map);

#if UNITY_EDITOR
    [UnityEditor.InitializeOnLoadMethod]          // editor: importer and Save
#endif
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]   // player and Play Mode
    static void Register()
    {
        // Remove first so a second registration does not add the handlers twice.
        RTSMapSerializer.CustomSectionWriter -= Write;
        RTSMapSerializer.CustomSectionWriter += Write;
        RTSMapSerializer.CustomSectionReader -= Read;
        RTSMapSerializer.CustomSectionReader += Read;
    }

    static void Write(MapData map, Action<int, byte[]> writeSection)
    {
        if (!s_Data.TryGetValue(map, out Data data)) return;   // nothing to save for this map
        using (var stream = new MemoryStream())
        {
            using (var writer = new BinaryWriter(stream))
            {
                writer.Write(PayloadVersion);   // our own version, so the payload can grow later
                writer.Write(data.startingGold);
            }
            writeSection(Tag, stream.ToArray());
        }
    }

    static void Read(MapData map, int tag, byte[] payload)
    {
        if (tag != Tag) return;   // another system's section: ignore it
        using (var reader = new BinaryReader(new MemoryStream(payload)))
        {
            int version = reader.ReadInt32();
            if (version >= 1) Get(map).startingGold = reader.ReadInt32();
        }
    }
}

在游戏代码中通过 StartingGoldSection.Get(terrain.Map).startingGold 使用它。在编辑器中修改该值后，需要将地图标记为已更改（例如调用 terrain.NotifyChanged(MapLayers.Info, terrain.Map.CellBounds)，或设置 terrain.HasUnsavedChanges = true），这样地图才会被保存。

RTS Terrain Studio 窗口

该窗口是编辑器的控制中心。它本身不保存任何编辑状态，而是显示并修改一个共享的编辑会话；Scene 视图、Scene 视图叠加层以及 RTS Terrain 组件的 Inspector 也都使用这个会话。你在任何一处所做的更改都会立即反映到其他地方。

你可以通过以下任一方式打开该窗口：

• Tools ▸ RTS Terrain Studio ▸ Editor Window
• RTS Terrain 组件 Inspector 中的 Open RTS Terrain Studio 按钮
• Scene 视图中 RTS Terrain Studio 叠加层上的窗口按钮

窗口分为四个区域：顶部的标题栏、选项卡栏、可滚动的页面，以及底部的状态栏。

工具页面

每个类别选项卡中都有一列纵向排列的卡片。单击卡片标题即可将其折叠。

卡片	内容
Category Tools	工具列表。单击某个工具即可在 Scene 视图中用它进行绘制；再次单击当前工具则停止编辑。将鼠标悬停在工具上可查看其说明和修饰键。你自己编写的自定义工具会自动出现在这里。
工具卡片	显示所选工具的名称、说明和提示，一个可打开本手册对应章节的 ? 按钮，以及一行实时状态信息。将鼠标移到地形上即可看到状态信息，例如高度工具显示 Ground 4.25 m | Fine +0.25 m | Level 2，悬崖工具显示 Level 2 → 3。
Getting Started	在未选择该类别中的任何工具时显示。如果你正在使用其他类别的工具绘制，这里会显示 Active tool: X，并提供 Go to Tool 按钮。
Brush	形状、半径、强度、硬度、衰减曲线、旋转、随机旋转、间距和抖动。所有笔刷工具共享这些设置。对于不使用笔刷的工具，此卡片会隐藏。参见笔刷。
Symmetry	对称模式和对称中心（拖拽工具不显示此卡片）。参见对称。
Tool Settings	所选工具的设置，根据工具的代码自动生成。即使重启编辑器，这些设置也会保留。工具参考中的表格列出了全部设置项。
类别操作	部分类别特有的额外卡片：Auto Paint Whole Map（Paint）、Selection（Decor，仅在 Select Decor 处于激活状态时）、Water at Cursor（Water）和 Pathing Overlay（Pathing）。

编辑暂停时，会出现一条横幅提示 Editing is paused – the Scene View uses Unity's tools。单击其中的 Resume 按钮即可重新开启编辑。

Map 选项卡

Map 选项卡包含作用于整张地图的设置和操作。除非对话框另有说明，所有更改都可以撤销。顶部的 ? 按钮会打开本节。

Settings 选项卡

在 Scene 视图中绘制

所有编辑都在 Scene 视图中进行。开启地形编辑并选中一个工具后，鼠标左键会使用该工具进行绘制，而不是选择对象。你可以通过窗口中的 Editing 按钮、叠加层中的 Start Editing 按钮、Inspector 窗口中的 Edit Terrain 按钮，或直接单击某个工具来开启编辑。按 Esc 可关闭编辑。

using RTSTerrainStudio.Editor;
using UnityEditor;

static class MyBuildSteps
{
    [MenuItem("Tools/My Project/Run Map Batch")]
    static void RunMapBatch()
    {
        // No save prompts while this scope is open. Scopes can be nested.
        using (RTSMapSaveGuard.Suppress())
        {
            // ... open scenes, edit or generate maps, enter and leave Play Mode ...
        }
    }
}

键盘快捷键

Scene 视图快捷键注册在 Unity 的 Shortcut Manager 中的 RTS Terrain Studio 类别下。只有同时满足以下条件时它们才会生效：地形编辑已开启；Scene 视图或某个 RTS Terrain Studio 编辑器窗口拥有键盘焦点（或鼠标位于 Scene 视图上方）；并且你没有在文本或数字字段中输入。不在编辑状态时，R 或数字键等按键保持其在 Unity 中的常规功能。

以下按键和鼠标操作由本包自身处理，无法重新绑定：

以下按键属于 Unity 自带的快捷键和命令。RTS Terrain Studio 会响应它们，但它们遵循你在 Edit ▸ Shortcuts... 中 Unity 类别（Main Menu/Edit、Tools）下设置的绑定：

Select Decor 下的 R 是本包自身的 RTS Terrain Studio/Toggle Random Rotation 条目：当 Select Decor 处于激活状态时，它会切换到 Unity 的 Scale 工具，而不是切换随机旋转。

笔刷

所有笔刷工具共用同一个笔刷。你可以在任意工具页面的 Brush 卡片中、在叠加层中（Size 和 Strength）或通过快捷键来设置它。笔刷设置会在编辑器会话之间保留。

对称

对称功能会在镜像或旋转后的位置重复每个笔印、每次单击和每个放置的对象。制作公平的竞技地图就靠它：每位玩家都能获得相同的山丘、悬崖、坡道、树木和金矿。在 Symmetry 卡片或叠加层中选择模式。Scene 视图中的品红色参考线会显示对称轴和中心。

Centre 是以归一化地图坐标表示的对称中心：(0.5, 0.5) 为地图中心，也是默认值。Reset 会将其移回该位置。如果移动了中心，某些副本可能会落在地图之外并被跳过；卡片会显示警告。

撤销与重做

每次地形编辑都会记录在地图自身的撤销历史中，该历史与 Unity 的撤销系统相关联。Ctrl+Z、Ctrl+Y 和 Edit ▸ Undo 菜单对地形编辑的作用与对其他任何更改完全相同，Edit 菜单还会显示步骤名称，例如 Undo Raise / Lower。窗口顶部的 Undo 和 Redo 按钮作用相同，并会让 Unity 的历史保持同步。在此期间撤销对其他对象的更改不会干扰地形历史。

using RTSTerrainStudio;
using RTSTerrainStudio.Editor;
using UnityEditor;

static class MyTerrainCommands
{
    [MenuItem("Tools/My Project/Raise Whole Map 1 m")]
    static void RaiseWholeMap()
    {
        // The terrain edited by the RTS Terrain Studio window and the Scene View tools.
        RTSTerrain terrain = RTSEditorContext.Terrain;
        if (terrain == null || terrain.Map == null) return;

        RTSEditSession session = RTSEditorContext.Session;

        // Records the Heights layer, runs the code and pushes one undo step named "Raise Whole Map".
        session.RunOperation("Raise Whole Map", MapLayers.Heights, ctx =>
        {
            var heights = ctx.Map.Heights; // fine height per vertex, on top of the cliff level
            for (int i = 0; i < heights.Length; i++)
                heights[i] = TerrainToolUtility.ClampFineHeight(ctx.Map, heights[i] + 1f);

            // Tell the terrain which layers changed so meshes, water and pathing are rebuilt.
            ctx.Terrain.NotifyChangedAll(MapLayers.Heights);
        });
    }
}

工具参考

以下各节逐一介绍八个类别中的所有工具。所有工具在 Unity 编辑器和游戏内编辑器中的用法完全相同。有几条约定对所有工具都适用：

• ID 是工具的唯一标识。可以在代码中使用它，例如 RTSEditorContext.ActivateTool("height.raise")。
• 输入：笔刷工具在拖动时持续绘制。点击工具每次单击执行一次。拖拽工具通过按下、拖动和松开来操作（矩形、框选）。
• 重复频率：按住鼠标按键且不移动时，每秒产生的笔印数。
• 在表格注明的情况下，Shift 用于反转，Ctrl+单击用于拾取。
• 每个设置项都列出了范围和默认值。设置会在编辑器会话之间保留。Settings 选项卡上的 Reset All Tool Settings 可恢复默认值。

using RTSTerrainStudio;

// Appears on the Height tab after the built-in tools (Order 100).
public sealed class StepTool : HeightTool
{
    public override string Id => "mygame.step";
    public override string DisplayName => "Step";
    public override string Description => "Raises the ground under the brush by a fixed step per click.";
    public override string Hint => "Shift: step down";
    public override int Order => 100;

    // One dab per click; keep the brush panel visible for the radius and falloff.
    public override ToolInputMode InputMode => ToolInputMode.Click;
    public override bool UsesBrush => true;

    [ToolSetting("Step", Min = 0.05f, Max = 4f, Order = 0, Tooltip = "Height change per click in metres at full strength.")]
    public float step = 0.5f;

    // Called once per click and once for every symmetry copy.
    public override void ApplyDab(RTSToolContext ctx, in BrushDab dab)
    {
        var map = ctx.Map;
        // Computes the vertex weights and records the Heights layer for undo.
        bool any = BeginVertexEdit(ctx, dab, out var w, out var cells);
        using (w) // the weights must always be disposed
        {
            if (!any) return;
            float sign = dab.invert ? -1f : 1f; // Shift inverts
            var heights = map.Heights;
            for (int z = w.rect.yMin; z < w.rect.yMax; z++)
            for (int x = w.rect.xMin; x < w.rect.xMax; x++)
            {
                float weight = w[x, z];
                if (weight <= 0f) continue;
                int i = map.VertexIndex(x, z);
                heights[i] = TerrainToolUtility.ClampFineHeight(map, heights[i] + sign * step * dab.strength * weight);
            }
        }
        // Rebuilds the chunks, water and pathing of the changed cells.
        EndVertexEdit(ctx, cells);
    }
}

高度工具

高度工具用于雕刻精细高度：在悬崖层级之上塑造丘陵、山谷、道路和自然细节。它们从不改变悬崖层级，因此崖壁始终清晰利落。状态栏会显示光标下的地面高度、精细高度和悬崖层级。

Raise / Lower 设置

Smooth 设置

Flatten 设置

Set Height 设置

Noise 设置

Terrace 设置

Erode 设置

悬崖工具

悬崖工具用于更改顶点的悬崖层级（0–15），以及层级之间崖壁的外观。笔刷会吸附到顶点并作为硬选区生效，因此你绘制的总是完整的顶点，绝不会出现半个层级。状态栏会显示光标所在的层级和即将绘制的层级，例如 Level 2 → 3。

Raise / Lower Level 设置

目标层级取自笔触开始时光标下的顶点：比它高一个层级（按住 Shift 时低一个层级）。拖动时始终绘制同一个层级，因此你可以扩展高地而不会叠加层级。该工具只会升高（或只会降低）顶点。

Set Level 设置

Ramp

Ramp 没有设置项。只有当单元格的四个角点都带有坡道标记，并且该单元格恰好跨越一个层级的高差时，它才会成为坡道。状态栏可以帮你检查：它会统计笔刷下有效的坡道单元格数量，提示带有坡道标记但没有层级差的单元格，并在坡道跨越多个层级时发出警告（此时坡道会被拉伸）。

Cliff Type 设置

Clean Cliffs 设置

自动悬崖边缘

在经典 RTS 地图编辑器中，抬高悬崖时也会同时改变旁边的地面。悬崖工具也会这样做：笔触结束时，每条新悬崖边缘沿线的地面都会用该悬崖类型的边缘地面图层绘制，例如一圈多石的“Rocky Dirt”边沿。边沿沿着圆润的悬崖轮廓分布，在 Edge Width 范围内逐渐淡出，外缘也略带不规则，因此看起来自然，而不是一格一格的方块形状。

1. 选中图块集并打开 Cliff Layers。在每张悬崖卡片上选择一个 Edge Layer（演示图块集使用 Rocky Dirt）。
2. 选择 Raise / Lower Level、Set Level、Ramp 或 Clean Cliffs，并保持 Paint Cliff Edges 处于开启状态。
3. 像平常一样绘制悬崖。松开鼠标按键后，边沿就会出现。

• 一个撤销步骤：层级变化和边缘绘制会一起被撤销。
• 对称：所有对称副本的边缘都会在同一遍处理中一并绘制。
• 坡道：坡道单元格永远不会生成边沿。启用 Clean Up Old Edges 时，横跨边缘绘制坡道会移除该处的边沿。
• 移动过的悬崖：启用 Clean Up Old Edges 后，已消失的边缘（高地被降低或被扩展）上的边沿会随之移除。如果你曾在那里手动绘制过边缘图层，它也会一并被移除。
• 可选：可以为单个工具关闭 Paint Cliff Edges，或将悬崖类型的 Edge Layer 设为 None，从而对整个图块集禁用。如果该选项已开启但未设置边缘图层，状态栏会给出提示。

绘制工具

绘制工具用于绘制图块集中的地面图层（最多 16 个）。每个 Splat 纹素都存储所有图层的权重，这些权重之和始终为 100%。如果所选图层在图块集中不存在或没有纹理，状态栏会给出提示，而不会悄悄地用备用纹理绘制。

Paint Layer 设置

Tile Paint 设置

Fill / Replace 设置

每次单击对应一个撤销步骤，并且只记录实际发生变化的区域。

Smooth Paint 设置

Auto Paint 设置

Paint 选项卡上还会显示 Auto Paint Whole Map 卡片，它可以根据配置文件一步重新绘制整张地图。

植被工具

植被工具使用地形的 Vegetation Library 绘制草和小型植物（细节）并放置树木。如果地形没有植被库，工具页面会提供 Create Vegetation Library。在原型列表中选择原型；如果未选择任何原型，则使用库中的第一个原型。

Paint Details 设置

Erase Details 设置

Place Trees 设置

Erase Trees 设置

装饰物工具

装饰物工具用于放置、擦除和编辑地形 Decor Library 中的场景道具，例如岩石、废墟和围栏。如果地形还没有装饰物库，工具页面会提供 Create Decor Library 按钮。原型列表带有搜索框和类别筛选器。

Place Decor 设置

Erase Decor 设置

Select Decor 设置

Selection 卡片

Select Decor 处于激活状态时，Decor 选项卡会显示 Selection 卡片，其中列出已选对象的数量。每个编辑按钮（Delete、Duplicate、Snap to Ground、Rotate 90°、Lock、Unlock）的操作都对应一个撤销步骤。Select All 和 Clear 只改变选区。

使用手柄移动、旋转和缩放的方法详见装饰物选区手柄。

水体工具

水体按顶点存储：每个顶点要么有水（带有水面高度），要么无水。与悬崖工具一样，水体工具使用硬选区。Water at Cursor 卡片显示鼠标下方的水位和水深，并根据图块集的浅水深度上限，指明该处属于浅水（可行走）还是深水。

水面高度设置（Paint Water 和 Flood Fill）

Paint Water 设置

Flood Fill 设置

通行工具

通行图（可行走、可建造、可飞行、水体）会根据坡度、悬崖、水体、地面图层、树木和装饰物自动推导。通行工具在此基础上绘制手动覆盖，并使用以通行单元格为单位的硬选区。在 Pathing Overlay 卡片上或按 P 开启叠加层，即可查看结果。

Paint Pathing 设置

通行叠加层颜色

自动推导部分所用的规则（最大坡度、悬崖边距等）在 RTS Terrain 组件上设置，参见 Pathing Rules。

标记点工具

标记点工具用于向地图添加游戏玩法信息：玩家出生点、供触发器使用的命名区域，以及摄像机位置等命名点。当标记点工具处于激活状态或 Show Markers 开启时，标记点会显示在 Scene 视图中。

Start Locations 设置

Regions 设置

新区域会自动获得唯一的名称。

Markers 设置

Auto Paint（自动绘制）

Auto Paint 根据地形的形状绘制地面图层：平地铺草，陡坡和悬崖沿线铺岩石，岸边铺沙，再加上被噪声打散的泥土斑块。这是让刚雕刻或生成的地图看起来像成品的最快方法，之后还可以手动细化。

有三种使用方式：

• Paint 选项卡上的 Auto Paint 笔刷工具：在笔刷范围内按规则绘制，并根据笔刷权重和强度与现有的地面涂层混合。按住 Shift 则改为绘制基础图层，从而清除规则绘制的结果；
• Paint 选项卡上的 Auto Paint Whole Map 卡片：重新绘制地图上的所有地面纹素，整个操作为一个撤销步骤。该卡片包含 Profile 字段和 Create Profile 按钮；
• 配置文件的 Inspector 窗口中的 Apply To Map 按钮，以及地图生成器的 Paint 阶段。