Runtime API (agent reference)

Namespace rescripted. Include <ReScripted.h>. C++17. Do not invent parallel names.

Version

RESCRIPTED_VERSION_MAJOR
RESCRIPTED_VERSION_MINOR
RESCRIPTED_VERSION_PATCH
RESCRIPTED_VERSION_STRING
rescripted::version(); // const char*

Language

static Language compile(std::string_view json_text);

Parses JSON and digests fields the engine needs. Throws Error if the root is not an object or name is missing / still <LANGUAGE_NAME>. Throws ParseError if JSON is invalid.

const std::string& name() const;
const std::vector<std::string>& extensions() const;
bool matches_path(std::string_view path) const;
const json::Value& definition() const; // full DOM

json::Value is ReScripted’s small JSON DOM ([] by key or index, as_bool, as_string, as_array, as_object). Use it if you must inspect the compiled config. Do not replace it with nlohmann in the amalgamated header.

Macro:

engine.add_language(RESCRIPTED_LANGUAGE(R"json({ "name": "X", "extensions": [".x"] })json"));

Engine

Constructs with default host functions: print, len, str, type. print concatenates with spaces and returns that string; it does not write stdout unless the host rebinds it.

Languages

void add_language(Language language);
void remove_language(std::string_view name);
bool has_language(std::string_view name) const;
const Language& language(std::string_view name) const; // throws Error if missing

Host bindings

using HostFn = std::function<Value(const std::vector<Value>&)>;
using DecoratorFn = std::function<void(const std::string& target, const Value& value)>;

void bind(std::string name, HostFn fn);
void unbind(std::string_view name);
void bind_type(std::string name, HostFn construct); // also bind()s the same name
void bind_decorator(std::string name, DecoratorFn fn);
void add_library(std::string import_name, Library lib);
void add_library(std::string import_name, std::map<std::string, HostFn> members);
void add_library(std::string import_name, std::map<std::string, Value> members);
void add_library(std::string import_name, std::string source, std::string_view language_name);
void add_library(std::string import_name, std::string path);
void add_library_file(std::string import_name, std::string script_path);
void remove_library(std::string_view import_name);
bool has_library(std::string_view import_name) const;
void add_search_path(std::string path);
void set_plugin_entry(std::string name);
void load_plugin(const std::string& path);
void load_plugin(const std::string& path, std::string entry_name);

The host chooses every import name. CMake only compiles sources. See libraries.md and ../user/libraries.md.

Decorator hooks run at load time for each decorated function, not at call time.

import resolves registered libraries first, then files. File search order: importer directory, ., imports.search_directories, then add_search_path (a.b.c → a/b/c + language extension).

Scripts

using ScriptId = std::size_t;

ScriptId load(std::string source, std::string script_name, std::string_view language_name);
ScriptId load_file(const std::string& path, std::string_view language_name = {});
void unload(ScriptId id);
void unload(std::string_view script_name);
Value run(ScriptId id);
Value run(std::string_view script_name);
Value run_file(const std::string& path, std::string_view language_name = {});
Value eval(std::string_view source, std::string_view language_name);
Value call(std::string_view function_name, const std::vector<Value>& args = {});
const Value* get(std::string_view name) const;
Environment& globals() noexcept;

load_file without a language name picks the first compiled language whose extensions match the path suffix.

load parses and registers fn / custom function-kind / type-first function declarations so call works before run. Top-level let, assignments, class/actor bodies, and import execute on run. After run, call("OnSpawn") finds a top-level function or an instance method of that name.

Imported script modules do not dump their names onto engine globals until import binds them (bind_as). Host bind / add_library names stay for the life of the engine.

eval = load + run + unload.

unload removes that script’s function and var names from globals.

run_file loads and runs but does not unload.

Typical host sequence

engine.add_language(Language::compile(kJson));
engine.bind("log", ...);
auto id = engine.load_file("ai/guard.mylang");
engine.run(id);                       // top-level setup
auto v = engine.call("update", {});
engine.unload(id);                    // hot-reload: load again after

What does not exist

Do not generate: