View source for Runtime Script Compilation

OpenBOR can construct and manage complete script programs while a module is running. Source may be loaded from one or more files into an independently owned script object, compiled once, and executed repeatedly on demand. Because the calling script controls its lifecycle and execution, a runtime script can operate as a persistent subsystem without being tied to one of OpenBOR’s predefined events. OpenBOR’s [[File Operations|file operations]] can even generate new source code for compilation, enabling runtime metaprogramming.

Potential uses include:

* Combining movement, combat, and personality packages into specialized AI behavior.
* Loading optional systems only when required by a game mode or campaign.
* Providing development and diagnostic tools that remain unloaded during ordinary play.
* Creating multiple instances of the same behavior with independent persistent state.
* Replacing a subsystem by releasing its handle and compiling a new implementation from different source files.

Runtime compilation is not a single evaluation call. The feature uses an owned script object with a four-stage lifecycle:

# Create the object with <code>allocscript()</code>.
# Load and parse source with <code>loadscript()</code>.
# Compile the accumulated source with <code>compilescript()</code>.
# Run it with <code>executescript()</code>, then release it with <code>[[free()]]</code> when finished.

The resulting handle owns a complete OpenBOR script interpreter and a private local-variable list. Compiled instructions remain available until the handle is freed, so one script can be compiled once and executed many times.

<blockquote>'''Important:''' Runtime scripts execute with the same native script API and engine access as ordinary module scripts. They are not sandboxed. Only compile trusted source.</blockquote>

== Lifecycle ==

{| class="wikitable"
!Stage
!Function
!Result
|- 
|Allocate
|<code>allocscript()</code>
|Creates an owned script object and returns its pointer handle.
|-
|Load
|<code>loadscript()</code>
|Reads a loose or packed source file into memory and parses it into the handle.
|-
|Compile
|<code>compilescript()</code>
|Resolves functions, imports, constants, variables, and jump targets, then runs <code>[[oncreate()]]</code> when present.
|-
|Execute
|<code>executescript()</code>
|Runs top-level immediate code and calls <code>[[main()]]</code>.
|-
|Release
|<code>[[free()]]</code>
|Calls <code>[[ondestroy()]]</code> when present, then releases the interpreter, variables, and handle.
|}

Loading and compilation are separate by design. <code>loadscript()</code> parses source but does not make it executable. <code>compilescript()</code> finalizes the collected instructions into the interpreter's runtime representation. Calling <code>executescript()</code> before successful compilation is invalid.

Once compiled, the same handle may be passed to <code>executescript()</code> repeatedly. Compilation should normally occur only once. Reloading or recompiling a finalized handle is not a supported replacement mechanism - free the old handle and build a new one instead.

== Walk-through ==

Place the following source in <code>data/scripts/runtime_square.c</code>:

<syntaxhighlight lang="c" line="1">
void oncreate()
{
    setlocalvar("execution_count", 0);
}

void main()
{
    int execution_count = getlocalvar("execution_count") + 1;
    int input_value = getglobalvar("runtime.input");

    setlocalvar("execution_count", execution_count);
    setglobalvar("runtime.result", input_value * input_value);
    setglobalvar("runtime.executions", execution_count);
}

void ondestroy()
{
    setglobalvar("runtime.released", 1);
}
</syntaxhighlight>

Another script can load, compile, execute, and release it:

<syntaxhighlight lang="c" line="1">
void run_runtime_example()
{
    void script_handle = allocscript(
        "runtime_square",
        "data/scripts/runtime_square.c"
    );

    loadscript(script_handle, "data/scripts/runtime_square.c");
    compilescript(script_handle);

    setglobalvar("runtime.input", 12);
    executescript(script_handle);

    log("Result: " + getglobalvar("runtime.result") + "\n");
    log("Executions: " + getglobalvar("runtime.executions") + "\n");

    setglobalvar("runtime.input", 25);
    executescript(script_handle);

    log("Result: " + getglobalvar("runtime.result") + "\n");
    log("Executions: " + getglobalvar("runtime.executions") + "\n");

    free(script_handle);
    script_handle = NULL();
}
</syntaxhighlight>

The first execution publishes <code>144</code> and an execution count of <code>1</code>. The second publishes <code>625</code> and an execution count of <code>2</code>. <code>[[free()]]</code> runs <code>[[ondestroy()]]</code>, which sets <code>runtime.released</code> to <code>1</code> before the object is destroyed.

== Execution Model ==

=== Entry Point ===

