> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/docs-zh/shi-yong-bian-ji-qi/tilemap.md).

# 图块地图

瓦片地图系统让你使用自动铺砖遮罩、多层以及带内置碰撞生成的墙体挤出，来绘制基于瓦片的世界。

## 添加瓦片地图

添加一个 `Tilemap_Component` 到任何实体上。瓦片地图以实体的位置为中心，并跨越一个由多个区块组成的网格（每个区块为 32×32 个瓦片）。瓦片总尺寸为 `width_in_chunks × 32` 乘以 `height_in_chunks × 32`.

## 瓦片地图属性

| 属性            | 描述                                                     |
| ------------- | ------------------------------------------------------ |
| **区块宽度 / 高度** | 瓦片网格的大小。每个区块为 32×32 个瓦片。一个 10×10 的瓦片地图会得到 320×320 个瓦片。 |

进入编辑模式后，图层会单独配置（见下文）。

## 运行时脚本

`Tilemap_Component` 暴露了编辑器所使用的相同持久化图层数据。图层按从零开始的索引寻址。移除图层会使之后的每个索引向下移动一位，因此除非你更新索引，否则不要在移除图层后继续保留该索引。

### CSL

```csl
tilemap := entity.get_component(Tilemap_Component);
ground := tilemap.add_layer(.GROUND);
tilemap.set_layer_tile_size(ground, 1.5);
tilemap.set_layer_tint(ground, v4{0.8, 0.9, 1, 1});
tilemap.add_layer_texture(ground, get_asset(Texture_Asset, "tiles/grass.png"), 1);
tilemap.set_layer_mask(ground, get_asset(Texture_Asset, "$AO/tile_mask.png"));
tilemap.set_tile(ground, 10, 12);

world_position := tilemap.tile_to_world(ground, 10, 12);
tile_x, tile_y := tilemap.world_to_tile(ground, world_position);
```

CSL 瓦片地图变更属于普通场景状态。它们会像其他 CSL 游戏玩法状态一样参与预测、回滚和服务器校正。

### C\#

```csharp
Tilemap_Component tilemap = Entity.GetComponent<Tilemap_Component>();
int ground = tilemap.AddLayer(TilemapLayerKind.Ground);
tilemap.SetLayerTileSize(ground, 1.5f);
tilemap.SetLayerTint(ground, new Vector4(0.8f, 0.9f, 1.0f, 1.0f));
tilemap.AddLayerTexture(ground, Assets.GetAsset<Texture>("tiles/grass.png"));
tilemap.SetLayerMask(ground, Assets.GetAsset<Texture>("$AO/tile_mask.png"));
tilemap.SetTile(ground, 10, 12);

Vector2 worldPosition = tilemap.TileToWorld(ground, 10, 12);
tilemap.WorldToTile(ground, worldPosition, out int tileX, out int tileY);
```

C# 调用只会修改当前模拟。对于多人运行时变更，请使用游戏现有的 RPC 流程在每个对等端上触发相同的变更；瓦片地图 API 不会创建新的复制通道。

运行时 API 包括：

* `大小调整`、区块/瓦片尺寸，以及基于图层的本地/世界坐标转换。
* 图层添加、移除、清空、种类、渲染模式/顺序、瓦片大小、色调、遮罩、轮廓、墙体设置和碰撞设置。
* 加权纹理的添加、替换、重新加权、移除和查找。
* 单个瓦片的查询、设置和清除操作。

瓦片地图至少为 2×2 个区块。调整大小会保留地图中心，将现有瓦片坐标按尺寸差的一半平移，并裁剪新边界之外的瓦片。越界的瓦片写入不会生效，查询会返回 false。纹理权重必须为非负数，并且每个图层最多支持 256 张纹理。

无效的图层或纹理索引以及无效的图层设置会在脚本边界处被拒绝。C# 会抛出 `ArgumentOutOfRangeException` （或 `ArgumentException` ，用于纹理数量限制），而 CSL 会报告一个包含无效值和有效范围的脚本错误。

图层色调会乘算整个图层，包括轮廓和墙顶。色调更改会作为渲染统一变量应用，不会重新烘焙瓦片或重建碰撞。在瓦片地图下一次更新之前进行的多次瓦片和碰撞更改会合并为一次几何体/碰撞重建。

## 编辑模式

选择瓦片地图实体并点击检查器中的 **编辑** 按钮以进入瓦片地图编辑模式。点击 **取消** 退出。如果你取消选择该实体，编辑模式会自动停用。

编辑时，瓦片地图边界会以红色边框标出，并在场景视图中绘制网格叠加层。

## 工具

瓦片地图编辑器有三种工具模式，可通过快捷键切换：

| 工具      | 快捷键   | 描述                      |
| ------- | ----- | ----------------------- |
| **画笔**  | `B/W` | 通过单击并拖动来绘制瓦片。           |
| **橡皮擦** | `E`   | 通过单击并拖动来移除瓦片。           |
| **印章**  | `S/R` | 选择一个区域进行复制，然后将其粘贴到其他位置。 |

你也可以 **按住 Shift** 在画笔模式下临时擦除。

## 画笔绘制

单击并拖动即可在所选图层上绘制瓦片。画笔在帧与帧之间使用 Bresenham 直线插值，因此即使快速移动也不会漏掉瓦片。

**画笔大小** 可通过 `[` 和 `]` 进行调整（范围 1–32）。画笔是圆形的——半径内的瓦片都会受到影响。

**Alt+单击** 会从上一次单击位置到当前瓦片绘制一条直线，适合长直边。

**Ctrl+拖动** 会切换到矩形填充模式——拖动以定义一个矩形，松开时区域内所有瓦片都会被填充（如果同时按住 Shift，则会被擦除）。

