Engine

⚙️ Overview

A callback is a script function that executes repeatedly on a background thread created by the engine. Each callback receives a unique callback ID (integer) and runs at a defined interval in milliseconds.

---

🧩 Registration Functions

Register Callback

int register_callback(const __Internal_CallbackFn@ fn, int every_ms, int data_index, bool render_on_top = false)

Registers a new recurring callback function. The engine launches a lightweight thread that periodically invokes your callback, passing both its unique ID and the data_index you supplied.

Parameter	Type	Description
fn	__Internal_CallbackFn@	Function pointer to the callback (takes two integer arguments — the callback ID and the data index).
every_ms	int	Delay in milliseconds between callback executions.
data_index	int	User-defined integer value forwarded to your callback each time it runs. This can represent a dataset slot, UI layer, or logic group.
render_on_top	bool	Optional flag. Set to true to render this callback’s output above everything else. If multiple callbacks use this, registration order still determines which one is topmost. Defaults to false.

Returns: A unique callback ID (int) if successful, or 0 on failure. Drawing And Input is unique for each thread.

🧠 The callback executes in its own thread. Each iteration:

1. Begins input collection

2. Executes your callback function

3. Submits the current draw list

4. Ends input and sleeps for every_ms

---

Unregister Callback

void unregister_callback(int id)

Stops a previously registered callback and terminates its thread.

Parameter	Type	Description
id	int	The callback ID returned by register_callback.

---

🧠 Callback Function Type

The callback function type is defined internally by the engine:

funcdef void __Internal_CallbackFn(int callback_id, int data_index)

Your script callback must accept two integer parameters:

Parameter	Type	Description
callback_id	int	The callback ID returned by register_callback. This uniquely identifies the running callback instance.
data_index	int	A user-defined or engine-supplied index value associated with this callback execution. Can be used to differentiate multiple data contexts handled by the same callback.

---

Example

void on_update(int callback_id, int data_index)
{
    log("Callback " + callback_id + " tick (data=" + data_index + ")");

    // draw something using data_index
    float x = 100 + data_index * 40;
    draw_circle(x, 200, 10, 255,200,100,255, 2.0f, false);
}

int main()
{
    // Run callback every 50ms
    int cb = register_callback(on_update, 50, 34);
    log("Registered callback " + cb);

    return 1; // keep script running
}

---

🪵 Logging Helper

void log(const string &in message)
// Displays a standard informational message in the UI log overlay.

void log_error(const string &in message)
// Displays an error-styled message in the UI log overlay and raises an exception.

void log_console(const string &in message)
// Writes a message to the debug console (persistent until the console is cleared).

void log_console_error(const string &in message)
// Writes an error-styled message to the debug console in red and raises an exception.

Example:

log("Log Example");
log_error("Error Log Example");
log_console("Current HP : 100");
log_console_error("Error Log Example");

---

get_username(): string

Returns the current PCX username as a string.

Syntax

string get_username()

---

📜 Example: Animated Cursor

float r = 0.0f;

void animate_cursor(int id, int data_index)
{
    float x, y;
    get_mouse_pos(x, y);
    
    r += 2.0f;
    
    draw_circle(x, y, 12 + sin(r * 0.1f) * 4,
    255, 100, 50, 255,
    2.0f, false);
}

int main()
{
    register_callback(animate_cursor, 1, 0);
    return 1;
}