322 lines
12 KiB
Markdown
322 lines
12 KiB
Markdown
|
# Extra2D 模块化脚本系统融合方案
|
|||
|
|
|
|||
|
|
结合 **Yosin 的配置驱动脚本加载** 和 **Kiwano 的模块系统**，为 Extra2D 实现一个强大的模块化 Squirrel 脚本架构。
|
|||
|
|
|
|||
|
|
## 融合架构设计
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Extra2D.exe (C++ 引擎) │
|
|||
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ Application (单例) │ │
|
|||
|
|
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
|
|||
|
|
│ │ │ ModuleList (模块列表) │ │ │
|
|||
|
|
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │
|
|||
|
|
│ │ │ │ ScriptModule│ │ AudioModule │ │ PhysicsModule │ │ │ │
|
|||
|
|
│ │ │ │ (脚本系统) │ │ (音频系统) │ │ (物理系统) │ │ │ │
|
|||
|
|
│ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ │
|
|||
|
|
│ │ └─────────────────────────────────────────────────────────┘ │ │
|
|||
|
|
│ │ │ │
|
|||
|
|
│ │ - Run() - 运行应用 │ │
|
|||
|
|
│ │ - Use(Module&) - 注册模块 │ │
|
|||
|
|
│ │ - Update(dt) - 更新所有模块 │ │
|
|||
|
|
│ │ - Render() - 渲染所有模块 │ │
|
|||
|
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ ScriptModule (脚本模块) │
|
|||
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ Squirrel VM │ │
|
|||
|
|
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
|
|||
|
|
│ │ │ ScriptConfig.cfg (配置驱动) │ │ │
|
|||
|
|
│ │ │ - 定义脚本加载顺序 │ │ │
|
|||
|
|
│ │ │ - 定义模块依赖关系 │ │ │
|
|||
|
|
│ │ └─────────────────────────────────────────────────────────┘ │ │
|
|||
|
|
│ │ │ │
|
|||
|
|
│ │ 加载流程: │ │
|
|||
|
|
│ │ 1. 加载 Core 层 (基础工具类) │ │
|
|||
|
|
│ │ 2. 加载 Engine 层 (引擎封装类) │ │
|
|||
|
|
│ │ 3. 执行 User/main.nut (用户入口) │ │
|
|||
|
|
│ │ │ │
|
|||
|
|
│ │ 每帧调用: │ │
|
|||
|
|
│ │ - OnUpdate(dt) -> 调用脚本的 update 函数 │ │
|
|||
|
|
│ │ - OnRender() -> 调用脚本的 render 函数 │ │
|
|||
|
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Squirrel 脚本层 │
|
|||
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|||
|
|
│ │ Core/ │ │ Engine/ │ │ User/ │ │ Modules/ │ │
|
|||
|
|
│ │ │ │ │ │ │ │ │ │
|
|||
|
|
│ │ _init.nut │ │ _init.nut │ │ main.nut │ │ ui.nut │ │
|
|||
|
|
│ │ class.nut │ │ app.nut │ │ stages/ │ │ network.nut │ │
|
|||
|
|
│ │ array.nut │ │ director.nut│ │ objects/ │ │ ... │ │
|
|||
|
|
│ │ math.nut │ │ stage.nut │ │ ui/ │ │ │ │
|
|||
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心组件设计
|
|||
|
|
|
|||
|
|
### 1. Module 基类（来自 Kiwano）
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
// base/module.h
|
|||
|
|
class Module {
|
|||
|
|
public:
|
|||
|
|
virtual void setupModule(); // 初始化
|
|||
|
|
virtual void destroyModule(); // 销毁
|
|||
|
|
virtual void onUpdate(float dt); // 更新
|
|||
|
|
virtual void onRender(); // 渲染
|
|||
|
|
virtual void handleEvent(Event* evt); // 事件
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. ScriptModule（脚本模块）
|
|||
|
|
|
|||
|
|
```cpp
|
|||
|
|
// script/script_module.h
|
|||
|
|
class ScriptModule : public Module {
|
|||
|
|
public:
|
|||
|
|
void setupModule() override {
|
|||
|
|
// 1. 初始化 Squirrel VM
|
|||
|
|
vm_ = sq_open(1024);
|
|||
|
|
|
|||
|
|
// 2. 注册 C++ 绑定
|
|||
|
|
registerBindings(vm_);
|
|||
|
|
|
|||
|
|
// 3. 读取 ScriptConfig.cfg
|
|||
|
|
auto config = loadConfig("scripts/ScriptConfig.cfg");
|
|||
|
|
|
|||
|
|
// 4. 按顺序加载脚本
|
|||
|
|
for (auto& path : config.preload) {
|
|||
|
|
executeFile(path);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 5. 调用 main 函数
|
|||
|
|
callMainFunction();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
void onUpdate(float dt) override {
|
|||
|
|
// 调用脚本的全局 update 函数
|
|||
|
|
callScriptFunction("onUpdate", dt);
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 脚本配置系统（来自 Yosin）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
# scripts/ScriptConfig.cfg
|
|||
|
|
# 定义脚本加载顺序
|
|||
|
|
|
|||
|
|
# ========== Core 层（基础工具）==========
|
|||
|
|
scripts/core/_init.nut
|
|||
|
|
scripts/core/class.nut
|
|||
|
|
scripts/core/array.nut
|
|||
|
|
scripts/core/table.nut
|
|||
|
|
scripts/core/math.nut
|
|||
|
|
scripts/core/string.nut
|
|||
|
|
|
|||
|
|
# ========== Engine 层（引擎封装）==========
|
|||
|
|
scripts/engine/_init.nut
|
|||
|
|
scripts/engine/application.nut
|
|||
|
|
scripts/engine/director.nut
|
|||
|
|
scripts/engine/stage.nut
|
|||
|
|
scripts/engine/node.nut
|
|||
|
|
scripts/engine/sprite.nut
|
|||
|
|
scripts/engine/action.nut
|
|||
|
|
scripts/engine/audio.nut
|
|||
|
|
scripts/engine/input.nut
|
|||
|
|
|
|||
|
|
# ========== User 层（用户逻辑）==========
|
|||
|
|
scripts/user/stages/start_stage.nut
|
|||
|
|
scripts/user/objects/player.nut
|
|||
|
|
scripts/user/ui/main_ui.nut
|
|||
|
|
scripts/user/main.nut # 入口脚本（最后加载）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 脚本类层次结构（来自 Yosin）
|
|||
|
|
|
|||
|
|
```squirrel
|
|||
|
|
// scripts/core/class.nut
|
|||
|
|
// 基础类系统
|
|||
|
|
|
|||
|
|
// scripts/engine/node.nut
|
|||
|
|
class Node {
|
|||
|
|
C_Object = null; // C++ 对象指针
|
|||
|
|
|
|||
|
|
constructor() {
|
|||
|
|
C_Object = Node_Create();
|
|||
|
|
Register_Destruction(C_Object, this);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function setPosition(x, y) {
|
|||
|
|
Node_SetPosition(C_Object, x, y);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function getPosition() {
|
|||
|
|
return Node_GetPosition(C_Object);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// scripts/engine/stage.nut
|
|||
|
|
class Stage extends Node {
|
|||
|
|
constructor() {
|
|||
|
|
C_Object = Stage_Create();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function enter() {
|
|||
|
|
Director_EnterStage(C_Object);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function onUpdate(dt) {
|
|||
|
|
// 子类重写
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// scripts/engine/application.nut
|
|||
|
|
class Application {
|
|||
|
|
title = "Extra2D Game";
|
|||
|
|
width = 1280;
|
|||
|
|
height = 720;
|
|||
|
|
|
|||
|
|
function run(stageClass) {
|
|||
|
|
App_SetTitle(title);
|
|||
|
|
App_SetSize(width, height);
|
|||
|
|
App_Run(stageClass);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. 用户入口脚本（main.nut）
|
|||
|
|
|
|||
|
|
```squirrel
|
|||
|
|
// scripts/user/main.nut
|
|||
|
|
function main(args) {
|
|||
|
|
// 创建应用
|
|||
|
|
local app = Application();
|
|||
|
|
app.title = "My Game";
|
|||
|
|
app.width = 800;
|
|||
|
|
app.height = 600;
|
|||
|
|
|
|||
|
|
// 运行开始舞台
|
|||
|
|
app.run(StartStage);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 定义开始舞台
|
|||
|
|
class StartStage extends Stage {
|
|||
|
|
function onEnter() {
|
|||
|
|
// 创建精灵
|
|||
|
|
local sprite = Sprite("assets/logo.png");
|
|||
|
|
sprite.setPosition(400, 300);
|
|||
|
|
this.addChild(sprite);
|
|||
|
|
|
|||
|
|
// 创建 UI
|
|||
|
|
local ui = MainUI();
|
|||
|
|
this.addChild(ui);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function onUpdate(dt) {
|
|||
|
|
// 每帧更新
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 实现步骤
|
|||
|
|
|
|||
|
|
### 阶段 1: 基础架构
|
|||
|
|
|
|||
|
|
1. 创建 `base/module.h/cpp`（Kiwano 风格）
|
|||
|
|
2. 修改 `Application` 支持模块注册
|
|||
|
|
3. 实现模块生命周期管理
|
|||
|
|
|
|||
|
|
### 阶段 2: 脚本模块
|
|||
|
|
|
|||
|
|
1. 创建 `script/script_module.h/cpp`
|
|||
|
|
2. 实现配置解析（`ScriptConfig.cfg`）
|
|||
|
|
3. 实现脚本加载器
|
|||
|
|
|
|||
|
|
### 阶段 3: C++ 绑定扩展
|
|||
|
|
|
|||
|
|
1. 扩展 `Node` 绑定（添加 `C_Object` 指针桥接）
|
|||
|
|
2. 添加 `Stage` 类绑定
|
|||
|
|
3. 添加 `Director` 类绑定
|
|||
|
|
4. 添加 `Application` 配置绑定
|
|||
|
|
|
|||
|
|
### 阶段 4: 脚本类库
|
|||
|
|
|
|||
|
|
1. 创建 `scripts/core/` 基础工具
|
|||
|
|
2. 创建 `scripts/engine/` 引擎封装
|
|||
|
|
3. 实现类继承机制
|
|||
|
|
|
|||
|
|
### 阶段 5: 入口机制
|
|||
|
|
|
|||
|
|
1. 实现 `main()` 函数自动调用
|
|||
|
|
2. 实现 `GameWindow` 封装类
|
|||
|
|
3. 创建示例项目
|
|||
|
|
|
|||
|
|
## 文件变更清单
|
|||
|
|
|
|||
|
|
### 新增文件
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/extra2d/base/module.h
|
|||
|
|
src/extra2d/base/module.cpp
|
|||
|
|
src/extra2d/script/script_module.h
|
|||
|
|
src/extra2d/script/script_module.cpp
|
|||
|
|
src/extra2d/script/sq_binding_stage.cpp
|
|||
|
|
src/extra2d/script/sq_binding_director.cpp
|
|||
|
|
scripts/ScriptConfig.cfg
|
|||
|
|
scripts/core/_init.nut
|
|||
|
|
scripts/core/class.nut
|
|||
|
|
scripts/engine/_init.nut
|
|||
|
|
scripts/engine/application.nut
|
|||
|
|
scripts/engine/director.nut
|
|||
|
|
scripts/engine/stage.nut
|
|||
|
|
scripts/user/main.nut
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 修改文件
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/extra2d/app/application.h/cpp
|
|||
|
|
src/extra2d/script/script_engine.cpp
|
|||
|
|
src/extra2d/script/sq_binding_node.cpp
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 最终效果
|
|||
|
|
|
|||
|
|
用户只需编写脚本即可创建完整游戏：
|
|||
|
|
|
|||
|
|
```squirrel
|
|||
|
|
// 纯脚本游戏
|
|||
|
|
function main() {
|
|||
|
|
local app = Application();
|
|||
|
|
app.config({
|
|||
|
|
title = "Hello World",
|
|||
|
|
width = 800,
|
|||
|
|
height = 600
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
local director = Director();
|
|||
|
|
director.enterStage(MyStage());
|
|||
|
|
|
|||
|
|
app.run();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
class MyStage extends Stage {
|
|||
|
|
function onEnter() {
|
|||
|
|
local label = Label("Hello Squirrel!");
|
|||
|
|
label.position = [400, 300];
|
|||
|
|
this.addChild(label);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
请确认此方案后，我将开始
|