akbasic/docs/10-embedding.md

10. Embedding

The whole design of this interpreter is shaped by one requirement: a game must be able to embed it as a scripting engine without giving up control. That produces four rules, and they explain most of what looks unusual elsewhere in this guide.

1. Nothing in the library terminates the process. Errors come back as akerr_ErrorContext * for you to handle.
2. The interpreter owns no window, no renderer and no event loop. It draws through whatever you already created.
3. It never blocks. SLEEP, GETKEY, PLAY and WAIT hold the program without holding your frame rate.
4. You can bound it. A script with 10 GOTO 10 cannot take your game with it.

Linking

add_subdirectory(deps/akbasic EXCLUDE_FROM_ALL)
target_link_libraries(YOUR_GAME PRIVATE akbasic::akbasic)

Target	What it is	Link it?
akbasic	The interpreter. No SDL, nothing that exits.	Always
akbasic_akgl	The graphics, sound, input and sprite backends, drawing through your renderer	If you want them
akbasic_frontend	The standalone program's host: creates the window, owns the loop	No. You are the host

The shortest useful host

#include <akbasic/runtime.h>
#include <akbasic/sink.h>

static akbasic_Runtime RUNTIME;      /* too big for a stack */
static akbasic_TextSink SINK;
static akbasic_StdioSink SINKSTATE;

akerr_ErrorContext AKERR_NOIGNORE *run_script(const char *source)
{
    PREPARE_ERROR(e);

    PASS(e, akbasic_sink_init_stdio(&SINK, &SINKSTATE, stdout, NULL));
    PASS(e, akbasic_runtime_init(&RUNTIME, &SINK));
    PASS(e, akbasic_runtime_load(&RUNTIME, source));
    PASS(e, akbasic_runtime_start(&RUNTIME, AKBASIC_MODE_RUN));

    while ( RUNTIME.mode != AKBASIC_MODE_QUIT ) {
        PASS(e, akbasic_runtime_settime(&RUNTIME, your_clock_ms()));
        PASS(e, akbasic_runtime_run(&RUNTIME, 256));   /* 256 steps, then return */
        your_draw_a_frame();
    }
    SUCCEED_RETURN(e);
}

akbasic_runtime_run(rt, n) runs at most n steps and returns. That bound is what keeps a runaway script from owning your process.

The source you hand akbasic_runtime_load() does not need line numbers. A game script is written in a text editor and branches by LABEL, so numbering its lines is work with nothing on the other end of it:

static const char *SCRIPT =
    "PRINT \"SPAWNING\"\n"
    "FOR I# = 1 TO HEALTH#\n"
    "  PRINT I#\n"
    "NEXT I#\n"
    "GOTO DONE\n"
    "PRINT \"NOT REACHED\"\n"
    "LABEL DONE\n"
    "PRINT \"READY\"\n";

Lines that carry a number are filed under it and lines that do not are given the next one going, so the two can be mixed and a numbered script still loads exactly as it did. What a script may not do is GOTO 100 when nothing wrote a line 100 — the interpreter refuses that before the first line runs rather than branching somewhere plausible and wrong.

akbasic_runtime_settime() is how the interpreter knows what time it is. It reads no clock of its own, because it owns no loop. If you never call it, every duration expires immediately — audible, but never a hang.

Exchanging variables with a script

Use akbasic_runtime_global(). It finds or creates the variable in the script's outermost scope, which is the only place both of you can reliably see:

akbasic_Variable *health = NULL;
int64_t subscript[1] = { 0 };

PASS(e, akbasic_runtime_global(&RUNTIME, "HEALTH#", &health));
PASS(e, akbasic_variable_set_integer(health, 100, subscript, 1));

Do not reach for akbasic_environment_get(). A script suspended part-way through a bounded run is usually inside a FOR or GOSUB body, and a variable created there dies when the body pops — silently, with the script reading it correctly right up until it stops.

Calling a function every frame

akbasic_runtime_call_function() calls a DEF by name with values you already hold — the entry point a game loop wants. A host that calls it repeatedly signs up for three rules the one-shot examples never meet:

CATCH(errctx, akbasic_runtime_call_function(&SCRIPT, "THINK", argp, 1, &result));
/* ...consume the result... */
CATCH(errctx, akbasic_environment_zero(SCRIPT.environment));

1. Reset the value scratch after every call, once the result is consumed. Each call parks its result in the caller environment's per-line scratch (AKBASIC_MAX_VALUES slots), and a host calling in a loop never crosses the line boundary that would reset it. Skip the akbasic_environment_zero() and the pool drains — measured at under two frames of forty calls — after which every call fails with Maximum values per line reached. The reset also invalidates result, which is why it comes after the consumption.
2. Force RUN mode once after the boot run. A multi-line DEF body only runs while the runtime is in RUN mode, and by the time a host can call, the program that filed the definitions has ended. One akbasic_runtime_set_mode(&SCRIPT, AKBASIC_MODE_RUN) after akbasic_runtime_run() makes the bodies run, and the mode stays put because nothing steps the runtime between calls. Issue #8 tracks making this unnecessary.
3. Revive after a script error, deliberately. A BASIC-level error inside a called body reports through the sink, answers a stale value, and latches: the runtime leaves RUN mode and every later call does nothing. When your policy is to absorb the error and keep calling — a game marking one actor dumb rather than killing the frame — the revival is two calls: akbasic_runtime_clear_error(), then akbasic_runtime_set_mode(RUN) again. The latch is deliberate for programs — the first error ends a run, once, with one line — so nothing clears it for you.

