Loading scripts

A script is a text file. You load it, use it, and throw it away. You do not rebuild C++.

auto id = engine.load_file("ai/guard.mini");
engine.run(id);
auto result = engine.call("think", {rescripted::Value("player")});
engine.unload(id);

.mini picks the language, because you registered a language with that extension.

What each call does

Take this file:

let greeting = "hello";

fn shout(name) {
    return "hey " + name;
}

print(greeting);

load / load_file parses the text. After this:

shout exists. engine.call("shout", ...) works.
greeting does not exist yet.
print(greeting) has not run.

run executes the top of the file. After this:

greeting is "hello".
print has run.
type blocks like entity Hero { ... } become maps.

unload removes that script’s functions and variables. shout and greeting are gone. print from bind stays.

load returns a ScriptId (std::size_t). run and unload also accept the script name you passed — for a file, that is the path.

eval and run_file

engine.eval("print(1);", "Mini");     // load + run + unload
engine.run_file("intro.mini");        // load + run, leave it loaded

Use eval for a snippet. Use load / run / unload when the file should stay — AI, a UI theme, a console.

Which language?

load_file("ai/guard.mini") with no language name walks the languages you added and uses the first whose extensions match. If none match, you get an error.

Pass the name when two languages share a suffix, or the file has no suffix:

engine.load_file("ai/guard", "Mini");

load(source, "guard", "Mini") is the same for a string you already have in memory.

Hot reload

engine.unload("scripts/ai.mini");
auto id = engine.load_file("scripts/ai.mini");
engine.run(id);

That re-reads the file from disk. You decide when to call it (file watcher, console command, editor save).

Names after run

Top-level lets stay on the engine until unload. A later call can see them.

A let inside { } dies at the end of the block. Functions do not remember those inner names.

engine.get("greeting") returns a pointer to a top-level value, or nullptr.

Errors

Exception	When
`rescripted::ParseError`	bad JSON or bad script syntax; `line()`, `column()`, `what()`
`rescripted::RuntimeError`	unknown name, bad call, division by zero, wrong `Value` conversion
`rescripted::Error`	unknown language, missing file, missing script — and the two above inherit this

All of them are std::runtime_error. Catch Error to handle every ReScripted failure.

A script can loop forever or allocate until memory runs out. ReScripted does not add quotas. Treat untrusted text as untrusted code in your process.