西风逍遥游
ede37ca479
- Updated `.gitignore` to reflect changes in documentation generation commands. - Modified `CMakeLists.txt` to set a new version format and streamline documentation handling by adding a subdirectory for docs. - Removed the outdated `Doxyfile` and replaced it with a new configuration in `docs/Doxyfile.in`. - Updated README files to reference the new documentation structure and generation process. - Deleted unused `imgui.ini` and API conventions documentation file to clean up the repository.
39 lines
2.0 KiB
Markdown
39 lines
2.0 KiB
Markdown
# API 使用约定
|
||
|
||
## 模块和辅助对象
|
||
|
||
EVEngine 把脚本 API 放在全局 `eve` 表中。`eve.Physics()`、`eve.Audio()` 这类构造器返回模块对象；模块再创建 `World`、`Body`、`Source` 等辅助对象。模块手册的“API 快查”同时列出模块和辅助对象方法，调用时必须先从相应工厂取得对象。
|
||
|
||
```squirrel
|
||
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`：
|
||
|
||
```squirrel
|
||
try {
|
||
level <- map.newLayerFromFile("maps/level.json");
|
||
} catch (e) {
|
||
print("load level failed: " + e + "\n");
|
||
level <- map.newLayer(20, 12, 32, 32);
|
||
}
|
||
```
|