## 图层

每个瓦片地图都支持多个图层。单击检查器中的某个图层即可选中它进行绘制。被选中的图层会以蓝色高亮显示。

### 添加和移除图层

* 点击 **添加图层** 底部可创建新图层。
* 点击 **移除图层** 在某个图层面板内删除它。

### 图层属性

| 属性       | 描述                                                                     |
| -------- | ---------------------------------------------------------------------- |
| **种类**   | `地面` 或 `墙体`。地面瓦片是平的；墙体瓦片会垂直挤出。                                         |
| **图层模式** | `默认` 使用自动图层（地面在玩家后方，墙体按 Y 轴排序）。 `手动` 允许你设置固定的渲染图层值。                    |
| **手动图层** | 仅在手动模式下显示。显式的渲染图层值。                                                    |
| **瓦片大小** | 每个瓦片在世界单位中的视觉大小。                                                       |
| **色调**   | 整个图层的颜色乘数，包括墙顶和轮廓。                                                     |
| **纹理**   | 一个或多个带权重的纹理，用于随机变化。引擎会对瓦片坐标进行哈希处理，并根据权重确定性地为每个瓦片选择一种纹理。                |
| **遮罩**   | 用于自动铺砖的 8×8 网格纹理。每个格子对应不同的邻接配置（边缘、角落、孤立等）。包含一个默认地图 `$AO/tile_mask.png` |
| **轮廓**   | 瓦片轮廓的颜色（alpha = 0 表示没有轮廓）。                                             |

### 多纹理变化

每个图层都可以有多个带权重的纹理。瓦片会基于其网格坐标的哈希确定性地选择一个纹理变体，因此这种图案在保存之间是稳定的，且在添加/移除瓦片时不会偏移。

调整 **权重** 数值即可控制其相对于其他纹理的出现频率。

## 自动铺砖

瓦片会根据其 8 向邻居配置自动选择正确的遮罩格子。该系统：

1. 检查全部 8 个邻居（北、东北、东、东南、南、西南、西、西北）。
2. 只有在两个相邻的正交邻居都存在时，对角邻居才计入（可防止角落处出现视觉伪影）。
3. 将得到的 8 位邻接遮罩映射到 8×8 遮罩纹理中的 64 个格子之一。

这意味着你只需要绘制瓦片存在与否——正确的边缘、角落和内部视觉效果会自动计算出来。

## 墙体图层

将某个图层的种类设置为 **墙体** 即可启用垂直挤出。墙体瓦片像地面瓦片一样放置在网格上，但每个放置的瓦片都会生成一列向上延伸 **墙高**.

### 墙体属性

| 属性       | 描述                            |
| -------- | ----------------------------- |
| **墙高**   | 每列墙体的高度（最小为 2 个瓦片）。           |
| **顶部纹理** | 墙顶（“帽檐”）使用的单独纹理。              |
| **顶部遮罩** | 墙顶使用的遮罩纹理（与地面使用相同的 8 邻居自动铺砖）。 |
| **顶部轮廓** | 墙顶瓦片的轮廓颜色。                    |

墙体主体使用图层的主纹理。墙顶使用底部行的邻居，这样能保持帽檐边缘干净。

墙体按其底部行进行 Y 轴排序，因此玩家会走在其上方墙体的后面，以及其下方墙体的前面。

### 墙体碰撞

| 属性       | 描述                          |
| -------- | --------------------------- |
| **碰撞**   | 为 navmesh 重建生成障碍边缘。         |
| **内缩**   | 将碰撞边缘从瓦片边界向内收缩，以获得更紧密贴合的碰撞。 |
| **偏移**   | 将所有碰撞边缘按固定量移动。              |
| **调试绘制** | 在场景视图中绘制绿色碰撞边缘以便调试。         |

启用碰撞后，引擎会从暴露的瓦片边界构建障碍边缘。启用了自动重建的 navmesh 会使用这些边缘。

## 印章工具（复制与粘贴）

按 `S` 切换到印章模式。这会启用一个区域选择流程：

1. **选择**：单击并拖动以高亮一个矩形区域。选中的瓦片会被复制到剪贴板。弹出的“已复制”提示会确认该操作。
2. **粘贴**：按 `Ctrl+V` 进入幽灵模式。剪贴板的半透明预览会跟随你的光标。
3. **旋转**：滚动鼠标滚轮可按 90 度增量旋转幽灵预览。
4. **放置**：单击即可印上这些瓦片。单击时按住 Shift 可在不退出幽灵模式的情况下放置多个副本。
5. **取消**：按 `Esc` 以在不放置的情况下退出幽灵模式。

按住 **Ctrl** 在开始印章选择时，可从 **所有图层** 同时复制，保留多图层结构。

## 键盘快捷键摘要

| 快捷键          | 操作                 |
| ------------ | ------------------ |
| `B` 或 `W`    | 切换到画笔工具            |
| `E`          | 切换到橡皮擦工具           |
| `S` 或 `R`    | 切换到印章工具            |
| `Shift` （按住） | 在画笔模式下临时擦除         |
| `[` / `]`    | 减小 / 增大画笔大小        |
| `Ctrl+拖动`    | 使用当前画笔或橡皮擦工具进行矩形填充 |
| `Alt+单击`     | 从上一次单击开始绘制直线       |
| `Ctrl+V`     | 进入粘贴/幽灵模式          |
| `鼠标滚轮`       | 旋转幽灵预览（在幽灵模式中）     |
| `Shift+单击`   | 放置多个副本（在幽灵模式中）     |
| `Esc`        | 取消幽灵模式             |