send a prompt to the configured LLM and return its reply

One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

returns the model's reply, or an empty string on any failure (read aiGetError for the reason)

reply.s = aiAsk("Explain CX in one line.");

accepted for API compatibility; does nothing

A started job runs to completion. Collect it with aiAsyncResult, or ignore it -- there is no cancellation path, and this builtin says so rather than pretending one exists.

returns void

aiAsyncCancel(id);

ask whether a background job has finished

The same reading as aiAsyncStatus. 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 (aiAsyncReady(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 = aiAsyncResult(id);

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

while (aiAsyncStatus(id) == 0) { sleep(1); }

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

aiCacheClear();

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 = aiCacheGet("q");

test whether a key has a non-empty cached reply

Implemented as a get whose result is tested for length, so it COUNTS AS A LOOKUP in the hit/miss statistics, and a key whose cached value is the empty string answers 0.

returns 1 if the key holds a non-empty value; 0 otherwise

if (aiCacheHas("q")) { ... }

count cache lookups that found an entry

Reset by aiCacheClear. Note that aiCacheHas performs a lookup, so it moves this counter.

returns the hit count since start or since the last clear

h = aiCacheHits();

count cache lookups that found nothing

Reset by aiCacheClear. Note that aiCacheHas performs a lookup, so it moves this counter.

returns the miss count since start or since the last clear

m = aiCacheMiss();

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

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

count the entries currently in the response cache

returns the number of cached entries

n = aiCacheSize();

read the cache counters as one formatted line

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

print(aiCacheStats());

send a prompt to the configured LLM and return its reply

The same synchronous operation as aiQuery. One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

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

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

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 = aiCallAsync("Summarise this.");

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

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

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

r = aiCallFunc("clamp", 130);

collect a background job's reply, waiting if necessary

The same operation as aiAsyncResult. 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 = aiCallGet(id);

send a prompt to the configured LLM and return its reply

The same synchronous operation as aiQuery, spelled to contrast with aiCallAsync. One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

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

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

send a prompt to the configured LLM and return its reply

One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

returns the model's reply, or an empty string on any failure (read aiGetError for the reason)

reply.s = aiChat("Explain CX in one line.");

empty the response cache and reset its counters

The same operation as aiCacheClear -- a heritage spelling kept for programs written against the beta API.

returns void

aiClearCache();

send a prompt to the configured LLM and return its reply

One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

returns the model's reply, or an empty string on any failure (read aiGetError for the reason)

reply.s = aiComplete("Explain CX in one line.");

disassemble a named AI function back to readable text

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

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

print(aiDumpAsm("clamp"));

read the reason the last AI operation failed

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

returns the error text, or an empty string

print(aiGetError());

read an integer from a named AI slot

Names must have been DECLARED to the AI subsystem first; calling this with an unknown or undeclared name is a hard, loud failure rather than a silent 0 (FP4). A name bound to a program variable reads and writes that variable directly; a register-only name keeps its value in the slot table.

returns the slot's value

v = aiGetNamed("hp");

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

True if aiSetKey supplied one, or the provider's environment variable is set and non-empty. ollama and cxllama always answer 1, because they run locally and need no key.

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

if (aiHasKey()) { ... }

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 and cxllama run locally and need no key.

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

if (aiInit() == 0) { print(aiGetError()); }

set the API key explicitly instead of reading it from the environment

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.

A heritage spelling of aiSetKey. 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

aiKey(k);

read the reason the last AI operation failed

The same value aiGetError returns -- a heritage spelling kept for programs written against the beta API.

returns the error text, or an empty string

print(aiLastError());

read an integer from a named AI slot

The same operation as aiGetNamed -- a heritage spelling kept for programs written against the beta API. Names must have been DECLARED to the AI subsystem first; calling this with an unknown or undeclared name is a hard, loud failure rather than a silent 0 (FP4). A name bound to a program variable reads and writes that variable directly; a register-only name keeps its value in the slot table.

returns the slot's value

v = aiNamedGet("hp");

write an integer into a named AI slot

The same operation as aiSetNamed -- a heritage spelling kept for programs written against the beta API. Names must have been DECLARED to the AI subsystem first; calling this with an unknown or undeclared name is a hard, loud failure rather than a silent 0 (FP4). A name bound to a program variable reads and writes that variable directly; a register-only name keeps its value in the slot table.

returns 1

aiNamedSet("hp", 42);

assemble AI-authored bytecode text into a named callable function

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

aiParseBytecode("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 = aiPending();

send a prompt to the configured LLM and return its reply

One implementation behind four names: 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 aiGetError -- so test the result, do not assume it.

returns the model's reply, or an empty string on any failure (read aiGetError for the reason)

reply.s = aiQuery("Explain CX in one line.");

collect a background job's reply, waiting if necessary

The same operation as aiAsyncResult -- a heritage spelling kept for programs written against the beta API. 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 = aiResult(id);

set the async-preference flag

Stored and readable by the program; the query builtins themselves remain synchronous -- use aiCallAsync/aiResult for a real background request.

returns void

aiSetAsync(1);

turn the in-process response cache on or off

On by default. While on, aiQuery/aiAsk/aiChat/aiComplete answer a repeated prompt from memory without contacting the provider, keyed by the prompt text itself.

returns void

aiSetCache(0);

set a comma-separated chain of providers to try when the primary fails

Tried in order, left to right, only after the configured provider returns an error. 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

aiSetFallback("openai, groq");

set the API key explicitly instead of reading it from the environment

Takes priority over the provider's environment variable. 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

aiSetKey(k);

cap the tokens the model may generate per reply

Values <= 0 are IGNORED and leave the previous setting in place. Default 1024.

returns void

aiSetMaxTokens(4096);

set the model name sent with each request

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

aiSetModel("claude-sonnet-4");

write an integer into a named AI slot

Names must have been DECLARED to the AI subsystem first; calling this with an unknown or undeclared name is a hard, loud failure rather than a silent 0 (FP4). A name bound to a program variable reads and writes that variable directly; a register-only name keeps its value in the slot table.

returns 1

aiSetNamed("hp", 42);

choose the LLM provider for subsequent calls

Accepts anthropic, openai, google, mistral, cohere, xai, deepseek, groq, ollama or cxllama, plus the aliases claude -> anthropic, grok -> xai and gpt -> openai. Switching provider CLEARS any key set by aiSetKey, so set the key after the provider, not before. 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

aiSetProvider("anthropic");

set the system prompt prepended to each request

Sent with every subsequent query until changed; empty clears it. 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

aiSetSystem("Answer in one sentence.");

set the sampling temperature sent with each request

Stored as given and passed through to the provider; the runtime does not clamp it. Default 0.7.

returns void

aiSetTemp(0.2);

set the per-request transport timeout in milliseconds

Values <= 0 are IGNORED and leave the previous setting in place. Default 60000 (60 s).

returns void

aiSetTimeout(15000);

override the provider's endpoint URL

For a proxy, a self-hosted gateway or a local ollama/cxllama server. Empty restores the provider default. 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

aiSetUrl("http://localhost:11434/api/chat");

ask whether a background job has finished

The same reading as aiAsyncStatus -- a heritage spelling kept for programs written against the beta API. 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

s = aiStatus(id);

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

aiWait(id);

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 = codeSize();

delete a marker region's code

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

deleteCode(1);

drop a marker region

returns void

delMarker(1);

ask the AI to write the body for a marker region

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

returns non-zero on success

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

read back a marker region's current source text

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns an empty string

s.s = getCode();

look up a marker by name

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.

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

m = getMarker();

test whether a marker id names a live region

returns non-zero if the marker exists

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

insert code at a marker region

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

insertCode(1);

count the live marker regions

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.

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

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

peekCode(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

peekFlags(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

peekFuncid(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

peekI(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

peekJ(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

peekN(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

pokeCode(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

pokeFlags(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

pokeFuncid(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

pokeI(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

pokeJ(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

pokeN(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

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

n = rt_aiFuncCount();

run a run-time AI function

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time. Always addresses id 0.

returns 0

rt_callAiFunc();

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

returns the new function's id

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

drop a run-time AI function

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns void

rt_destroyAiFunc(id);

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 run-time AI function by id

NOT IMPLEMENTED on this backend: the call prints a `not implemented` line on stderr and returns the value below rather than doing anything. It is listed here because the compiler accepts it -- an absence you can see beats one you discover at run time.

returns 0

rt_runAiFunc(id);

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.

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);

read a float from an entity's baked persist lane

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 float half of the same one-name `lookup` surface -- see lookupI. There are no F/I variants in CX source: the lanes are already typed by `persist float`/`persist int`, and the read coerces to whatever you assign it to.

returns the lane's value as a float

float th = lookup(e, "reorder");

read an integer from an entity's baked persist lane

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 native read surface onto the persist bank that `arm` baked -- a reader over the EXISTING bank, not a second copy. In CX you write ONE name, `lookup`, and the value COERCES TO THE SINK exactly like a json subscript; this typed entry point is what an integer sink resolves to.

returns the lane's value as an integer

int n = lookup(e, "critical", i);

bind a CX function 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. A function pointer cannot live in json, so the binding stores the function's NAME and resolves it through the handler registry.

returns void

onEventFunc(1, "1", &onKey);

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.

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();

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);

register a CX function under a name so a json-loaded table can reach it

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. Needed when the table came from a FILE rather than from onEventFunc calls: the json holds a name, and this is what a name resolves through. Names are case-insensitive, like every CX identifier.

returns void

ruleFuncReg("onHit", &onHit);

emit a compilable .cxi from a json array of authored rules

CHECKPOINT PROMOTION, and it is **HOST ONLY -- never rule-callable**: a rule that could promote itself would be capability escalation, so this name must never be on a rule whitelist. Writes one `function <name>.f(json e) <body>` per entry plus a registration block. ALL-OR-NOTHING: it refuses to overwrite a file without the generated marker, compile-checks every body first and writes NOTHING if any fails, refuses name collisions, and writes temp-then-rename so a crash cannot leave half a file. On success it marks each entry `promoted:true` in place.

returns 1 on full success (and the array is marked in place); 0 on any failure, with nothing written

rulePromote(rules, "rules_promoted.cxi");

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) + ")";

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);

apply a colour preset to the grid by name

"light" = white with light-grey zebra; anything else = the default dark palette. Only colours change; heights are untouched.

returns void

gpu_grid_theme(g, "light");

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);

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

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);

update a camera with a raylib movement mode

Calls raylib UpdateCamera; mode selects the built-in controller.

returns void

gpu_camera_update(cam, 1);

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);

read a camera's position x

returns camera position.x as float; 0.0 if the handle is invalid

float px = gpu_camera_posx(cam);

read a camera's position y

returns camera position.y as float; 0.0 if the handle is invalid

float py = gpu_camera_posy(cam);

read a camera's position z

returns camera position.z as float; 0.0 if the handle is invalid

float pz = gpu_camera_posz(cam);

draw a filled 3D cube centered at (x,y,z) (raylib DrawCube)

returns void

gpu_draw_cube(0.0,0.0,0.0, 2.0,2.0,2.0, 255);

draw a wireframe 3D cube centered at (x,y,z) (raylib DrawCubeWires)

returns void

gpu_draw_cube_wires(0.0,0.0,0.0, 2.0,2.0,2.0, 255);

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 wireframe 3D sphere at (x,y,z) (raylib DrawSphereWires)

Uses a fixed 12 rings x 12 slices tessellation.

returns void

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

draw a filled 3D cylinder/cone at (x,y,z) (raylib DrawCylinder)

Separate top and bottom radii allow cones (one radius 0) and tapered shapes.

returns void

gpu_draw_cylinder(0.0,0.0,3.0, 1.0,1.0,2.0, 16, 255);

draw a wireframe 3D cylinder/cone at (x,y,z) (raylib DrawCylinderWires)

returns void

gpu_draw_cylinder_wires(0.0,0.0,3.0, 1.0,1.0,2.0, 16, 255);

draw a flat XZ plane centered at (x,y,z) (raylib DrawPlane)

returns void

gpu_draw_plane(0.0,-1.0,0.0, 10.0,10.0, 128);

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 filled 3D triangle from three vertices (raylib DrawTriangle3D)

returns void

gpu_draw_triangle3d(0.0,0.0,0.0, 1.0,0.0,0.0, 0.0,1.0,0.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 cube mesh and return it as a model handle (raylib GenMeshCube)

Wraps the generated mesh in a model via LoadModelFromMesh.

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

int cube = gpu_mesh_cube(2.0,2.0,2.0);

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);

generate a subdivided plane mesh and return it as a model handle (raylib GenMeshPlane)

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

int pln = gpu_mesh_plane(10.0,10.0, 4,4);

generate a cylinder mesh and return it as a model handle (raylib GenMeshCylinder)

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

int cyl = gpu_mesh_cylinder(1.0, 3.0, 16);

draw a model at (x,y,z) with uniform scale (raylib DrawModel)

returns void

gpu_model_draw(cube, 0.0,0.0,0.0, 1.0, 255);

draw a model as wireframe at (x,y,z) with uniform scale (raylib DrawModelWires)

returns void

gpu_model_draw_wires(sph, 0.0,0.0,0.0, 1.0, 255);

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);

destroy a model handle immediately (raylib UnloadModel)

Unconditional teardown: drops the ARC bucket then unloads the model and frees the slot. Standalone counterpart to the codegen-emitted decref.

returns void

gpu_model_free(m);

decrement an owned model's ARC refcount, reclaiming it at zero

Codegen emits this at scope exit for an owned `model` local; the shared CXB_RESOURCE tracer unloads the model when the refcount hits 0. Bounds-checked no-op on an out-of-range handle.

returns void

gpu_model_decref(m);

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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. 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

gpuMsaa(4);   // before the window opens

set the default sampling filter for model textures

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. 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

gpuTextureFilter(1);

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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. Applies a filter mode to that model's diffuse textures immediately, overriding the global default gpuTextureFilter set. It is TEXTURE FILTERING, not shading -- it does not change how normals are interpolated.

returns void

gpuModelSmooth(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("", "");

load a shader from in-memory source blobs (raylib LoadShaderFromMemory)

Takes vertex and fragment shader source from embed()/blob handles rather than files.

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

int sh = gpu_shader_loadmem(vs, fs);

begin rendering with a shader (raylib BeginShaderMode)

Subsequent draws use this shader until gpu_shader_end.

returns void

gpu_shader_begin(sh);

destroy a shader handle immediately (raylib UnloadShader)

Unconditional teardown: drops the ARC bucket then unloads the shader and frees the slot.

returns void

gpu_shader_free(sh);

decrement an owned shader's ARC refcount, reclaiming it at zero

Codegen emits this at scope exit for an owned `shader` local; the shared tracer unloads the shader at refcount 0. Bounds-checked no-op on an out-of-range handle.

returns void

gpu_shader_decref(sh);

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 an integer uniform value on a shader (raylib SetShaderValue)

Looks up the uniform by name; a missing uniform (loc < 0) is a silent no-op. The uniform-type code maps to raylib's SHADER_UNIFORM_* enum.

returns void

gpu_shader_set(sh, "mode", 1, 4);

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 point light to a shader and return its index (rlights CreateLight)

Creates a LIGHT_POINT at (x,y,z) with the given RGBA color, registered against the shader.

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

int pl = gpu_light_point(sh, 5.0,5.0,5.0, 255,0,0,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);

move a light and push the update to its shader (rlights UpdateLightValues)

Sets light lt's position to (x,y,z) and re-uploads its values to the shader. No-op if the shader or light index is invalid.

returns void

gpu_light_pos(sh, pl, 6.0,6.0,6.0);

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);

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)

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);

read a ray's direction x component

returns ray direction.x as float; 0.0 if the handle is invalid

float rx = gpu_ray_x(ray);

read a ray's direction y component

returns ray direction.y as float; 0.0 if the handle is invalid

float ry = gpu_ray_y(ray);

read a ray's direction z component

returns ray direction.z as float; 0.0 if the handle is invalid

float rz = gpu_ray_z(ray);

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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. Pairs with the camera-begin call; drawing between them is in world space.

returns void

gpuCameraEnd();

how long the last frame took, in seconds

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. The delta to scale movement by so speed is frame-rate independent.

returns the frame time in seconds

x = x + speed * gpuFrameTime();

stop drawing through the active shader

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns void

gpuShaderEnd();

get the current viewport width in pixels

raylib GetScreenWidth; updates live as the user resizes the window.

returns viewport width, or 0 if no window

cw.i = gpu_screen_width();

get the current viewport height in pixels

raylib GetScreenHeight; updates live as the user resizes the window.

returns viewport height, or 0 if no window

ch.i = gpu_screen_height();

return 1 on the first frame after the user resizes the window

Wraps raylib IsWindowResized (auto-clears after the call). Pair with a re-layout so percent-based UI reflows. Always 0 if the window is not resizable.

returns 1 the frame after a resize, else 0

if (gpu_window_resized()) { relayout(); }

toggle borderless-windowed fullscreen

raylib ToggleBorderlessWindowed; restores the prior windowed size on toggle-off, so one call covers both directions. Re-read screen width/height afterwards.

returns void

function evFullscreen.v(json e) { gpu_window_fullscreen(); }

return 1 while borderless-windowed fullscreen is active

Checks raylib FLAG_BORDERLESS_WINDOWED_MODE.

returns 1 if fullscreen, else 0

int f = gpu_window_isfullscreen();

move the window's top-left to desktop coordinates (x,y)

raylib SetWindowPosition; lets a docked panel window position itself.

returns void

gpu_window_pos(0, 40);

resize the window to width x height, or pass (0,0) to maximize

raylib SetWindowSize; (0,0) maximizes to the monitor work area. Restores from a maximized state first. Requires a resizable window.

returns void

gpu_window_size(scrW, gh);

maximize the window to fill the monitor work area

Convenience for gpu_window_size(0,0) (raylib MaximizeWindow).

returns void

gpu_window_maximize();

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

get the window's top-left x on the desktop

raylib GetWindowPosition().x; useful for docking a second window beside this one.

returns window x position, or 0 if no window

int wx = gpu_window_x();

get the window's top-left y on the desktop

raylib GetWindowPosition().y.

returns window y position, or 0 if no window

int wy = gpu_window_y();

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);

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; }

register/update a named rectangular hot region and test if the mouse is inside it

(Re)registers the rect each call and returns 1 if the cursor currently sits inside AND the region is not paused. Polling pattern; the table holds up to 64 named regions.

returns 1 if the mouse is inside the (unpaused) region, else 0

if (gpu_mouse_region("btn", 10, 10, 80, 30)) { onHover(); }

remove a named mouse region

Frees the region's slot in the table.

returns 1 on removal, 0 if the name was not found

gpu_mouse_unregion("btn");

return the name of the first unpaused region containing (mx,my)

Walks the region table and returns the first matching region's name, or an empty string if none contain the point. Lets a dispatch loop find the hit region without re-registering each name.

returns the matching region name, or an empty string if none

string r = gpu_mouse_region_at(mousex(), mousey());

pause a named mouse region so it stops reporting hits

A paused region returns 0 from gpu_mouse_region and is skipped by gpu_mouse_region_at.

returns 1 if the region was found, else 0

gpu_mouse_pause("btn");

resume a paused mouse region

Re-enables hit reporting for the named region.

returns 1 if the region was found, else 0

gpu_mouse_resume("btn");

draw one atlas cell centred, scaled and rotated

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. 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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. (cx, cy) is the CENTRE, and the rotation pivots about that centre. Degrees, clockwise.

returns void

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

take a snapshot of the keyboard for this frame

STUBBED: answers 0 (no key event) on both backends. Use gpuKeyPressed instead.

returns 0, always

k = gpuKeyPressed();

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();

release a loaded font

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

fontFree(f);

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);

switch to additive blending for subsequent draws

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. What makes glows and particle flares brighten what is under them.

returns void

gpuBlendAdd();

switch back to normal alpha blending

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns void

gpuBlendNormal();

draw a string at a screen position

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. Two forms: four arguments use the default 20-pixel size, five pick the size.

returns void

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

finish the frame and present it

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. This is what makes drawing appear; it also swaps the buffers, which is why the flip calls are no-ops.

returns void

gpuFrameEnd();

test whether the graphics window is still open

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. The canonical main-loop guard -- `while (gpuFramePoll()) { ... }` -- 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 (gpuFramePoll()) { gpuFrameBegin(); ... gpuFrameEnd(); }

take a snapshot of the keyboard for this frame

STUBBED: answers 0 (no key event) on both backends. Listed because the compiler accepts it -- use gpuKeyPressed for a key this frame.

returns 0, always

k = gpuKeyPressed();

request that the frame loop stop

ACCEPTED AND DOES NOTHING on both backends. The loop guard is gpuFramePoll, 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 (gpuFramePoll()) { ... }

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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. 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

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

the key pressed this frame

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. Reports one key per frame; 0 when nothing was pressed.

returns the key code, or 0

k = gpuKeyPressed();

stop every registered mouse region from responding

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. The way to make a modal dialog swallow clicks without unregistering the regions behind it.

returns void

gpuMousePauseAll();

let every registered mouse region respond again

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns void

gpuMouseResumeAll();

how far the wheel moved since the last frame

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns the wheel delta; 0 if it did not move

dz = gpuMouseWheel();

the mouse pointer's x position in the window

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns x in pixels

mx = gpuMouseX();

the mouse pointer's y position in the window

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns y in pixels

my = gpuMouseY();

close the graphics window

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op.

returns void

gpuScreenClose();

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 gpuFrameEnd.

returns void

gpuFrameEnd();

open the graphics window, ignoring the placement hints

Only `w` and `h` are used: raylib places the window itself, so the x, y and mode arguments are accepted and DISCARDED. The title is fixed to "CX". gpu_screen_open is the plain form and the one to prefer.

returns 1 always -- it does not report failure

gpu_screen_openex(0, 0, 0, 1280, 720);

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

NATIVE ONLY -- the register VM cannot drive a window, so a call under `-P pcode=risc` (or in the browser, which runs the same VM) is refused at compile time with CX-E1013 advising a native build, never a silent no-op. 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 = gpuTextWidth("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 gpuScreenFlip: the frame end swaps buffers.

returns void

gpuFrameEnd();

measure how wide a string will be drawn

The same measurement as gpuTextWidth 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");

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 .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);

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);

destroy a font handle now, unloading its GPU glyph atlas

Unconditional free (raylib UnloadFont); drops the resource bucket then reclaims the slot. Standalone counterpart to the ARC decref.

returns void

gpu_font_free(fnt);

decrement a font handle's ARC refcount for scope-exit reclaim

Codegen emits this at scope exit for an owned `font` local; the shared tracer unloads the font when the refcount reaches 0. Rarely called by hand.

returns void

gpu_font_decref(fnt);

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); }

