diff --git a/README.md b/README.md new file mode 100644 index 0000000..19eed32 --- /dev/null +++ b/README.md @@ -0,0 +1,279 @@ +# Frostbite2D + +一个轻量级、跨平台的 2D 游戏引擎，使用现代 C++ 编写。 + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![C++17](https://img.shields.io/badge/C%2B%2B-17-blue.svg)](https://en.cppreference.com/w/cpp/17) +[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Switch-green.svg)](#平台支持) + +## 特性 + +- **跨平台**: 支持 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 +#include + +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/) - 跨平台构建系统