CX+AI Builtins Reference

copy one marker region's code into another

returns non-zero on success

cloneMarker(1, 2);

report how many bytecode scratch slots are addressable

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. Seeded lazily, so a program that only ever reads still sees a non-zero window.

returns the live capacity of the scratch table (always > 0)

n = code_size();

drop a marker region

Marks the id free. Answers whether it actually removed anything, so a caller can tell a delete from a no-op -- it returned nothing until 2026-08-25.

returns 1 if a marker was dropped, 0 if there was nothing at that id

delMarker(1);

ask the AI to write the body for a marker region

Runs the prompt through the same query path as ai_call, so the cache, provider and fallback chain all apply.

returns non-zero on success

generateCode("clamp hp to 0..100", 1);

read back the code most recently installed by setCode or generateCode

The exact inverse of setCode, and the reason generateCode is usable at all: it lets you LOOK at the bytecode the model wrote before replaceCode commits it to a marker. `generateCode(task, 1); println(getCode()); replaceCode(1);` is the whole review loop. It reads the pending buffer, not a marker -- the call takes no arguments, so there is no region for it to name.

returns the pending code text, or an empty string if nothing is pending

s.s = getCode();

test whether a marker id names a live region

returns non-zero if the marker exists

if (hasMarker(1)) { ... }

count the live marker regions

Walks the marker table and answers how many ids currently hold installed code. Real on BOTH backends since 2026-08-25: it used to bind only on the register VM, to a stub that answered 0 however many markers were installed, while the native side refused it outright.

returns the number of markers with code installed; 0 if none

n = markerCount();

read the opcode field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's opcode field, or the out-of-range sentinel -1 beyond the allocated table

peek_code(0);

read the flags field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's flags field, or the out-of-range sentinel -1 beyond the allocated table

peek_flags(0);

read the function-id field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's function-id field, or the out-of-range sentinel -1 beyond the allocated table

peek_funcid(0);

read the 64-bit `i` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's 64-bit `i` operand, or the out-of-range sentinel 0 beyond the allocated table

peek_i(0);

read the `j` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's `j` operand, or the out-of-range sentinel 0 beyond the allocated table

peek_j(0);

read the `n` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT.

returns the slot's `n` operand, or the out-of-range sentinel 0 beyond the allocated table

peek_n(0);

write the opcode field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_code(0, 7);

write the flags field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_flags(0, 7);

write the function-id field of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_funcid(0, 7);

write the 64-bit `i` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_i(0, 7);

write the `j` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_j(0, 7);

write the `n` operand of a bytecode scratch slot

Native AOT has no live bytecode -- the program IS native C -- so this family works over a growable scratch table, one entry per PC slot, which the register VM path delegates to as well so both backends agree. Writes grow the table on demand (capped by `#pragma MaxCodeScratch`); READS NEVER GROW IT. A negative address, or one past the configured cap, is not written.

returns void

poke_n(0, 7);

swap a marker region's body for the code most recently installed

returns non-zero on success

replaceCode(1);

count the registered run-time AI functions

The first half of the enumeration pair: it bounds the index that rt_aifunc_name(i) takes, so valid positions are 0 to rt_aifunc_count() - 1. The verbs themselves take a NAME, not a position -- read the name with rt_aifunc_name and act on that.

returns how many run-time AI functions are registered

for (i = 0; i < rt_aifunc_count(); i = i + 1) { println(rt_aifunc_name(i)); }

the name of the i-th registered run-time AI function

The second half of the enumeration pair, and the ONLY place an index still means anything in this family: it converts a position into the identity rt_runAiFunc and rt_destroyAiFunc take. Out of range answers the empty string rather than failing, because the loop that reaches it has already checked its own bound -- and "" is not a legal function name, so it stays distinguishable from every real answer.

returns the function's name, or an empty string if the index is out of range

s = rt_aifunc_name(0);

run the FIRST registered run-time AI function

Takes no arguments -- that is fixed at its binding -- so "the first registered" is the only thing it can mean. Prefer rt_runAiFunc(name), which says which function it means; this exists because the name is published.

returns the first function's result, or -1 if the registry is empty

v = rt_callAiFunc();

register an AI-authored function under a name at run time

returns 0 on error, 1 if the function was newly registered, 2 if it replaced one of the same name -- NOT a handle (cxtest 152 asserts rc == 1)

rt_createAiFunc("clamp", "clamp to 0..100");

drop a registered run-time AI function by name

The registry is addressed by NAME, like the rest of the AI family (ai_call_func, ai_dump_asm) -- his ruling of 2026-08-24. rt_createAiFunc still returns 0/1/2 for error, new registration, or replaced, and is still not a handle. To ENUMERATE, use the pair rt_aifunc_count() and rt_aifunc_name(i): ask how many, ask what the i-th is called, then act on that name. An index is a position you read a name FROM, never a target you act ON -- which is also why it is safe that destroying compacts the table. It ANSWERS whether anything was dropped, and still records the detail in ai_last_error: 1/0 says WHETHER, the error text says WHICH name and how many were registered. Neither replaces the other -- a caller should not have to interrogate a separate channel to learn that its call did nothing.

returns 1 if a function of that name was dropped, 0 if none was registered

if (rt_destroyAiFunc("triple") == 0) { println("nothing to drop"); }

print the AI subsystem's current disassembly to stdout

The shared implementation the register VM's own rt_disasm uses, so both backends print the same thing.

returns void

rt_disasm();

run a registered run-time AI function by name

The registry is addressed by NAME, like the rest of the AI family (ai_call_func, ai_dump_asm) -- his ruling of 2026-08-24. rt_createAiFunc still returns 0/1/2 for error, new registration, or replaced, and is still not a handle. To ENUMERATE, use the pair rt_aifunc_count() and rt_aifunc_name(i): ask how many, ask what the i-th is called, then act on that name. An index is a position you read a name FROM, never a target you act ON -- which is also why it is safe that destroying compacts the table. The function runs with argument 0. To pass an argument, use ai_call_func(name, arg) instead.

returns the function's result, or -1 if no function of that name is registered (-1 rather than 0, because 0 is a legitimate result)

v = rt_runAiFunc("triple");

install CX source text as the body of a codeswap marker region

returns void

setCode(src);

fire an event of the given type from CX code

Calls cx_event_raise: uses `source` as the event context/payload passed to OnEvent handlers (falls back to the shared event ctx when source is 0), then runs every handler registered for that type. It also sets a legacy ctx["source"] field, which is deprecated and warns once.

returns void

raise(50, e);

ask the AI to author a rule and register it on an entity, in one call

The automation engine, and the reason CX exists: an entity is a json document, a rule is a string, and behaviour is DATA you can load, edit, save and let an AI write. Registered behaviour runs on a SCHEDULE and behind a TRIGGER, so nothing polls. THE ONE-LINER THE PRODUCT IS ABOUT: an LLM query and a rule registration fused, so a sentence becomes autonomously running behaviour with no recompile. What the AI returns is a rule STRING -- data you can read, edit and save, not opaque code. ANSWERS AT THE CALL SITE -- 1 registered, 0 refused (his ruling 2026-08-25: a door handed rule TEXT can be handed something malformed at RUNTIME, so its caller must be able to learn nothing was registered; a door handed a compiled FUNCTION cannot, which is why funcAdd stays silent). Every refusal has already printed its reason, so the number is an answer and not a diagnosis. aiRule PROPAGATES that answer rather than reporting success for producing text: the authoring loop may yield no valid rule, and the rule it does yield may still fail to compile.

returns void

aiRule(e, 60, "1", "restock when stock falls below the reorder point");

bake an entity's persist lanes by running a preload rule once

The preload half of the rules ABI: it sizes the entity's typed lanes to the compiler's persist counts, runs `preload` ONCE so its writes land in those lanes, and stamps the source document's revision. Every later ruleExec on that entity then READS the baked lanes instead of recomputing. A fire whose source document has changed re-bakes at the fire boundary. Needs `#pragma rules c`.

returns 1 when armed; 0 on failure -- and the entity stays UN-armed, so a later persist read faults loudly rather than reading a half-baked table

arm(e, "persist float th; th = 0.8;");

tick flat out until a named key on an entity goes non-zero

The automation engine, and the reason CX exists: an entity is a json document, a rule is a string, and behaviour is DATA you can load, edit, save and let an AI write. Registered behaviour runs on a SCHEDULE and behind a TRIGGER, so nothing polls. The console equivalent of riding a graphics frame loop: hand over control in one line instead of writing the while. A rule flips the key when the work is done.

returns void

automationRun(e, "done");

advance the clock and fire every rule that is due and triggered

The automation engine, and the reason CX exists: an entity is a json document, a rule is a string, and behaviour is DATA you can load, edit, save and let an AI write. Registered behaviour runs on a SCHEDULE and behind a TRIGGER, so nothing polls. The per-frame call. A graphics program gets this driven for it once the first rule is added.

returns void

automationTick();

the json object the dispatcher fills with the current event

The event registry IS json, which is what makes it two-way: load a binding set from a file, edit a binding while the program runs, save it back, or let an AI author it. A gate rule is evaluated against THIS -- `event["key"]`, `event["mx"]` and so on.

returns a json handle to the current event context

e = eventCtx();

dispatch an event through the registry

The event registry IS json, which is what makes it two-way: load a binding set from a file, edit a binding while the program runs, save it back, or let an AI author it. Every entry registered for the type is considered: its gate rule is evaluated against the event context, and the handler runs only if the gate passes.

returns the result of the dispatch

eventFire(1);

replace the whole event table with a caller-parsed json array

The two-way, AI-authorable load: a program (or an AI) builds the handler table as json and installs it in one call, instead of accumulating it through OnEvent. HANDLER NAMES ARE CASE-INSENSITIVE, like every CX identifier: an entry's `"fn"` refers to a handler registered from a CX function name, and the scanner folds that name, so the table's string is folded to match. `"OnHit"`, `"onhit"` and `"ONHIT"` all name the same handler -- two handlers differing only by case cannot exist, so nothing legitimate is lost. EVERY `"fn"` IS RESOLVED HERE, AT LOAD. A name that matches no registered handler is a loud CX-E5033 and STOPS the run. It is checked at load rather than at first fire because an unresolvable handler used to fail by simply never running -- the quietest failure mode there is, and one that let a run start with a dead handler and look healthy (FP4). Entries with only a `"do"` rule carry no name and are not checked. The registry keeps `tbl` for the process lifetime and increfs it, so a table built inside a function survives that function's scope exit.

eventSetTable(jsonLoad("events.json"));

the json array holding every event binding

The event registry IS json, which is what makes it two-way: load a binding set from a file, edit a binding while the program runs, save it back, or let an AI author it. Indexed by event type (1 keyboard, 2 mouse, 3 timer, 4 window; 4..255 are free for your own). Created on first use.

returns a json handle to the event table

t = eventTable();

register a compiled CX function on an entity, on the same schedule and trigger

The automation engine, and the reason CX exists: an entity is a json document, a rule is a string, and behaviour is DATA you can load, edit, save and let an AI write. Registered behaviour runs on a SCHEDULE and behind a TRIGGER, so nothing polls. The fast, heavy path beside the data path -- the function is `function f.v(json e)` and receives the entity. **NATIVE ONLY**: native carries a function value as a C address, the register VM as a bytecode index, so on the VM this hard-errors rather than calling the wrong thing. Windowed games run native.

returns void

funcAdd(e, 1, "1", &onTick);

bind a data-only rule handler to an event type

Callable, but its argument list is not derivable from its binding: it is bound only by the register VM's name table, where the C signature is the generic (vm, N) wrapper form. Named here so an absence is never mistaken for non-existence.

The event registry IS json, which is what makes it two-way: load a binding set from a file, edit a binding while the program runs, save it back, or let an AI author it. Both the gate and the handler are RULES -- pure data, so the binding is json-native, loadable and AI-authorable.

returns void

onEventRule(1, "event[\"key\"] == 27", "quit = 1");

register a rule on an entity, to run on a schedule behind a trigger

The automation engine, and the reason CX exists: an entity is a json document, a rule is a string, and behaviour is DATA you can load, edit, save and let an AI write. Registered behaviour runs on a SCHEDULE and behind a TRIGGER, so nothing polls. ANSWERS AT THE CALL SITE -- 1 registered, 0 refused (his ruling 2026-08-25: a door handed rule TEXT can be handed something malformed at RUNTIME, so its caller must be able to learn nothing was registered; a door handed a compiled FUNCTION cannot, which is why funcAdd stays silent). Every refusal has already printed its reason, so the number is an answer and not a diagnosis.

returns void

ruleAdd(e, 30, "hp < 20", "hp = hp + 5");

queue a canned authoring response instead of calling the AI

The AI rule-authoring loop. While the queue is non-empty, ruleAuthor consumes it INSTEAD of contacting a provider -- one push per attempt, FIFO. What makes an authoring test deterministic, offline and free, and equally the seam for feeding rules from a source that is not an LLM.

returns void

ruleAuthMock("{ speed = speed / 2; }");

ask the AI for one rule, validate that it compiles, and retry on a decline

The AI rule-authoring loop. The returned text is a `{ ... }` body over `json e`. A reply that does not compile in the rules subset is DECLINED and retried with the compile error appended, up to a bounded number of extra attempts. Every attempt and decline is recorded for ruleAuthStats.

returns the validated rule text; the EMPTY string on final failure -- loud, never a silent no-rule

body.s = ruleAuthor("halve speed below 20 hp");

clear the authoring feed, drain the mock queue and forget the fire warnings

The AI rule-authoring loop. Test isolation, or the start of a fresh authoring session.

returns void

ruleAuthReset();

read the authoring loop's evidence feed as a json document

The AI rule-authoring loop. Returns attempts, declines, whether the final attempt succeeded, the last decline's class and reason, and a record per attempt. The class is a stable string -- `pointer`, `call-denied`, `arity`, `struct`, `nonscalar`, `foreach-colon`, `syntax`, `empty`, `other` -- so a test can assert WHY the model was refused, not merely that it was.

returns a NEW json handle you own

s = ruleAuthStats();

how many distinct rule strings are currently compiled and cached

The cache-effectiveness instrument: compiling N distinct rules M times should cache N. Use it to prove a hot loop is not recompiling.

returns the number of cached rule programs

n = ruleCacheCount();

LINK A NAME TO AN OBJECT, so a rule reaches the world without

being handed it (RULEX-325 Part E; his catch: "link an entity with a variable/global"). The entity NAME is the join key the rules already had -- `#pragma rules entity ship` names it, a rule body spells its parameter with it, and a stored key carries it. This says which OBJECT that name currently is. TWO SPELLINGS, ONE MECHANISM (his ruling 2026-09-06). `ruleEntity(obj)` binds the name this program DECLARED; `ruleEntity("name", obj)` binds any name. The one-arg form is a COMPILE-TIME REWRITE -- the compiler supplies the declared name as a literal, exactly as rulec_fixup_raise already turns a rule's `raise(type)` into `raise(type, <entity>)` -- so there is one C function here and no runtime question about which name was meant. **A one-arg call in a program that declared no entity is a NAMED REFUSAL at compile time, never a silent bind to the default `e`** (his ruling, FP4). BINDING AN ALREADY-BOUND NAME REPLACES IT. It does not stack, there is no scope and there is no unbind -- a name is whatever it was last bound to. Said here because it is the only place a reader will look, and because the opposite (a stack) is what a reader coming from a scoping language will assume.

returns 1 when bound, 0 when refused (empty name).

ruleEntity(ship);              // the declared name
ruleEntity("world2", other);   // any name

the object currently linked to a name, or -1

-1 RATHER THAN 0, and the difference is load-bearing: 0 is a legal json handle, so a caller testing `if (ruleEntityOf(n))` on a 0-handle would read a live entity as a missing link. The vtable checks `< 0`.

returns the linked handle, or -1 when nothing is bound to that name.

e.i = ruleEntityOf("ship"); if (e < 0) { ...no link... }

