From ce815ed58b12fea0eaa1391bc65e831229b6825e Mon Sep 17 00:00:00 2001 From: 1165565692-lang <1165565692@qq.com> Date: Tue, 9 Jun 2026 00:29:23 +0800 Subject: [PATCH] Localize game architecture documentation --- game/docs/ARCHITECTURE.md | 121 +++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 61 deletions(-) diff --git a/game/docs/ARCHITECTURE.md b/game/docs/ARCHITECTURE.md index 575ddd6..b3d9a3c 100644 --- a/game/docs/ARCHITECTURE.md +++ b/game/docs/ARCHITECTURE.md @@ -1,28 +1,28 @@ -# Game Architecture +# 游戏架构 -This project keeps the game layer separate from the Frostbite2D engine. The -engine remains in `Frostbite2D/`; game-specific code lives under `game/`. +该项目将游戏层与 Frostbite2D 引擎分离开来。引擎保留在 `Frostbite2D/` +目录下；游戏特定代码位于 `game/` 目录下。 -## Directory Layout +## 目录结构 ```text game/ ├─ assets/ -│ ├─ character/ Runtime character spritesheets. -│ └─ shaders/ Runtime shaders used by the game target. +│ ├─ character/ 运行时角色精灵图 +│ └─ shaders/ 游戏目标使用的运行时着色器 ├─ docs/ -│ └─ ARCHITECTURE.md This document. +│ └─ ARCHITECTURE.md 本文档 └─ src/ - ├─ actor/ Game actors such as player, enemy, projectile. - ├─ combat/ Hitbox, hurtbox, damage and combat resolution types. - ├─ core/ Shared config, input snapshots and asset paths. - ├─ data/ Level and gameplay data definitions. - ├─ movement/ Reusable movement and collision helpers. - ├─ scene/ Game scenes and level orchestration. - └─ main.cpp Game executable entry point. + ├─ actor/ 游戏角色，如玩家、敌人、抛射物 + ├─ combat/ 碰撞箱、伤害判定和战斗解算类型 + ├─ core/ 共享配置、输入快照和资源路径 + ├─ data/ 关卡和游戏数据定义 + ├─ movement/ 可复用的移动和碰撞辅助工具 + ├─ scene/ 游戏场景和关卡编排 + └─ main.cpp 游戏可执行文件入口点 ``` -## Runtime Flow +## 运行时流程 ```text main.cpp @@ -30,83 +30,82 @@ main.cpp -> SceneManager::ReplaceScene(WhiteboxScene) -> WhiteboxScene::onEnter() -> CreateWhiteboxLevel() - -> create PlayerActor - -> pass PlatformWorld to PlayerActor - -> every frame: - -> PlayerActor samples InputState - -> PlayerActor moves through PlatformMover - -> PlayerActor updates animation - -> WhiteboxScene updates camera - -> WhiteboxScene draws whitebox level + -> 创建 PlayerActor + -> 将 PlatformWorld 传递给 PlayerActor + -> 每一帧： + -> PlayerActor 采样 InputState + -> PlayerActor 通过 PlatformMover 移动 + -> PlayerActor 更新动画 + -> WhiteboxScene 更新摄像机 + -> WhiteboxScene 绘制白盒关卡 ``` -## Module Responsibilities +## 模块职责 `core` -- `game_config.h` stores shared tuning constants such as virtual resolution, - gravity, player speed and attack duration. -- `asset_paths.h` stores stable runtime asset paths. -- `input_state.*` converts raw SDL keyboard state into an engine-independent - `InputState` snapshot. Player logic consumes this snapshot instead of reading - SDL directly. +- `game_config.h` 存储共享的调整常数，如虚拟分辨率、 + 重力、玩家速度和攻击持续时间 +- `asset_paths.h` 存储稳定的运行时资源路径 +- `input_state.*` 将原始 SDL 键盘状态转换为与引擎无关的 + `InputState` 快照。玩家逻辑使用此快照而不是直接读取 + SDL `movement` -- `PlatformWorld` owns level boundaries and platform rectangles. -- `MovementBody` is a reusable position/size/velocity container. -- `PlatformMover` applies gravity, clamps horizontal bounds and resolves basic - top-side platform landing. +- `PlatformWorld` 拥有关卡边界和平台矩形 +- `MovementBody` 是可复用的位置/尺寸/速度容器 +- `PlatformMover` 应用重力、限制水平边界并解算基本的 + 顶面平台着陆 `data` -- `LevelDefinition` groups collision and whitebox props. -- `CreateWhiteboxLevel()` currently returns the first hard-coded blockout level. - Later this can be replaced by JSON, Tiled, LDtk, or a custom editor export - without changing `PlayerActor`. +- `LevelDefinition` 组合碰撞和白盒道具 +- `CreateWhiteboxLevel()` 当前返回第一个硬编码的阻挡关卡。 + 稍后可以替换为 JSON、Tiled、LDtk 或自定义编辑器导出， + 而无需更改 `PlayerActor` `actor` -- `PlayerActor` owns player sprites, player state and animation. -- It depends on `InputStateProvider` and `PlatformMover`, so input and movement - can be reused for enemies or changed independently. +- `PlayerActor` 拥有玩家精灵、玩家状态和动画 +- 它依赖于 `InputStateProvider` 和 `PlatformMover`，因此输入和移动 + 可以被敌人复用或独立更改 `scene` -- `WhiteboxScene` orchestrates the current level: it loads level data, creates - actors, draws whitebox geometry and controls the camera. +- `WhiteboxScene` 编排当前关卡：加载关卡数据、创建 + 角色、绘制白盒几何和控制摄像机 `combat` -- `hitbox.h` defines early `Hitbox` and `Hurtbox` structs plus team filtering. - Full ACT combat should build from this instead of embedding hit detection in - actors. +- `hitbox.h` 定义早期的 `Hitbox` 和 `Hurtbox` 结构体及团队过滤。 + 完整的 ACT 战斗应该建立在此基础上，而不是在 + 角色中嵌入打击判定 -## Current Build Target +## 当前构建目标 -`xmake.lua` defines `Frostbite2DGame` for Windows. It compiles all -`game/src/**.cpp` files, links against `Frostbite2D`, and copies `game/assets` -next to the executable after build. +`xmake.lua` 为 Windows 定义 `Frostbite2DGame`。它编译所有 +`game/src/**.cpp` 文件，链接到 `Frostbite2D`，并在构建后 +将 `game/assets` 复制到可执行文件旁边。 -Build command: +构建命令： ```powershell xmake -b Frostbite2DGame ``` -Output: +输出： ```text build/windows/x64/release/Frostbite2DGame.exe ``` -## Next Architecture Steps +## 后续架构步骤 -1. Add `actor/enemy_actor.*` and reuse `PlatformMover`. -2. Add a `combat/CombatSystem` that collects active hitboxes and hurtboxes each - frame, resolves hits, and emits damage events. -3. Replace hard-coded animation timing in `PlayerActor` with data definitions. -4. Move `CreateWhiteboxLevel()` to an external level format once the first - whitebox loop is stable. -5. Add a `scene/gameplay_scene` base if multiple levels share spawn, camera, - combat and pause logic. +1. 添加 `actor/enemy_actor.*` 并复用 `PlatformMover` +2. 添加 `combat/CombatSystem` 来收集每一帧的活跃碰撞箱和伤害判定箱、 + 解算打击并发出伤害事件 +3. 用数据定义替换 `PlayerActor` 中的硬编码动画时序 +4. 当第一个白盒循环稳定后，将 `CreateWhiteboxLevel()` 迁移到外部关卡格式 +5. 如果多个关卡共享生成、摄像机、 + 战斗和暂停逻辑，则添加 `scene/gameplay_scene` 基类