# FX2DEngine

**Repository Path**: demo./FX2DEngine

## Basic Information

- **Project Name**: FX2DEngine
- **Description**: FX2DEngine 是一个轻量级、模块化的 C++ 2D 游戏引擎，基于 SDL2 构建。
它提供了从底层渲染、物理模拟到高层 UI 系统的完整游戏开发工具链，采用 ECS（Entity-Component）架构设计，让 2D 游戏开发变得简单高效。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FX2DEngine

[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](include/FX2DEngine/Core.h)
[![C++ Standard](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](CMakeLists.txt)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**FX2DEngine** 是一个轻量级、模块化的 C++ 2D 游戏引擎，基于 **SDL2** 构建。

它提供了从底层渲染、物理模拟到高层 UI 系统的完整游戏开发工具链，采用 ECS（Entity-Component）架构设计，让 2D 游戏开发变得简单高效。

---

## 🎮 特性

### 渲染系统
- **SDL2 硬件加速渲染** — 基于 SDL_Renderer 的 2D 图元绘制
- **字体渲染** — 内置 stb_truetype，支持 TTF/TTC 字体和中文渲染
- **纹理/精灵** — 支持 PNG/JPG 加载、翻转、缩放、旋转
- **相机系统** — 2D 视口变换、缩放、世界↔屏幕坐标转换
- **粒子系统** — 可配置发射器，支持点/圆形/矩形发射形状

### 游戏对象系统 (ECS)
- **GameObject + Component** — 轻量 ECS 架构
- **Scene 管理器** — 对象创建、查找（按名称/标签）、生命周期管理
- **Transform** — 位置、旋转、缩放和父子层级

### 动画系统
- **Animator 组件** — 多动画状态管理
- **Sprite Sheet** — 精灵帧配置
- **动画回调** — onFinished 事件

### 物理系统
- **Rigidbody2D** — 静态/动态刚体
- **碰撞检测** — AABB vs AABB、圆形 vs AABB
- **碰撞响应** — 分离+速度反弹
- **射线检测 (Raycast)**
- **空间查询** — queryAABB、queryCircle

### UI 系统
- **Canvas/Panel/Label/Button** — 完整的 UI 控件树
- **自动对齐** — hAlign (左/中/右) + vAlign (上/中/下)
- **按钮交互** — hover/press 状态和点击回调

### 其他子系统
- **音频** — WAV 加载、多实例混音、音量控制
- **输入** — 键盘（按下/按住/释放）+ 鼠标（位置/按钮/滚轮）
- **资源管理** — 纹理/音频缓存和热加载
- **配置系统** — 类型安全的键值存储 (int/float/string/bool)
- **游戏时钟** — 高精度 deltaTime、FPS 统计、时间缩放

---

## 🚀 快速开始

### 依赖

- **CMake** >= 3.16
- **SDL2** + **SDL2_image**
- **C++20** 编译器（Clang 12+ / GCC 10+ / MSVC 2022+）

### macOS 安装依赖

```bash
brew install cmake sdl2 sdl2_image
```

### 构建

```bash
cd FX2DEngine
mkdir build && cd build
cmake ..
make -j$(nproc)
```

### 运行 Demo

```bash
# 简单 ECS 射击 Demo
./build/FX2DDemo

# 综合功能演示（9 个页面）
./build/FX2DComprehensiveDemo
```

### 第一个游戏

```cpp
#include "FX2DEngine/Core.h"
using namespace FX2D;

int main() {
    Engine engine;
    engine.init("Hello FX2D", 800, 600);

    auto& r = engine.getRenderer();
    auto& input = engine.getInput();

    float x = 400, y = 300;

    engine.onUpdate([&]() {
        float dt = engine.deltaTime();
        if (input.isKeyDown(SDLK_RIGHT)) x += 200 * dt;
        if (input.isKeyDown(SDLK_LEFT))  x -= 200 * dt;
        if (input.isKeyDown(SDLK_ESCAPE)) engine.quit();
    });

    engine.onRender([&]() {
        r.drawCircle({x, y}, 30, 1, 0, 0);  // 红色圆球
        r.drawText("Use Arrow Keys to Move", {10, 10}, 1, 1, 1);
    });

    engine.run();
    return 0;
}
```

---

## 📁 项目结构

```
FX2DEngine/
├── include/FX2DEngine/     # 公开头文件
│   ├── Core.h              # 统一包含入口
│   ├── Engine.h            # 引擎主类
│   ├── Renderer.h          # 2D 渲染器
│   ├── Camera.h            # 2D 相机
│   ├── GameObject.h        # 游戏对象 + Component 基类
│   ├── Scene.h             # 场景管理器
│   ├── Transform.h         # 2D 变换
│   ├── ParticleSystem.h    # 粒子系统
│   ├── Animation.h         # 动画系统
│   ├── Physics.h           # 2D 物理
│   ├── TileMap.h           # 瓦片地图
│   ├── UI.h                # UI 控件
│   ├── InputManager.h      # 输入管理
│   ├── AudioManager.h      # 音频管理
│   ├── ResourceManager.h   # 资源管理
│   ├── Config.h            # 配置系统
│   ├── GameClock.h         # 游戏时钟
│   ├── Texture.h           # 纹理
│   ├── Sprite.h            # 精灵
│   ├── Vector2D.h          # 2D 向量
│   ├── Matrix3x3.h         # 3x3 矩阵（仿射变换）
│   └── MathUtils.h         # 数学工具
├── src/                    # 引擎实现
│   ├── core/               # 核心系统
│   ├── math/               # 数学库
│   ├── graphics/           # 渲染/图形
│   ├── objects/            # 游戏对象
│   ├── input/              # 输入
│   ├── audio/              # 音频
│   ├── physics/            # 物理
│   ├── scene/              # 场景元素
│   └── ui/                 # UI
├── demos/                  # 示例程序
│   ├── main.cpp            # ECS 射击 Demo
│   └── comprehensive_demo.cpp  # 全功能演示（9 页）
├── tests/                  # 单元测试
├── CMakeLists.txt          # CMake 构建配置
└── README.md
```

---

## 🏗️ 架构概览

```
┌─────────────────────────────────────────────────┐
│                    Engine                        │
│  ┌─────────┐ ┌──────┐ ┌────────┐ ┌───────────┐ │
│  │Renderer │ │Clock │ │ Input  │ │   Audio   │ │
│  └─────────┘ └──────┘ └────────┘ └───────────┘ │
│                     ┌──────┐                     │
│                     │Config│                     │
│                     └──────┘                     │
├─────────────────────────────────────────────────┤
│                    Scene                         │
│  ┌──────────────────────────────────────────┐   │
│  │              GameObject                   │   │
│  │  ┌───────┐ ┌──────┐ ┌──────────┐        │   │
│  │  │ Transf│ │PrtSys│ │Rigidbody │  ...   │   │
│  │  └───────┘ └──────┘ └──────────┘        │   │
│  └──────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│  Animation │ Physics │ TileMap │ UI │ Resource  │
└─────────────────────────────────────────────────┘
```

**设计理念：**

1. **回调驱动** — 用户设置 `onUpdate`/`onRender`/`onKeyDown` 回调，引擎负责主循环调度
2. **ECS 组件模式** — `GameObject` 通过 `addComponent<T>()` 添加功能，而非深层继承
3. **零依赖头文件** — 大部分头文件可独立使用（如 `Vector2D.h`、`MathUtils.h`）
4. **SDL2 底层** — 经久考验的跨平台多媒体库，支持 Windows/macOS/Linux

---

## 🎯 核心 API 速览

### 引擎生命周期

```cpp
Engine engine;
engine.init("Title", 1280, 720);   // 初始化
engine.onStart([](){ ... });       // 启动回调（一次）
engine.onUpdate([](){ ... });      // 每帧更新
engine.onRender([](){ ... });      // 每帧渲染
engine.onKeyDown([](){ ... });     // 按键回调
engine.onDestroy([](){ ... });     // 退出清理
engine.run();                       // 阻塞运行
engine.quit();                      // 请求退出
```

### 渲染

```cpp
auto& r = engine.getRenderer();
r.drawRect(pos, size, r, g, b);     // 矩形
r.drawCircle(center, radius, r, g, b);  // 圆
r.drawLine(from, to, r, g, b);      // 线段
r.drawText("Hello", pos, r, g, b);  // 文字
float w = r.measureText("Hi", 16);  // 测量文字宽度
```

### 输入

```cpp
auto& input = engine.getInput();
input.isKeyDown(SDLK_SPACE);        // 按住
input.isKeyPressed(SDLK_SPACE);     // 按下瞬间
input.isKeyReleased(SDLK_SPACE);    // 释放瞬间
input.isMouseDown(SDL_BUTTON_LEFT); // 鼠标按下
input.mousePosition();              // 鼠标坐标
input.mouseWheel();                 // 滚轮增量
```

### GameObject + Component

```cpp
Scene scene;
auto obj = scene.createObject("Player");
obj->setTag("Player");

auto* rb = obj->addComponent<Rigidbody2D>();
rb->bodyType = Rigidbody2D::BodyType::Dynamic;
rb->mass = 1.0f;

// 查找
auto found = scene.findByTag("Enemy");
auto& objects = scene.objects();
```

### 粒子系统

```cpp
auto* ps = obj->addComponent<ParticleSystem>();
ps->config.emissionRate = 30;
ps->config.speedMin = 40;
ps->config.speedMax = 120;
ps->config.lifetimeMin = 0.5f;
ps->config.lifetimeMax = 1.5f;
ps->play();    // 开始发射
ps->burst(20); // 爆发 20 个粒子
```

### 物理

```cpp
PhysicsWorld world;
world.setGravity({0, 980});
world.addBody(rb);
world.step(dt);  // 每帧步进

auto hit = world.raycast(origin, direction, maxDist);
auto bodies = world.queryCircle(center, radius);
```

### UI

```cpp
Canvas canvas;
auto panel = canvas.createElement<Panel>();
auto label = canvas.createElement<Label>();
label->text = "Hello World";
label->hAlign = 1;  // 居中

auto button = canvas.createElement<Button>();
button->text = "Click Me";
button->onClick = []{ std::cout << "Clicked!" << std::endl; };

canvas.update(dt, input);
canvas.render(renderer);
```

---

## 📖 Demo 说明

### FX2DDemo — ECS 射击游戏

简单的俯视角射击演示，展示 ECS 架构的基本用法：
- WASD 移动玩家，空格射击，Q/E 旋转
- 自定义 EnemyAI 和 Bullet 组件
- 子弹-敌人碰撞检测
- 粒子特效（引擎火花、爆炸）

### FX2DComprehensiveDemo — 全功能演示

包含 9 个演示页面（按键 1-9 切换）：

| 按键 | 演示页面 | 演示内容 |
|-----|------|---------|
| 1 | 概览 | 基础渲染、粒子、文字、纹理 |
| 2 | ECS | GameObject + Component、碰撞检测 |
| 3 | 物理 | Rigidbody2D、碰撞响应、射线检测 |
| 4 | 瓦片地图 | 瓦片地图、坐标转换 |
| 5 | 动画 | Animator、SpriteSheet、动画回调 |
| 6 | UI | Canvas、Label、Button、对齐 |
| 7 | 相机 | 相机跟随、缩放、坐标转换 |
| 8 | 音频 | 音频播放、音量控制 |
| 9 | 数学 | Vector2D、Matrix3x3、MathUtils |

---

## 🧪 测试

```bash
cd build
cmake ..
make FX2DTests
ctest
```

---

## 🔧 构建选项

| CMake 选项 | 默认值 | 说明 |
|-----------|-------|------|
| `CMAKE_BUILD_TYPE` | — | 构建类型：`Debug` / `Release` |
| `CMAKE_CXX_STANDARD` | 20 | C++ 标准版本 |

---

## 📄 License

MIT License

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request。

---

*用 ❤️ 为 2D 游戏开发而打造*