docs: 添加项目README文档
包含项目概述、特性、平台支持、构建说明、快速开始示例、架构说明、核心模块介绍、项目结构和API参考等内容
This commit is contained in:
parent
9f29192ae8
commit
8619316289
|
|
@ -0,0 +1,279 @@
|
||||||
|
# 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/) - 跨平台构建系统
|
||||||
Loading…
Reference in New Issue