Every executable runtime script needs a <code>[[main()]]</code> function. <code>executescript()</code> first evaluates top-level immediate code, such as file-scope declarations and initializers, then calls <code>[[main()]]</code> with no parameters.

<code>[[main()]]</code> runs once for every call to <code>executescript()</code>. The function's return value is not exposed to the calling script because <code>executescript()</code> itself does not return the runtime script's result.

=== Passing Data ===

<code>executescript()</code> accepts only the script handle, so arguments cannot be passed directly to <code>[[main()]]</code>. Use shared engine state or global variables to exchange data:

<syntaxhighlight lang="c">
setglobalvar("runtime.input", value);
executescript(script_handle);
void result = getglobalvar("runtime.result");
</syntaxhighlight>

Global variables are visible to both the caller and the runtime script. Namespacing exchange variables reduces accidental collisions with unrelated module code.

=== Persistent State ===

Each script object has its own local-variable list, accessed from inside that script with <code>[[getlocalvar()]]</code> and <code>[[setlocalvar()]]</code>. Values in this list survive repeated calls to <code>executescript()</code> and remain private to the handle.

Ordinary declared variables are part of the interpreter's execution state. Do not rely on them to preserve values between executions. Store persistent values in the local-variable list instead.

The caller cannot target another script handle with <code>[[getlocalvar()]]</code> or <code>[[setlocalvar()]]</code>. Publish values through global variables or another shared engine object when outside code needs them.

=== Lifecycle Callbacks ===

Runtime script objects recognize three special functions:

{| class="wikitable"
!Function
!Invocation
!Purpose
|-
|<code>[[oncreate()]]</code>
|Once, immediately after successful compilation.
|Initialize the object's persistent local state or allocate resources.
|-
|<code>[[main()]]</code>
|Once per <code>executescript()</code> call.
|Perform the runtime script's requested work.
|-
|<code>[[ondestroy()]]</code>
|Once when the handle is released with <code>[[free()]]</code>, or during engine cleanup if it was never freed.
|Release resources owned by the script and perform final bookkeeping.
|}

During <code>[[oncreate()]]</code>, the local variable <code>iscopy</code> is <code>0</code> for a newly compiled runtime script and <code>localclear</code> is <code>1</code>. During <code>ondestroy()</code> for a freed runtime script, <code>localclear</code> is <code>2</code>. OpenBOR clears these temporary local variables after the callback completes.

Keep the handle alive while resources or persistent state are still needed. Do not call <code>[[free()]]</code> on the currently executing handle from inside its own <code>[[main()]]</code>; let the owning script release it after <code>executescript()</code> returns.

== Loading Source ==

<code>loadscript()</code> reads the complete source file into memory. OpenBOR first checks for a loose file at the supplied path, then checks the active packfile. Standard script preprocessing remains available, including macros and supported include or import directives.

One handle may receive more than one <code>loadscript()</code> call before compilation. Each successfully parsed file contributes source to the same interpreter:

<syntaxhighlight lang="c">
void script_handle = allocscript("runtime_module");

loadscript(script_handle, "data/scripts/runtime/common.c");
loadscript(script_handle, "data/scripts/runtime/main.c");

compilescript(script_handle);
executescript(script_handle);
free(script_handle);
</syntaxhighlight>

Every source fragment must parse successfully, and the combined program must compile as one script. Compile only after the final source file has been loaded.

== Generating Source at Runtime ==

[[File Operations|Filestream functions]] can construct a source file before it is loaded. This permits code generation from trusted module data:

<syntaxhighlight lang="c" line="1">
void execute_generated_script()
{
    void source_stream = createfilestream();

    filestreamappend(
        source_stream,
        "void main() { setglobalvar(\"runtime.generated\", 1); }"
    );

    savefilestream(
        source_stream,
        "generated.c",
        "data/generated/"
    );

    closefilestream(source_stream);

    void script_handle = allocscript(
        "generated_runtime_script",
        "data/generated/generated.c"
    );

    loadscript(script_handle, "data/generated/generated.c");
    compilescript(script_handle);
    executescript(script_handle);
    free(script_handle);
}
</syntaxhighlight>

The custom [[File Operations|filestream]] pathname is relative to the engine's working directory, and <code>loadscript()</code> must be able to read the same loose path. Writable locations and working directories can vary by platform and launch environment. Test the complete save-and-load path on every supported target before relying on generated source in a distributed module.

Generated source is code, not ordinary save data. Never construct it from untrusted files, downloaded text, player names, or other uncontrolled input. Runtime scripts have access to the full OpenBOR script API.

== Functions ==

=== allocscript() ===