run a rule against an entity and return its value

The explicit one-shot path, beside the registered one. **COMPILE-CACHED**: the same rule string compiles ONCE, content-keyed for the life of the process, and runs cached after that -- so calling it in a loop does not recompile. Member writes to `e` PERSIST on the bound document.

returns the rule's `return` value as a float; a rule returning a string reads as 0

v = ruleExec(e, "return hp * 2;");

run one rule entry, using its compiled form if it has been promoted

The dispatcher that honours promotion. Given a json rule entry `{ name, body, promoted }`: if it is marked promoted AND its name is registered, the COMPILED function runs with no recompile of the text; otherwise the body runs through the cached text path. A promoted mark with no registered function -- promote ran, the rebuild did not -- falls back to text AND warns LOUDLY once per rule name: graceful for the player, visible for the developer.

returns the rule's value as a float, on both paths

v = ruleFire(e, entry);

promote a rule to a more durable form -- the store, or generated source

TWO FORMS UNDER ONE NAME, picked by how many arguments you give it, because both do the same thing at different distances: they graduate a rule out of the moment it was written in. **`rulePromote(rule)`** appends the rule to the program's rule store AND makes it live in the same call -- the store is durable, so a rule learned in one run is there for the next. It needs `#pragma rules persistence yes`, and the compiler refuses the call without it rather than let a promote go nowhere. A rule that does NOT compile is written to the store anyway, marked `failed`, with the frontend's own sentence beside it: the store records what was TRIED. The return value answers *did this rule work*, never *did anything happen*. **`rulePromote(rules, path)`** emits a compilable `.cxi` from a json array of authored rules -- one `function <name>.f(json e) <body>` per entry plus a registration block. **HOST ONLY, never rule-callable**: a rule that could promote itself would be capability escalation, so this name must never appear on a rule whitelist. ALL-OR-NOTHING -- every body is compile-checked first, a file carrying no generated marker is never overwritten, and if any rule fails nothing is written.

returns 1 on success, 0 on failure -- and for the one-argument form a failed rule is still recorded

rulePromote("{ e[\"hull\"] = 100; }");

what the last ruleExec() actually did, which its return value

cannot tell you. ruleExec returns the RULE'S OWN value (`{ return hp > 0; }` is how a gate is written), so a rule that applies, a rule that changes nothing, a rule that is refused and a rule that does not compile all answer 0 -- the refusals print, loudly, but a program cannot branch on a printout. This answers the other question, and it is written once per ruleExec. 1 APPLIED the rule ran and WROTE the json it was given. Exactly that: the document's mutation counter moved. Writing the same value again still counts as a write, and a rule that changes something other than `e` -- a persist lane, a global -- does not. 2 NOCHANGE the rule ran and wrote nothing to that document. 3 REFUSED CX declined the rule's FORM or the capability: a blank rule, the retired non-brace DSL (CX-E5027), or a binary built with no `#pragma rules c`. 4 DIDNOTPARSE the C frontend refused the BODY. A DENIED CALL (`system()` in a rule) is here too, with syntax errors: separating them is what ruleAuthor's own stats already do, and a second classifier would be a second answer to one question. 0 NOTRUN nothing has run yet. THE AMBIENT READER IS DELIBERATE, and it is the door the filed `onerror()` arc consumes: a handler reached from somewhere else in the program needs the fact without having been at the call site. Nothing wires it there yet -- that design is still open -- but when it lands, its input is already standing.

returns one of the five values above.

ruleExec(ship, rule); if (ruleStatus() == 4) { println("bad rule"); }

the program's rule store, as data you can walk

A json ARRAY of entries in the shape ruleFire already reads -- `{ name, body, promoted }` -- plus `phrase`, `status` ("ok" or "failed") and, on a failed one, the `error` the frontend gave. The store is TEXT ON DISK and is meant to be read, edited and curated by hand; this is the same array the running program holds, so an entry promoted a moment ago is already in it. FAILED ENTRIES ARE IN HERE TOO, deliberately: the store records what was TRIED, not only what worked. They are reported once at load and are NOT applied, so walking this array is how a program shows its author what its AI reached for and what the sandbox refused.

returns the entry array's json handle, or 0 if the program declared no store (`#pragma rules persistence yes`).

json s = ruleStore(); foreach s { ... }

how many entries the rule store holds

Loaded entries plus anything promoted so far this run, failed entries included. 0 when no store was declared, and 0 on a first run that has learned nothing yet -- those are the same number and deliberately so: neither is an error, and a program that wants to tell them apart asks ruleStore() for 0.

returns the entry count.

printf("%d rules known\n", ruleStoreCount());

the whole store as one document

A store is `{ "options": { ... }, "rules": [ ... ] }`, and the vtable takes that DOCUMENT -- it reads both halves from it. `ruleStore()` answers only the rules array and `ruleStoreOptions()` only the options, so without this a program that LOADS a store file could not drive the vtable at all.

returns the document handle, or 0 when no store is open.

ran.i = __vtRun(wish, ruleStoreDoc(), "ship");

the store's `options` object

A store is `{ "options": { ... }, "rules": [ ... ] }` (his ruling 2026-09-06). The options hold the matcher's settings -- `match`, `trigram_min` and the length rule -- so they travel with the rules they govern rather than with whichever program loads them, and so the BAKE can read them at build time.

returns the options object handle, or 0 when no store is open.

json o = ruleStoreOptions();

read the store file again, now

The store is read ONCE, in main's prologue. A rules file edited by anything else while the program runs -- a person, another process, a deploy -- is invisible until this is called. **Explicit, never watched** (his ruling 2026-09-06: a file watch is a later item): the program says when to look. ⚠ A FAILED RELOAD KEEPS THE OLD TABLE RUNNING and names the reason. This is the whole difference between it and opening twice: OPEN binds an empty store when the file is broken, which is right at startup and catastrophic mid-run, because a typo would silently disarm every rule a running program has. The worst a bad file can cost you here is the edit.

returns 1 when the store was replaced, 0 when it was not (and the old one is still live).

if (!ruleStoreReload()) { ...the previous rules are still running... }

configure AI from ONE json document, per model

Replaces a scatter of individual setters with a document describing every model the program may reach. `defaults` holds what every section inherits; `models` is an ARRAY of sections, and **its order is the fallback chain** -- an array rather than an object because sequence is load-bearing and json promises no member order. A section carries its own `host` and `port`, so **an endpoint belongs to the model that owns it**. That is the point of the shape rather than a convenience: the older `ai_set_url` applied to every provider the chain walked, and per-section options make that unexpressible. Keys are checked when the document is read, not when a request is sent. A key misspelled inside a section is REFUSED and named; a key that is documented but not yet built is refused as "not yet wired", which is a different sentence on purpose -- the reader of the first is hunting their own typo, the reader of the second is waiting for a feature. Keys in `defaults` are PERMISSIVE: they apply where they mean something and are skipped where they do not, because a mixed local-and-hosted document would otherwise refuse itself.

returns 1 when the document was accepted and is now in force; 0 when it was refused, with ai_get_error() naming the key and the reason. Nothing is applied on a refusal -- the previous configuration stands, so a bad document cannot leave a program half-configured.

if (ai_set_options(cfg) == 0) { println(ai_get_error()); }

ask whether a background job has finished

WINDOWS ONLY. On Linux and macOS the async family is not implemented: start and wait answer -1, pending answers 0, and result answers the unknown-job marker. Use the synchronous query builtins there.

returns 0 while pending, 1 when done, -1 for an unknown id

if (ai_async_ready(id) == 1) { ... }

collect a background job's reply, waiting if necessary

BLOCKS until the job finishes if it has not already, then RETIRES the job -- the id is spent and its slot is reusable, so a second call with the same id gets the unknown-job marker. An unknown id answers the string `ERROR: unknown job id N` rather than an empty one, so a caller can test for `ERROR` without having to distinguish failure from a genuinely empty reply. WINDOWS ONLY. On Linux and macOS the async family is not implemented: start and wait answer -1, pending answers 0, and result answers the unknown-job marker. Use the synchronous query builtins there.

returns the model's reply, or an `ERROR: unknown job id N` marker

r.s = ai_async_result(id);

empty the response cache and reset its counters

Releases every cached value's reference; the hit and miss counters go back to zero.

returns void

ai_cache_clear();

read a cached reply by key

Counts a hit or a miss either way, so the counters reflect real lookups.

returns the cached reply, or an EMPTY STRING on a miss -- a stored empty string is therefore indistinguishable from absence

v.s = ai_cache_get("q");

count cache lookups that found an entry

Reset by ai_cache_clear. Note that ai_cache_get performs a lookup, so it moves this counter.

returns the hit count since start or since the last clear

h = ai_cache_hits();

count cache lookups that found nothing

Reset by ai_cache_clear. Note that ai_cache_get performs a lookup, so it moves this counter.

returns the miss count since start or since the last clear

m = ai_cache_miss();

store a reply in the response cache under a key

The cache is a PROCESS-LIFETIME owner and takes its own reference on the value, so the entry stays valid after the caller's string goes out of scope. Re-putting an existing key replaces the value. THE TTL ARGUMENT IS ACCEPTED AND IGNORED -- the cache has no clock and entries never expire.

returns void

ai_cache_put("q", "a", 60);

count the entries currently in the response cache

returns the number of cached entries

n = ai_cache_size();

read the cache counters as one formatted line

returns a string of the form `entries=N hits=N misses=N`

print(ai_cache_stats());

send a prompt to the configured LLM and return its reply

Cache lookup (when enabled), provider auto-pick if none was set, the request, then the fallback chain if it failed. A successful reply is cached under the prompt text. On any failure the answer is an EMPTY STRING and the reason is readable from ai_get_error -- so test the result, do not assume it.

returns the model's reply, or an empty string on failure

r.s = ai_call("...");

start a background LLM request and return a job id

WINDOWS ONLY. On Linux and macOS the async family is not implemented: start and wait answer -1, pending answers 0, and result answers the unknown-job marker. Use the synchronous query builtins there. Fails FAST with -1 when no API key is available, rather than starting a worker that cannot succeed. At most 32 jobs may be live at once.

returns a positive job id; -1 with no key, no free slot, or on a non-Windows build

id = ai_call_async("Summarise this.");

run an AI-authored function on the native AI mini-VM

The function must have been created by ai_parse_bytecode (or the codeswap path) under this name.

returns the function's integer result; 0 if the name cannot be read

r = ai_call_func("clamp", 130);

disassemble a named AI function back to readable text

The counterpart to ai_parse_bytecode: what the AI wrote, as the runtime holds it.

returns the disassembly text; an empty string if the name cannot be read

print(ai_dump_asm("clamp"));

read the reason the last AI operation failed

Set by ai_init and by the query family; an empty string means the last operation reported no error.

returns the error text, or an empty string

print(ai_get_error());

report whether a usable API key is available for the current provider

True if the model's section in the ai_set_options document carries a "key", or the provider's environment variable is set and non-empty. A provider whose table row carries no environment key -- ollama, kwaai and custom -- always answers 1, because none is needed.

returns 1 if a key is available (or none is needed); 0 otherwise

if (ai_has_key()) { ... }

check that a provider and a usable key are configured

Auto-picks a provider from the environment if none was set (anthropic, openai, google, xai, deepseek, groq, mistral, cohere, ollama -- first key found wins). Sets the error text on failure. ollama, kwaai and custom carry no environment key in the provider table and so need none.

returns 1 when a provider and key are available; 0 otherwise, with ai_get_error explaining which is missing

if (ai_init() == 0) { print(ai_get_error()); }

assemble AI-authored bytecode text into a named callable function

returns the result of the assembler -- non-zero identifies the parsed function

ai_parse_bytecode("clamp", src);

count background jobs that have not finished

WINDOWS ONLY. On Linux and macOS the async family is not implemented: start and wait answer -1, pending answers 0, and result answers the unknown-job marker. Use the synchronous query builtins there.

returns the number of live, unfinished jobs

n = ai_pending();

choose the LLM provider for subsequent calls

Accepts anthropic, openai, google, mistral, cohere, xai, deepseek, groq, ollama, kwaai or custom, plus the aliases claude -> anthropic, grok -> xai and gpt -> openai. A key belongs to the model that uses it -- give it as "key" in that model's section of the ai_set_options document, where it cannot travel to a provider you did not name. Stored in a fixed runtime buffer; a value too long to fit is refused LOUDLY with CX-E5025 naming the limit rather than silently truncated.

returns void

ai_set_provider("anthropic");

what the AI has cost so far, as a json document

Totals across every provider (`in`, `out`, `calls`, `uncounted`), the same four plus `cap` per provider under `providers`, and the call that just happened under `last` (`provider`, `in`, `out`, `counted`). The numbers are the PROVIDER'S OWN accounting, read out of its reply, so they are what you will be billed for rather than an estimate. A reply that carried no usage block adds nothing to the totals and increments `uncounted` instead -- zero is a legal token count, so "the provider did not say" is never reported as "the call was free". Counts are per PROCESS; ai_usage_reset() clears them. Only providers that have been called or capped get a row.

returns a json document handle -- read it with jsonMember/jsonAsInt, or print it with exportDoc

