3.9 KiB

Raw Blame History

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。

项目概述

Extra2D 是一个使用 C++17 编写的轻量级跨平台 2D 游戏引擎。支持 Windows (MinGW)、Linux、macOS 和 Nintendo Switch。项目注释和文档使用中文。

构建系统

项目使用 xmake（非 CMake）。

# 配置 (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

3.9 KiB Raw Blame History Unescape Escape