# 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