280 lines
8.7 KiB
Markdown
280 lines
8.7 KiB
Markdown
# Frostbite2D
|
||
|
||
一个轻量级、跨平台的 2D 游戏引擎，使用现代 C++ 编写。
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://en.cppreference.com/w/cpp/17)
|
||
[](#平台支持)
|
||
|
||
## 特性
|
||
|
||
- **跨平台**: 支持 Windows、Linux、macOS 和 Nintendo Switch
|
||
- **现代 C++17**: 类型安全的代码，使用智能指针
|
||
- **OpenGL ES 3.2**: 硬件加速的 2D 渲染
|
||
- **模块化架构**: 灵活的模块系统，易于扩展
|
||
- **UTF-8 支持**: 完整支持中文及其他 Unicode 路径
|
||
- **批量渲染**: 高效的精灵批处理，支持数千个精灵
|
||
- **字体渲染**: 通过 stb_truetype 支持 TrueType 字体
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 状态 |
|
||
|------|------|
|
||
| Windows | ✅ 已支持 |
|
||
| Linux | ✅ 已支持 |
|
||
| macOS | ✅ 已支持 |
|
||
| Nintendo Switch | ✅ 已支持 (homebrew) |
|
||
|
||
## 依赖库
|
||
|
||
- **SDL2** - 窗口管理和输入处理
|
||
- **OpenGL ES 3.2** - 图形 API
|
||
- **GLAD** - OpenGL 函数加载器
|
||
- **GLM** - 数学库
|
||
- **stb 库** - 图像加载、字体渲染等
|
||
|
||
## 构建
|
||
|
||
### 环境要求
|
||
|
||
- [xmake](https://xmake.io/zh-cn/) 构建系统
|
||
- 支持 C++17 的编译器
|
||
- SDL2 开发库
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/yourusername/Frostbite2D.git
|
||
cd Frostbite2D
|
||
|
||
# 构建项目
|
||
xmake build
|
||
|
||
# 运行
|
||
xmake run
|
||
```
|
||
|
||
### 指定平台构建
|
||
|
||
```bash
|
||
# Windows
|
||
xmake config --plat=windows
|
||
xmake build
|
||
|
||
# Linux
|
||
xmake config --plat=linux
|
||
xmake build
|
||
|
||
# Nintendo Switch (需要 devkitPro)
|
||
xmake config --plat=switch
|
||
xmake build
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```cpp
|
||
#include <fostbite2D/core/application.h>
|
||
#include <fostbite2D/utils/asset.h>
|
||
|
||
using namespace frostbite2D;
|
||
|
||
class GameModule : public Module {
|
||
public:
|
||
const char* getName() const override { return "GameModule"; }
|
||
|
||
void setupModule() override {
|
||
auto& asset = Asset::get();
|
||
asset.setWorkingDirectory("assets");
|
||
}
|
||
|
||
void onRender() override {
|
||
// 在这里编写渲染代码
|
||
}
|
||
};
|
||
|
||
int main() {
|
||
auto& app = Application::get();
|
||
|
||
AppConfig config = AppConfig::createDefault();
|
||
config.appName = "我的游戏";
|
||
config.windowConfig.width = 1280;
|
||
config.windowConfig.height = 720;
|
||
|
||
if (!app.init(config)) {
|
||
return -1;
|
||
}
|
||
|
||
app.use(new GameModule());
|
||
app.run();
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户应用层 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 应用程序层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 单例管理 │ │ 模块系统 │ │ 时间管理 │ │ 窗口管理 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 核心系统层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 渲染器 │ │ 着色器 │ │ 资源管理 │ │ 输入系统 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 平台抽象层 │
|
||
│ SDL2 + OpenGL │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心模块
|
||
|
||
### Application（应用程序）
|
||
|
||
主入口点和生命周期管理器。
|
||
|
||
```cpp
|
||
Application::get().init(config); // 初始化
|
||
Application::get().use(module); // 添加模块
|
||
Application::get().run(); // 运行主循环
|
||
```
|
||
|
||
### Window（窗口）
|
||
|
||
跨平台窗口管理，支持 OpenGL 上下文。
|
||
|
||
```cpp
|
||
WindowConfig config;
|
||
config.width = 1280;
|
||
config.height = 720;
|
||
config.title = "我的窗口";
|
||
config.vsync = true;
|
||
config.fullscreen = false;
|
||
```
|
||
|
||
### Asset（资源管理）
|
||
|
||
文件系统工具，支持 UTF-8 中文路径。
|
||
|
||
```cpp
|
||
auto& asset = Asset::get();
|
||
|
||
// 设置工作目录
|
||
asset.setWorkingDirectory("D:/游戏/资源");
|
||
|
||
// 读取文件
|
||
std::string content;
|
||
asset.readTextFile("config.json", content);
|
||
|
||
// 遍历文件
|
||
auto files = asset.listFiles("textures", true);
|
||
auto pngs = asset.listFilesWithExtension("sprites", ".png");
|
||
```
|
||
|
||
### Math Types（数学类型）
|
||
|
||
基于 GLM 的 2D 数学工具。
|
||
|
||
```cpp
|
||
Vec2 position(100.0f, 200.0f);
|
||
Size size(50.0f, 50.0f);
|
||
Rect bounds(position, size);
|
||
|
||
// 变换
|
||
auto transform = Transform2D::translation(100, 100)
|
||
* Transform2D::rotation(45.0f)
|
||
* Transform2D::scaling(2.0f);
|
||
```
|
||
|
||
### Module System（模块系统）
|
||
|
||
创建自定义模块来扩展功能。
|
||
|
||
```cpp
|
||
class MyModule : public Module {
|
||
public:
|
||
const char* getName() const override { return "MyModule"; }
|
||
|
||
void setupModule() override { /* 初始化 */ }
|
||
void onUpdate() override { /* 更新逻辑 */ }
|
||
void onRender() override { /* 渲染 */ }
|
||
void destroyModule() override { /* 清理 */ }
|
||
};
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Frostbite2D/
|
||
├── Fostbite2D/
|
||
│ ├── include/
|
||
│ │ └── fostbite2D/
|
||
│ │ ├── core/ # 应用程序、窗口
|
||
│ │ ├── module/ # 模块系统
|
||
│ │ ├── platform/ # 平台相关代码
|
||
│ │ ├── types/ # 数学类型、颜色
|
||
│ │ └── utils/ # 资源管理
|
||
│ └── src/
|
||
│ └── fostbite2D/
|
||
│ ├── core/
|
||
│ ├── platform/
|
||
│ └── utils/
|
||
├── platform/ # 平台构建配置
|
||
│ ├── windows.lua
|
||
│ ├── linux.lua
|
||
│ └── switch.lua
|
||
├── xmake.lua # 构建配置
|
||
└── README.md
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### Application
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `get()` | 获取单例实例 |
|
||
| `init(config)` | 使用配置初始化 |
|
||
| `run()` | 启动主循环 |
|
||
| `quit()` | 请求退出 |
|
||
| `use(module)` | 添加模块 |
|
||
| `deltaTime()` | 获取帧间隔时间 |
|
||
| `fps()` | 获取当前帧率 |
|
||
|
||
### Asset
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `readTextFile(path, out)` | 读取文本文件 |
|
||
| `writeTextFile(path, content)` | 写入文本文件 |
|
||
| `readBinaryFile(path, out)` | 读取二进制文件 |
|
||
| `listFiles(dir, recursive)` | 列出目录中的文件 |
|
||
| `exists(path)` | 检查路径是否存在 |
|
||
| `setWorkingDirectory(path)` | 设置工作目录 |
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
|
||
|
||
## 致谢
|
||
|
||
- [SDL2](https://www.libsdl.org/) - 跨平台多媒体库
|
||
- [GLM](https://github.com/g-truc/glm) - OpenGL 数学库
|
||
- [stb libraries](https://github.com/nothings/stb) - 单文件库集合
|
||
- [xmake](https://xmake.io/zh-cn/) - 跨平台构建系统
|