u = ai_usage(); printf("%d tokens in
", jsonAsInt(jsonMember(u, "in")));

clear the AI usage counters, keeping the caps

Zeroes every provider's token totals, call count and uncounted count, and forgets the last call. THE CAPS SURVIVE: a cap is a policy your program declared and a counter is a measurement, so a program rolling a daily budget at midnight resets what it counted without disarming what it decided.

returns nothing

ai_usage_reset();

block until a background job finishes

WINDOWS ONLY. On Linux and macOS the async family is not implemented: start and wait answer -1, pending answers 0, and result answers the unknown-job marker. Use the synchronous query builtins there. Waits with no timeout.

returns 1 once the job is done; -1 for an unknown id

ai_wait(id);

evaluate an arithmetic expression held in a string, at runtime

Returns a FLOAT. Names in the expression come from the eval store (evalSet / evalGet / evalClear), which is separate from the program's own variables. An expression it cannot parse is LOUD -- CX-E5029 -- not a silent 0.

returns the value as a float; a parse failure raises CX-E5029

evalSet("x", 3.0); v.f = eval("x * 2 + 1");

store a named float variable for the expression evaluator

Inserts or updates the value in a small case-insensitive table (max 64 vars, names truncated to 31 chars); these variables are what the eval() expression parser reads. A full table drops the insert silently.

returns void

evalSet("a", 100);

read a named float variable from the expression evaluator

Case-insensitive lookup in the eval variable table; yields 0.0 when the name is undefined.

returns the variable's stored float value; 0.0 if not defined

assertFloatEqual(evalGet("a"), 10.0);

clear all expression-evaluator variables

Resets the eval variable table to empty (count back to 0).

returns void

evalClear();

create a native data-grid widget at x,y,w,h and return its handle

Reuses a free registry slot or grows the grid registry; the grid is a pure data structure until drawn.

returns int 1-based grid handle, 0 = failure

g.i = gpu_grid_new(60, 96, 840, 600);

unconditionally destroy a grid handle now, freeing all its storage

Drops the ARC bucket directly then reclaims cells, columns, sections and text handles.

returns void

gpu_grid_free(g);

ARC-decrement a grid handle, reclaiming it when its refcount reaches 0

Codegen-emitted at scope exit for an owned `datagrid` local; the shared tracer calls the internal reclaim at refcount 0.

returns void

gpu_grid_decref(g);

return the number of currently-open grid handles

Leak/regression-test signal (mirrors cxmf_live_count); a leaked grid also shows in the generic checks leak walk.

returns int count of live grid handles

int before = gpu_grid_livecount();

reposition and resize an existing grid to x,y,w,h

returns void

gpu_grid_bounds(insp, 10, topY, w - 20, iH);

set the grid's column count, reallocating cell storage

n must be > 0; also (re)allocates the initial row buffer.

returns void

gpu_grid_cols(g, 6);

set the grid's row count, growing storage and resorting

Grows cell storage as needed, re-applies the active sort, and tails the view if follow mode is on.

returns void

gpu_grid_rows(g, NROWS);

define column c with a label, width, type and alignment

type: 0 TEXT, 1 NUMBER, 2 CHECK, 3 BAR, 4 COLOR, 5 BADGE; align: 0 left, 1 centre, 2 right; width is clamped to a minimum of 24px.

returns void

gpu_grid_col(g, 0, "Module",  220, GT_TEXT,  0);

empty all cells and section headers, resetting the grid to zero rows

Clears cell text/numbers/colours, drops section headers, and resets selection and scroll.

returns void

gpu_grid_clear(insp);

set the text of cell (r,c)

returns void

gpu_grid_set(g, i, 0, dName[i]);

set the numeric value of cell (r,c)

Value drives NUMBER display, CHECK on/off, and BAR percentage.

returns void

gpu_grid_num(g, i, 2, dPower[i]);

read back the (possibly edited) numeric value of cell (r,c)

returns float cell value, 0 if the handle or indices are out of bounds

pw.i = gpu_grid_getnum(g, sel, 2);

read back the (possibly edited) text of cell (r,c)

returns string cell text, empty string if the handle or indices are out of bounds

selName = gpu_grid_gettext(g, sel, 0) + "   (" + gpu_grid_gettext(g, sel, 1) + ")";

fill a grid from a json ARRAY OF OBJECTS, one object per row

Keys map to columns BY POSITION, in the first element's own key order -- which is the DOCUMENT's order, so the column order is visible in the source rather than decided elsewhere. If the grid has no columns yet they are CREATED from those keys (label = the key, type inferred from the first value); if it already has columns they are respected and never relabelled, because this call fills a sheet, it does not restyle one. Rows GROW to fit and are never shrunk, so a summary row added afterwards survives a refill. A VALUE IS MAPPED BY THE COLUMN'S DECLARED TYPE, NEVER BY THE JSON'S, and that is forced rather than chosen: cx_grid's numeric formatter prints a whole number without decimals, so an invoice whose money columns were GT_NUM showed "720" beside "658.80". Into a TEXT column a number is therefore rendered at cx_print_decimals -- the program's own `#pragma decimals`, not a new knob -- and into a GT_NUM column it is stored as a number. THE WHOLE DOCUMENT IS CHECKED BEFORE ONE CELL IS WRITTEN. A refusal leaves the grid exactly as it was, because a half-filled sheet looks filled.

returns the number of rows written; 0 for an empty array or a dead handle

n.i = gridJson(g, doc, 0, 0);

merge cell (r,c) across cspan columns and rspan rows

Spans are clamped to at least 1 and to the grid bounds; covered cells are flagged and not drawn.

returns void

gpu_grid_merge(g, 11, 0, 6, 1);

set the grid's title-bar text and enable the title bar

returns void

gpu_grid_title(g, "MODULE DATABASE   (cx_grid demo)");

set the grid's default font

0 = raylib default pixel font; otherwise a loadfont() handle for crisp TTF text.

returns void

gpu_grid_font(g, gFont);

set the font used by every cell in column c

0 = inherit the grid font; overridden per-cell by gpu_grid_cellfont.

returns void

gpu_grid_colfont(g, 0, gFontBold);

set the font of one cell (r,c)

Cell font wins over the column font, which wins over the grid font; 0 = inherit.

returns void

gpu_grid_cellfont(g, 11, 0, gFontBold);

set the colour of cell (r,c)

Used by BAR tint, COLOR swatch and BADGE pill cells.

returns void

gpu_grid_color(g, i, 3, dTint[i]);

set the per-cell TEXT colour of cell (r,c)

-1 reverts the cell to the grid's default text colour.

returns void

gpu_grid_textcolor(g, i, 2, parsehex("ff6b6b"));

set a per-row background colour override for row r

-1 = none, reverting the row to zebra/normal shading.

returns void

gpu_grid_rowstyle(g, 7,  parsehex("3a2a14"));

set one named style property of the grid to an int value

Keys: headerbg, rowbg, rowalt, sel, hover, grid, text, accent, titlebg (colours) and rowh, headerh, titleh, footerh, zebra (metrics/flags).

returns void

gpu_grid_style(g, "rowh", 30);

set the whole look at once, from a preset name or a json

document. A THEME IS A DOCUMENT (his ruling, 2026-08-25: "a json theme for the grid is a good idea too like a style sheet"). The shipped presets -- "light", "dark", "sheet" -- are not cases in a switch; each IS a json document that ships with the runtime, and a name is shorthand for one of them. Pass anything beginning with '{' and it is read as your own theme instead, so a program (or a rule, or a visitor) can restyle a grid by editing data. Keys are exactly gpu_grid_style's keys, and a value may be a json NUMBER or a hex STRING ("#e3ece5" or "e3ece5") -- a human writing a stylesheet writes the hex, a program generating one writes the number, and refusing either would make the door useless to one of them. REFUSES LOUDLY. Until 2026-08-25 any name that was not "light" fell through to dark, so a typo -- or `gridTheme(g, "sheet")` before this existed -- quietly handed back the dark theme and said nothing.

gridTheme(g, "sheet");

style the WHOLE sheet from ONE json document, in layers,

down to a single named cell. Sections, applied in this order so that a later layer wins: "theme" a preset name, exactly gpu_grid_theme's ("light" / "dark") "sheet" an object of gpu_grid_style keys -- the sheet-wide defaults "cols" an ARRAY, one entry per column, in column order "rows" an object keyed by the 1-based row number as text "cells" an object keyed by A1 address ("d9"), the single-cell layer Every section is optional; an empty object in "cols" leaves that column alone. Column keys: "label" "width" "type" "align" "decimals" "font" "edit". Row keys: "bg" "level". Cell keys: "bg" "text" "decimals" "font" "edit". A ROW IS ADDRESSABLE FROM THE END: "-1" is the last row, "d-1" its column D cell. A sheet whose length comes from its data has no fixed row 9, and a document that names one goes silently wrong the day a line item is added. A COLOUR is either "#rrggbb" / "rrggbb" or a plain number; "type" and "align" take either their word ("number", "right") or their number. WHY A DOCUMENT AND NOT MORE CALLS. The look of a sheet is data about the sheet, so it is written as data -- read from a file, sent by a server or chosen by a person, with nothing rebuilt. This composes the single-value doors above rather than reimplementing them (one truth, rule 33). FP4: a section, key, address or value the loader cannot honour raises CX-E5052 naming the offending row and STOPS -- deliberately unlike the 3-arg cx_grid_style it composes, which drops an unknown key in silence. A whole document is exactly where one mistyped row would otherwise vanish.

gpu_grid_sheet(g, look);

declare how every cell is TYPED from ONE json document:

the sheet's default, a column's, a row's, and a single named cell's. The SIBLING of gpu_grid_sheet and it reads the same way: the same four sections, the same column array, the same row keys, the same A1 cell addresses including a row counted from the end. The style document says how the sheet LOOKS; this one says what each cell IS. { "sheet": "text", "cols": [ "text", "number", "bar" ], "rows": { "3": "badge", "-1": "number" }, "cells": { "c2": "check", "d-1": "number" } } The value at every layer is a bare type NAME, not an object -- there is only one thing to say about a cell here, and a document that says it in one word is the shorter program (FP5). The six types: "text" "number" "check" "bar" "color" "badge" -- the same six a column has always had, now reachable at every layer. "" means INHERIT the layer above, so a document can un-type a cell as well as type one; at the "sheet" layer, which has no layer above it, "" means plain text. PRECEDENCE, and it is resolved at the READ, not at the load: a CELL's type beats its ROW's, which beats its COLUMN's, which beats the SHEET's default. A grid nobody has typed answers "text" everywhere, exactly as it always did. WHAT A TYPE GOVERNS. How the cell is drawn (a number, a check box, a progress bar, a colour swatch, a badge); what clicking it does; what an edit commits into; and how the cell BINDS into a formula's `e` -- a "number" cell binds as a number, every other type binds as its text. A TYPE DOES NOT CONVERT DATA. A cell holds a number and a string in separate stores and the type chooses which one is read, so typing a text-filled column "number" shows the numbers nobody set (0), not the text parsed. This is the long-standing behaviour of a column's type, reachable per cell; set the store you mean with gpu_grid_num / gpu_grid_set. AGAINST A FORMULA CELL: the formula owns the VALUE, the type owns how that value is presented and bound, and a REFUSED formula outranks both -- a cell showing #ERR or #CIRC keeps its marker whatever it is typed, because a marker is not a value and a clean 0 in a number cell would look computed. FP4: a section, address, or type name the loader cannot honour raises CX-E5054 naming the offending row and STOPS. An unknown type name is refused WITH THE LEGAL SET SPELLED OUT, because the alternative is sending a person who typed "colour" to a manual they are not holding.

gpu_grid_types(g, kinds);

give a cell a FORMULA: text that is compiled in-process

and re-run whenever the sheet changes, so a total follows its inputs. THE FORMULA IS A RULE (DOCS/design/C_RULES.md) -- a `{ ... }` C body over `json e` whose `return` is the cell's value. It is not compiled with the program: it is text the program can read, show and replace while it runs, which is what lets the person in front of the sheet change the arithmetic. Needs `#pragma rules c`, the same gate every other rule needs. `e` binds the three things a spreadsheet formula asks for: e["this"]["b"] this row's cell in column B e["above"]["d"] column D's cells ABOVE this row, as an array -- the range a subtotal sums: `sum(e["above"]["d"])` e["d7"] any cell by its A1 address (1-based row) e["d-1"] the same, counted from the END -- so a totals formula is the same text whatever number of line items the data has A cell in a NUMBER column binds as a number; any other column binds as its text, which the rule engine reads leniently ("3.50" is 3.5). The result is written to the cell as BOTH a number (gpu_grid_getnum) and the text the sheet paints (gpu_grid_gettext), formatted to that cell's decimals. Passing an EMPTY text removes the formula and leaves the cell a plain one. The sheet is re-evaluated to a fixed point, so a formula may name a cell below it. FP4: a formula that does not compile, or a sheet that does not settle because a value depends on itself, marks the CELL (`#ERR` / `#CIRC`) and reports CX-E5053 -- it never leaves the previous number sitting there looking computed, and it never spins.

gpu_grid_formula(g, 8, 3, "{ return sum(e[\"above\"][\"d\"]); }");

read a cell's formula text back

The companion to gpu_grid_formula, and the reason it exists: a formula the program cannot show is one the person at the sheet cannot find, let alone edit. Answers "" for a cell that has no formula, so a caller can tell the two apart.

returns the formula's text, or "" when the cell has none

gpu_draw_text(24, 496, gpu_grid_getformula(g, row, 3), ink);

toggle the automatic row-number gutter on the left

Numbers are 1-based by original row index.

returns void

gpu_grid_rownum(top, 1);

mark row r as a collapsible section header with a label

Rows after it (until the next header) belong to it and hide when it folds; clicking the header toggles it.

returns void

gpu_grid_section(g, 0, "WEAPONS");

programmatically fold or unfold the section header at row r

returns void

gpu_grid_fold(insp, r, 1);

set the nesting depth of the section header at row r

0 = top-level, 1 = sub-section, and so on; folding a parent also hides nested sub-sections. Nesting past depth 15 raises CX-E5025.

returns void

gpu_grid_rowlevel(insp, r, 1);

mark a TEXT/NUM column c as click-to-edit

CHECK/BAR/COLOR cells are always interactive regardless of this flag.

returns void

gpu_grid_coledit(g, 0, 1);

make one cell (r,c) typeable even if its column is not editable

Used for an editable cell sitting in an otherwise read-only grid.

returns void

gpu_grid_celledit(insp, r, 2, 1);

programmatically set the sort column and direction

dir < 0 sorts descending, otherwise ascending; col < 0 clears the sort. Group-aware when the grid has sections (sections move as whole blocks).

returns void

gpu_grid_sort(g, 2, 1);

set the horizontal scroll offset in pixels

Clamped to 0..(content width - viewport width).

returns void

gpu_grid_scrollx(g, 0);

toggle follow mode so the view auto-tails to the bottom as rows append

Re-enabled automatically when the user scrolls back to the bottom.

returns void

gpu_grid_follow(dlog, 1);

drive one frame of grid input from the mouse state

Handles wheel/scrollbar scrolling, header sort clicks, column resize, section fold, cell selection and text/number editing.

returns void

gpu_grid_update(g, mx, my, wheel, down, pressed);

render the grid this frame using raylib primitives

Draws the title bar, header, visible rows (cells/sections), vertical and horizontal scrollbars and the footer.

returns void

gpu_grid_draw(g);

snap the view to the last rows (log tail)

returns void

gpu_grid_tail(dlog);

return the selected original row index

returns int selected original row index, -1 = none

sel.i = gpu_grid_sel(g);

the COLUMN the selecting click landed on, the twin of

gpu_grid_sel's row. Answers the column index the last selecting press ACTED on, which inside a horizontal merge is the span's origin rather than the column the pointer was over. -1 means no column, and it is a real state rather than a failure: a press in the row-number gutter or to the right of the last column selects a ROW and no column, and a grid nobody has clicked has neither. It reads what the press already decided and does not hit-test again, so asking costs a field read. Pair it with gpu_grid_sel to tell one gesture from another -- typing into a value column, asking about a formula column -- without re-deriving the geometry, which a caller cannot do anyway: the column boundaries move by the row-number gutter, whose width is not reachable from CX and is not meant to be.

returns the column index (0 = leftmost), or -1 for no column

if (gpu_grid_selcol(g) >= 2) { pick(gpu_grid_sel(g)); }

return the current sort column index

returns int current sort column, -1 = unsorted

gpu_grid_sortcol(g);

return the hovered original row index

returns int hovered original row index, -1 = none

gpu_grid_hover(g);

return the grid's row count

returns int number of rows

gpu_draw_text(60, 744, "rows: " + str(gpu_grid_count(g)), colDim, 16);

draws an immediate-mode button in a borderless panel and reports whether it was clicked this frame

Meant to be polled every frame inside the draw loop; wraps nuklear's nk_button_label in a mini-window keyed by its coordinates.

returns int -- 1 if the button was clicked this frame, else 0 (also 0 when there is no window/GL context)

if (gpu_gui_button(20, 60, 120, 32, "Click me")) {

draws a static left-aligned text label in a borderless panel

returns void

gpu_gui_label(160, 60, 200, 32, "clicks: " + str(clicks));

draws a labelled checkbox and returns its new on/off state

The passed state seeds the widget each frame; the return value reflects any toggle the user made this frame.

returns int -- the checkbox's new state (1 checked, 0 unchecked; echoes the input state when there is no window)

on = gpu_gui_checkbox(20, 60, 140, 32, "enabled", on);

draws a bordered multi-line text panel, splitting the text on newlines into rows

A minimal read-only log/console view; each newline-separated line becomes its own row and a trailing carriage return is stripped.

returns void

gpu_gui_console(640, 152, 340, 460, log_text);

draws a single-line text input field whose buffer persists across frames, keyed by name

On the first call for a given key the field is seeded with initial; later calls return whatever the user has typed. State lives in a 32-slot table with a 255-char buffer.

returns string -- the field's current text (empty string when there is no window or the 32-slot table is full)

string name = gpu_gui_input(20, 60, 200, 32, "name", "");

draws a multi-line scrollable text editor box whose buffer persists across frames, keyed by name

Like gpu_gui_input but backed by nuklear's NK_EDIT_BOX with an 8 KB buffer and its own scrollbar, intended as a code/log scratch pad. State lives in an 8-slot table.

returns string -- the editor's current text (empty string when there is no window or the 8-slot table is full)

string code = gpu_gui_editor(20, 152, 600, 460, "src", "// type CX code here\nint x = 7;\nprintln(x * 6);\n");

sets the GUI widget font size in pixels, before the font atlas is baked

Only takes effect if called before the first widget renders (nuklear bakes its atlas on first use); the value is clamped to 8..64 and defaults to 18.

returns void

gpu_gui_fontsize(20);

return the X component of adding two 3D vectors (x1+x2)

CX has no vec3 value type, so vector ops are split into per-component scalar builtins; call vec3addx/y/z to build the sum vector. Only x1 and x2 are used.

returns float x1 + x2

vec3addx(1.0,2.0,3.0, 4.0,5.0,6.0)

return the Y component of adding two 3D vectors (y1+y2)

Component-wise scalar helper; only y1 and y2 are used.

returns float y1 + y2

vec3addy(1.0,2.0,3.0, 4.0,5.0,6.0)

return the Z component of adding two 3D vectors (z1+z2)

Component-wise scalar helper; only z1 and z2 are used.

returns float z1 + z2

vec3addz(1.0,2.0,3.0, 4.0,5.0,6.0)

return the X component of subtracting two 3D vectors (x1-x2)

Component-wise scalar helper; only x1 and x2 are used.

returns float x1 - x2

vec3subx(5.0,5.0,5.0, 1.0,2.0,3.0)

return the Y component of subtracting two 3D vectors (y1-y2)

Component-wise scalar helper; only y1 and y2 are used.

returns float y1 - y2

vec3suby(5.0,5.0,5.0, 1.0,2.0,3.0)

return the Z component of subtracting two 3D vectors (z1-z2)

Component-wise scalar helper; only z1 and z2 are used.

returns float z1 - z2

vec3subz(5.0,5.0,5.0, 1.0,2.0,3.0)

return the X component of a 3D vector scaled by a scalar (x*s)

Component-wise scalar helper; only x and s are used.

returns float x * s

vec3scalex(2.0,3.0,4.0, 10.0)

return the Y component of a 3D vector scaled by a scalar (y*s)

Component-wise scalar helper; only y and s are used.

returns float y * s

vec3scaley(2.0,3.0,4.0, 10.0)

return the Z component of a 3D vector scaled by a scalar (z*s)

Component-wise scalar helper; only z and s are used.

returns float z * s

vec3scalez(2.0,3.0,4.0, 10.0)

return the length (magnitude) of a 3D vector

Computes sqrt(x*x + y*y + z*z).

returns float sqrt(x^2 + y^2 + z^2)

vec3length(3.0, 4.0, 0.0)

return the Euclidean distance between two 3D points

Computes sqrt of the summed squared component differences.

returns float distance between the two points

vec3distance(0.0,0.0,0.0, 3.0,4.0,0.0)

return the dot product of two 3D vectors

Computes x1*x2 + y1*y2 + z1*z2.

returns float x1*x2 + y1*y2 + z1*z2

vec3dot(1.0,2.0,3.0, 4.0,5.0,6.0)

return the X component of the cross product of two 3D vectors

Computes y1*z2 - z1*y2.

returns float y1*z2 - z1*y2

vec3crossx(1.0,0.0,0.0, 0.0,1.0,0.0)

return the Y component of the cross product of two 3D vectors

Computes z1*x2 - x1*z2.

returns float z1*x2 - x1*z2

vec3crossy(1.0,0.0,0.0, 0.0,1.0,0.0)

return the Z component of the cross product of two 3D vectors

Computes x1*y2 - y1*x2.

returns float x1*y2 - y1*x2

vec3crossz(1.0,0.0,0.0, 0.0,1.0,0.0)

return the X component of the normalized (unit-length) vector

Computes x/|v|; returns 0.0 when the vector length is zero.

returns float x divided by the vector length, or 0.0 if length is 0

vec3normx(3.0,4.0,0.0)

return the Y component of the normalized (unit-length) vector

Computes y/|v|; returns 0.0 when the vector length is zero.

returns float y divided by the vector length, or 0.0 if length is 0

vec3normy(3.0,4.0,0.0)

return the Z component of the normalized (unit-length) vector

Computes z/|v|; returns 0.0 when the vector length is zero.

returns float z divided by the vector length, or 0.0 if length is 0

vec3normz(0.0,0.0,5.0)

return the X component of the linear interpolation between two 3D points

Computes x1 + (x2 - x1) * t; t is NOT clamped.

returns float x1 + (x2 - x1) * t

vec3lerpx(0.0,0.0,0.0, 10.0,0.0,0.0, 0.5)

return the Y component of the linear interpolation between two 3D points

Computes y1 + (y2 - y1) * t; t is NOT clamped.

returns float y1 + (y2 - y1) * t

vec3lerpy(0.0,0.0,0.0, 0.0,10.0,0.0, 0.5)

return the Z component of the linear interpolation between two 3D points

Computes z1 + (z2 - z1) * t; t is NOT clamped.

returns float z1 + (z2 - z1) * t

vec3lerpz(0.0,0.0,0.0, 0.0,0.0,10.0, 0.5)

return the angle in degrees between two 3D vectors

Computes acos(dot/(|a||b|)) converted to degrees; returns 0.0 if either vector has zero length, and the cosine is clamped to [-1,1].

returns float angle between the vectors in degrees, or 0.0 if either is zero-length

vec3angle(1.0,0.0,0.0, 0.0,1.0,0.0)

smoothly lerp a camera's target toward a world point

Moves the cx_gfx Camera3D target from its current position toward (tx,ty,tz) by fraction speed each call (speed clamped 0..1); call per-frame for smooth following.

returns void

camfollow(cam, tx, ty, tz, 0.1)

smoothly move a camera toward a target orbit distance

Slides the camera position along its current view direction so the distance to the target approaches dist by fraction speed (clamped 0..1); honors mindist/maxdist clamps set by camorbitsettings and is a no-op when position equals target.

returns void

camzoomto(cam, 20.0, 0.1)

apply a decaying random positional jitter to a camera

Call per-frame while shaking: undoes the previous frame's offset (so it composes with camfollow/zoom), then adds xorshift-random jitter scaled by intensity and a linear time-decay envelope over duration; intensity or duration <= 0 stops the shake. Only camera handles 1..7 hold shake state.

returns void

camshake(cam, 0.5, 1.0)

store min/max speed and distance clamps for a camera

Records orbital tuning on the camera's shake-state slot; the min/max distance is later honored by camzoomto. Only camera handles 1..7 hold this state.

returns void

camorbitsettings(cam, 0.1, 2.0, 5.0, 50.0)

load a game object from a JSON definition file and return its handle

Resolves name in order (raw path, data/ships/<name>.json, data/<name>, <name>.json), parses the JSON into a reusable object-pool slot, and reads optional scale plus model/shader assets (assets only load when a window is open). Grows the pool up to #pragma MaxGameObjects; on empty name or no loadable/parseable file it prints an error and exits the process (never returns a sentinel).

returns int object handle (>= 1); on failure it prints an error and exits, so it never returns an invalid handle

int h = goload(tmp);

free a game object and release its slot for reuse

Releases the object's JSON doc, any loaded model/shader, and its override array, then clears the slot so a later goload can reclaim it. No-op on an invalid handle.

returns void

gofree(h);

read a float property of a game object

Returns the runtime override for key if one was set via gosetf/goseti, otherwise reads the key from the object's JSON. Returns 0.0 on an invalid handle.

returns float property value (override first, else JSON member); 0.0 if the handle is invalid

speed = gogetf(obj, "speed")

read an integer property of a game object

Returns the runtime override for key if one was set, otherwise reads the key from the object's JSON. Returns 0 on an invalid handle.

returns int property value (override first, else JSON member); 0 if the handle is invalid

hp = gogeti(obj, "health")

read a string property of a game object

Reads the key from the object's JSON (string overrides are not supported — only numeric overrides exist). Returns an empty string on an invalid handle.

returns string property value from the JSON member; empty string if the handle is invalid

name = gogets(obj, "name")

set a runtime float override on a game object property

Stores an in-memory override for key (read back by gogetf/gogeti) without modifying the underlying JSON; grows the per-object override array up to #pragma MaxGameOverrides. No-op on an invalid handle.

returns void

gosetf(obj, "speed", 12.5)

set a runtime integer override on a game object property

Stores an in-memory override for key (kept as a double, read back by gogeti/gogetf) without touching the JSON. No-op on an invalid handle.

returns void

goseti(obj, "health", 100)

create a countdown timer and return its handle

Allocates a timer counting down from duration seconds (negative clamped to 0); reuses freed slots and grows the pool up to #pragma MaxGameTimers.

returns int timer handle (>= 1)

lastTmr = timercreate(1.0);

advance a timer by subtracting a delta from its remaining time

Decrements the timer's remaining time by delta, floored at 0. No-op on an invalid handle.

returns void

timerupdate(tmr, 0.016)

test whether a timer has counted down to zero

Returns 1 once the remaining time reaches 0, else 0; 0 for an invalid handle.

returns int 1 if remaining time <= 0, else 0 (0 for an invalid handle)

timerexpired(timercreate(1000.0))

reset a timer's remaining time back to its full duration

No-op on an invalid handle.

returns void

timerreset(tmr)

return a timer's elapsed fraction from 0.0 to 1.0

Computes 1 - remaining/duration, clamped to 0..1; a zero-length timer reports 1.0 (instantly done) and an invalid handle returns 0.0.

returns float progress in 0..1 (1.0 for a zero-length timer; 0.0 if the handle is invalid)

p = timerprogress(tmr)

poll a timer as a cooldown and auto-restart it when ready

Returns 1 the moment the timer reaches 0 and simultaneously reloads it to full duration for the next interval (the weapon/AI cooldown pattern); otherwise 0, and 0 for an invalid handle.

returns int 1 if the cooldown is ready (and it auto-restarts), else 0 (0 for an invalid handle)

if (cooldownready(tmr)) { fire(); }

return the Euclidean distance between two 3D points

Computes sqrt of the summed squared component differences (same as vec3distance).

returns float distance between the two points

dist3d(0.0,0.0,0.0, 3.0,4.0,0.0)

test whether two 3D points are within a given range

Compares squared distance against range squared (no sqrt), returning 1 if within range inclusive.

returns int 1 if the distance is <= range, else 0

inrange3d(0.0,0.0,0.0, 1.0,0.0,0.0, 2.0)

project a 3D world point to its screen X coordinate

Uses raylib GetWorldToScreen for the given camera; returns 0.0 when no window is open or the camera handle is invalid (headless-safe).

returns float screen-space X pixel of the projected point; 0.0 if no window/invalid camera

sx = worldtoscreenx(cam, wx, wy, wz)

project a 3D world point to its screen Y coordinate

Uses raylib GetWorldToScreen for the given camera; returns 0.0 when no window is open or the camera handle is invalid (headless-safe).

returns float screen-space Y pixel of the projected point; 0.0 if no window/invalid camera

sy = worldtoscreeny(cam, wx, wy, wz)

return the yaw heading in degrees from one XZ point to another

Computes atan2(x2-x1, z2-z1) in degrees on the XZ plane, where 0 degrees is +Z increasing toward +X.

returns float heading in degrees (0 = +Z, increasing toward +X)

h = headingto(x1, z1, x2, z2)

linearly interpolate between two packed colors

Blends two 0xAARRGGBB colors channel-wise (alpha, red, green, blue) with t clamped to 0..1, returning the packed result.

returns int the interpolated packed 0xAARRGGBB color

colorlerp(0, 16777215, 0.5)

blend a base color toward a flash color by an amount

Alias of colorlerp: t=0 returns col unchanged, t=1 returns full flashcol, with t clamped to 0..1.

returns int the blended packed 0xAARRGGBB color

c = colorflash(col, 0xFFFFFFFF, 0.5)

close the open asset bundle

returns void

assetClose();

load one asset by name from the open bundle

returns a handle to the loaded asset; 0 on failure

h = assetLoad("hero.png");

open an asset bundle for subsequent loads

The resolver works in two modes -- loose files on disk, or a packed datafile -- and this chooses the source. assetLoad then reads through whichever is open.

returns non-zero on success

assetOpen("game.dat");

load a file from disk as a blob

Callable, but its argument list is not derivable from its binding: it is bound only by the register VM's name table, where the C signature is the generic (vm, N) wrapper form. Named here so an absence is never mistaken for non-existence.

returns a blob handle; 0 on failure

h = blobLoad("data.bin");

create a perspective Camera3D and return its handle

Fills a camera slot with position/target/up/fov and CAMERA_PERSPECTIVE projection. Returns 0 if no window is open; hard errors (CX-E5025) if the 3-slot camera table is full.

returns 1-based camera handle; 0 if the window is not open

int cam = gpu_camera_new(0.0,10.0,10.0, 0.0,0.0,0.0, 0.0,1.0,0.0, 45.0);

begin 3D rendering through a camera (raylib BeginMode3D)

Enters 3D mode for this camera; also feeds the camera position into every loaded shader's viewPos uniform for correct lighting. All 3D draws must sit between this and gpu_camera_end.

returns void

gpu_camera_begin(cam);

set a camera's position vector

returns void

gpu_camera_setpos(cam, 1.0,2.0,3.0);

set a camera's look-at target vector

returns void

gpu_camera_settarget(cam, 0.0,0.0,0.0);

draw a filled 3D sphere at (x,y,z) (raylib DrawSphere)

returns void

gpu_draw_sphere(3.0,0.0,0.0, 1.0, 255);

draw a reference grid on the XZ plane centered at the origin (raylib DrawGrid)

returns void

gpu_draw_grid(10, 1.0);

draw a 3D line from (x1,y1,z1) to (x2,y2,z2) (raylib DrawLine3D)

returns void

gpu_draw_line3d(0.0,0.0,0.0, 1.0,1.0,1.0, 255);

draw a 3D point at (x,y,z) (raylib DrawPoint3D)

returns void

gpu_draw_point3d(1.0,1.0,1.0, 255);

draw a 2D image as a camera-facing billboard at a 3D position (raylib DrawBillboard)

Reuses an existing 2D image/texture handle from the image registry; always faces the given camera.

returns void

gpu_draw_billboard(cam, tex, 0.0,2.0,0.0, 1.0, 255);

draw an ORIENTED textured billboard (raylib DrawBillboardPro): a quad

of one texture at a world position, its height axis aligned to `up`, sized (w,h) in world units, spun `rot` degrees about the view axis, tinted col(0xRRGGBB) at `alpha`. Origin is centred on the position. This is the general oriented-quad primitive (strands, tracers, beams, sprites-along-a- path); unlike gpu_draw_billboard it is NOT locked to a camera-facing square. Draws into the CURRENT blend/depth state -- bracket a glow pass with gpu_blend_add/gpu_blend_normal and gpu_depth_write for clean additive sums.

gpu_draw_billboard_pro(cam, tex, 0,0,0,0, x,y,z, dx,dy,dz, 0.4, len, 0, rgb(120,180,255), 200)

toggle depth-buffer WRITES (rlgl global state). on=0 stops transparent

billboards/particles from writing depth -- so overlapping additive sprites sum cleanly instead of a near quad punching a rectangular depth hole that rejects the sprites behind it (the transparent-quad self-occlusion artifact). on=1 restores normal depth writes. Pair off/on around a glow pass, and re-enable AFTER the blend batch is flushed (i.e. after gpu_blend_normal).

gpu_blend_add(); gpu_depth_write(0); ...draw strands...; gpu_blend_normal(); gpu_depth_write(1);

load a 3D model from a file and return its handle (raylib LoadModel)

Allocates a model slot with a leak-tracking ARC bucket. A failed load (meshCount==0) prints a CX error and exits (FP4), never a silent invisible model.

returns 1-based model handle; 0 if the window is not open; hard-exits on load failure

model m = gpu_model_load("ship.obj");

generate a sphere mesh and return it as a model handle (raylib GenMeshSphere)

returns 1-based model handle; 0 if the window is not open

int sph = gpu_mesh_sphere(1.0, 16, 16);

draw a model with rotation axis/angle and per-axis scale (raylib DrawModelEx)

returns void

gpu_model_draw_ex(pln, 0.0,0.0,0.0, 0.0,1.0,0.0, 45.0, 1.0,1.0,1.0, 255);

apply a 2D image as a model's first-material diffuse map (raylib SetMaterialTexture)

Uses an existing image/texture handle from the 2D image registry as MATERIAL_MAP_DIFFUSE on material 0.

returns void

gpu_model_texture(cube, tex);

count currently-live model slots

Leak-check signal for the `model` resource type: number of in-use slots in the model table.

returns number of live model slots (int)

int n = gpu_model_livecount();

request multi-sample anti-aliasing at the given level

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). The level is STORED and applied when the window OPENS -- calling it afterwards has no effect on the live window. Any level above 0 turns on raylib's 4x MSAA hint; a negative level clamps to 0 (off).

returns void

gpu_msaa(4);   // before the window opens

set the default sampling filter for model textures

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Applies to textures loaded or applied AFTER this call; never calling it leaves every texture exactly as its loader made it. Modes: 0 point (crisp pixel art), 1 bilinear, 2 trilinear, 3 anisotropic.

returns void

gpu_texture_filter(1);

set the sampling filter for ONE model's textures, now

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Applies a filter mode to that model's diffuse textures immediately, overriding the global default gpu_texture_filter set. It is TEXTURE FILTERING, not shading -- it does not change how normals are interpolated.

returns void

gpu_model_smooth(m, 1);

load a shader from vertex + fragment shader files (raylib LoadShader)

An empty-string path becomes NULL so raylib uses its built-in default for that stage. Also caches the viewPos uniform location so gpu_camera_begin can feed camera position automatically.

returns 1-based shader handle; 0 if the window is not open

shader s = gpu_shader_load("", "");

count currently-live shader slots

Leak-check signal for the `shader` resource type: number of in-use shader slots.

returns number of live shader slots (int)

int n = gpu_shader_livecount();

set a float uniform value on a shader (raylib SetShaderValue)

Looks up the uniform by name; missing uniform is a silent no-op.

returns void

gpu_shader_setf(sh, "strength", 0.5, 0);

set a vec3 uniform value on a shader (raylib SetShaderValue)

Packs (x,y,z) into a float[3] and uploads to the named uniform; missing uniform is a silent no-op.

returns void

gpu_shader_setvec3(sh, "tint", 1.0,0.5,0.2, 2);

set a shader's "ambient" vec4 light uniform from an RGBA color

Normalizes r,g,b,a (0..255) to 0..1 and uploads to the shader's "ambient" uniform; no-op if that uniform is absent.

returns void

gpu_light_ambient(sh, 10,10,25, 255);

add a directional light to a shader and return its index (rlights CreateLight)

Creates a LIGHT_DIRECTIONAL travelling along (dx,dy,dz): the light sits at the origin with its target along the direction vector.

returns 1-based light index; 0 if the shader handle is invalid; hard errors if the 16-light table is full

int sun = gpu_light_directional(sh, -1.0,-0.5,0.0, 255,240,200,255);

assign a shader to a model's first material

Sets material[0].shader on the model so it renders with the given shader. No-op if either handle is invalid or the model has no materials.

returns void

gpu_model_shader(cube, sh);

read a model's bounding-box minimum x (raylib GetModelBoundingBox)

returns bounding box min.x as float; 0.0 if the handle is invalid

float bminx = gpu_model_minx(cube);

read a model's bounding-box minimum y (raylib GetModelBoundingBox)

returns bounding box min.y as float; 0.0 if the handle is invalid

float bminy = gpu_model_miny(cube);

read a model's bounding-box minimum z (raylib GetModelBoundingBox)

returns bounding box min.z as float; 0.0 if the handle is invalid

float bminz = gpu_model_minz(cube);

read a model's bounding-box maximum x (raylib GetModelBoundingBox)

returns bounding box max.x as float; 0.0 if the handle is invalid

float bmaxx = gpu_model_maxx(cube);

read a model's bounding-box maximum y (raylib GetModelBoundingBox)

returns bounding box max.y as float; 0.0 if the handle is invalid

float bmaxy = gpu_model_maxy(cube);

read a model's bounding-box maximum z (raylib GetModelBoundingBox)

returns bounding box max.z as float; 0.0 if the handle is invalid

float bmaxz = gpu_model_maxz(cube);

build a pick ray from the mouse position through a camera (raylib GetScreenToWorldRay)

Stores the ray in a round-robin ring of transient slots so per-frame calls never exhaust the table. Returns a 1-based ray handle for use with gpu_ray_x/y/z and the ray-collision tests.

returns 1-based ray handle; 0 if the window is closed or the camera is invalid

int ray = gpu_ray_mouse(cam);

test whether a ray hits a sphere (raylib GetRayCollisionSphere)

returns 1 if the ray hits the sphere, else 0 (also 0 if the ray handle is invalid)

int rhitS = gpu_collide_ray_sphere(ray, 0.0,0.0,0.0, 1.0);

test whether a ray hits an axis-aligned box (raylib GetRayCollisionBox)

Box given by its min and max corners.

returns 1 if the ray hits the box, else 0 (also 0 if the ray handle is invalid)

int rhitB = gpu_collide_ray_box(ray, -1.0,-1.0,-1.0, 1.0,1.0,1.0);

end 3D camera mode and go back to screen-space drawing

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Pairs with the camera-begin call; drawing between them is in world space.

returns void

gpu_camera_end();

stop drawing through the active shader

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns void

gpu_shader_end();

how long the last frame took, in seconds

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). The delta to scale movement by so speed is frame-rate independent.

