216 lines
5.5 KiB
Markdown
216 lines
5.5 KiB
Markdown
# 01. 快速开始
|
||
|
||
本教程将带你快速上手 Extra2D 引擎，通过一个简单的 Hello World 示例了解引擎的基本使用方法。
|
||
|
||
## 示例代码
|
||
|
||
完整示例位于 `examples/hello_world/main.cpp`：
|
||
|
||
```cpp
|
||
#include <extra2d/extra2d.h>
|
||
|
||
using namespace extra2d;
|
||
|
||
// ============================================================================
|
||
// Hello World 场景
|
||
// ============================================================================
|
||
|
||
/**
|
||
* @brief Hello World 场景类
|
||
* 显示简单的 "Hello World" 文字
|
||
*/
|
||
class HelloWorldScene : public Scene {
|
||
public:
|
||
/**
|
||
* @brief 场景进入时调用
|
||
*/
|
||
void onEnter() override {
|
||
E2D_LOG_INFO("HelloWorldScene::onEnter - 进入场景");
|
||
|
||
// 设置背景颜色为深蓝色
|
||
setBackgroundColor(Color(0.1f, 0.1f, 0.3f, 1.0f));
|
||
|
||
// 加载字体（支持多种字体后备）
|
||
auto &resources = Application::instance().resources();
|
||
font_ = resources.loadFont("assets/font.ttf", 48, true);
|
||
|
||
if (!font_) {
|
||
E2D_LOG_ERROR("字体加载失败，文字渲染将不可用！");
|
||
return;
|
||
}
|
||
|
||
// 创建 "你好世界" 文本组件 - 使用屏幕空间（固定位置，不随相机移动）
|
||
auto text1 = Text::create("你好世界", font_);
|
||
text1->withCoordinateSpace(CoordinateSpace::Screen)
|
||
->withScreenPosition(640.0f, 360.0f) // 屏幕中心
|
||
->withAnchor(0.5f, 0.5f) // 中心锚点，让文字中心对准位置
|
||
->withTextColor(Color(1.0f, 1.0f, 1.0f, 1.0f));
|
||
addChild(text1);
|
||
|
||
// 创建提示文本组件 - 使用屏幕空间，固定在屏幕底部
|
||
auto text2 = Text::create("退出按键（START 按钮）", font_);
|
||
text2->withCoordinateSpace(CoordinateSpace::Screen)
|
||
->withScreenPosition(640.0f, 650.0f) // 屏幕底部
|
||
->withAnchor(0.5f, 0.5f)
|
||
->withTextColor(Color(1.0f, 1.0f, 0.0f, 1.0f));
|
||
addChild(text2);
|
||
}
|
||
|
||
/**
|
||
* @brief 每帧更新时调用
|
||
* @param dt 时间间隔（秒）
|
||
*/
|
||
void onUpdate(float dt) override {
|
||
Scene::onUpdate(dt);
|
||
|
||
// 检查退出按键
|
||
auto &input = Application::instance().input();
|
||
|
||
// 使用手柄 START 按钮退出 (GamepadButton::Start)
|
||
if (input.isButtonPressed(GamepadButton::Start)) {
|
||
E2D_LOG_INFO("退出应用 (START 按钮)");
|
||
Application::instance().quit();
|
||
}
|
||
}
|
||
|
||
private:
|
||
Ptr<FontAtlas> font_; // 字体图集
|
||
};
|
||
|
||
// ============================================================================
|
||
// 程序入口
|
||
// ============================================================================
|
||
|
||
int main(int argc, char **argv)
|
||
{
|
||
// 初始化日志系统
|
||
Logger::init();
|
||
Logger::setLevel(LogLevel::Debug);
|
||
|
||
// 获取应用实例
|
||
auto &app = Application::instance();
|
||
|
||
// 配置应用
|
||
AppConfig config;
|
||
config.title = "Easy2D - Hello World";
|
||
config.width = 1280;
|
||
config.height = 720;
|
||
config.vsync = true;
|
||
config.fpsLimit = 60;
|
||
|
||
// 初始化应用
|
||
if (!app.init(config)) {
|
||
E2D_LOG_ERROR("应用初始化失败！");
|
||
return -1;
|
||
}
|
||
|
||
// 进入 Hello World 场景
|
||
app.enterScene(makePtr<HelloWorldScene>());
|
||
|
||
// 运行应用
|
||
app.run();
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### 1. 应用生命周期
|
||
|
||
Extra2D 应用遵循以下生命周期：
|
||
|
||
```
|
||
初始化 (Application::init)
|
||
↓
|
||
进入场景 (enterScene)
|
||
↓
|
||
主循环 (run) → 更新 (onUpdate) → 渲染 (onRender)
|
||
↓
|
||
退出 (quit)
|
||
```
|
||
|
||
### 2. 场景系统
|
||
|
||
场景是游戏内容的容器，通过继承 `Scene` 类并重写以下方法：
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `onEnter()` | 场景进入时调用，用于初始化资源 |
|
||
| `onExit()` | 场景退出时调用，用于清理资源 |
|
||
| `onUpdate(dt)` | 每帧更新时调用，用于处理游戏逻辑 |
|
||
| `onRender(renderer)` | 渲染时调用，用于自定义绘制 |
|
||
|
||
### 3. 坐标空间
|
||
|
||
Extra2D 支持三种坐标空间：
|
||
|
||
```cpp
|
||
// 屏幕空间 - 固定位置，不随相机移动
|
||
text->withCoordinateSpace(CoordinateSpace::Screen)
|
||
->withScreenPosition(640.0f, 360.0f);
|
||
|
||
// 相机空间 - 跟随相机但保持相对偏移
|
||
text->withCoordinateSpace(CoordinateSpace::Camera)
|
||
->withCameraOffset(50.0f, 50.0f);
|
||
|
||
// 世界空间 - 随相机移动（默认行为）
|
||
text->withCoordinateSpace(CoordinateSpace::World)
|
||
->withPosition(100.0f, 100.0f);
|
||
```
|
||
|
||
### 4. 输入处理
|
||
|
||
支持手柄输入检测：
|
||
|
||
```cpp
|
||
auto &input = Application::instance().input();
|
||
|
||
// 检测按键按下（持续触发）
|
||
if (input.isButtonDown(GamepadButton::A)) { }
|
||
|
||
// 检测按键按下（单次触发）
|
||
if (input.isButtonPressed(GamepadButton::A)) { }
|
||
|
||
// 检测按键释放
|
||
if (input.isButtonReleased(GamepadButton::A)) { }
|
||
```
|
||
|
||
常用按键：
|
||
- `GamepadButton::A` - A 键
|
||
- `GamepadButton::B` - B 键
|
||
- `GamepadButton::X` - X 键
|
||
- `GamepadButton::Y` - Y 键
|
||
- `GamepadButton::Start` - + 键 (Switch)
|
||
- `GamepadButton::DPadUp/Down/Left/Right` - 方向键
|
||
|
||
### 5. 资源加载
|
||
|
||
通过资源管理器加载字体、纹理等资源：
|
||
|
||
```cpp
|
||
auto &resources = Application::instance().resources();
|
||
|
||
// 加载字体
|
||
auto font = resources.loadFont("assets/font.ttf", 48, true);
|
||
|
||
// 加载纹理
|
||
auto texture = resources.loadTexture("assets/image.png");
|
||
```
|
||
|
||
### 6. 日志系统
|
||
|
||
使用宏进行日志输出：
|
||
|
||
```cpp
|
||
E2D_LOG_DEBUG("调试信息");
|
||
E2D_LOG_INFO("普通信息");
|
||
E2D_LOG_WARN("警告信息");
|
||
E2D_LOG_ERROR("错误信息");
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- [02. 场景系统](./02_Scene_System.md) - 深入了解场景管理
|
||
- [03. 节点系统](./03_Node_System.md) - 学习节点和精灵的使用
|