Avoid running untrusted scripts! They can compromise your system and data
For more info, read here

Windows

System, audio, and window functions for interacting with the Windows platform.

System Functions

winapi.get_tickcount64

Signature: winapi.get_tickcount64()

Description: Returns the system uptime in milliseconds as a 64-bit integer.

Parameters: None

Returns:

  • number: The number of milliseconds that have elapsed since the system was started.

Example:

local uptime_ms = winapi.get_tickcount64()
local uptime_seconds = uptime_ms / 1000
local uptime_minutes = uptime_seconds / 60
local uptime_hours = uptime_minutes / 60
local uptime_days = uptime_hours / 24

engine.log("System uptime: " .. uptime_ms .. " ms", 255, 255, 255, 255)
engine.log("System uptime: " .. math.floor(uptime_days) .. " days, " .. 
           math.floor(uptime_hours % 24) .. " hours, " .. 
           math.floor(uptime_minutes % 60) .. " minutes", 255, 255, 255, 255)

Audio Playback

winapi.play_sound

Signature: winapi.play_sound(file_name)

Description: Plays a sound file (supports .wav and .mp3). The file can be a full path or a file located in the My Games directory.

Parameters:

  • file_name (string): Path to the sound file to play.

Returns:

  • boolean: true if the sound was played successfully, false otherwise.

Example:

-- Play a sound file
local success = winapi.play_sound("sounds/notification.wav")
if success then
    engine.log("Sound played successfully", 0, 255, 0, 255)
else
    engine.log("Failed to play sound", 255, 0, 0, 255)
end

-- Play a sound when a specific event occurs
function on_achievement_unlocked()
    winapi.play_sound("sounds/achievement.wav")
    engine.log("Achievement unlocked!", 255, 255, 0, 255)
end

Window Handling

winapi.get_hwnd

Signature: winapi.get_hwnd(class_name, window_name)

Description: Returns a window handle (HWND) as an integer. Both parameters can be nil to perform a broad match.

Parameters:

  • class_name (string, optional): The window class name to search for.

  • window_name (string, optional): The window title to search for.

Returns:

  • number: The window handle (HWND) if found, or nil if not found.

Example:

-- Find a window by its title
local notepad_hwnd = winapi.get_hwnd(nil, "Untitled - Notepad")
if notepad_hwnd then
    engine.log("Found Notepad window: " .. notepad_hwnd, 0, 255, 0, 255)
else
    engine.log("Notepad window not found", 255, 0, 0, 255)
end

-- Find a window by both class and title
local calculator_hwnd = winapi.get_hwnd("CalcFrame", "Calculator")
if calculator_hwnd then
    engine.log("Found Calculator window: " .. calculator_hwnd, 0, 255, 0, 255)
else
    engine.log("Calculator window not found", 255, 0, 0, 255)
end

Message Posting

winapi.post_message

Signature: winapi.post_message(hwnd, msg, wparam, lparam)

Description: Sends a Windows message to the given window handle. All arguments must be integers.

Parameters:

  • hwnd (number): The window handle to send the message to.

  • msg (number): The message ID to send.

  • wparam (number): The WPARAM value (interpretation depends on the message).

  • lparam (number): The LPARAM value (interpretation depends on the message).

Returns:

  • boolean: true if the message was successfully posted, false otherwise.

Example:

-- Find a window and send a message to it
local hwnd = winapi.get_hwnd(nil, "Untitled - Notepad")
if hwnd then
    -- Windows message constants
    local WM_CLOSE = 0x0010
    
    -- Send a message to close the window
    local success = winapi.post_message(hwnd, WM_CLOSE, 0, 0)
    if success then
        engine.log("Close message sent successfully", 0, 255, 0, 255)
    else
        engine.log("Failed to send close message", 255, 0, 0, 255)
    end
else
    engine.log("Target window not found", 255, 0, 0, 255)
end

Windows API Usage Examples