Do not pass structures as per-frame arguments. A structure or pointer parameter spends a value-pool slot on every call and the pool never reclaims, so the interface dies after about a thousand calls — issue #36 has the measurements. Bind the instance once with akbasic_host_bind() and point it at each object with akbasic_host_rebind() (Chapter 16), which spends nothing per call. The GALAGA tutorial (Chapters 20 and 21) is this whole recipe as a working game, forty calls a frame.

Where the output goes

PRINT writes through an akbasic_TextSink, which is a record of function pointers plus whatever state you hang off self:

typedef struct akbasic_TextSink
{
    void *self;
    akerr_ErrorContext AKERR_NOIGNORE *(*write)(struct akbasic_TextSink *self, const char *text);
    akerr_ErrorContext AKERR_NOIGNORE *(*writeln)(struct akbasic_TextSink *self, const char *text);
    akerr_ErrorContext AKERR_NOIGNORE *(*readline)(struct akbasic_TextSink *self, char *dest, size_t len, bool *eof);
    akerr_ErrorContext AKERR_NOIGNORE *(*clear)(struct akbasic_TextSink *self);
    akerr_ErrorContext AKERR_NOIGNORE *(*moveto)(struct akbasic_TextSink *self, int col, int row);
    akerr_ErrorContext AKERR_NOIGNORE *(*window)(struct akbasic_TextSink *self, int left, int top, int right, int bottom);
    akerr_ErrorContext AKERR_NOIGNORE *(*grid)(struct akbasic_TextSink *self, int *columns, int *rows, int *cellw, int *cellh);
    akerr_ErrorContext AKERR_NOIGNORE *(*graphic)(struct akbasic_TextSink *self, int mode, int split);
} akbasic_TextSink;

akbasic_sink_init_stdio() ships with the library and is what the driver uses. A game supplies its own and draws into a text layer. readline is expected to set *eof rather than block — that is how INPUT behaves sanely inside a frame.

The last four are optional and may be NULL, which is how CHAR, WINDOW, RWINDOW and GRAPHIC know to refuse by name rather than pretending. Supply grid if your text layer has a character cell: it is the only way a script can find out how big one is, and without it anything placing a character and a sprite at the same spot has to hardcode a number measured against your font.

akbasic_sink_init_tee() also ships, and composes two sinks into one: writes go to both, and readline comes from whichever of the two you name as the reader. That is how the SDL build puts PRINT in a window and on stdout. It needs no SDL, so you can use it to log a script's output to a file while you draw.

Lending devices

PASS(e, akbasic_runtime_set_devices(&RUNTIME, &graphics, &audio, &input, &sprites));
PASS(e, akbasic_runtime_set_ui(&RUNTIME, &ui));

The fifth one is set on its own rather than as a fifth argument to the first, because that signature predates it and had twenty-eight call sites that do not care about menus.

Any of them may be NULL, and that is how you withhold a capability: a script given no audio backend gets an error from SOUND rather than silence. Each is a record of function pointers, so you can supply your own and never link the graphics library at all.

akbasic_akgl provides implementations that draw through a renderer you created:

PASS(e, akbasic_graphics_init_akgl(&graphics, &gstate, my_renderer));
PASS(e, akbasic_sprite_init_akgl(&sprites, &sstate, my_renderer, &gstate));

Sprites become real actors in your registry, so your game can see them.

Where a script's errors go

A BASIC-level error is reported through the sink and stops the script; it does not come back to you as a failure. What comes back to you is an error in the interpreter — pool exhaustion, a NULL argument — which is yours to handle.

That is the split to hold on to: a script's mistakes are the script's problem, and your program keeps running.

Threads

One runtime belongs to one thread, and there is no lock anywhere in this interpreter. An akbasic_Runtime is a large struct of fixed pools mutated in place by every step, so two threads calling akbasic_runtime_step() on the same runtime will corrupt it. If your game is threaded, drive the script from whichever thread owns it and hand results across yourself.

Two runtimes on two threads are fine — they share no state. What they do share is libakerror's error pool and status registry, and those became thread safe in 2.0.0, so raising, handling and releasing errors from either thread is safe with no coordination from you. One error context still belongs to the thread that raised it; passing one to another thread is your synchronization.

Call akbasic_error_register() once, during single-threaded startup, before you spawn anything. It is idempotent and safe to repeat, but registering a status name while another thread looks one up is the single registry operation no lock can make safe.

Reading it all

Two complete hosts are checked in and built by every build, so neither can rot: examples/embed.c runs a script a bounded number of steps at a time, and examples/hostvars.c passes integers, floats and strings in both directions. The full API surface is the headers under include/akbasic/, which doxygen Doxyfile renders; the pool limits are the table at the end of Chapter 13.