From c87b245ceaa4b1258280876e574756a4253ec3b7 Mon Sep 17 00:00:00 2001
From: 1165565692-lang <1165565692@qq.com>
Date: Tue, 9 Jun 2026 01:02:36 +0800
Subject: [PATCH] Organize game planning docs

---
 game/docs/ARCHITECTURE.md                     | 149 ------------------
 game/docs/README.md                           |  14 ++
 .../game_architecture_board.md}               |   0
 .../scene_build_plan.md}                      |   0
 4 files changed, 14 insertions(+), 149 deletions(-)
 delete mode 100644 game/docs/ARCHITECTURE.md
 create mode 100644 game/docs/README.md
 rename game/docs/{GAME_ARCHITECTURE_BOARD.md => planning/game_architecture_board.md} (100%)
 rename game/docs/{SCENE_BUILD_PLAN.md => planning/scene_build_plan.md} (100%)

diff --git a/game/docs/ARCHITECTURE.md b/game/docs/ARCHITECTURE.md
deleted file mode 100644
index f48c864..0000000
--- a/game/docs/ARCHITECTURE.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# 游戏架构
-
-该项目将游戏层与 Frostbite2D 引擎分离开来。引擎保留在 `Frostbite2D/`
-目录下；游戏特定代码位于 `game/` 目录下。
-
-## 目录结构
-
-```text
-game/
-├─ assets/
-│  ├─ character/        运行时角色精灵图
-│  └─ shaders/          游戏目标使用的运行时着色器
-├─ docs/
-│  └─ ARCHITECTURE.md   本文档
-└─ src/
-   ├─ actor/            游戏角色，如玩家、敌人、抛射物
-   ├─ combat/           碰撞箱、伤害判定和战斗解算类型
-   ├─ core/             共享配置、输入快照和资源路径
-   ├─ data/             关卡和游戏数据定义
-   ├─ debug/            调试可视化叠层
-   ├─ movement/         可复用的移动和碰撞辅助工具
-   ├─ scene/            游戏场景和关卡编排
-   ├─ stage/            关卡视觉层渲染
-   └─ main.cpp          游戏可执行文件入口点
-```
-
-## 运行时流程
-
-```text
-main.cpp
-  -> Application::init()
-  -> SceneManager::ReplaceScene(WhiteboxScene)
-  -> WhiteboxScene::onEnter()
-      -> CreateWhiteboxLevel()
-      -> 创建 PlayerActor
-      -> 将 PlatformWorld 传递给 PlayerActor
-  -> 每一帧：
-      -> PlayerActor 采样 InputState
-      -> PlayerActor 通过 PlatformMover 移动
-      -> PlayerActor 更新动画
-      -> WhiteboxScene 更新摄像机
-      -> StageRenderer 绘制关卡视觉层
-      -> Actor 渲染
-      -> DebugOverlay 绘制调试叠层
-```
-
-## 模块职责
-
-`core`
-
-- `game_config.h` 存储共享的调整常数，如虚拟分辨率、
-  重力、玩家速度和攻击持续时间
-- `asset_paths.h` 存储稳定的运行时资源路径
-- `debug_flags.h` 集中控制开发期调试显示开关
-- `input_state.*` 将原始 SDL 键盘状态转换为与引擎无关的
-  `InputState` 快照。玩家逻辑使用此快照而不是直接读取
-  SDL
-
-`movement`
-
-- `PlatformWorld` 拥有关卡边界和平台矩形
-- `MovementBody` 是可复用的位置/尺寸/速度容器
-- `PlatformMover` 应用重力、限制水平边界并解算基本的
-  顶面平台着陆
-
-`data`
-
-- `LevelDefinition` 组合碰撞和白盒道具
-- `CreateWhiteboxLevel()` 当前返回第一个硬编码的阻挡关卡。
-  稍后可以替换为 JSON、Tiled、LDtk 或自定义编辑器导出，
-  而无需更改 `PlayerActor`
-
-`actor`
-
-- `PlayerActor` 拥有玩家精灵、玩家状态和动画
-- 它依赖于 `InputStateProvider` 和 `PlatformMover`，因此输入和移动
-  可以被敌人复用或独立更改
-
-`scene`
-
-- `WhiteboxScene` 编排当前关卡：加载关卡数据、创建
-  角色、委托关卡渲染、委托调试叠层并控制摄像机
-
-`stage`
-
-- `StageRenderer` 绘制当前关卡视觉层，包括背景、网格、白盒道具和平台
-- 后续 tileset、视差背景和 props 渲染都应该优先接入该模块
-
-`debug`
-
-- `DebugOverlay` 绘制碰撞矩形和玩家包围盒
-- `DebugFlags` 决定哪些调试层启用
-
-`combat`
-
-- `hitbox.h` 定义早期的 `Hitbox` 和 `Hurtbox` 结构体及团队过滤。
-  完整的 ACT 战斗应该建立在此基础上，而不是在
-  角色中嵌入打击判定
-
-## 当前构建目标
-
-`xmake.lua` 为 Windows 定义 `Frostbite2DGame`。它编译桌面游戏入口
-`game/src/main.cpp` 和所有通用游戏源码，链接到 `Frostbite2D`，并在构建后
-将 `game/assets` 复制到可执行文件旁边。
-
-构建命令：
-
-```powershell
-xmake -b Frostbite2DGame
-```
-
-输出：
-
-```text
-build/windows/x64/release/Frostbite2DGame.exe
-```
-
-Switch/NS 游戏框架目标为 `Frostbite2DGameSwitch`。它复用
-`game/src/main.cpp`，入口内部通过 `__SWITCH__` 编译分支处理平台差异，
-并复用同一套 Scene、Stage、Actor、Movement、Debug 和 Data 模块。
-
-构建命令：
-
-```powershell
-xmake -b Frostbite2DGameSwitch
-```
-
-输出：
-
-```text
-build/switch/aarch64/release/Frostbite2DGame.elf
-build/switch/aarch64/release/switch_game/NSUnknownGame.nro
-```
-
-Switch 运行时资源目录优先使用内嵌 RomFS：
-
-```text
-romfs:/assets
-```
-
-## 后续架构步骤
-
-1. 添加 `actor/enemy_actor.*` 并复用 `PlatformMover`
-2. 添加 `combat/CombatSystem` 来收集每一帧的活跃碰撞箱和伤害判定箱、
-   解算打击并发出伤害事件
-3. 用数据定义替换 `PlayerActor` 中的硬编码动画时序
-4. 当第一个白盒循环稳定后，将 `CreateWhiteboxLevel()` 迁移到外部关卡格式
-5. 如果多个关卡共享生成、摄像机、
-   战斗和暂停逻辑，则添加 `scene/gameplay_scene` 基类
diff --git a/game/docs/README.md b/game/docs/README.md
new file mode 100644
index 0000000..65cc54f
--- /dev/null
+++ b/game/docs/README.md
@@ -0,0 +1,14 @@
+# Game Docs
+
+本文档目录只放游戏层相关文档；引擎、构建和仓库级说明仍保留在项目根目录。
+
+## Planning
+
+- `planning/game_architecture_board.md`：游戏整体架构白板，包含思维导图、模块划分、数据流和阶段路线。
+- `planning/scene_build_plan.md`：第一关场景搭建计划，包含素材清单、场景分层和验收标准。
+
+## Naming
+
+- 文件名使用小写 `snake_case`。
+- 长期有效的计划放入 `planning/`。
+- 临时调研、实验记录后续单独放入 `research/` 或 `notes/`，避免混在根目录。
diff --git a/game/docs/GAME_ARCHITECTURE_BOARD.md b/game/docs/planning/game_architecture_board.md
similarity index 100%
rename from game/docs/GAME_ARCHITECTURE_BOARD.md
rename to game/docs/planning/game_architecture_board.md
diff --git a/game/docs/SCENE_BUILD_PLAN.md b/game/docs/planning/scene_build_plan.md
similarity index 100%
rename from game/docs/SCENE_BUILD_PLAN.md
rename to game/docs/planning/scene_build_plan.md