decrement a texture handle's ARC refcount for scope-exit reclaim

Wraps cx_gfx_texture_decref; codegen emits it at scope exit for an owned `texture` local, and the shared tracer unloads the texture at refcount 0.

returns void

gpu_image_decref(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);

count currently-open GPU texture slots

Wraps cx_gfx_texture_live_count; live-slot introspection for leak/churn tests over the `texture` type.

returns number of live texture slots

int n = gpu_image_livecount();

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 texture unscaled at (x,y) with an alpha fade

raylib DrawTexture with a white tint at `alpha` (0-255); draws at the texture's native size.

returns void

gpu_image_draw_alpha(img, 220, 100, 128);

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();

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")

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(); }

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 at (x,y) sized width x height

raylib DrawRectangle.

returns void

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

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). Native-only (no register-VM path).

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. Native-only.

returns void

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

rounded-rectangle OUTLINE (raylib DrawRectangleRoundedLinesEx)

8 segments/corner. Native-only.

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. Native-only.

returns void

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

draw concentric fading rings that open up as progress rises (wormhole effect)

Legacy immediate-mode effect built from raylib DrawCircleLines. progress_pct (0-100, clamped) controls the inner radius so the wormhole opens; rings<=0 defaults to 3. New work should prefer the cx_pfx particle system.

