Add stage map tile rendering path

game/docs/modules/data_map.md

@@ -37,6 +37,7 @@ stage_01.map
 - 玩家出生点。
 - 摄像机边界。
 - 平台碰撞世界。
+- tileset 定义和 tile entry。
 - 场景视觉层。
 - battle zone。
 - enemy spawn point。
@@ -49,18 +50,32 @@ world <width> <height>
 camera <x> <y> <width> <height>
 player_spawn <x> <y>
 collision <x> <y> <width> <height>
+tileset <id> <texture> <tile_w> <tile_h> <r> <g> <b> <a>
 layer <id> <BackgroundFar|BackgroundMid|LevelVisual|PropsBack|PropsFront> <parallax>
 rect <x> <y> <width> <height> <r> <g> <b> <a>
 rect_sprite <x> <y> <width> <height> <r> <g> <b> <a> <texture>
 rect_sprite_src <x> <y> <width> <height> <r> <g> <b> <a> <texture> <sx> <sy> <sw> <sh>
+tile_rect <tileset> <x> <y> <columns> <rows> <tile_index> <r> <g> <b>
 endlayer
 battle_zone <id> <trigger_x> <trigger_y> <trigger_w> <trigger_h> <camera_x> <camera_y> <camera_w> <camera_h>
 spawn <id> <x> <y>
 endbattle_zone
 ```
 
+## Tile 约定
+
+`tileset` 定义 tile 图片来源、单格尺寸和 fallback 色。图片不存在时，`StageRenderer` 会按 tile fallback 色绘制，不阻断场景启动。
+
+`tile_rect` 只能写在 `layer` 内，用于批量铺同一种 tile：
+
+- `columns` / `rows` 是重复格数。
+- `tile_index` 当前表示 tileset 第一行的横向 tile 序号。
+- `r g b` 是该批 tile 的灰盒 fallback 色，alpha 固定为 `1.0`。
+
+当前 `stage_01.map` 已把 `level_visual` 地面和平台从长色块替换为 `tile_rect`，碰撞仍由 `collision` 独立定义。
+
 ## 下一步
 
-- 给 `.map` 增加 tileset/tile entry。
-- 增加重复 block、空 layer、battle zone 无 spawn、tile 引用不存在等错误日志。
+- 把 `tile_rect` 扩展成可表达 tile row/column 或 tile id。
+- 增加空 layer、battle zone 无 spawn、tile texture 不存在等更严格错误日志。
 - 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。

game/docs/modules/stage_rendering.md

@@ -31,6 +31,8 @@ UI
 - 支持色块占位。
 - 支持普通 PNG texture path。
 - 支持 source rect。
+- 支持 `.map` tile entry 绘制。
+- 支持 tileset 图片缺失时按 tile fallback 色绘制。
 - 资源缺失时回退色块，不阻断场景运行。
 
 ## 约束
@@ -41,6 +43,6 @@ UI
 
 ## 下一步
 
-- 增加 tile entry 绘制路径。
-- 把 `level_visual` 长色块逐步替换为 tile。
+- 给 tile entry 增加 tile id 或二维 source index。
+- 把正式 tileset 素材接入 `stage_01.map`。
 - 如果引擎提供统一 Texture cache，再迁移当前局部贴图缓存。

game/docs/planning/scene_build_plan.md

@@ -286,11 +286,21 @@ game/assets/stage/stage_01/
 
 继续沿着“优先使用引擎能力”的方向，把地图从色块灰盒推进到可放素材的完整骨架。当前不进入敌人和战斗玩法，下一轮只处理地图视觉表达：
 
-1. 给 `.map` 增加 tileset/tile entry 约定，先不做编辑器，只保证工具或手写数据能表达重复地砖。
-2. 在 `StageRenderer` 中增加 tile 绘制路径，复用当前 `Texture` 加载和 source rect 支持。
-3. 把 `level_visual` 的长色块逐步替换成 tile entries，碰撞仍独立保留在 `collision`。
-4. 给 map loader 增加更严格的错误日志，例如重复 block、空 layer、battle zone 无 spawn、tile 引用不存在的提示。
-5. 补一个轻量 map 验收流程：启动时日志确认加载 `.map`，Windows/Switch 产物确认存在 `assets/map/stage_01.map` 和全局素材槽位。
+1. 已完成：给 `.map` 增加 `tileset` / `tile_rect` 约定，先不做编辑器，保证手写数据能表达重复地砖。
+2. 已完成：在 `StageRenderer` 中增加 tile 绘制路径，复用当前 `Texture` 加载和 source rect 支持。
+3. 已完成：把 `level_visual` 的长色块替换成 tile entries，碰撞仍独立保留在 `collision`。
+4. 已完成：给 map loader 增加重复 tileset、未知 tileset、非法 tile rect 等错误日志。
+5. 已完成：补轻量 map 验收流程：启动时日志确认加载 `.map`，Windows/Switch 产物确认存在 `assets/map/stage_01.map` 和全局素材槽位。
+
+### 下一轮建议任务
+
+继续围绕地图视觉骨架，不进入战斗玩法：
+
+1. 给 `tile_rect` 增加二维 source index 或 tile id，避免只支持 tileset 第一行。
+2. 按正式素材规格整理 `stage_01_tileset.png` 的格子约定。
+3. 用一个临时 tileset PNG 替换当前 fallback 色块，验证 source rect 对齐。
+4. 增加 tile texture 缺失的日志去重，避免大量 tile 重复报同一个资源。
+5. 手动跑图确认所有平台视觉和碰撞误差不超过 4 像素。
 
 ### Debug 快捷键
 

game/docs/scene_acceptance.md

@@ -14,6 +14,7 @@
 - Battle zones：`zone_01_intro`、`zone_02_platform`、`zone_03_exit`
 - 资源槽位：`game/assets/stage/stage_01/`
 - 地图资源：`game/assets/map/stage_01.map`
+- Tile 数据：`stage_01.map` 中的 `tileset` / `tile_rect`
 - 全局资源槽位：`game/assets/ASSETS.md`
 - UI overlay：`GameUiOverlay`，有字体时使用 `TextSprite`，无字体时使用 fallback 色条。
 - 音频 cue：`stage_01`、`player_jump`、`player_attack`、`battle_zone_enter`。
@@ -91,6 +92,7 @@ Test-Path build\switch\aarch64\release\switch_game\romfs\assets\fonts
 - Switch `Frostbite2DGameSwitch` 构建：通过。
 - Switch RomFS：已包含 character、shader、`stage_01` 资源槽位和 `assets/map/stage_01.map`。
 - 地图加载：`stage_01.map` 已作为第一关主数据源；C++ 白盒数据仅作为 fallback。
+- 地图 tile 化：`level_visual` 已由 `tileset` / `tile_rect` 表达；tileset 图片缺失时使用 fallback 色绘制。
 - 引擎能力接入：`Animation`/NPK/PNG 角色资源优先级、`UIScene`/`TextSprite` UI、`Sound`/`Music` cue、`SaveSystem` debug 存档已接入。
 - 手动跑图：未在本轮执行，等待后续素材/战斗区域进一步接入时复测。