# 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`

## 数据流

```text
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`

当前包含：

- 世界宽高。
- 玩家出生点。
- 摄像机边界。
- 平台碰撞世界。
- 场景视觉层。
- battle zone。
- enemy spawn point。

## `.map` 当前命令

```text
map <id>
world <width> <height>
camera <x> <y> <width> <height>
player_spawn <x> <y>
collision <x> <y> <width> <height>
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>
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
```

## 下一步

- 给 `.map` 增加 tileset/tile entry。
- 增加重复 block、空 layer、battle zone 无 spawn、tile 引用不存在等错误日志。
- 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。