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