returns the frame time in seconds

x = x + speed * gpu_frame_time();

load a .ttf/.otf font at a base pixel size, returning a font handle

raylib LoadFontEx into a 1-based slot table (32 slots). size<=0 defaults to 20. A full table is a hard CX-E5025 error.

returns 1-based font handle, or 0 if no window is open

fnt.i = gpu_font_load("data/fonts/Nunito/static/Nunito-SemiBold.ttf", 34);

draw text at (x,y) using a loaded font handle at a pixel size

raylib DrawTextEx with the font from gpu_font_load; falls back to the built-in default font (DrawText) if font_id is invalid. size<=0 uses the font's loaded base size.

returns void

gpu_draw_text_font(px, py, fntB, "MOUNT EDITOR", colHi, sc(30));

load a font from an in-memory embed() blob, returning a font handle

raylib LoadFontFromMemory; `ext` is the format hint (".ttf"/".otf"). Same slot handle as gpu_font_load.

returns 1-based font handle, or 0 on failure/no window

int fnt = gpu_font_loadmem(ttf, ".ttf", 24);

count currently-loaded font slots

Live-slot introspection for leak/churn tests over the `font` resource type.

returns number of live font slots

int before = gpu_font_livecount() + gpu_model_livecount() + gpu_shader_livecount();

