Engine

Core functions for script lifecycle, logging, and user information.

engine.register_onunload

Signature: engine.register_onunload(callback)

Description: Registers a function to be called when the script is unloaded.

Parameters:

• callback (function): The function to be called when the script is unloaded.

Returns: None

Example:

-- Register a cleanup function to be called when the script is unloaded
function on_unload_callback()
    engine.log("Script is being unloaded", 255, 255, 255, 255)
    -- Perform any necessary cleanup operations here
end

-- Register the callback with the engine
engine.register_onunload(on_unload_callback)

This function is useful for cleanup operations when your script is being unloaded, such as freeing allocated resources, closing file handles, or saving state.

---

engine.register_on_engine_tick

Signature: engine.register_on_engine_tick(callback)

Description: Registers a function to be called every engine tick. This is useful for implementing continuous operations or monitoring.

Parameters:

• callback (function): The function to be called on every engine tick.

Returns: None

Example:

-- Callback function that will execute on every engine tick
function enginetick_callback()
    -- Your logic here (executed on every engine tick)
    -- For example, checking game state, updating UI, etc.
    local fps = render.get_fps()
    if fps < 30 then
        engine.log("Low FPS detected: " .. fps, 255, 0, 0, 255)
    end
end

-- Register the callback with the engine
engine.register_on_engine_tick(enginetick_callback)

This function should be used for operations that need to be performed continuously, such as monitoring game state, updating UI elements, or performing animations.

---

engine.register_on_network_callback

Signature: engine.register_on_network_callback(callback)

Description: Registers a function to handle network responses from HTTP requests made with net.send_request().

Parameters:

• callback (function): The function to be called when a network response is received. The callback should accept two parameters: response_data (buffer handle) and url (string).

Returns: None

Example:

-- Callback function to handle network responses
function network_callback(response_data, url)
    -- Read the response data from the buffer
    local response_text = m.read_string(response_data, 0)
    
    -- Log the response
    engine.log("Received response from: " .. url, 0, 255, 0, 255)
    engine.log("Response: " .. response_text, 255, 255, 255, 255)
    
    -- You can also write the response to a file
    fs.write_to_file_from_buffer("response.txt", response_data)
end

-- Register the network callback
engine.register_on_network_callback(network_callback)

-- Make an HTTP request (the response will be handled by the callback)
net.send_request("https://example.com/api", "User-Agent: MyScript/1.0", nil)

This function is essential for handling asynchronous network responses in your scripts. The response data is provided as a memory buffer that you can read using the appropriate memory functions.

---

engine.log

Signature: engine.log(message, r, g, b, a)

Description: Logs a message to the console with the specified RGBA color.

Parameters:

• message (string): The message to log.

• r (number): Red color component (0-255).

• g (number): Green color component (0-255).

• b (number): Blue color component (0-255).

• a (number): Alpha (transparency) component (0-255).

Returns: None

Example:

-- Log a white message
engine.log("This is a white message", 255, 255, 255, 255)

-- Log an error in red
engine.log("Error: Something went wrong!", 255, 0, 0, 255)

-- Log a success message in green
engine.log("Success: Operation completed", 0, 255, 0, 255)

-- Log a warning message in yellow
engine.log("Warning: Proceed with caution", 255, 255, 0, 255)

-- Log a debug message in blue
engine.log("Debug: x = " .. tostring(x), 0, 0, 255, 255)

This function is commonly used for debugging, displaying status messages, and providing feedback to the user.

---

engine.get_username

Signature: engine.get_username()

Description: Returns the username of the currently logged-in user.

Parameters: None

Returns:

• string: The username of the currently logged-in user.

Example:

-- Get the current username
local username = engine.get_username()
engine.log("Hello, " .. username .. "!", 255, 255, 255, 255)

This function is useful for personalizing messages or identifying the current user in logs or saved files.