Extra2D/docs/ScriptModule_Usage.md

Extra2D ScriptModule 使用指南

快速开始

1. 在 C++ 中注册 ScriptModule

#include <extra2d/extra2d.h>

int main(int argc, char** argv) {
    // 初始化日志
    Logger::init();
    
    // 配置应用
    AppConfig config;
    config.title = "Script Game";
    config.width = 1280;
    config.height = 720;
    
    // 初始化应用
    auto& app = Application::instance();
    if (!app.init(config)) {
        return -1;
    }
    
    // 注册 ScriptModule
    auto scriptModule = makePtr<ScriptModule>();
    app.use(scriptModule);
    
    // 运行应用
    app.run();
    
    return 0;
}

2. 创建脚本配置文件

创建 scripts/ScriptConfig.cfg:

# 预加载脚本列表
scripts/core/_init.nut
scripts/core/class.nut
scripts/core/math.nut

# 入口脚本
entry: scripts/user/main.nut

3. 编写游戏脚本

创建 scripts/user/main.nut:

// 游戏入口
function main(args) {
    print("Game started!");
    
    // 创建场景
    local scene = Scene();
    scene.setBackgroundColor(0.1, 0.1, 0.3, 1.0);
    
    // 进入场景
    Director.enterScene(scene);
}

// 每帧更新
function onUpdate(dt) {
    // 游戏逻辑
}

// 每帧渲染
function onRender() {
    // 渲染逻辑
}

// 启动游戏
main([]);

脚本类库

Core 层工具

类系统

// 定义类
local MyClass = class(null);
MyClass.value <- 0;

MyClass.constructor <- function(v) {
    this.value = v;
}

MyClass.getValue <- function() {
    return this.value;
}

// 创建实例
local obj = MyClass.new(42);
print(obj.getValue());  // 输出: 42

数学工具

// 向量
local v1 = Vector2(100, 200);
local v2 = Vector2(50, 50);
local v3 = v1.add(v2);

// 插值
local value = lerp(0, 100, 0.5);  // 50

// 限制
local clamped = clamp(value, 0, 100);

配置格式

ScriptConfig.cfg

# 注释以 # 开头

# 预加载脚本（按顺序加载）
scripts/core/_init.nut
scripts/core/class.nut
scripts/core/array.nut
scripts/core/math.nut
scripts/core/string.nut
scripts/core/table.nut

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

# 用户脚本
scripts/user/stages/start_stage.nut
scripts/user/objects/player.nut
scripts/user/ui/main_ui.nut

# 入口脚本（最后加载，必须包含 main 函数）
entry: scripts/user/main.nut

API 参考

ScriptModule C++ API

// 创建模块
auto scriptModule = makePtr<ScriptModule>();

// 加载配置
scriptModule->loadConfig("path/to/config.cfg");

// 执行脚本
scriptModule->executeFile("script.nut");
scriptModule->executeString("print('Hello')");

// 调用脚本函数
scriptModule->callFunction("onUpdate", 0.016f);

// 获取 Squirrel VM
HSQUIRRELVM vm = scriptModule->getVM();

全局函数

脚本中可以使用的全局函数：

// 日志
print("message");           // 输出到控制台
log("message");             // 输出到日志系统

// 数学
sqrt(x);                    // 平方根
abs(x);                     // 绝对值
sin(x); cos(x); tan(x);     // 三角函数
rand();                     // 随机数

示例项目

参见 examples/script_demo/ 目录获取完整示例。