load an image file into a GPU texture, returning a texture handle

raylib LoadImage + LoadTextureFromImage into a 1-based slot. Requires an open window. Returns 0 on failure (no window, missing/undecodable file, or table full).

returns 1-based texture handle, or 0 on failure

img.i = gpu_image_load("data/ships/" + shipFile[0] + ".png");

load an image and apply an image-treatment CLASS at load time

The class (see cx_imgclass.h) is a recipe of operations run automatically: pixel-stage fixes (synthesize alpha from brightness, black transparent edges, force opaque, premultiply) then the GL filter (smooth/sharp/mipmaps). Built-in classes: particle, smoke, sprite, texture, background; a data/imageclasses.json section (gpu_image_classes) can add or redefine them.

returns texture handle usable like gpu_image_load; 0 on failure

tex = gpu_image_load_as("fx/puff.png", "particle")

load an image-class override file, redefining/adding treatment recipes

The file is a JSON object of the shape { "imageClasses": { "<name>": ["op", "op", ...], ... } } where each op is one of: smooth, sharp, mipmaps, alphaFromLuma, edgeBlack, opaque, premultiply. Each listed class replaces (or adds) a recipe; classes not mentioned keep their built-in defaults. Unknown op names are reported loudly and skipped (FP4). An absent file or missing "imageClasses" section is a silent no-op, so the built-in defaults simply stand.

returns nothing

gpu_image_classes("data/imageclasses.json")

load a texture from an in-memory embed() blob, returning a texture handle

raylib LoadImageFromMemory then GPU upload; `ext` is the format hint (".png"/".jpg"). Same handle space as gpu_image_load.

returns 1-based texture handle, or 0 on failure

int img = gpu_image_loadmem(png, ".png");

destroy a texture handle now, unloading its GPU texture

Unconditional free (UnloadTexture, or UnloadRenderTexture for render targets); drops the resource bucket then reclaims the slot.

returns void

if (img > 0) { gpu_image_free(img); }

get a texture's width in pixels

returns texture width, or 0 for an invalid handle

iw.i = gpu_image_width(img);

get a texture's height in pixels

returns texture height, or 0 for an invalid handle

ih.i = gpu_image_height(img);

set the GPU texture-table capacity before the window opens

Raises the maximum texture slots (default 64), clamped to 16..8192. Must be called before the first image load; a no-op once the table is allocated. The underlying C function returns nothing (the I_I sig is only for binding generation).

returns void

gpu_image_cap(384);

create a blank transparent render-target texture of width x height

raylib LoadRenderTexture, cleared to transparent. Draw into it between gpu_image_begin/gpu_image_end, then use the handle like any texture. Returns 0 if no window or non-positive size.

returns 1-based texture handle, or 0 on failure

gPlayerComposite = gpu_image_new(COMPW, COMPH);

redirect subsequent draw calls into a render-target texture

raylib BeginTextureMode on the target handle; must be paired with gpu_image_end. No-op for a non-target handle.

returns void

gpu_image_begin(comp);

stop drawing into the current render-target texture

raylib EndTextureMode.

returns void

gpu_image_end();

clear the active render target to a color at an alpha

raylib ClearBackground; call between gpu_image_begin/gpu_image_end (e.g. alpha=0 for a transparent canvas before compositing).

returns void

gpu_image_clear(rgb(0, 0, 0), 0);

draw a texture at (x,y) scaled to width x height

raylib DrawTexturePro; render-target textures are y-flipped automatically so they present right-side-up.

returns void

gpu_image_draw(img0, sx0 - dw/2, sy0 - dh/2, dw, dh);

draw a sub-rectangle (atlas cell) of a texture, scaled to a destination rect

raylib DrawTexturePro: source cell (sx,sy,sw,sh) mapped onto destination (dx,dy,dw,dh). Render targets are y-flipped automatically.

returns void

gpu_image_draw_region(img, 400, 100, 200, 240, 0, 0, gpu_image_width(img) / 2, gpu_image_height(img));

the general 2D image blit (raylib DrawTexturePro verbatim):

SOURCE sub-rect + DEST rect + pivot + clockwise rotation + TINT. The one draw that supersedes region/rotated/region_rot when colour is needed (tinted strands/bursts, a lightning texture drawn at any angle/hue from ONE asset). Native-only (raylib window); float coords match gpu_draw_billboard_pro.

returns void

gpu_image_draw_pro(bolt, 0,0,0,0, x,y, 8,len, 4,0, angle, 0xff3030, 200)

loads an image file (PNG/JPG/...) from disk into a CPU image in RAM

Calls raylib LoadImage and normalises the pixels to R8G8B8A8; needs no open window. Returns 0 if the file is missing or fails to decode.

returns cx_int image handle (1-based), or 0 on failure

int sheet = imageOpen("art/ModuleFrames.png");

creates a blank CPU image of the given size filled with a colour

Colour is packed 0xAARRGGBB (alpha 0 means opaque, as elsewhere). Returns 0 if w or h is <= 0 or the slot allocation fails.

returns cx_int image handle (1-based), or 0 on invalid size/failure

image h = imageNew(4, 4, 0);

duplicates a CPU image into a new independent image

Wraps raylib ImageCopy. Returns 0 if the source handle is invalid.

returns cx_int new image handle (1-based), or 0 on failure

int dup = imageCopy(h);

crops a CPU image in place to a rectangular region

Wraps raylib ImageCrop; mutates the existing image. No-op if the handle is invalid.

returns void

imageCrop(h, 0, 0, 16, 16);

crops a rectangular region of a CPU image into a new image

Wraps raylib ImageFromImage; leaves the source untouched. Returns 0 if the source handle is invalid.

returns cx_int new image handle (1-based), or 0 on failure

int part = imageCropCopy(h, 0, 0, 16, 16);

resizes a CPU image in place, resampling its pixels to the new size

Wraps raylib ImageResize (bicubic), so this SCALES the picture rather than cropping or padding it -- the whole image still fills the new rectangle and the aspect ratio is the caller's to preserve. The alpha channel survives. It is the last step of a derivation and mutates the handle you already own; there is deliberately no `imageResizeCopy`, because `imageCopy` composes to give that and a second name for one operation is a forwarder (rule 33).

returns nothing. A bad handle is a no-op, as everywhere in this family. A non-positive dimension is REFUSED rather than obeyed: a zero-width image is a live handle whose every later read is meaningless, which is the silent-wrong this project does not ship (FP4).

int a = imageOpen("plaque.png");
imageResize(a, 424, 128);
imageSave(a, "plaque_web.png");

copies a rectangular region from one CPU image onto another

Wraps raylib ImageDraw; the source rect (sx,sy,sw,sh) is drawn to the destination at (dx,dy) at the same size. No-op if either handle is invalid.

returns void

imageBlit(dst, src, 0, 0, 16, 16, 0, 0);

makes every pixel of a given colour fully transparent

The white-box alpha bake: wraps raylib ImageColorReplace, swapping the keyed colour for transparent (BLANK). No-op if the handle is invalid.

returns void

imageColorKey(sheet, parseHex("ffffff"));

scales the whole image's alpha channel by a/255

Multiplies every pixel's alpha by a/255 in place; a is clamped to 0..255. No-op if the handle is invalid.

returns void

imageAlpha(h, 128);

sets the alpha of a rectangular region to a fixed value

Writes alpha = a to every pixel in the region, which is clipped to the image bounds; a is clamped to 0..255. No-op if the handle is invalid.

returns void

imageRectAlpha(h, 0, 0, 16, 16, 128);

exports a CPU image to a file, format chosen by the extension

Wraps raylib ExportImage. No-op if the handle is invalid.

returns void

imageSave(sheet, "art/_alpha/ModuleFrames.png");

uploads a CPU image to the GPU texture registry for drawing

The one bridge from the design-time CPU world to the run-time GPU draw registry (raylib LoadTextureFromImage). Needs an open window/GL context; returns 0 when headless or if the handle is invalid.

returns cx_int GPU texture handle, or 0 if headless/invalid

int tex = imageToTexture(h);

releases a CPU image and frees its slot immediately

Unconditional destroy that drops the resource bucket (bypassing ARC) then unloads the image; a bare imageFree(h) call still works standalone. No-op if the handle is invalid.

returns void

imageFree(sheet);

decrements an owned image's ARC refcount, reclaiming the slot at zero

Compiler-emitted at scope exit for an owned `image` local (CXB_RESOURCE bucket ARC); reclaims the slot when the refcount reaches 0. Not normally written by hand.

returns void

imageDecref(h);

returns a CPU image's width in pixels

returns cx_int width in pixels, or 0 if the handle is invalid

return imagew(h);

returns a CPU image's height in pixels

returns cx_int height in pixels, or 0 if the handle is invalid

int hgt = imageH(h);

reads the packed 0xAARRGGBB colour of a pixel at (x, y)

Reads the R8G8B8A8 pixel and packs it as (a<<24)|(r<<16)|(g<<8)|b. Returns 0 if the handle is invalid or (x,y) is out of range.

returns cx_int packed 0xAARRGGBB colour, or 0 if out of range/invalid

int c = imageGetPixel(h, 0, 0);

returns the number of currently-open CPU image slots

Always-available leak introspection (not gated by `checks on`); the CPU image pool grows on leak, so a rising count signals leaked handles.

returns cx_int count of live CPU image slots

int before = imagelivecount();