returns void

gpu_fx_wormhole(400, 300, 120, 50, rgb(80, 160, 255), 5);

draw layered translucent rectangles as a soft energy-field (plasma) effect

Legacy immediate-mode effect: nested rectangles centred on the given rect, fading outward. intensity (0-100, clamped) dials brightness; rings<=0 defaults to 3.

returns void

gpu_fx_plasma(100, 100, 200, 150, 80, rgb(255, 80, 200), 4);

draw a rotated flame sprite plus a cone of random particles (thruster effect)

Legacy immediate-mode effect: if `img` is a valid texture it is blitted rotated at (x,y) as the flame core, then `density` random particles are scattered in a cone behind it. Uses a shared non-deterministic xorshift RNG. Prefer cx_pfx for new work.

returns void

gpu_fx_thruster(0, 400, 300, 90.0, 32, 40, rgb(255,180,60), 30, rgb(255,120,40), 12);

sprinkle static two-color sparkle dots inside a rectangle

Legacy immediate-mode effect alternating color_a/color_b for each dot. density<=0 defaults to 32. lifetime_ms is currently ignored (this is an immediate draw, not a lifetimed particle spawn).

returns void

gpu_fx_glitter(50, 50, 200, 120, rgb(255,255,180), rgb(255,200,80), 40, 500);

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();