87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
Extra2D 是一个使用 C++17 编写的轻量级跨平台 2D 游戏引擎。支持 Windows (MinGW)、Linux、macOS 和 Nintendo Switch。项目注释和文档使用中文。
|
||
|
||
## 构建系统
|
||
|
||
项目使用 **xmake**（非 CMake）。
|
||
|
||
```bash
|
||
# 配置 (Windows/MinGW 示例)
|
||
xmake f -p mingw -a x86_64 -m release -y
|
||
|
||
# 配置调试构建
|
||
xmake f -p mingw -a x86_64 -m debug -y
|
||
|
||
# 构建全部
|
||
xmake build
|
||
|
||
# 构建特定目标
|
||
xmake build demo_basic
|
||
xmake build demo_hello_module
|
||
|
||
# 运行示例
|
||
xmake run demo_basic
|
||
xmake run demo_hello_module
|
||
|
||
# Nintendo Switch 构建
|
||
export DEVKITPRO=/opt/devkitpro
|
||
xmake f -p switch -m release -y
|
||
xmake build
|
||
```
|
||
|
||
构建目标：`extra2d`（引擎静态库）、`demo_basic`、`demo_hello_module`、`hello_module_lib`。
|
||
|
||
调试构建定义 `E2D_DEBUG` 和 `_DEBUG`。`debug_logs` 选项启用调试日志。
|
||
|
||
## 架构
|
||
|
||
### 双系统设计：模块 + 服务
|
||
|
||
引擎有两个由 `Application`（单例）管理的并行系统：
|
||
|
||
- **模块**（`Module` 基类）：处理平台级初始化，具有生命周期钩子（`setupModule`、`destroyModule`、`onUpdate`、`onRender`、`handleEvent`）。通过 `E2D_MODULE` 宏注册，在静态初始化时自动发现。按优先级排序（数值越小越先初始化）。
|
||
- **服务**（`IService` 基类）：提供通过 `ServiceLocator` 访问的运行时功能。通过 `Application` 便捷方法获取：`app.scenes()`、`app.timers()`、`app.events()`、`app.camera()`。
|
||
|
||
### 模块自动注册
|
||
|
||
模块使用 `E2D_MODULE(类名, 优先级)` 宏，放置在 `.cpp` 文件末尾、**任何命名空间之外**。这会创建一个静态的 `ModuleAutoRegister<T>` 变量，在静态初始化期间向 `ModuleRegistry` 注册。静态链接需要 `--whole-archive` 链接器标志，以防止链接器剥离这些未引用的符号。
|
||
|
||
内置模块优先级顺序：Logger(-1) → Config(0) → Platform(10) → Window(20) → Input(30) → Render(40)。用户模块应使用优先级 1000+。
|
||
|
||
### 模块上下文链
|
||
|
||
模块生命周期方法接收上下文对象（`UpdateContext`、`RenderContext`、`EventContext`）。**必须调用 `ctx.next()`** 以继续链式调用到下一个模块。
|
||
|
||
### 关键子系统
|
||
|
||
- **平台层**：统一的 SDL2 后端（`E2D_BACKEND_SDL2` 宏定义）。通过 `IWindow`/`IInput` 接口实现平台抽象。实现在 `Extra2D/src/platform/backends/sdl2/`。
|
||
- **图形**：通过 glad 使用 OpenGL ES 3.2。渲染器（`gl_renderer`）、精灵批处理（`gl_sprite_batch`）、支持热重载的着色器管理。内置着色器在 `Extra2D/shaders/builtin/`（构建后复制到构建目录）。
|
||
- **场景图**：基于树的 `Node` 层级结构，支持变换继承。`Scene` 是根节点。专用节点：`ShapeNode`、`Sprite`。场景过渡效果（淡入淡出、滑动、翻转、缩放、方块）。
|
||
- **事件系统**：`EventType` 枚举驱动。事件使用 `std::variant` 实现类型化数据（`KeyEvent`、`MouseEvent`、`GamepadEvent`）。输入使用扫描码（非键码）。
|
||
|
||
## 源码布局
|
||
|
||
- `Extra2D/include/extra2d/` — 按子系统组织的公共头文件
|
||
- `Extra2D/src/` — 实现，镜像 include 结构
|
||
- `Extra2D/shaders/` — GLSL 着色器文件（复制到构建输出）
|
||
- `examples/` — 示例程序（`basic/`、`hello_module/`）
|
||
- `xmake/engine.lua` — 引擎静态库目标定义
|
||
- `xmake.lua` — 根构建配置，包含示例目标
|
||
|
||
## 依赖
|
||
|
||
由 xmake 管理：`glm`、`nlohmann_json`、`libsdl2`。内嵌：`glad`、`stb_image`、`stb_truetype`、`stb_rect_pack`、`KHR`。
|
||
|
||
## 约定
|
||
|
||
- 命名空间：`extra2d`
|
||
- 智能指针：`Ptr<T>`（shared_ptr 别名）、`SharedPtr<T>`，通过 `makeShared<T>()` 创建
|
||
- 日志：`E2D_LOG_INFO(...)`、`E2D_LOG_WARN(...)`、`E2D_LOG_ERROR(...)`
|
||
- 导出宏：`E2D_API` 用于 DLL 可见符号
|
||
- 自定义模块直接编译到可执行文件（静态链接，推荐）或作为独立 DLL
|