Skip to content
NovaMark 文档
API 参考
C API 参考

C API 参考

NovaMark 提供 C 语言接口，便于与游戏引擎集成。

头文件 

#include "nova/renderer/nova_c_api.h"

生命周期管理

nova_create 

NovaVM* nova_create();

创建 VM 实例。

返回值: VM 实例指针，失败返回 NULL。

nova_destroy 

void nova_destroy(NovaVM* vm);

销毁 VM 实例并释放所有资源。

游戏加载

nova_load_package 

int nova_load_package(NovaVM* vm, const char* path);

从文件加载游戏包。

参数:

  • vm - VM 实例
  • path - .nvmp 文件路径

返回值: 成功返回 1，失败返回 0。使用 nova_get_error() 获取错误详情。

nova_load_from_buffer 

int nova_load_from_buffer(NovaVM* vm, const unsigned char* data, size_t size);

从内存缓冲区加载游戏包。

游戏控制

nova_advance 

void nova_advance(NovaVM* vm);

推进到下一个离散阻塞点（如对话、选择或结局）。

nova_choose 

void nova_choose(NovaVM* vm, const char* choiceId);

选择选项。

参数:

  • vm - VM 实例
  • choiceId - 要选择的选项 ID

状态获取

nova_get_state 

NovaState nova_get_state(NovaVM* vm);

获取当前渲染状态。

返回值: 包含所有渲染信息的 NovaState 结构体。

nova_get_error 

const char* nova_get_error(NovaVM* vm);

获取最后的错误信息。

运行时状态快照

当前 Web/WASM 扩展接口提供统一运行时状态导出：

const char* nova_export_runtime_state_json(void* vm, size_t* outSize);

该接口返回 JSON 字符串，包含：

  • textConfig
  • variables
  • inventory
  • itemDefinitions
  • characterDefinitions
  • inventoryItems

适合 GUI 与调试工具一次性读取完整运行时状态。

AST 快照导出

当前 C API 也提供 AST 快照导出接口：

char* nova_export_ast_snapshot_from_path(const char* path);
char* nova_export_ast_snapshot_from_scripts(const NovaMemoryScript* scripts, size_t count);

这两个接口返回 AST JSON 字符串，适合：

  • 编辑器 / Creator 可视化语法树
  • 调试脚本解析结果
  • 多文件项目合并结果检查

其中：

  • nova_export_ast_snapshot_from_path：从项目路径导出
  • nova_export_ast_snapshot_from_scripts：从内存脚本数组导出

如果文本中使用了 {{}} 插值或 {style:text} 内联样式，导出的 AST 快照中会保留对应的文本分段信息。

回调

nova_set_state_callback 

void nova_set_state_callback(NovaVM* vm, NovaStateCallback callback, void* userData);

typedef void (*NovaStateCallback)(NovaState state, void* userData);

设置状态变化时的回调函数。

存档

NovaMark 当前将存档分为两层：

  • 正式文件存档：使用二进制格式，供玩家和产品环境使用
  • JSON 导入导出：保留给 Web/WASM 调试、测试和开发工具使用

此外，运行时现在支持一种仅导入多周目继承数据的能力：

  • 只恢复已经触发过的结局（ending 历史）
  • 只恢复已经设置过的标记（flag 历史）
  • 不会恢复变量、背包、当前场景、对话、背景音乐等运行时现场

这适合：

  • 新周目继承历史结局解锁状态
  • 跨设备同步已解锁结局/关键标记
  • 成就或图鉴系统恢复历史进度，但不打断当前游玩现场

nova_save_snapshot_file 

int nova_save_snapshot_file(NovaVM* vm, const char* path);

将当前运行时快照以二进制格式保存到文件。

nova_load_snapshot_file 

int nova_load_snapshot_file(NovaVM* vm, const char* path);

从二进制快照文件恢复运行时状态。

仅导入多周目进度（桥接/宿主层）

在 NAPI/宿主桥接层，现已提供两种"只导入结局和标记"的接口：

runtimeImportPlaythroughJson(vmHandle, saveJson)
runtimeImportPlaythroughBinary(vmHandle, saveBuffer)

语义说明：

  • 输入仍然是完整存档（JSON 或二进制）
  • 运行时只会提取其中的：
    • triggeredEndings
    • flags
  • 当前 VM 的变量、场景、背包和渲染状态保持不变

这两个接口不会替代普通 runtimeImportSaveJson / runtimeImportSaveBinary，而是提供一个"只同步周目继承数据"的安全选项。

变量和背包

nova_get_variable_count 

size_t nova_get_variable_count(NovaVM* vm);

获取当前变量总数。

nova_get_variable_name 

const char* nova_get_variable_name(NovaVM* vm, size_t index);

按索引获取变量名。

顺序说明：变量名按字典序（升序）排序后返回，索引从 0 开始。

注意事项：

  • 每次调用会重新生成内部缓存
  • 返回的指针在下一次调用该函数后可能失效
  • 如果 index 越界，返回 NULL

nova_get_variable_number 

double nova_get_variable_number(NovaVM* vm, const char* name);

获取数值变量的值。

nova_get_variable_string 

const char* nova_get_variable_string(NovaVM* vm, const char* name);

获取字符串变量的值。

nova_get_inventory_count 

size_t nova_get_inventory_count(NovaVM* vm, const char* itemId);

获取背包中物品的数量。

nova_has_item 

int nova_has_item(NovaVM* vm, const char* itemId);

检查玩家是否拥有某物品。

返回值: 拥有返回 1，否则返回 0。

标志查询（v1.0）

nova_get_flags_count 

size_t nova_get_flags_count(NovaVM* vm);

获取已触发标志的数量。

nova_get_flag 

const char* nova_get_flag(NovaVM* vm, size_t index);

按索引获取标志名称。

注册重载系统（v1.0）

注册重载系统允许宿主在运行时扩展和覆写 NovaMark 的内置函数与状态字段。详见 注册重载系统 文档。

nova_register_function 

int nova_register_function(NovaVM* vm, const char* name,
    NovaFunctionCallback callback, void* userData, int override_);

注册自定义函数。

nova_register_state_field 

int nova_register_state_field(NovaVM* vm, const char* key,
    NovaStateFieldSerializeCb serialize,
    NovaStateFieldDeserializeCb deserialize,
    const char* defaultValueJson,
    void* userData);

注册自定义状态字段。

Last updated on
运行时状态与快照 API