92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
# 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`
|
||
|
||
当前包含：
|
||
|
||
- 世界宽高。
|
||
- 玩家出生点。
|
||
- 摄像机边界。
|
||
- 平台碰撞世界。
|
||
- tileset 定义和 tile entry。
|
||
- 场景视觉层。
|
||
- 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>
|
||
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` 已接入 Mossy Cavern 场景图集：
|
||
|
||
- 世界尺寸为 `6400 x 720`，当前按现有摄像机逻辑保持 720 高度，主要扩展横向探索长度。
|
||
- `BackgroundFar` 使用 `mossy_background_decoration.png` 做远景洞穴轮廓。
|
||
- `BackgroundMid` 使用 `mossy_hills.png` 做中景苔藓轮廓。
|
||
- `LevelVisual` 使用 `mossy_floating_platforms.png` 做地面和悬空平台。
|
||
- `PropsBack` / `PropsFront` 使用苔藓悬挂植物、发光装饰和前景暗部遮挡。
|
||
- Battle zone 已扩展为 5 段：入口、下沉洞道、主洞厅、高低平台群和出口段。
|
||
|
||
本轮只接入地图场景视觉，碰撞仍由 `collision` 独立定义；角色、怪物、植物动画和 hazard 玩法暂不接入。
|
||
|
||
## 下一步
|
||
|
||
- 继续用地图编辑器调整 Mossy 场景视觉块和碰撞对齐。
|
||
- 把 `tile_rect` 扩展成可表达 tile row/column 或 tile id。
|
||
- 增加空 layer、battle zone 无 spawn、tile texture 不存在等更严格错误日志。
|
||
- 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。
|