Where Ready fits: the three phases
A script passes three phases before and while it runs (Core concept): the parser checks the syntax, the binder checks names, types and the calls into plugins, and the runtime checks what can only be checked while running. The plugin lifecycle sits inside the second and at the end of the third phase:
Figure 0 — the plugin lifecycle inside the three phases: Ready at the start of the binder, Deinit at the end of the run.
So a typo in the script is reported before any plugin is touched, and a missing library before a single statement runs: each problem is caught in the earliest phase that can see it.
What happens at startup
Once the parser has accepted the whole script, the binder loads each plugin named in its plugin lines. Right after loading one — before the script’s names and types are checked, before main() — it calls the plugin’s Ready hook. The plugin answers with a constant, READY or NOT_READY, and may add a message.
Figure 1 — the steps; a NOT_READY answer or a plugin that does not fit the line’s condition ends the run before step 3.
A NOT_READY answer is final: the host prints plugin 'Sdl2ImagePlugin' is not ready: followed by the plugin’s own message, and exits with status 1. No statement of the script has run, no file has been touched, nothing is half done. This is the point of the mechanism: a problem that can be found before running is found before running. The old behaviour — a plugin that loaded fine and failed on its first real call, possibly minutes into a run — is gone.
A plugin that has no Ready hook at all (one built against an older plugin header) is treated as not ready too; the message says to rebuild it.
Versions
From 0.1.1 on, versions travel both ways at startup, and each side decides only what it can know (amber in Figure 1).
The host tells the plugin its version when it loads it (step 1). A plugin that needs a newer DominScript says so in its Ready hook — one line, DOMIN_PLUGIN_REQUIRE_HOST(Message, Cap, 0, 2, 0); — and the script does not start: plugin 'X' is not ready: needs DominScript 0.2.0 or newer; this is 0.1.1. The host itself never judges whether a plugin fits it; the plugin knows what it needs.
Every plugin states its own version, and the oldest DominScript it is meant for; a script sees both with plugin.Version(i) and plugin.MinDominVersion(i). A built-in plugin carries the DominScript version.
The script may set a version condition on the plugin line (step 2b), with ==, >=, >, <= or <:
plugin "tls" >= "1.2.0"; // at least 1.2.0 plugin "tls" < "2.0.0"; // and not 2.0 or later: both must hold
The version is written "1", "1.2" or "1.2.0" (a missing part is 0). An exact version is == — a single = assigns in DominScript, and on a plugin line it is refused with that hint; pin an exact version only on purpose, as a fix release of the plugin then stops the script too. The condition is checked right after the plugin loaded and answered READY, before anything runs: a plugin that does not fit stops the script — even though its Ready said yes — with, e.g., plugin 'TlsPlugin' 1.1.0 is older than the script requires: 1.2.0 or newer (net.dom:3). If several lines name the same plugin — also inside an #included file — every condition must hold, and the message names the line of the first one that does not. With --validate it is a warning, as for a NOT_READY plugin: the script is fine, the plugin on this machine does not fit.
A plugin built against an older plugin header states no version, and is refused at load with a message that says how to rebuild it.
Adapters: the library opens in Ready
Most plugins have nothing to check and simply answer READY. The ones that matter are the adapters — plugins that wrap a third-party library at run time: SDL2, SDL2_image, FFmpeg, OpenSSL, SQLite, the MariaDB and PostgreSQL clients, cJSON. Their Ready opens the library, keeps the handle, and answers accordingly.
Figure 2 — an adapter’s Ready: the runtime folder first, then the system; the message names the file and the folder.
The search order is the same for every adapter and is described on the Optional libraries page. What matters here: the message the person reads is written by the plugin at the moment it knows exactly what is missing, so it can say which file and which folder.
Constants and messages are independent
The constant decides; the text informs. A plugin may answer READY and still leave a note — the ffmpeg plugin does, when it was built without decoding support: the script runs, and the host shows plugin 'FfmpegPlugin': decoding is disabled in this build … as a notice. An empty message means nothing to say, and the host stays silent.
| Answer | Message | What the host does |
|---|---|---|
READY | empty | nothing; the script runs |
READY | text | shows it as a notice; the script runs |
NOT_READY | text | refuses to start, quoting the text; exit 1 |
NOT_READY | empty | refuses to start: “the plugin gave no reason” |
domin --validate runs the same check but reports a NOT_READY plugin as a warning, anchored at the plugin line, and still says Validation OK. A script can therefore be checked — and edited in VS Code with live diagnostics — on a machine that lacks the library it will run with elsewhere.
Shutdown and Deinit
At the end of a run — a normal return from main(), a runtime error, or a Stop from the debugger — the host calls each plugin’s Deinit hook, in load order, before unloading the library. The plugin closes what Ready opened and frees what it allocated. Deinit answers with a constant and an optional message in the same way: DEINIT_OK with an empty message is silence; a message is shown as a notice; anything other than OK is reported as a warning on stderr — the script’s exit code is not changed by it, because the script itself did not fail.
How plugins hand data to each other
One plugin per library is a rule with a consequence: a PNG decoded by sdl2_image has to reach a texture owned by sdl2 or open_gl, and the two plugins must not know each other’s internals. DominScript’s answer is the one it gives everywhere: the blob is the interface. The decoder returns a pixel packet — a small fixed header (width, height, stride, format) followed by raw RGBA bytes — and anything that draws pixels accepts that packet.
Figure 3 — producers on the left, consumers on the right, one packet format in the middle; a file, a socket or the script’s own code can be either (the arrows both ways). No handles cross a plugin boundary.
The same packet can be written to a file, sent over a socket, inspected by the script with a struct over the header, or produced by your own code. A plugin you write joins either side of the picture by reading or writing the same bytes.
If you write a plugin
Two functions with fixed names, PluginReady(Message, Cap) and PluginDeinit(Message, Cap), defined before the export line; the export macro wires them, and a plugin without them does not compile. A plain plugin writes one line, DOMIN_PLUGIN_ALWAYS_READY(). An adapter opens its library in Ready with the shared loader and, when that fails, lets DominRtl_NotFound write the message; if the library has a purely software init of its own (IMG_Init, mysql_library_init), that runs in Ready too, and its counterpart in Deinit. Device- or session-level initialisation (an SDL subsystem, a GL context) is not Ready’s business: only the script knows whether it needs video, audio or both, so those come up at the first verb that asks for them. The Writing an adapter plugin page shows the whole file; plugins/adapter_skeleton in the tree is the pattern with every obligation numbered.