close the graphics window

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns void

gpu_screen_close();

request that the frame loop stop

ACCEPTED AND DOES NOTHING on both backends. The loop guard is gpu_frame_poll, which already answers 0 once the window is closed -- so there is nothing for this to set. Listed so you know it is a no-op rather than assuming it ends your loop.

returns void

while (gpu_frame_poll()) { ... }

set how the frame loop is PACED

Replaces the hardcoded 60 fps that every CX program shipped with; the default is still 60, so a program that never calls this paces exactly as before. Callable BEFORE or AFTER the screen is open. Before: the choice is stored and applied at open (vsync must be a config flag before InitWindow, so this is the only way to get vsync from the first frame). After: applied immediately, so a settings screen can change pacing live without reopening the window.

returns nothing.

gpu_target_fps(144);   // cap at 144
gpu_target_fps(0);     // follow the display

test whether the graphics window is still open

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). The canonical main-loop guard -- `while (gpu_frame_poll()) { ... }` -- so the loop exits cleanly on the close button or Alt+F4. It is the INVERSE of raylib's should-close, not an event pump; the frame begin/end pair does the pumping. Variadic and argument-tolerant for beta-era 1-argument calls.

returns non-zero while the window is open and no close has been requested; 0 once it has

while (gpu_frame_poll()) { gpu_frame_begin(); ... gpu_frame_end(); }

the mouse pointer's x position in the window

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns x in pixels

mx = gpu_mouse_x();

the mouse pointer's y position in the window

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns y in pixels

my = gpu_mouse_y();

how far the wheel moved since the last frame

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns the wheel delta; 0 if it did not move

dz = gpu_mouse_wheel();

return 1 while a mouse button is held down

raylib IsMouseButtonDown. Button codes: 0=left, 1=right, 2=middle; other values return 0.

returns 1 while held, else 0

down.i = gpu_mouse_button(0);

take the window's current contents as an image

Returns an ordinary image handle, so every `image*` verb works on it: save it with imageSave, measure it with imageW/imageH, trim it with imageCrop, release it with imageFree. It captures the window THIS program owns -- not another program's window and not the desktop, neither of which has a portable answer. Call it inside the frame, between gpu_frame_begin and gpu_frame_end, so it reads what you have just drawn rather than whatever survived the buffer swap. THE IMAGE IS IN REAL PIXELS, WHICH MAY NOT BE YOUR WINDOW'S NUMBERS. On a high-DPI display the framebuffer is larger than the size you asked for -- a 320x240 window captures 640x480 on a Retina Mac, and everything you drew is at the same scale inside it. Ask the image (imageW/imageH), not the window (gpu_screen_width), when the numbers have to match the picture. Unlike its neighbours here, this REFUSES (CX-E5048) when no window is open instead of answering 0. Zero is an honest width for an unopened screen; it is not an honest picture, and a caller's next move is to save the handle and believe it.

returns an image handle, ready for any image verb

while (gpu_frame_begin(rgb(20,20,30))) { drawWorld(); shot = gpu_capture(); imageSave(shot, "frame.png"); imageFree(shot); gpu_frame_end(); }

return 1 while a key (raylib keycode) is held down

raylib IsKeyDown.

returns 1 while held, else 0

if (gpu_key_down(65) == 1) { marc[sel] = marc[sel] - 2; }

switch to additive blending for subsequent draws

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). What makes glows and particle flares brighten what is under them.

returns void

gpu_blend_add();

switch back to normal alpha blending

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013).

returns void

gpu_blend_normal();

draw one atlas cell centred, scaled and rotated

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). The source rectangle picks the cell out of a sprite atlas; (cx, cy) is the drawn CENTRE.

returns void

drawImageRegionRot(atlas, 400, 300, 64, 64, 0, 0, 32, 32, 90);

draw an image centred, scaled and rotated

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). (cx, cy) is the CENTRE, and the rotation pivots about that centre. Degrees, clockwise.

returns void

drawImageRot(spr, 400, 300, 64, 64, 45);

signal that the event loop should stop

Callable, but its argument list is not derivable from its binding: it is bound only by the register VM's name table, where the C signature is the generic (vm, N) wrapper form. Named here so an absence is never mistaken for non-existence.

returns void

eventQuit();

load a font for later use

ACCEPTED AND DOES NOTHING: there is no font registry yet -- raylib's built-in font is what draws. Kept so beta-era source compiles, and listed so you know it is a no-op rather than assuming a font was loaded. Pass 0 as the font id wherever one is wanted.

returns 0, always -- the default font id

f = fontLoad("arial.ttf", 20);

select a loaded font for subsequent text

ACCEPTED AND DOES NOTHING: there is no font registry yet -- raylib's built-in font is what draws. Kept so beta-era source compiles, and listed so you know it is a no-op rather than assuming a font was loaded. Pass 0 as the font id wherever one is wanted.

returns void

fontSet(f);

draw a string at a screen position

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Two forms: four arguments use the default 20-pixel size, five pick the size.

returns void

gpu_draw_text(10, 10, "score", 0xFFFFFF, 32);

draw an image centred, scaled, and multiplied by a colour

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). The position is the image's CENTRE, not its top-left. Reuses the particle tint blit, so one cached white sprite can be drawn in any colour with true alpha.

returns void

gpu_image_draw_tint(spr, 400, 300, 64, 64, 0xFF8080, 200);

the key pressed this frame

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Reports one key per frame; 0 when nothing was pressed.

returns the key code, or 0

k = gpu_key_pressed();

swap the front and back buffers

ACCEPTED AND DOES NOTHING: raylib swaps buffers itself when the frame ends, so there is nothing left for this to do. Kept because beta-era source calls it, and listed here so you know it is a no-op rather than assuming it is what makes your drawing appear -- that is gpu_frame_end.

returns void

gpu_frame_end();

resize the graphics window

Reopens the screen at the new size with an empty title. Read the live dimensions back with the screen-width and screen-height builtins rather than assuming the request took effect.

returns void

gpu_screen_resize(1920, 1080);

measure how wide a string will be drawn

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). Two forms: one argument measures with the default font at size 20; three take a registered font id, the text and an explicit size.

returns the width in pixels

w = gpu_text_width("score");

swap the front and back buffers

Callable, but its argument list is not derivable from its binding: it is bound only by the register VM's name table, where the C signature is the generic (vm, N) wrapper form. Named here so an absence is never mistaken for non-existence.

ACCEPTED AND DOES NOTHING, for the same reason as gpu_screen_flip: the frame end swaps buffers.

returns void

gpu_frame_end();

measure how wide a string will be drawn

The same measurement as gpu_text_width on native. ON THE REGISTER VM there is no window to measure against, so it falls back to a flat EIGHT PIXELS PER CHARACTER -- useful for laying out headless, but not a real measurement.

returns the width in pixels

w = textWidth("score");

clear the whole screen to a color

Wraps raylib ClearBackground; tolerates being called outside a BeginDrawing/EndDrawing frame by opening a transient one.

returns void

gpu_screen_clear(0);

draw a filled rectangle with an explicit alpha

Like gpu_draw_rect but overrides the color's alpha with `alpha` (0-255, clamped).

returns void

gpu_draw_rect_alpha(10, 60, 200, 15, rgb(100, 80, 60), 128);

draw a line from (x1,y1) to (x2,y2)

raylib DrawLine.

returns void

gpu_draw_line(10, 110, 200, 110, rgb(100, 80, 60));

draw a filled circle centred at (x,y) with a radius

raylib DrawCircle.

returns void

gpu_draw_circle(msx, msy, r2, colMnt);

draw a filled circle with an explicit alpha

Like gpu_draw_circle but overrides alpha (0-255); used for soft translucent particles.

returns void

gpu_draw_circle_alpha(485, 140, 45, rgb(255, 130, 80), 150);

draw a single pixel at (x,y)

raylib DrawPixel.

returns void

gpu_draw_pixel(560, 60, rgb(255, 255, 255));

draw a filled triangle through three points

raylib DrawTriangle, drawn in both windings so it is order-independent (no back-face culling gap).

returns void

gpu_draw_triangle(340, 330, 430, 330, 385, 255, rgb(210, 210, 70));

filled rounded rectangle (raylib DrawRectangleRounded)

Corner smoothness is a fixed internal default of 8 segments/corner (not a parameter -- no consumer needs it; a one-line signature extension if one ever does). Both engines (GAP, 3.5.006.0).

returns void

gpu_draw_roundrect(x, y, 200, 80, 0.3, 0x2244aa)

filled rounded rectangle with an explicit alpha

Twin of gpu_draw_roundrect (family idiom, cf. gpu_draw_rect / gpu_draw_rect_alpha). 8 segments/corner. Both engines.

returns void

gpu_draw_roundrect_alpha(x, y, 200, 80, 0.3, 0x2244aa, 128)

rounded-rectangle OUTLINE (raylib DrawRectangleRoundedLinesEx)

8 segments/corner. Both engines.

returns void

gpu_draw_roundrect_lines(x, y, 200, 80, 0.3, 2.0, 0x8fb2ff)

rounded-rectangle outline with an explicit alpha

Twin of gpu_draw_roundrect_lines. The Gigantica shield HUD box (rounded outline + intensity) is the named consumer. 8 segments/corner. Both engines.

returns void

gpu_draw_roundrect_lines_alpha(x, y, 200, 80, 0.3, 2.0, 0x8fb2ff, 180)

open the graphics window at w x h and start its world

Idempotent: a second call while a window is open does nothing. w or h <= 0 falls back to 800 x 600. The window is RESIZABLE on the desktop, so the size you ask for is where it STARTS -- read gpu_screen_width()/gpu_screen_height() if your layout must follow it, and gpu_window_resized() to know when it moved. ON THE WEB (a wasm build in a browser tab) whether this size is honoured is decided by your own program text, not by a flag: a program that references gpu_screen_width() or gpu_screen_height() ANYWHERE has said it can lay out against a size it did not pick, so its canvas fills the browser window and this w x h is only where it starts; a program that never asks has hardcoded its world, so its canvas is exactly w x h and the rest of the page is left alone. Desktop behaviour is identical either way.

gpu_screen_open(1280, 720, "My Game")

draw a filled rectangle at (x,y) sized width x height

raylib DrawRectangle.

returns void

gpu_draw_rect(10, 10, 100, 100, rgb(50,50,50));

open a frame, clear it to color, and say whether to keep going

Wraps raylib BeginDrawing + ClearBackground and returns 0 when the user has asked to close, so the idiom is `while (gpu_frame_begin(color)) { ... }`. Also fires the per-frame automation + GUI hooks. WHAT COUNTS AS "asked to close": on the desktop, the window's close button or the ESC key (raylib's default exit key). IN A BROWSER TAB (a wasm build) there is no close button, and raylib's web platform never reports one -- so ESC is the only exit, and CX checks it there itself so that the same `while` loop ends on the same key it ends on natively. A program whose only exit is the close button therefore never ends on the web; give it a frame cap or an ESC.

returns 1 to draw this frame, 0 once the window should close

while (gpu_frame_begin(rgb(20,20,30))) { ...draw...; gpu_frame_end(); }

finish the frame and present it

Runs on both engines (since GAP, 3.5.006.0 -- until then the register VM refused it with CX-E1013). This is what makes drawing appear; it also swaps the buffers, which is why the flip calls are no-ops.

returns void

gpu_frame_end();

draw a scene document, once

Walks the scene's elements in document order and draws each one the renderer knows, reading its place, its size and its look from the element's own fields. The program never names a drawing verb: it writes fields on the document, and this walks them. THE SEVENTEEN TYPES IT DRAWS. Flat: `rect` (plain, rounded or outlined), `circle`, `text`, `line`, `triangle`, `pixel`, `image`. In the world, inside the camera: `cube`, `sphere`, `cylinder`, `plane`, `line3d`, `point3d`, `grid`, `model`, `billboard`, `emitter3d`. And `emitter`, which is flat. `window` and `camera` are ACTED ON rather than drawn. Ask the running renderer with `mediaReport()["types"]` rather than keeping a copy of this list. WHERE AN ELEMENT IS. `->x` `->y` `->w` `->h` are percent of the window, PER AXIS -- x and w of its width, y and h of its height -- unless `->units` is `"absolute"`. `->pos` `->dim` `->target` `->axis` are world coordinates and are NEVER percent: a world has no edges to be a percentage of. `->points` holds the corners of a shape whose place is not one x,y (a line reads four numbers, a triangle six). `->z` is what covers what -- an ordering, not a distance -- and does not yet order the draw; that is the renderer's remaining debt. HOW IT LOOKS. `->color`, `->alfa1` (opacity 0-100), `->tint`, `->round` (corner roundness 0-1), `->outline` (thickness in pixels; absent or 0 means FILLED, and it is what makes every `*_wires` and `*_lines` variant one shape), `->size` (a text's height in pixels), `->hidden`. WHAT IT SHOWS. `->source` is a filename, the bytes, or PARSEDOC's own image document; `->frame` is the part of the source drawn, in the SOURCE's own pixels; `->pivot` is what a rotation turns about, in percent of the element's own box; `->rot` is that rotation; `->scale` sizes a model or a billboard. `->orgw` and `->orgh` are written by the renderer when the source loads. BEHAVIOUR AND EVENTS. `->rules` is CX source as TEXT, compiled at run time, with the element bound as `e`; `->tick` asks for it every frame rather than only when the element changed. `->hover` and `->clicked` are written by the renderer -- `->clicked` is the frame a press BEGAN inside the element, and it is cleared once the rules have seen it. THE WINDOW ELEMENT carries `->fullscreen`, `->maximized`, `->resized`, `->load` (`"lazy"` or `"full"`, the scene's default), and the input the renderer sampled: `->mouse` (percent), `->buttons`, `->wheel`, `->key`, `->char`. THE CAMERA carries `->pos`, `->target` and `->fov`. AN EMITTER carries `->source` (the effects file), `->effect`, `->on`, `->burst`, `->dir` and `->vel`. THE DRAW IS GATED ON `->changed`, through a cached render target priced before it was relied on: at one changed frame in a hundred it costs 12 ms where an immediate loop costs 507, and at every-frame change it is still 13% cheaper. The renderer CLEARS the flag as it acts, because "only the changed items are acted on" is only true if acting is what ends the change. A change walks `->parent` and `->next` in both directions, and the flag is its own visited mark, so a cycle stops on its second arrival. A LIVE EMITTER MAKES EVERY FRAME STALE, and that is correctness rather than caution: its particles move inside the particle system, so nothing in the document changes while the picture does.

returns how many elements it drew; -1 when the program never declared a media anywhere, so no renderer was linked

media scene = parseDoc(text); mediaDraw(scene);
n.i = mediaDraw(scene);

hand the window to the renderer and get it back when it closes

THE FRAME IS THE RENDERER'S, which is what "the renderer is invisible" means in practice: a program opens a window, hands over its scene, and writes no drawing verb at all -- not even a thin one. gpu_screen_open(640, 480, "title"); mediaRun(scene, 0); gpu_screen_close(); The frame clears to black and a scene that wants a background says so with an element, not with an argument -- one fewer parameter, and the background stays IN the document with every other visual fact. `mediaDraw` is the STEP this is the LOOP over, and they are two operations rather than two names for one: a check cannot open a window, so the step is what a check drives. IT OWNS THE WHOLE FRAME, which is more than the drawing. Each pass samples the pointer and the keyboard onto the scene, runs the rules, walks the change, updates any particle system the scene is running, draws the world inside the camera and the flat elements on top of it, and spends the flags it acted on. A program that hands over its scene writes none of that.

returns how many frames it ran -- 0 with no window, which is the honest answer rather than a hang

mediaRun(scene, 0);
n.i = mediaRun(scene, 120);

what the last walk saw, as a document

