472 lines
12 KiB
Markdown
472 lines
12 KiB
Markdown
<div align="center">
|
||
|
||
# Extra2D
|
||
|
||
<p align="center">
|
||
<a href="#">
|
||
<img src="https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge&logo=appveyor" alt="Build Status">
|
||
</a>
|
||
<a href="#">
|
||
<img src="https://img.shields.io/badge/C++-17-00599C?style=for-the-badge&logo=c%2B%2B" alt="C++17">
|
||
</a>
|
||
<a href="#">
|
||
<img src="https://img.shields.io/badge/OpenGL%20ES-3.2-555555?style=for-the-badge&logo=opengl" alt="OpenGL ES 3.2">
|
||
</a>
|
||
<a href="#">
|
||
<img src="https://img.shields.io/badge/SDL2-2.0+-1DA1F2?style=for-the-badge" alt="SDL2">
|
||
</a>
|
||
<a href="#">
|
||
<img src="https://img.shields.io/badge/Nintendo%20Switch-E60012?style=for-the-badge&logo=nintendo-switch&logoColor=white" alt="Nintendo Switch">
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<b>轻量级跨平台 2D 游戏引擎</b><br>
|
||
<i>高性能、模块化、支持 Nintendo Switch</i>
|
||
</p>
|
||
|
||
[构建指南](#构建指南) | [快速开始](./docs/quick_start.md) | [示例程序](#示例程序) | [模块系统](./docs/module_system.md)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 简介
|
||
|
||
**Extra2D** 是一个轻量级跨平台 2D 游戏引擎，采用现代 C++17 架构，支持 Windows、Linux、macOS 和 Nintendo Switch 平台。
|
||
|
||
### 核心特性
|
||
|
||
- **跨平台支持**：Windows、Linux、macOS、Nintendo Switch
|
||
- **模块化架构**：模块系统 + 服务系统，灵活可扩展
|
||
- **显式注册**：通过 `Application::use()` 注册模块，参考 Kiwano 设计
|
||
- **场景图系统**：树形节点结构，支持变换继承
|
||
- **输入系统**：键盘、鼠标、手柄、触摸，事件驱动
|
||
- **渲染系统**：OpenGL ES 3.2，支持自定义着色器
|
||
- **视口适配**：多种适配模式，自动响应窗口大小变化
|
||
|
||
---
|
||
|
||
## 架构概览
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Application["Application (应用层)"]
|
||
direction TB
|
||
APP[Application]
|
||
end
|
||
|
||
subgraph Core["Core Layer (核心层)"]
|
||
direction LR
|
||
MOD[Module<br/>模块基类]
|
||
SL[ServiceLocator<br/>服务定位器]
|
||
end
|
||
|
||
subgraph Modules["Modules (模块系统)"]
|
||
direction TB
|
||
subgraph CoreModules["Core Modules"]
|
||
LOGGER[Logger Module<br/>日志系统]
|
||
CONFIG[Config Module<br/>配置管理]
|
||
PLATFORM[Platform Module<br/>平台检测]
|
||
WINDOW[Window Module<br/>窗口管理]
|
||
end
|
||
subgraph FeatureModules["Feature Modules"]
|
||
INPUT[Input Module<br/>输入处理]
|
||
RENDER[Render Module<br/>渲染系统]
|
||
end
|
||
end
|
||
|
||
subgraph Services["Services (服务系统)"]
|
||
direction TB
|
||
EVENT[EventService<br/>事件分发]
|
||
TIMER[TimerService<br/>计时器]
|
||
SCENE_SVC[SceneService<br/>场景管理]
|
||
CAMERA[CameraService<br/>相机系统]
|
||
end
|
||
|
||
subgraph Scene["Scene System (场景系统)"]
|
||
direction TB
|
||
SCENE[Scene<br/>场景]
|
||
NODE[Node<br/>节点]
|
||
SHAPE[ShapeNode<br/>形状节点]
|
||
SPRITE[Sprite<br/>精灵]
|
||
end
|
||
|
||
subgraph Graphics["Graphics (图形系统)"]
|
||
direction TB
|
||
BACKEND[RenderBackend<br/>渲染后端]
|
||
GL[OpenGL Renderer<br/>OpenGL 渲染器]
|
||
SHADER[ShaderManager<br/>着色器管理]
|
||
TEXTURE[TexturePool<br/>纹理池]
|
||
end
|
||
|
||
subgraph Platform["Platform (平台层)"]
|
||
direction TB
|
||
SDL2[SDL2 Backend<br/>SDL2 后端]
|
||
INPUT_SYS[Input System<br/>输入系统]
|
||
end
|
||
|
||
APP --> MOD
|
||
APP --> SL
|
||
MOD --> Modules
|
||
SL --> Services
|
||
SCENE_SVC --> SCENE
|
||
SCENE --> NODE
|
||
NODE --> SHAPE
|
||
NODE --> SPRITE
|
||
RENDER --> BACKEND
|
||
BACKEND --> GL
|
||
GL --> SHADER
|
||
GL --> TEXTURE
|
||
WINDOW --> SDL2
|
||
INPUT --> INPUT_SYS
|
||
INPUT_SYS --> SDL2
|
||
```
|
||
|
||
### 模块系统
|
||
|
||
| 模块 | 职责 | 优先级 |
|
||
|-----|------|-------|
|
||
| Logger | 日志系统 | -1 |
|
||
| Config | 配置管理 | 0 |
|
||
| Platform | 平台检测 | 10 |
|
||
| Window | 窗口管理 | 20 |
|
||
| Input | 输入处理 | 30 |
|
||
| Render | 渲染系统 | 40 |
|
||
|
||
### 模块自发现原理
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as 编译时
|
||
participant R as 运行时
|
||
participant MR as ModuleRegistry
|
||
participant App as Application
|
||
|
||
Note over C: E2D_MODULE 宏展开
|
||
C->>C: 创建静态变量 ModuleAutoRegister<T>
|
||
C->>C: 添加 __attribute__((used)) 防止优化
|
||
|
||
Note over R: 程序启动
|
||
R->>MR: 静态初始化阶段
|
||
MR->>MR: 构造函数自动调用 registerModule()
|
||
MR->>MR: 模块信息存入注册表
|
||
|
||
Note over App: Application::init()
|
||
App->>MR: getModules()
|
||
MR->>App: 返回按优先级排序的模块列表
|
||
App->>App: 按顺序调用 setupModule()
|
||
```
|
||
|
||
### 服务系统
|
||
|
||
| 服务 | 职责 | 优先级 |
|
||
|-----|------|-------|
|
||
| EventService | 事件分发 | 100 |
|
||
| TimerService | 计时器 | 200 |
|
||
| SceneService | 场景管理 | 300 |
|
||
| CameraService | 相机系统 | 400 |
|
||
|
||
---
|
||
|
||
## 构建指南
|
||
|
||
### 环境要求
|
||
|
||
| 组件 | 要求 |
|
||
|:----:|:-----|
|
||
| 编译器 | GCC 9+ / Clang 10+ / MSVC 2019+ |
|
||
| C++ 标准 | C++17 |
|
||
| 构建工具 | xmake 2.5+ |
|
||
| 目标平台 | Windows / Linux / macOS / Nintendo Switch |
|
||
|
||
### 安装 xmake
|
||
|
||
```powershell
|
||
# Windows (PowerShell)
|
||
Invoke-Expression (Invoke-WebRequest 'https://xmake.io/psget.text' -UseBasicParsing).Content
|
||
```
|
||
|
||
```bash
|
||
# macOS
|
||
brew install xmake
|
||
|
||
# Linux
|
||
sudo add-apt-repository ppa:xmake-io/xmake
|
||
sudo apt update
|
||
sudo apt install xmake
|
||
```
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
# 配置项目
|
||
xmake f -p mingw -a x86_64 -m release -y
|
||
|
||
# 构建
|
||
xmake build
|
||
|
||
# 运行示例
|
||
xmake run demo_basic
|
||
```
|
||
|
||
### Nintendo Switch 构建
|
||
|
||
```bash
|
||
# 设置 devkitPro 环境
|
||
export DEVKITPRO=/opt/devkitpro
|
||
|
||
# 配置并构建
|
||
xmake f -p switch -m release -y
|
||
xmake build
|
||
```
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 创建应用
|
||
|
||
```cpp
|
||
#include <extra2d/extra2d.h>
|
||
|
||
using namespace extra2d;
|
||
|
||
int main() {
|
||
// 配置应用
|
||
AppConfig config = AppConfig::createDefault();
|
||
config.appName = "My Game";
|
||
config.appVersion = "1.0.0";
|
||
|
||
// 获取应用实例
|
||
Application& app = Application::get();
|
||
|
||
// 初始化
|
||
if (!app.init(config)) {
|
||
return -1;
|
||
}
|
||
|
||
// 创建场景
|
||
auto scene = Scene::create();
|
||
scene->setBackgroundColor(Color(0.1f, 0.1f, 0.15f, 1.0f));
|
||
scene->setViewportSize(app.window().width(), app.window().height());
|
||
|
||
// 配置视口适配
|
||
auto cameraService = app.camera();
|
||
if (cameraService) {
|
||
ViewportConfig vpConfig;
|
||
vpConfig.logicWidth = app.window().width();
|
||
vpConfig.logicHeight = app.window().height();
|
||
vpConfig.mode = ViewportMode::AspectRatio;
|
||
cameraService->setViewportConfig(vpConfig);
|
||
}
|
||
|
||
// 运行场景
|
||
app.enterScene(scene);
|
||
app.run();
|
||
|
||
// 清理
|
||
app.shutdown();
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 创建自定义模块
|
||
|
||
```cpp
|
||
#include <extra2d/core/module.h>
|
||
|
||
class MyModule : public extra2d::Module {
|
||
public:
|
||
const char* getName() const override { return "MyModule"; }
|
||
|
||
int getPriority() const override { return 1000; }
|
||
|
||
void setupModule() override {
|
||
// 初始化资源
|
||
extra2d::E2D_LOG_INFO("MyModule initialized");
|
||
}
|
||
|
||
void destroyModule() override {
|
||
// 清理资源
|
||
extra2d::E2D_LOG_INFO("MyModule destroyed");
|
||
}
|
||
|
||
void onUpdate(extra2d::UpdateContext& ctx) override {
|
||
// 更新逻辑
|
||
ctx.next(); // 继续下一个模块
|
||
}
|
||
};
|
||
|
||
// 在 main 中注册
|
||
int main() {
|
||
auto& app = extra2d::Application::get();
|
||
|
||
MyModule myModule;
|
||
app.use(myModule); // 显式注册
|
||
|
||
app.init();
|
||
app.run();
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 场景图示例
|
||
|
||
```cpp
|
||
// 创建节点层级
|
||
auto root = makeShared<Node>();
|
||
root->setPos(width / 2, height / 2);
|
||
scene->addChild(root);
|
||
|
||
// 添加形状节点
|
||
auto rect = ShapeNode::createFilledRect(
|
||
Rect(-50, -50, 100, 100),
|
||
Color(1.0f, 0.4f, 0.4f, 1.0f)
|
||
);
|
||
root->addChild(rect);
|
||
|
||
// 变换继承
|
||
auto child = makeShared<Node>();
|
||
child->setPos(100, 0);
|
||
child->setRotation(45); // 旋转 45 度
|
||
child->setScale(0.5f); // 缩放 0.5
|
||
root->addChild(child);
|
||
```
|
||
|
||
### 输入事件
|
||
|
||
```cpp
|
||
auto eventService = app.events();
|
||
|
||
// 键盘事件
|
||
eventService->addListener(EventType::KeyPress, [](Event& e) {
|
||
auto& key = std::get<KeyEvent>(e.data);
|
||
if (key.scancode == static_cast<int>(Key::Escape)) {
|
||
Application::get().quit();
|
||
}
|
||
});
|
||
|
||
// 鼠标事件
|
||
eventService->addListener(EventType::MousePress, [](Event& e) {
|
||
auto& mouse = std::get<MouseEvent>(e.data);
|
||
// 处理鼠标点击
|
||
});
|
||
|
||
// 手柄事件
|
||
eventService->addListener(EventType::GamepadPress, [](Event& e) {
|
||
auto& gamepad = std::get<GamepadEvent>(e.data);
|
||
// 处理手柄输入
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 示例程序
|
||
|
||
| 示例 | 说明 |
|
||
|-----|------|
|
||
| `demo_basic` | 基础示例：场景图、输入事件、视口适配 |
|
||
| `demo_hello_module` | 自定义模块示例：展示如何创建和注册模块 |
|
||
|
||
运行示例：
|
||
|
||
```bash
|
||
xmake run demo_basic
|
||
xmake run demo_hello_module
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 技术 | 用途 | 版本 |
|
||
|:----:|:-----|:----:|
|
||
| OpenGL ES | 2D 图形渲染 | 3.2 |
|
||
| SDL2 | 窗口和输入管理 | 2.0+ |
|
||
| GLM | 数学库 | 0.9.9+ |
|
||
| nlohmann_json | JSON 解析 | 3.x |
|
||
| glad | OpenGL 加载器 | 最新版 |
|
||
| stb_image | 图像加载 | 最新版 |
|
||
| stb_truetype | 字体渲染 | 最新版 |
|
||
| xmake | 构建系统 | 2.5+ |
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
- [快速入门指南](./docs/quick_start.md) - 从安装到创建第一个游戏
|
||
- [模块系统文档](./docs/module_system.md) - 模块系统、服务系统、场景图、视口适配
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
Extra2D/
|
||
├── Extra2D/
|
||
│ ├── include/
|
||
│ │ ├── KHR/ # KHR 平台头文件
|
||
│ │ ├── extra2d/ # 引擎公共头文件
|
||
│ │ │ ├── app/ # 应用程序
|
||
│ │ │ ├── config/ # 配置系统
|
||
│ │ │ ├── core/ # 核心类型、模块基类
|
||
│ │ │ ├── event/ # 事件系统
|
||
│ │ │ ├── graphics/ # 图形渲染
|
||
│ │ │ ├── input/ # 输入配置
|
||
│ │ │ ├── modules/ # 内置模块
|
||
│ │ │ ├── platform/ # 平台抽象
|
||
│ │ │ ├── scene/ # 场景系统
|
||
│ │ │ ├── script/ # 脚本系统
|
||
│ │ │ ├── services/ # 服务接口
|
||
│ │ │ └── utils/ # 工具库
|
||
│ │ ├── glad/ # OpenGL 加载器
|
||
│ │ └── stb/ # STB 单文件库
|
||
│ ├── shaders/ # 着色器文件
|
||
│ └── src/ # 源文件
|
||
│ ├── app/ # 应用实现
|
||
│ ├── core/ # 核心实现
|
||
│ ├── event/ # 事件实现
|
||
│ ├── graphics/ # 图形实现
|
||
│ ├── modules/ # 模块实现
|
||
│ ├── platform/ # 平台实现
|
||
│ ├── scene/ # 场景实现
|
||
│ ├── script/ # 脚本实现
|
||
│ ├── services/ # 服务实现
|
||
│ └── utils/ # 工具实现
|
||
├── docs/ # 文档
|
||
├── examples/ # 示例程序
|
||
│ ├── basic/ # 基础示例
|
||
│ └── hello_module/ # 自定义模块示例
|
||
└── xmake/ # 构建配置
|
||
```
|
||
|
||
---
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 窗口后端 | 图形 API | 状态 |
|
||
|-----|---------|---------|------|
|
||
| Windows | SDL2 | OpenGL ES 3.2 | ✅ 支持 |
|
||
| Linux | SDL2 | OpenGL ES 3.2 | ✅ 支持 |
|
||
| macOS | SDL2 | OpenGL ES 3.2 | ✅ 支持 |
|
||
| Nintendo Switch | SDL2 | OpenGL ES 3.2 | ✅ 支持 |
|
||
|
||
---
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
Extra2D 使用 [MIT](LICENSE) 许可证。
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
- GitHub Issues: https://github.com/ChestnutYueyue/extra2d/issues
|