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)

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.

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