<syntaxhighlight lang="c">
void script_handle = allocscript(name[, comment]);
</syntaxhighlight>

Allocates a script object and returns its pointer handle. <code>name</code> should be a nonempty string. OpenBOR uses it to identify the interpreter in diagnostic output. The optional <code>comment</code> provides additional diagnostic context and is useful for recording the source path or the system that owns the handle.

Allocation alone does not load, compile, or execute source. The returned object is registered with OpenBOR's managed script heap and remains allocated until passed to <code>[[free()]]</code> or released during engine shutdown.

=== loadscript() ===

<syntaxhighlight lang="c">
loadscript(script_handle, path);
</syntaxhighlight>

Loads and parses the source at <code>path</code> into a handle returned by <code>allocscript()</code>. Loose files take priority over files with the same path in the current packfile.

The function does not compile the source and does not return a success flag to script code. Missing files are not reliably reported through a script-visible result. Parse failures terminate execution with a script error. Use known paths and ship or generate every required source file before calling this function.

=== compilescript() ===

<syntaxhighlight lang="c">
compilescript(script_handle);
</syntaxhighlight>

Finalizes all source previously added to the handle. Compilation resolves native and script functions, imported functions, variables, constants, parameter references, branches, and the special entry points <code>[[main()]]</code>, <code>[[oncreate()]]</code>, and <code>[[ondestroy()]]</code>.

Successful compilation immediately calls <code>[[oncreate()]]</code> when that function exists. Compilation does not produce a script-visible return value. Parse or compile errors are fatal rather than recoverable exceptions.

=== executescript() ===

<syntaxhighlight lang="c">
executescript(script_handle);
</syntaxhighlight>

Executes top-level immediate code and calls <code>[[main()]]</code>. The handle must refer to a successfully compiled script, and the compiled source must provide <code>[[main()]]</code>.

The function accepts no arguments beyond the handle and does not return the value produced by <code>[[main()]]</code>. Use global variables or shared engine state for input and output. Repeated calls reuse the compiled program and the handle's persistent local-variable list.

OpenBOR tracks whether a script interpreter is already executing. Recursive re-entry into the same handle can interfere with its current interpreter state and should be avoided. The <code>nonestedscript</code> setting in <code>data/script.txt</code> can suppress an attempt to execute a script that is already active, but clear ownership and nonrecursive control flow remain preferable.

=== free() ===

<syntaxhighlight lang="c">
free(script_handle);
script_handle = NULL();
</syntaxhighlight>

Releases a runtime script object created by <code>allocscript()</code>. OpenBOR calls <code>[[ondestroy()]]</code> first when it exists, then clears the script's local variables, compiled interpreter, diagnostic comment, and object storage.

The old pointer becomes invalid immediately. Clear every stored copy and never execute, compile, load, or free it again. Engine shutdown releases handles that were not explicitly freed and reports outstanding managed script objects, though explicit ownership is recommended.

== Error Behavior ==

These functions were designed as an advanced engine facility rather than a recoverable evaluator. Their public wrappers do not provide detailed status values:

* <code>loadscript()</code>, <code>compilescript()</code>, and <code>executescript()</code> return no useful result to the calling script.
* Invalid handles cause script-function exceptions.
* Syntax errors are reported while loading and stop the module.
* Compilation errors identify the script name, diagnostic comment, source, line, and column when available, then stop the module.
* Runtime exceptions identify the executing script and the failing native call when available, then stop the module.
* A missing or invalid <code>[[main()]]</code> causes execution to fail.

Runtime compilation is therefore best used with source that has already been validated during development. It is not suitable for probing arbitrary text to discover whether it compiles.

== Practical Guidance ==

* Allocate once, load all source, compile once, and execute as often as needed.
* Give every handle a unique, descriptive name and a useful comment for diagnostics.
* Keep the handle in a global or other long-lived owner when execution spans multiple events.
* Use the handle's local-variable list for private persistent state.
* Use namespaced global variables for arguments and results shared with the caller.
* Free the handle when its compiled code and owned resources are no longer needed.
* Clear every reference after <code>free()</code>; pointer handles are not self-invalidating.
* Avoid recursive execution of the same handle.
* Do not compile on every update tick. Parsing and compilation are setup work, while execution is the reusable stage.
* Treat generated or externally stored source as trusted executable code.
* Test loose-file and writable-path behavior on every target platform when using generated scripts.

== See Also ==

* [[File Operations]]
* [[Script Overview]]
* [[:Category:Script Functions|Script Functions]]
* [[Variables Overview]]
* [[Strings]]

[[Category:Openbor]]
[[Category:Script]]