API 使用约定

模块和辅助对象

EVEngine 把脚本 API 放在全局 eve 表中。eve.Physics()、eve.Audio() 这类构造器返回模块对象；模块再创建 World、Body、Source 等辅助对象。模块手册的“API 快查”同时列出模块和辅助对象方法，调用时必须先从相应工厂取得对象。

local physics = eve.Physics();                 // 模块
local world = physics.newWorld(0, 980, true); // World
local body = world.newBody("dynamic", 0, 0); // Body

load.nut 已为常用模块创建 gfx、window、keyboard、mouse、event、timer、map、particles、physics、ui 等全局实例。手动构造模块适用于独立脚本和需要明确依赖的代码。

API 的可信边界

脚本能调用的方法以各模块 expose(...) 中的 addFunc、addVar 和脚本注入类为准，而不是以 C++ 头文件中的所有 public 方法为准。例如 Image 的部分 C++ 解码方法当前没有暴露给 Squirrel。模块手册的 API 快查来自实际绑定；方法的参数顺序、默认值和返回类型可继续查看链接的头文件与测试。

生命周期和所有权

将模块创建的世界、纹理、声音、发射器、场景宿主等对象保存在全局状态或实体组件中。
不要在 eve_render() 中重复载入磁盘资源或创建长期对象。
update(dt) 使用秒为单位；物理模块对外使用像素坐标。
输入和网络事件应在更新阶段消费，绘制调用放在渲染阶段。
热重载会重新执行脚本顶层代码，使用 if (!("name" in getroottable())) 保护需要保留的引用。

错误处理

无效枚举字符串、越界索引、空对象或后端未初始化通常会抛出 Squirrel 异常。开发阶段应让异常直接暴露；对可恢复的资源加载可以使用 Squirrel 的 try / catch：

try {
    level <- map.newLayerFromFile("maps/level.json");
} catch (e) {
    print("load level failed: " + e + "\n");
    level <- map.newLayer(20, 12, 32, 32);
}