From 3836afe5d97f45e4e48caabe9e8a73fb2fe381c8 Mon Sep 17 00:00:00 2001
From: unanmed <1319491857@qq.com>
Date: Sat, 17 Oct 2026 21:23:14 +0800
Subject: [PATCH] =?UTF-8?q?docs(10-10):=20=E5=BC=95=E5=AF=BC=E5=BC=8F?=
 =?UTF-8?q?=E9=87=8D=E5=86=99=20hero-location=E3=80=81map-structure?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/intermediate/hero-location.md | 6 ++++--
 docs/intermediate/map-structure.md | 8 ++++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/intermediate/hero-location.md b/docs/intermediate/hero-location.md
index 07fb84a..baaee2f 100644
--- a/docs/intermediate/hero-location.md
+++ b/docs/intermediate/hero-location.md
@@ -1,9 +1,11 @@
 # 勇士位置
 
-勇士位置（`state.hero.location`）记录当前坐标、朝向与所在楼层。本篇只讲如何**获取**这些信息。
+很多逻辑都要先知道一件事：勇士此刻站在哪一层、哪一格、朝哪个方向。比如「进门前朝向对不对」「这只怪离勇士多远」「当前在哪一层」。勇士位置（`state.hero.location`）记录的就是这些信息。本篇只讲如何**获取**它们；如何移动、如何切换楼层属于更底层的内容，留到高级教程。
 
 ## 当前坐标
 
+勇士站在哪一格，读 `x`、`y` 即可：
+
 ```ts
 const x = state.hero.location.x;
 const y = state.hero.location.y;
@@ -19,7 +21,7 @@ const y = state.hero.location.y;
 const dir = state.hero.location.getCurrentFaceDirection();
 ```
 
-`state.hero.getLocation()` 会返回一个包含 `x`、`y`、`direction` 的位置对象（`IFacedTileLocator`），适合一次性取走当前坐标与朝向：
+如果坐标和朝向要一起用，`state.hero.getLocation()` 会返回一个包含 `x`、`y`、`direction` 的位置对象（`IFacedTileLocator`），一次取走更省事：
 
 ```ts
 const loc = state.hero.getLocation();
diff --git a/docs/intermediate/map-structure.md b/docs/intermediate/map-structure.md
index 0427162..c8cf6cb 100644
--- a/docs/intermediate/map-structure.md
+++ b/docs/intermediate/map-structure.md
@@ -1,6 +1,10 @@
 # 地图结构
 
-地图在数据端分成三层：**楼层集合**（`state.maps`）、**楼层**（`IGameMap`）与**图层**（`IMapLayer`）。本篇说明这三层的关系与常用接口。
+地图并不是一张铺开的大图，而是分层的。要从代码里找到「某一层的某一块图块」，得先顺着它的层次往下走。地图在数据端分成三层：**楼层集合**（`state.maps`）、**楼层**（`IGameMap`）与**图层**（`IMapLayer`）。本篇说明这三层的关系与常用接口。
+
+## 三层结构
+
+可以把三层想成一棵树：`state.maps` 是「所有楼层的总目录」，里面每个条目是一个楼层；每个楼层里又有一组图层，图块就摆在图层上。日常查地图，大多是从第一层往下逐级找。
 
 ## 楼层集合（IMapState）
 
@@ -22,7 +26,7 @@ for (const [id, map] of state.maps.iterateAllMaps()) {
 
 ## 楼层激活（active）
 
-每个楼层（`IGameMap`）都有 `active` 表示是否激活。**只有已激活的楼层才会进入存档**——`IMapState` 的存档仅包含已激活楼层。`getActiveMap(id)` 只返回已激活的楼层，迭代可用 `iterateActiveMaps()` / `iterateInactiveMaps()`。
+每个楼层（`IGameMap`）都有 `active` 表示是否激活。**只有已激活的楼层才会进入存档**——`IMapState` 的存档仅包含已激活楼层。因此如果一处楼层改动要跟着存档走，记得先把它激活。`getActiveMap(id)` 只返回已激活的楼层，迭代可用 `iterateActiveMaps()` / `iterateInactiveMaps()`。
 
 ```ts
 state.maps.setMapActiveStatus('floor-1', true);