One handle rather than a builtin per number: `drawn` how many were drawn, `hidden` how many carried `->hidden`, `changed` how many carried `->changed` once the links had been walked, `unknown` how many drew nothing -- a `->type` the renderer does not know, or one it knows whose source would not load -- `walked` how many elements the propagation reached, `ruled` how many rules ran, `acted` how many elements were acted on rather than drawn (the window, the camera, an emitter), `stale` whether anything changed this frame, `redrew` whether the frame rebuilt the cached target or blitted the one it already had, and `types` the list of `->type` names this renderer draws. `types` IS THE FACE SAYING WHAT IT DRAWS, and it exists so a reader -- a check, a second provider, a person -- can ASK rather than keep a copy. A fixture that names every type the renderer claims cannot fall behind it; one written by hand falls behind the day a family lands. `walked`, `stale` AND `redrew` ARE WHAT MAKE THE RENDERER CHECKABLE. A propagation that terminates and a draw that was correctly skipped both look precisely like nothing happening, and "nothing happening" is not a measurement. `stale` AND `redrew` ARE TWO FACTS, not one spelled twice. `stale` is the question the gate asks -- did anything change? -- and has the same answer with a window and without one. `redrew` is what that answer CAUSED, and is only meaningful where a cached target exists, which means a window. A check that cannot open one reads `stale`. It exists so a scene can be checked WITHOUT a window and without reading pixels: the renderer says what it did instead of leaving a caller to infer it (FP4).

returns a json document; an invalid one when no renderer was linked

json r = mediaReport(); println(str(r["drawn"]));
json t = mediaReport()["types"];   // what this renderer draws
if (r["unknown"]) { println("the scene names a type the renderer does not know"); }
json r = mediaReport(); if (r["redrew"]) { println("the target was rebuilt"); }

loads particle-effect templates from a JSON file and resets the particle pool

Parses each effect under the JSON "effects" object into a named template; the "maxParticles" field sets the pool's hard cap. Reloading discards existing templates and live particles.

returns void

gpu_pfx_load("Orfeus/data/effects.json");

spawns a burst of particles from a named template at a position

Emits the template's count particles, each with randomized angle, velocity and lifetime; the parent velocity is added scaled by the template's velocityScale. No-op if the name is unknown.

returns void

gpu_pfx_spawn("sparks", 400.0, 300.0, 0.0, 0.0, 0.0);

emit a WORLD-space (3D) particle burst from a template

Spawns the template's `count` particles at world (x,y,z) with velocity biased along the direction (dx,dy,dz); the template's `angleSpread` is the emission cone half-angle. A near-zero direction bursts omnidirectionally (explosion). Each particle also inherits the emitter's velocity (pvx,pvy,pvz) scaled by the template's `velocityScale` -- so a continuously-emitted plume STREAMS with the moving ship (attached) instead of being left behind as a world-static jet. Pass 0,0,0 for a stationary burst (impacts / explosions). Requires the template's `space` to be `"world"` and a `texture`. Render with gpu_pfx_render3d.

gpu_pfx_spawn3d("engine", ex,ey,ez, -fx,-fy,-fz, svx,svy,svz);

advances every live particle by a time delta, ageing and moving them

Applies gravity, integrates position by velocity, and kills particles whose age reaches their lifetime.

returns void

gpu_pfx_update(16);

draws all live particles via the gfx layer, interpolating scale, colour and alpha by age

Renders each particle as a circle, rect, pixel or tinted image per its template, blending colour along the template's ramp and fading alpha over life.

returns void

gpu_pfx_render();

draw all WORLD-space particles as camera-facing billboards

Call INSIDE the active 3D camera pass (between gpu_camera_begin/…_end). Each world template is drawn in ONE internal batch. Screen-space templates are untouched -- render those with gpu_pfx_render (the 2D overlay) as before. Particles live in an application-defined ABSOLUTE space; each is mapped to render space as (pos - origin)*scale (the floating-origin transform). With no floating origin, pass origin (0,0,0) and scale 1. `size` stays in render units.

gpu_pfx_render3d(cam, gOriginX, gOriginY, gOriginZ, WORLD_SCALE);

live-tunes a named field of a particle template

Sets one of a fixed set of tunable fields (count, size, speed, randomVelocity, lifetime, randomLifetime, emitW, emitH, angleSpread, scaleStart, scaleEnd); int fields take the value cast to int. No-op if the template or field is unknown.

returns void

gpu_pfx_set(efx[curE], pField[idx], av);

reads a named field of a particle template

Returns one of the same tunable fields gpu_pfx_set accepts, as a float.

returns float -- the field's current value (0.0 if the template or field name is unknown)

av = gpu_pfx_get(efx[curE], pField[i]);

returns the number of loaded particle-effect templates

returns int -- count of loaded templates

nfx.i = gpu_pfx_count();

returns the name of the i-th loaded particle-effect template

Lets a tuner enumerate effects straight from the loaded JSON by index.

returns string -- the template's name (empty string if i is out of range)

efx[fi] = gpu_pfx_name(fi);

kills all live particles, keeping the loaded templates

Zeroes the particle pool and resets the recycle cursor; templates remain loaded.

returns void

gpu_pfx_clear();

test whether two spheres intersect (raylib CheckCollisionSpheres)

returns 1 if the spheres intersect, else 0

gpu_collide_spheres(0.0,0.0,0.0, 2.0, 1.0,0.0,0.0, 2.0)

test whether two axis-aligned bounding boxes intersect (raylib CheckCollisionBoxes)

Each box is given by its min and max corner.

returns 1 if the boxes intersect, else 0

gpu_collide_boxes(0.0,0.0,0.0, 2.0,2.0,2.0, 1.0,1.0,1.0, 3.0,3.0,3.0)

test whether a box and a sphere intersect (raylib CheckCollisionBoxSphere)

Box given by min/max corners; sphere by center and radius.

returns 1 if the box and sphere intersect, else 0

gpu_collide_box_sphere(0.0,0.0,0.0, 2.0,2.0,2.0, 1.0,1.0,1.0, 0.5)

pack red, green, blue bytes into a 24-bit color integer

Computes ((r&0xFF)<<16)|((g&0xFF)<<8)|(b&0xFF); each channel is masked to its low 8 bits.

returns packed 24-bit color integer in 0x00RRGGBB layout

colBg.i = rgb(20, 20, 40);

pack red, green, blue, alpha bytes into a 32-bit color integer

Computes ((a&0xFF)<<24)|((r&0xFF)<<16)|((g&0xFF)<<8)|(b&0xFF); each channel is masked to its low 8 bits.

returns packed 32-bit color integer in 0xAARRGGBB layout

c4.i = rgba(255, 0, 0, 128);

parse the leading base-10 integer out of a string

Forwards to bi_vali, which is strtoll(s, NULL, 10); takes only the leading numeric prefix and yields 0 when there are no leading digits.

returns the parsed 64-bit integer (base 10); 0 if the string has no leading numeric prefix

assertEqual(42, strtoi("42"));

parse the leading base-10 integer out of a string

Exact alias of strtoi (same cx_stub_strtoi/bi_vali/strtoll base-10 parse); the FP1 unification resolved a prior backend divergence where risc treated strint as int->string.

returns the parsed 64-bit integer (base 10); 0 if the string has no leading numeric prefix

assertEqual(12345, strint("12345"));

parse the leading floating-point number out of a string

Forwards to cx_stub_strtof, which is strtod(s, NULL); returns 0.0 for an empty string.

returns the parsed float (via strtod); 0.0 if the string is empty

f = strtof("3.14");

parse the leading floating-point number out of a string

Exact alias of strtof (same cx_stub_strtof/strtod parse).

returns the parsed float (via strtod); 0.0 if the string is empty

assertFloatEqual(3.14, strfloat("3.14"), 0.01);

strip whitespace from both ends

Whitespace is C's isspace(): space, tab, newline, carriage return, vertical tab, form feed. Interior whitespace is untouched -- `trim(" a b ")` is "a b", not "ab".

returns a new string with leading and trailing whitespace removed

name.s = trim(fread("name.txt"));

strip whitespace from the LEFT end only

returns a new string with leading whitespace removed; trailing whitespace stays

body.s = ltrim(line);

strip whitespace from the RIGHT end only

The one to reach for when stripping a line ending: it removes "\r\n" as whitespace, so a Windows-terminated line and a Unix one come out the same.

returns a new string with trailing whitespace removed; leading whitespace stays

line.s = rtrim(raw);

reverse a string's BYTES

Bytes, not characters: reversing UTF-8 text that has any multi-byte character in it produces invalid UTF-8. Safe for ASCII, wrong for anything else.

returns a new string with the bytes in the opposite order

r.s = reversestring(word);

an integer as UPPERCASE hexadecimal digits

No "0x" prefix and no padding, so 255 gives "FF". A negative number is rendered as its 64-bit two's-complement pattern -- `hex(-1)` is the 16 characters "FFFFFFFFFFFFFFFF", not "-1". Verified on both backends.

returns the hex digits; "0" for zero

println("mask=" + hex(flags));

an integer as binary digits

Leading zeros are trimmed, so 5 gives "101" and 0 gives "0". A negative number is rendered as its 64-bit two's-complement pattern -- `bin(-1)` is 64 '1' characters, not "-1". Verified on both backends.

returns the binary digits; "0" for zero

println(bin(mask));

a string of n spaces

returns the string, or "" if n <= 0

println(space(indent) + label);

the first n bytes of a string

Clamps rather than failing: asking for more than there is gives the whole string back, and a zero or negative count gives "". The original is never modified -- every builtin in this family returns a NEW string.

returns the leading n bytes, the whole string if n exceeds its length, or "" if n <= 0

code.s = left(line, 3);

the last n bytes of a string

The mirror of left(), with the same clamping: over-long n gives the whole string, n <= 0 gives "".

returns the trailing n bytes, the whole string if n exceeds its length, or "" if n <= 0

ext.s = right(path, 4);

left-justify a string in a fixed-width field

Pads on the RIGHT with spaces to reach `width`. A string already at or over the width is TRUNCATED to it, keeping the left -- so the result is always exactly `width` bytes, which is what makes it usable for column output.

returns a string of exactly `width` bytes, or "" if width <= 0

println(lset(name, 20) + str(score));

right-justify a string in a fixed-width field

Pads on the LEFT with spaces to reach `width`. Over-long input is truncated to the width keeping the LEFT-hand bytes -- the same truncation as lset(), which is worth knowing because right-justified numbers lose their least significant digits, not their most.

returns a string of exactly `width` bytes, or "" if width <= 0

println(rset(str(n), 8));

how many times a substring occurs

Matches are NON-OVERLAPPING: counting "aa" in "aaaa" gives 2, not 3, because the scan resumes after each hit. Same rule replacestring() uses, so the two always agree on how many replacements will happen.

returns the number of non-overlapping occurrences; 0 if the needle is empty or longer than the haystack

n.i = countstring(csv, ",");

does a string begin with this prefix?

Case-SENSITIVE, byte-exact. An empty prefix answers 1.

returns 1 if `hay` begins with `prefix` (or the prefix is empty), else 0

if (startswith(path, "http://")) { ... }

does a string end with this suffix?

Case-SENSITIVE, byte-exact. An empty suffix answers 1. The usual way to test a file extension -- lowercase the name first if the check should be case-blind.

returns 1 if `hay` ends with `suffix` (or the suffix is empty), else 0

if (endswith(tolower(name), ".json")) { ... }

compare two strings, ignoring ASCII case

Returns a SIGN, not a difference: exactly -1, 0 or +1, so the value is stable across backends and safe to compare against a literal. Ordering is by byte after lowercasing, and a string that is a prefix of the other sorts first. Equality is `== 0`, which is the usual C trap -- a bare `if (strcmpi(a,b))` tests for DIFFERENCE.

returns -1 if a sorts before b, 0 if they match case-insensitively, +1 if after

if (strcmpi(cmd, "QUIT") == 0) { ... }

delete every occurrence of a substring

Exactly replacestring(s, sub, "") -- same non-overlapping, all-occurrences rule.

returns a new string with every occurrence removed

clean.s = removestring(raw, "\r");

replace every occurrence of a substring

Replaces ALL non-overlapping matches in one pass, left to right, and never re-scans what it wrote -- so replacing "a" with "aa" terminates rather than running away. An empty `old` is a no-op returning a copy, not an insertion at every position.

returns a new string with every match replaced

out.s = replacestring(path, "\\", "/");

splice text into a string at a 0-based position

`where` counts from 0 like every other position in this family: 0 prepends, s->len appends, and a NEGATIVE `where` counts from the end exactly as substr(s, -3) does -- -1 inserts before the last character. OUT OF RANGE CLAMPS, it does not fail: past the end appends, and more tail than the string has prepends. That is substr's answer, taken deliberately rather than re-decided, because two out-of-range rules inside one string family is the seam counting from 0 exists to close.

returns a new string with `ins` spliced in

out.s = insertstring(num, ",", 3);

how many BYTES a string holds

Bytes, not characters: the whole string layer is UTF-8-byte-level, so `length("hello")` with an accented e is 6, not 5. Every other index in this family -- substr, strstr, left -- counts the same bytes, so they agree with each other; none of them is codepoint-aware. `length` is also the polymorphic spelling both backends accept on a container -- but the container form is the RETIRED one (CX-E1048 since v3.186.0). Read a list's or map's size with `<handle>->count` instead. This entry documents the string form, which is not retired.

returns its byte length; 0 for an empty string

n.i = length(name);

a one-byte string from a byte value

The inverse of asc(). Deliberately refuses to build a string containing an embedded NUL, and takes a BYTE rather than a codepoint, so there is no way to spell a multi-byte UTF-8 character with a single call.

returns a 1-byte string, or "" if n is 0, negative, or above 255

tab.s = chr(9);

the numeric value of a string's FIRST byte

Reads one byte, not one character, so the first byte of a multi-byte UTF-8 character gives that byte's value (a lead byte, >= 0xC0), not the codepoint.

returns the first byte as 0..255, or 0 for an empty string. An empty string and a string starting with a NUL are indistinguishable here.

code.i = asc(letter);

does a string hold this substring?

Case-SENSITIVE, byte-exact. An empty needle answers 1 -- everything contains nothing -- which now agrees with `strstr(s, "") >= 0`. "VERIFIED ON BOTH BACKENDS" IS WHAT THIS BLOCK USED TO SAY, AND IT WAS NOT TRUE: measured 2026-09-06, `contains(s, "")` answered 1 native and 0 on the register VM. The cause is W1's whole subject -- vb_contains did not call THIS function, it hand-rolled the test over the search core and read its "absent" as "no". Fixed by calling bi_contains, which is what a wrapper is for. `contains` is also the spelling for value-membership in a list or array, and both backends dispatch on the first argument's type. This entry documents the string form.

returns 1 if present (or the needle is empty), else 0

if (contains(line, "ERROR")) { ... }

break a string on a separator into a string list

