226 lines
4.5 KiB
Markdown
226 lines
4.5 KiB
Markdown
# Extra2D 文档索引
|
||
|
||
欢迎来到 Extra2D 文档中心！这里包含了使用 Extra2D 游戏引擎所需的所有文档。
|
||
|
||
## 📚 快速导航
|
||
|
||
### 入门指南
|
||
|
||
| 文档 | 描述 |
|
||
|------|------|
|
||
| [README.md](../README.md) | 项目概述和快速开始 |
|
||
| [Switch 构建指南](./SWITCH_BUILD_GUIDE.md) | Nintendo Switch 平台构建教程 |
|
||
| [PC 构建指南](./PC_BUILD_GUIDE.md) | Windows/Linux/macOS 构建教程 |
|
||
|
||
### API 参考
|
||
|
||
| 文档 | 描述 |
|
||
|------|------|
|
||
| [API 参考文档](./API_REFERENCE.md) | 完整的 API 文档和示例 |
|
||
|
||
### 开发文档
|
||
|
||
| 文档 | 描述 |
|
||
|------|------|
|
||
| [迁移完成记录](./SWITCH_MIGRATION_COMPLETE.md) | 项目迁移历史记录 |
|
||
| [数据存储文档](./DataStore.md) | 数据持久化系统文档 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 选择平台
|
||
|
||
**Nintendo Switch:**
|
||
```bash
|
||
# 设置环境变量
|
||
$env:DEVKITPRO = "C:/devkitPro"
|
||
|
||
# 配置并构建
|
||
xmake f --plat=switch -a arm64
|
||
xmake
|
||
```
|
||
|
||
**Windows PC:**
|
||
```bash
|
||
# 设置环境变量
|
||
$env:VCPKG_ROOT = "C:\vcpkg"
|
||
|
||
# 配置并构建
|
||
xmake f --plat=windows -a x64
|
||
xmake
|
||
```
|
||
|
||
### 2. 运行示例
|
||
|
||
```bash
|
||
# Switch（生成 .nro 文件）
|
||
./build/switch/hello_world.nro
|
||
|
||
# Windows
|
||
./build/windows/hello_world.exe
|
||
```
|
||
|
||
### 3. 开始开发
|
||
|
||
```cpp
|
||
#include <extra2d/extra2d.h>
|
||
|
||
using namespace extra2d;
|
||
|
||
int main() {
|
||
// 初始化
|
||
Logger::init();
|
||
|
||
AppConfig config;
|
||
config.title = "My Game";
|
||
config.width = 1280;
|
||
config.height = 720;
|
||
|
||
auto& app = Application::instance();
|
||
app.init(config);
|
||
|
||
// 创建场景
|
||
auto scene = makePtr<Scene>();
|
||
|
||
// 添加精灵
|
||
auto sprite = Sprite::create("player.png");
|
||
scene->addChild(sprite);
|
||
|
||
// 运行动画
|
||
sprite->runAction(makePtr<MoveTo>(1.0f, Vec2(300, 200)));
|
||
|
||
// 运行
|
||
app.enterScene(scene);
|
||
app.run();
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 核心概念
|
||
|
||
### 应用生命周期
|
||
|
||
```
|
||
main()
|
||
└── Application::init()
|
||
└── Scene::onEnter()
|
||
└── Node::onUpdate() [每帧]
|
||
└── Node::onRender() [每帧]
|
||
└── Scene::onExit()
|
||
```
|
||
|
||
### 场景图结构
|
||
|
||
```
|
||
Scene (场景)
|
||
├── Node (节点)
|
||
│ ├── Sprite (精灵)
|
||
│ ├── Text (文本)
|
||
│ └── CustomNode (自定义节点)
|
||
└── Node
|
||
└── ...
|
||
```
|
||
|
||
### 坐标系统
|
||
|
||
- **原点**: 左上角 (0, 0)
|
||
- **X轴**: 向右为正
|
||
- **Y轴**: 向下为正
|
||
- **单位**: 像素
|
||
|
||
---
|
||
|
||
## 🛠️ 平台差异
|
||
|
||
| 功能 | Switch | PC |
|
||
|------|--------|-----|
|
||
| 窗口 | 固定全屏 | 可调整大小 |
|
||
| 输入 | 手柄/触摸 | 键盘/鼠标/手柄 |
|
||
| 资源路径 | `romfs:/` | `./assets/` |
|
||
| 渲染 | OpenGL ES | OpenGL ES (Angle) |
|
||
|
||
---
|
||
|
||
## 💡 示例代码
|
||
|
||
### 基础示例
|
||
|
||
- [Hello World](../Extra2D/examples/hello_world/main.cpp) - 基础窗口和文本
|
||
- [Collision Demo](../Extra2D/examples/collision_demo/main.cpp) - 碰撞检测
|
||
- [Spatial Index Demo](../Extra2D/examples/spatial_index_demo/main.cpp) - 空间索引
|
||
|
||
### 常用模式
|
||
|
||
**场景切换:**
|
||
```cpp
|
||
auto newScene = makePtr<GameScene>();
|
||
auto transition = makePtr<FadeTransition>(0.5f);
|
||
app.enterScene(newScene, transition);
|
||
```
|
||
|
||
**输入处理:**
|
||
```cpp
|
||
void onUpdate(float dt) {
|
||
auto& input = app.input();
|
||
|
||
if (input.isKeyPressed(Key::Space)) {
|
||
jump();
|
||
}
|
||
|
||
if (input.isButtonPressed(GamepadButton::A)) {
|
||
jump();
|
||
}
|
||
}
|
||
```
|
||
|
||
**资源加载:**
|
||
```cpp
|
||
auto& resources = app.resources();
|
||
auto texture = resources.loadTexture("player.png");
|
||
auto font = resources.loadFont("font.ttf", 24);
|
||
auto sound = resources.loadSound("jump.wav");
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 项目结构
|
||
|
||
```
|
||
Extra2D/
|
||
├── docs/ # 文档
|
||
├── Extra2D/
|
||
│ ├── include/extra2d/ # 头文件
|
||
│ ├── src/ # 源文件
|
||
│ └── examples/ # 示例程序
|
||
├── squirrel/ # Squirrel 脚本引擎
|
||
├── xmake/ # xmake 配置
|
||
│ ├── toolchains/ # 工具链定义
|
||
│ └── targets/ # 构建目标
|
||
├── xmake.lua # 主构建配置
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 相关链接
|
||
|
||
- **GitHub**: https://github.com/ChestnutYueyue/extra2d
|
||
- **Issues**: https://github.com/ChestnutYueyue/extra2d/issues
|
||
- **devkitPro**: https://devkitpro.org/
|
||
- **Switch 开发**: https://switchbrew.org/
|
||
|
||
---
|
||
|
||
## 📝 许可证
|
||
|
||
Extra2D 使用 [MIT 许可证](../LICENSE)。
|
||
|
||
---
|
||
|
||
**最后更新**: 2026年2月10日
|
||
**版本**: 3.1.0
|