System Uptime Monitor

-- Function to format uptime in a readable way
function format_uptime(milliseconds)
    local seconds = milliseconds / 1000
    local minutes = seconds / 60
    local hours = minutes / 60
    local days = hours / 24
    
    return string.format("%d days, %02d:%02d:%02d",
                         math.floor(days),
                         math.floor(hours % 24),
                         math.floor(minutes % 60),
                         math.floor(seconds % 60))
end

-- Log uptime when script starts
local start_uptime = winapi.get_tickcount64()
engine.log("System uptime: " .. format_uptime(start_uptime), 255, 255, 255, 255)

-- Register a function to periodically check uptime
engine.register_on_engine_tick(function()
    -- Check uptime every 60 seconds
    local current_uptime = winapi.get_tickcount64()
    local elapsed = current_uptime - start_uptime
    
    if elapsed > 60000 then
        engine.log("Updated system uptime: " .. format_uptime(current_uptime), 255, 255, 255, 255)
        start_uptime = current_uptime
    end
end)

Sound Effect Player

-- Create a sound effect manager
local SoundManager = {
    sounds = {
        click = "sounds/click.wav",
        success = "sounds/success.wav",
        error = "sounds/error.wav",
        notification = "sounds/notification.wav"
    }
}

function SoundManager:play(sound_name)
    if not self.sounds[sound_name] then
        engine.log("Sound not found: " .. sound_name, 255, 0, 0, 255)
        return false
    end
    
    local success = winapi.play_sound(self.sounds[sound_name])
    if not success then
        engine.log("Failed to play sound: " .. sound_name, 255, 0, 0, 255)
    end
    
    return success
end

-- Usage examples
function on_button_click()
    SoundManager:play("click")
    -- Handle button click logic
end

function on_operation_success()
    SoundManager:play("success")
    engine.log("Operation completed successfully", 0, 255, 0, 255)
end

function on_operation_error()
    SoundManager:play("error")
    engine.log("Operation failed", 255, 0, 0, 255)
end

Window Management

-- Window manager for tracking and interacting with specific applications
local WindowManager = {
    target_windows = {}
}

-- Find and store a window handle by window title
function WindowManager:find_window(identifier, window_title)
    local hwnd = winapi.get_hwnd(nil, window_title)
    
    if hwnd then
        self.target_windows[identifier] = {
            hwnd = hwnd,
            title = window_title
        }
        engine.log("Found window '" .. window_title .. "': " .. hwnd, 0, 255, 0, 255)
        return true
    else
        engine.log("Window not found: " .. window_title, 255, 0, 0, 255)
        return false
    end
end

-- Close a tracked window
function WindowManager:close_window(identifier)
    local window = self.target_windows[identifier]
    if not window then
        engine.log("Window identifier not found: " .. identifier, 255, 0, 0, 255)
        return false
    end
    
    -- Windows message constants
    local WM_CLOSE = 0x0010
    
    local success = winapi.post_message(window.hwnd, WM_CLOSE, 0, 0)
    if success then
        engine.log("Close message sent to '" .. window.title .. "'", 0, 255, 0, 255)
        self.target_windows[identifier] = nil
    else
        engine.log("Failed to send close message to '" .. window.title .. "'", 255, 0, 0, 255)
    end
    
    return success
end

-- Check if a tracked window still exists
function WindowManager:window_exists(identifier)
    local window = self.target_windows[identifier]
    if not window then
        return false
    end
    
    -- Try to find the window again to see if it still exists
    local hwnd = winapi.get_hwnd(nil, window.title)
    return hwnd ~= nil
end

-- Usage example
WindowManager:find_window("notepad", "Untitled - Notepad")
WindowManager:find_window("calculator", "Calculator")

-- Later, when we need to close the windows
if WindowManager:window_exists("notepad") then
    WindowManager:close_window("notepad")
end
PreviousMatrixNextMarvel Rivals

Last updated

Was this helpful?