Initial engine repository

2026-06-08 19:58:35 +08:00
commit 7a925c3736
137 changed files with 162421 additions and 0 deletions
@@ -0,0 +1,144 @@
+# Frostbite2D
+
+一个现代化的跨平台 2D 游戏引擎，使用 C++17 开发。
+
+## 特性
+
+- **跨平台支持** - Windows、Linux、macOS、Nintendo Switch
+- **现代渲染** - OpenGL 4.x 渲染器，支持批量渲染和自定义着色器
+- **完整游戏框架** - 场景管理、Actor 系统、精灵动画
+- **资源管理系统** - NPK 图片归档、PVF 脚本归档、LRU 缓存
+- **音频系统** - SDL2_mixer，支持 MP3/OGG/WAV
+- **输入系统** - 键盘、鼠标、触摸、手柄完整支持
+- **智能指针** - 自定义引用计数系统，避免内存泄漏
+- **事件系统** - 支持捕获/冒泡、优先级、事件拦截
+
+## 构建
+
+本项目使用 [XMake](https://xmake.io/) 作为构建系统。
+
+### 前置要求
+
+- C++17 兼容编译器
+- XMake
+- SDL2、SDL2_image、SDL2_mixer、GLM、Glad、zlib
+
+### 基本构建
+
+```bash
+xmake build
+```
+
+### 调试构建
+
+```bash
+xmake build -m debug
+```
+
+### 发布构建
+
+```bash
+xmake build -m release
+```
+
+### 平台特定构建
+
+```bash
+xmake build -p windows
+xmake build -p linux
+xmake build -p switch
+```
+
+## 快速开始
+
+```cpp
+#include <frostbite2D/core/application.h>
+#include <frostbite2D/core/window.h>
+#include <frostbite2D/2d/actor.h>
+#include <frostbite2D/2d/sprite.h>
+#include <frostbite2D/scene/scene.h>
+#include <frostbite2D/scene/scene_manager.h>
+#include <frostbite2D/resource/asset.h>
+#include <frostbite2D/resource/npk_archive.h>
+
+using namespace frostbite2D;
+
+int main(int argc, char** argv) {
+  AppConfig config = AppConfig::createDefault();
+  config.windowConfig.width = 1280;
+  config.windowConfig.height = 720;
+  config.windowConfig.title = "My Game";
+
+  Application& app = Application::get();
+  if (!app.init(config)) {
+    return -1;
+  }
+
+  Asset::get().setWorkingDirectory("assets");
+  NpkArchive::get().open("images.npk");
+
+  auto scene = MakePtr<Scene>();
+  SceneManager::get().PushScene(scene);
+
+  auto sprite = Sprite::createFromFile("player.png");
+  if (sprite) {
+    sprite->SetPosition(100, 100);
+    scene->AddActor(sprite);
+  }
+
+  app.run();
+  app.shutdown();
+
+  return 0;
+}
+```
+
+## 模块概览
+
+| 模块 | 描述 |
+|------|------|
+| `core` | Application、Window 核心类 |
+| `2d` | Actor、Sprite 2D 组件 |
+| `graphics` | Renderer、Batch、Camera、Texture、Shader |
+| `scene` | Scene、SceneManager 场景管理 |
+| `resource` | Asset、NpkArchive、PvfArchive 资源管理 |
+| `audio` | AudioSystem、Music、Sound 音频系统 |
+| `animation` | Animation、AnimationData 动画系统 |
+| `event` | 事件系统（窗口、键盘、鼠标、触摸、手柄） |
+| `base` | RefObject、RefPtr 智能指针 |
+| `types` | Vec2、Vec3、Rect、Color 数学类型 |
+
+## 项目结构
+
+```
+Frostbite2D/
+├── Frostbite2D/              # 引擎核心
+│   ├── include/frostbite2D/ # 公共头文件
+│   │   ├── 2d/              # 2D 图形组件
+│   │   ├── animation/       # 动画系统
+│   │   ├── audio/           # 音频系统
+│   │   ├── base/            # 基础类型（智能指针）
+│   │   ├── core/            # 核心引擎类
+│   │   ├── event/           # 事件系统
+│   │   ├── graphics/        # 图形渲染系统
+│   │   ├── resource/        # 资源管理系统
+│   │   ├── scene/           # 场景管理
+│   │   ├── types/           # 类型定义
+│   │   └── utils/           # 工具类
+│   └── src/                 # 实现文件
+├── engine.lua                # 可被游戏仓库引用的引擎目标
+└── xmake.lua                 # 独立构建配置
+```
+
+## 技术亮点
+
+- **批量渲染** - 2048 四边形批次优化
+- **LRU 缓存** - NPK/SoundPack 资源缓存（默认 512MB）
+- **侵入式链表** - 高性能 Actor 子对象管理
+- **变换系统** - 局部/世界变换矩阵自动更新
+- **事件系统** - 支持捕获/冒泡、优先级、拦截
+- **资源归档** - 支持 NPK（图片/音频）、PVF（脚本）
+
+## 许可证
+
+MIT License