NS_unknown_game/game/docs/modules/data_map.md

Data and Map

职责

数据模块负责把外部关卡数据转换成游戏运行时使用的 LevelDefinition。

主要源码：

• game/src/data/level_definition.h
• game/src/data/stage_map_resource.*
• game/src/data/stage_map_loader.*
• game/src/data/whitebox_level.cpp
• game/assets/map/stage_01.map

数据流

stage_01.map
  -> StageMapResource
  -> StageMapLoader
  -> LevelDefinition
  -> WhiteboxScene / StageRenderer / DebugOverlay

读取优先级：

1. Asset 普通文本资源：map/stage_01.map
2. Asset fallback：assets/map/stage_01.map
3. PvfArchive 二进制脚本：map/stage_01.map
4. PvfArchive 文本内容：map/stage_01.map

LevelDefinition

当前包含：

• 世界宽高。
• 玩家出生点。
• 摄像机边界。
• 平台碰撞世界。
• tileset 定义和 tile entry。
• 场景视觉层。
• battle zone。
• enemy spawn point。

.map 当前命令

map <id>
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 已按 asset\Mossy Cavern\参考图\4HibZC.jpg 重做为一比一参考图复刻版：

• 原参考图尺寸为 2432 x 832，等比映射到当前游戏视口高度后，世界尺寸为 2105 x 720。
• BackgroundFar 使用 reference/mossy_cavern_reference_4hibzc.png 作为完整场景底图，保证第一轮视觉尽量贴近参考图。
• 碰撞只按参考图中的左侧、中央、右侧可站平台建立，不把背景洞壁和装饰当碰撞。
• Battle zone 分为 3 段：左侧平台、中央平台、右侧平台。

本轮只接入地图场景视觉，碰撞仍由 collision 独立定义；角色、怪物、植物动画和 hazard 玩法暂不接入。后续若要把底图拆成可编辑素材层，再逐步用 Mossy 图集替换完整参考底图。

下一步

• 继续用地图编辑器调整 Mossy 场景视觉块和碰撞对齐。
• 把 tile_rect 扩展成可表达 tile row/column 或 tile id。
• 增加空 layer、battle zone 无 spawn、tile texture 不存在等更严格错误日志。
• 保留 whitebox_level.cpp 作为 fallback，不再把主地图写死在 C++。