CLEARS `out` FIRST, then fills it, so a second split into the same list holds the second split and nothing else. His ruling 2026-09-17: "yes reset". IT APPENDED UNTIL THEN, and that was documented rather than accidental -- which is why this is a BEHAVIOUR CHANGE and is named as one. The accumulate idiom the old default licensed was used NOWHERE: measured over the whole corpus, NINE sites wrote `listClear(xs)` immediately before a split to defend against it (tests/anvil.cx x6, tests/forge.cx x2, tests/srcdb.cx x1 -- three of the tree's own primary tools) and ZERO relied on it. A default every caller defends against is the wrong default, and a caller that FORGOT to defend got a list holding two splits' worth of fields with no diagnostic (TOOLS-397 F2). A `listClear` before a split is now redundant, never wrong. EMPTY FIELDS ARE KEPT: "a,b,,c" yields four entries, the third being "" -- this is a faithful split, not a tokenizer, so consecutive separators do not collapse. There is always a trailing field, so a string ending in the separator contributes a final "". An empty separator yields the whole string as a single field and returns 1. `stringsplit` is NOT this builtin -- it reads ONE field and returns text. This is the whole-string form and it is the only name for it.

returns the number of fields -- always at least 1

list cols.s
n.i = split(row, ",", cols);

uppercase a whole string

Despite the C name it takes and returns a STRING, not a character code, and it converts the entire string -- there is no per-character form. ASCII only, per byte, via C's toupper(): bytes outside a-z pass through unchanged, so accented and non-Latin UTF-8 text is left exactly as it was rather than mangled. Codepoint-aware folding is a separate operation and is not this one.

returns a new uppercased string (ASCII letters only; other bytes unchanged)

shout.s = toupper(word);

lowercase a whole string

Takes and returns a STRING, not a character code, and converts the entire string -- there is no per-character form. ASCII only, per byte, via C's tolower(); bytes outside A-Z pass through unchanged, so non-Latin text survives intact.

returns a new lowercased string (ASCII letters only; other bytes unchanged)

key.s = tolower(header);

re-case a string, title-case by default

Called with one argument it TITLE-CASES: each word's first letter uppercase, the rest lowercase. A "word" boundary is any run of non-letters, which means digits and apostrophes start a new word too -- "o'brien x2y" becomes "O'Brien X2Y". Verified, on both backends; if that is not what you want, use toupper/tolower on the pieces yourself. The optional mode selects the whole-string forms instead: 0 = uppercase, 1 = lowercase, 2 = title-case. An out-of-range mode falls back to 0 (uppercase), it is not an error.

returns a new re-cased string

title.s = capitalize(raw);

format text and APPEND it to a file

Appends; it never truncates, so repeated calls build a file up (this is the log-writing shape). Formatting honours `#pragma decimals` for floats, and the formatted result spills to the heap when it outgrows the stack buffer, so output length is not capped.

returns the number of bytes written -- a genuine count, unlike fwrite. 0 on any failure (bad format, unopenable path).

n.i = fprintf("log.txt", "run %d took %f s\n", id, secs);

render a float as a string (C's name for str on a float)

The same renderer str reaches for a float argument, so the decimal count follows `#pragma decimals`. strf(v, d) is the form that takes the decimals per call.

returns the number as text

s.s = ftoa(ratio);

the byte at a 0-indexed position in a string

ZERO-indexed, like every index in the language. This is also what `s[i]` lowers to on both backends, so the subscript form and the call form are the same operation. Reads one BYTE, not one character. Out of range returns 0 by default. Under `#pragma checks on` it is instead a loud bounds error naming the index and the length -- the lenient 0 is the legacy behaviour, not the safe one.

returns the byte as 0..255, or 0 if idx is out of range

c.i = getc(line, 0);

how many BYTES a string holds -- or, on a json value, its length by kind

Callable, but its argument list is not derivable from its binding: it is bound only by the register VM's name table, where the C signature is the generic (vm, N) wrapper form. Named here so an absence is never mistaken for non-existence.

DISPATCHED BY TYPE on both backends: a string answers its byte count, and a JSON value answers its text length or its child count depending on the node's kind. **It is RETIRED for list / map / array**: `len(xs)` on a container is refused at compile time with CX-E1048 naming `<handle>->count`, which is the one spelling for a container's length. strlen is the string-only name for the same byte count.

returns the string's byte count (0 for ""), or the json value's length by kind; CX-E1048 on a list, map or array

n.i = len(line);          // a container asks a different way: xs->count

the numeric value of a string's FIRST byte (the other name for asc)

BYTES, NOT CODEPOINTS: a multi-byte UTF-8 character gives that character's lead byte (>= 0xC0), not its Unicode value. chr is the inverse.

returns the byte as 0..255; 0 for an empty string

code.i = ord(key);

read a hexadecimal string as an integer

A plain base-16 parse: no "0x" prefix is required (one is accepted), case does not matter, and parsing stops at the first non-hex character with no error channel -- unparseable text gives 0, the same silence the base-10 read behind `(int)<s>` has. For a "rrggbb" colour the result is the NATURAL 0xRRGGBB packing, so `parsehex("ff0000")` is 16711680 (red), matching `rgb()` and the draw builtins. This header claimed the opposite until v3.209.20 -- it described the PureBasic era's byte-swapped 0xBBGGRR and said so as the contract, while the implementation had carried a comment stating plainly that the C runtime does NOT swap and that `parsehex("ff0000") must be red, not blue`. Two homes, two truths; the header was the wrong one, and it is the versioned surface a reader sees. Measured on both backends before correcting.

returns the value, or 0 if the text does not start with a hex digit

col.i = parsehex("ff8800");

write a STRING to stdout with no newline

The raw piece-by-piece output form: no newline, no formatting, no conversion. prti, prtf and prtc are the int, float and character siblings.

returns void

format text. ONE name, TWO shapes, and ARGUMENT 1 chooses

`sprintf(fmt, args...)` returns the formatted STRING. This is CX's form and the one nearly every program wants: nothing to size, nothing to overflow. `fmt` may be a literal or a `string` variable; conversions are libc's (the compiler rewrites `%d` to `%lld` upstream) and honour `#pragma decimals`. `sprintf(buf, fmt, args...)` where `buf` is a `char` buffer is C's form, verbatim: it writes into the buffer, NUL-terminates, and returns the BYTE COUNT. It exists so that C pasted into CX means what it meant in C -- the `Examples/C/` programs are Rosetta-Code source, unedited. Both backends answer identically; the register VM clamps the write to the declared size rather than running off the array, since C's own answer there is undefined. Argument 1's DECLARED TYPE picks the shape, at compile time. Anything that is neither a `char` buffer nor a string -- an int, a float, a container -- is CX-E1065 at the .cx line, because there is no third reading to guess at.

returns the formatted string (CX form), or the byte count written (C form)

label.s = sprintf("%s: %d%%", name, pct);
char buf[64]; int n = sprintf(buf, "%d/%d", num, den);

render a number as a string

The compiler picks the int or the float renderer from the argument's type, so str(3) gives "3" and str(3.0) gives "3.000" -- three decimals, because the float form honours `#pragma decimals`, whose default is 3. Use strf when you want to fix the decimal count at the call site instead.

returns the number as text

line.s = "score: " + str(points);

0-indexed position of a character code in a string, C-style

Takes the character as a NUMERIC CODE, as C does, not as a one-character string. Returns -1 when the character is absent, so the test is `>= 0`; strstr is the same search with a string needle.

returns the 0-indexed position, or -1 if the character does not occur

at.i = strchr(line, 61);

compare two strings in byte order, C-style

Returns a SIGN, not a boolean: negative if `a` sorts before `b`, 0 if they are equal, positive if after. Comparison is by raw byte value, so it is case-sensitive and not locale-aware. CX's `==` on strings is the readable way to test equality; strcmp is for ordering.

returns negative, 0, or positive as `a` sorts before, equal to, or after `b`

if (strcmp(name, pivot) < 0) { ... }

a float as text, with the number of decimals you choose

`strf(v)` renders at the file's `#pragma decimals` setting (default 3), which is what `str()` and `ftoa()` do. `strf(v, d)` overrides it FOR THAT CALL -- the pragma is file-global and last-wins, so this is the only way to write a price at 2 decimals and an angle at 6 in the same program. `d` is C's `%.*f` precision and behaves as C does, including the corner: a NEGATIVE `d` means "precision omitted", which in C is six decimals. There is no upper limit -- ask for 40 and you get 40, correctly, however long the result runs.

returns the rendered string

label.s = strf(price, 2) + " at " + strf(angle, 6) + " rad";

how many BYTES a string holds (C's name for length, string-only)

Counts bytes, not characters, so a multi-byte UTF-8 string measures longer than it looks. Unlike len, this name is string-only: it does not answer for a list, map or array.

returns the byte count; 0 for an empty string

n.i = strlen(line);

where a substring starts, counting from 0

THE C answer and now the only one: a ZERO-indexed position, and -1 for "not found". So the test is `>= 0`, NOT `> 0` -- a `> 0` test silently rejects a match at the very start of the string, which is the whole reason the 1-based spelling is leaving. An optional third argument resumes the search from a 0-based position, which is how a program walks every occurrence without rebuilding the haystack. AN EMPTY NEEDLE MATCHES AT `start` -- `strstr(s, "")` is 0 and `strstr(s, "", 3)` is 3. That is C's answer (its strstr hands back a pointer to the haystack) and Python's. It CHANGED in this arc: the 1-based core it used to adapt answered "absent" for an empty needle so a loop could not spin, and at 0 that reasoning inverts -- 0 is a real position, and -1 would make the empty needle the one case where a substring the string demonstrably contains reports absent. A start past the end is -1, empty needle or not.

returns the 0-indexed byte position of the first match at or after `start`, or -1 if there is none

if (strstr(line, "=") >= 0) { ... }

a substring, counting from 0

THE substring operation -- there is no longer a second, 1-indexed one. Two forms: `substr(s, start)` runs to the end, `substr(s, start, n)` takes at most n bytes, and both clamp rather than fail. A NEGATIVE START COUNTS FROM THE END, which is what makes `right(s, n)` a call to this rather than a function of its own: `substr(s, -5)` is the last five bytes, and asking for more tail than there is gives the whole string. FIXED in v3.209.22 -- and the fix was NOT the one name this note predicted. Until then the compiler did not know substr returned a string, so `"x=" + substr(s, 0)` failed the BUILD on both backends with a type error out of the generated C. The cause was not a missing entry: the classifier consulted a GENERATED table that only ever read `CX_BUILTIN` spec lines, and this family has none, so ~66 hand-bound builtins were invisible to it and a hand list was expected to know them all. The generator now derives the answer from these C prototypes instead (tests/strret_derive.awk), which found four more builtins with the same defect. See tests/bugs/B_strret_two_sources.

returns the substring, or "" if start is at or past the end

part.s = substr(line, 4, 3);

does `pattern` match anywhere in `s`?

returns 1 on a match, 0 on none. A pattern that cannot be COMPILED does not answer 0 -- it refuses (CX-E5067), because 0 is a legitimate answer and cannot also mean "your pattern is broken".

if (regexMatch(line, "^[A-Z][a-z]+$")) { ... }

how many non-overlapping matches of `pattern` are in `s`?

returns the count, 0 for none. Agrees with regexExtract's `->count` by construction: both walk the subject with the same one-byte advance past an empty match.

n = regexCount(text, "\\bthe\\b");

every match of `pattern` in `s`, with its capture groups, as a json document

The document is an ARRAY of matches. A match with no NAMED groups is an array of groups -- `m[0]` the whole match, `m[1]` the first group. A match from a pattern that names any group is an OBJECT carrying both halves: "0", "1", ... as string keys AND each name as a member, because a json node is an array or an object and cannot be both, and dropping the positions to gain the names would silently break `m[1]` for a pattern that happens to name one group. Which form is in play is decided once from the PATTERN, never per match.

returns a json document handle. No match is an EMPTY ARRAY, not null, so `for (i = 0; i < d->count; i++)` needs no special case first. An unset group is an empty string rather than a missing element, so group N is always at index N.

json d = regexExtract(s, "(\\d+)-(\\d+)");
json m = d[0]; print m[1];   // the first group of the first match

`s` with every non-overlapping match of `pattern` replaced by `repl`

returns the rewritten text; `s` unchanged when nothing matched.

clean = regexReplace(s, "[^0-9]", "");

sine of an angle in radians

returns the sine, in -1.0 .. 1.0

y.f = amplitude * sin(t);

cosine of an angle in radians

returns the cosine, in -1.0 .. 1.0

x.f = radius * cos(angle);

tangent of an angle in radians

returns the tangent; unbounded, and huge near odd multiples of pi/2

arc sine: the angle whose sine is `x`

returns the angle in radians, in -pi/2 .. pi/2

arc cosine: the angle whose cosine is `x`

returns the angle in radians, in 0 .. pi

arc tangent: the angle whose tangent is `x`

Takes one argument, so it cannot tell quadrant II from IV -- use `atan2` when you have both components of a direction.

returns the angle in radians, in -pi/2 .. pi/2

the angle of the vector (x, y), using both signs to pick a quadrant

NOTE THE ARGUMENT ORDER: `y` FIRST, as in C. It is the usual way to turn a delta into a heading, and the reason it beats `atan(y/x)` is that it is defined when `x` is 0 and it knows which half of the circle you are in.

returns the angle in radians, in -pi .. pi

heading.f = atan2(ty - py, tx - px);

hyperbolic sine

returns the hyperbolic sine; overflows to infinity for large `x`

hyperbolic cosine

returns the hyperbolic cosine, always >= 1.0

hyperbolic tangent

returns the hyperbolic tangent, in -1.0 .. 1.0

e raised to the power `x`, the inverse of `log`

returns e**x; overflows to infinity for large `x`

natural logarithm (base e)

This is C's `log`, NOT base 10 -- `log10` is the base-10 one.

returns the natural log

base-10 logarithm

returns the base-10 log

digits.i = 1 + floor(log10(n));

base-2 logarithm

A direct bridge to the C library function of the same name; the answer is C's answer, to the bit.

returns log base 2 of x

b = log2(1024.0);   // 10.0

square root

returns the square root

cube root

A direct bridge to the C library function of the same name; the answer is C's answer, to the bit. Unlike `pow(x, 1.0/3.0)` this is exact for negative inputs.

returns the real cube root of x

r = cbrt(-27.0);   // -3.0

raise `b` to the power `e`

returns b**e

area.f = pow(side, 2.0);

the length of the hypotenuse, without overflow

A direct bridge to the C library function of the same name; the answer is C's answer, to the bit. Computes sqrt(x*x + y*y) in a way that does not overflow when x or y is large.

returns sqrt(x*x + y*y)

d = hypot(dx, dy);

round to the nearest whole number and return it as an INT

Ties go to the EVEN neighbour (2.5 gives 2, 3.5 gives 4, -2.5 gives -2), which is a decision, not C's: C's `round` is half-away-from-zero and would answer 3 and -3. The int return is what lets `a[round(x)]` compile.

returns the nearest whole number as an int; a value beyond int64's range cannot be represented exactly

idx.i = round(t * (count - 1));

which side of zero a value is on, as an INT

returns -1 if x is negative, +1 if positive, 0 if zero (including -0.0)

step.i = sign(target - current);

round DOWN to a whole number, towards negative infinity

Returns a FLOAT, unlike `round`, which returns an int -- so `floor(-2.5)` is -3.0, not -2.0.

returns the largest whole number <= x, as a float

round UP to a whole number, towards positive infinity

Returns a FLOAT; `ceil(-2.5)` is -2.0.

returns the smallest whole number >= x, as a float

discard the fractional part, toward zero

A direct bridge to the C library function of the same name; the answer is C's answer, to the bit. Differs from `floor` on negatives: trunc(-2.7) is -2.0, floor(-2.7) is -3.0.

returns x with its fraction removed, rounded toward zero

n = trunc(-2.7);   // -2.0

absolute value of a FLOAT

`abs` is the int form; this one keeps the fraction.

returns x without its sign

the smaller of two FLOATS

returns whichever is smaller

the larger of two FLOATS

returns whichever is larger

floating-point remainder of x/y

A direct bridge to the C library function of the same name; the answer is C's answer, to the bit. The result takes the SIGN OF X, which is what distinguishes it from a mathematical modulo.

returns the remainder of x/y with x's sign

r = fmod(-7.5, 2.0);   // -1.5

the constant pi

The value of pi as a double.

returns 3.14159265358979323846

c = 2.0 * pi() * r;

convert radians to degrees

returns the same angle in degrees

convert degrees to radians

Every trig builtin here takes radians, so this is the usual bridge from a human-authored angle.

returns the same angle in radians

y.f = cy + radius * sin(radians(deg));

linear interpolation between `a` and `b`

Computed as a + (b - a) * t, so it is NOT clamped: t below 0 or above 1 extrapolates past the endpoints, which is often what you want.

returns the interpolated value

x.f = lerp(startX, endX, elapsed / duration);

is `x` inside `lo`..`hi`, endpoints INCLUDED

A macro, so it works for ints and floats alike. It evaluates `x` TWICE -- do not pass a call with side effects.