Add native MP.SetTimeout and MP.CreateThread for async execution

[Kipstz]

Summary

Currently, executing code asynchronously or with a delay requires complex workarounds using MP.CreateEventTimer and MP.RegisterEvent. This proposal adds simple, intuitive functions for async execution:

1. MP.SetTimeout(ms, func) - Execute a function after a delay
2. MP.CreateThread(func) - Execute a function asynchronously

Current Workaround (Complex)

To achieve async execution today, developers must:

-- Current: 15+ lines of boilerplate for a simple delayed execution
local threadId = 0

function createAsyncTask(func)
    threadId = threadId + 1
    local id = "__thread_" .. threadId
    local handlerName = "__thread_handler_" .. threadId

    _G[handlerName] = function()
        func()
        MP.CancelEventTimer(id)
        _G[handlerName] = nil
    end

    MP.RegisterEvent(id, handlerName)
    MP.CreateEventTimer(id, 100)
end

-- Just to do this:
createAsyncTask(function()
    Wait(5000)
    print("5 seconds later")
end)

Proposed Solution (Simple)

-- SetTimeout: Execute after delay (like JavaScript)
MP.SetTimeout(5000, function()
    print("5 seconds later")
end)

-- CreateThread: Async execution
MP.CreateThread(function()
    print("This runs asynchronously")
    Wait(1000)
    print("Non-blocking code")
end)

Real-World Use Cases

Auto-restart warning system

function scheduleRestart(minutes)
    MP.SetTimeout(minutes * 60000, function()
        shutdownServer()
    end)

    -- Warning messages
    MP.SetTimeout((minutes - 5) * 60000, function()
        MP.SendChatMessage(-1, "^6[SERVER]^r Restart in 5 minutes!")
    end)

    MP.SetTimeout((minutes - 1) * 60000, function()
        MP.SendChatMessage(-1, "^4[SERVER]^r Restart in 1 minute!")
    end)
end

Delayed kick after warning

MP.RegisterEvent("onCheatDetected", function(playerID)
    MP.SendChatMessage(playerID, "^4[AntiCheat]^r Suspicious activity detected. You will be kicked in 10 seconds.")

    MP.SetTimeout(10000, function()
        MP.DropPlayer(playerID, "Kicked by AntiCheat")
    end)
end)

Non-blocking database operations

MP.RegisterEvent("onPlayerJoin", function(playerID)
    -- Don't block the main thread while loading data
    MP.CreateThread(function()
        local data = loadPlayerDataFromDB(playerID)
        applyPlayerData(playerID, data)
        print("Player data loaded for " .. playerID)
    end)
end)

Welcome sequence with delays

MP.RegisterEvent("onPlayerJoin", function(playerID, playerName)
    MP.SendChatMessage(playerID, "^2Welcome " .. playerName .. "!^r")

    MP.SetTimeout(3000, function()
        MP.SendChatMessage(playerID, "^3Type /help for available commands^r")
    end)

    MP.SetTimeout(6000, function()
        MP.SendChatMessage(playerID, "^3Join our Discord: discord.gg/example^r")
    end)
end)

Benefits

Current Approach	Proposed Approach
15+ lines of boilerplate	1 function call
Manual cleanup required	Automatic cleanup
Error-prone	Simple and reliable
Hard to read	Intuitive syntax
Must manage event timers manually	Native implementation

Technical Notes

• Backward compatible: Does not affect existing MP.CreateEventTimer functionality
• Familiar pattern: Same syntax as JavaScript setTimeout - millions of developers already know it
• Performance: Native C++ implementation would be faster than Lua workarounds
• Memory safe: Automatic cleanup of handlers after execution

Additional Context

I've implemented this as a Lua wrapper in my framework (https://github.com/Kipstz/Tree-BeamMP-Plugin/blob/main/_tree/threads.lua), but a native C++ implementation would be cleaner, more performant, and benefit all plugin developers without requiring external dependencies.

---

I'm willing to implement this feature and submit a PR if the approach is approved.

[OfficialLambdax]

A simpler use of delaying code execution is welcome, but i dont believe you can make async code possible in lua. Correct me if im wrong

-- CreateThread: Async execution
MP.CreateThread(function()
    print("This runs asynchronously")
    Wait(1000) -- <<<<---------------<<<<< this will block the thread just like MP.Sleep()
    print("Non-blocking code")
end)

See for example

local threadId = 0

function createAsyncTask(func)
    threadId = threadId + 1
    local id = "__thread_" .. threadId
    local handlerName = "__thread_handler_" .. threadId

    _G[handlerName] = function()
        func()
        MP.CancelEventTimer(id)
        _G[handlerName] = nil
    end

    MP.RegisterEvent(id, handlerName)
    MP.CreateEventTimer(id, 100)
end


function onChatMessage()
 createAsyncTask(function() -- create task with every chat message received
     Wait(5000)
     print("5 seconds later")
 end)
end

function onInit()
 MP.RegisterEvent("onChatMessage", "onChatMessage")
end

Then join the server and send one chat message after another, you will notice a delay in your chat messages bouncing back. That happens whenever you sleep in the lua thread. It simply cant execute more code in the thread until the previous has exited.

Same with this

MP.RegisterEvent("onPlayerJoin", function(playerID)
    -- Don't block the main thread while loading data
    MP.CreateThread(function() -- as long as this function is working nothing else in this lua state can run
        local data = loadPlayerDataFromDB(playerID)
        applyPlayerData(playerID, data)
        print("Player data loaded for " .. playerID)
    end)
end)

[Kipstz]

@OfficialLambdax

Hi, I've already done them here
https://github.com/Kipstz/Tree-BeamMP-Plugin/blob/main/_tree%2Fthreads.lua.

The goal is to do it natively and not manually.

[OfficialLambdax]

The goal is to do it natively and not manually.

Mind explaining? Because i dont see how this addresses the issue im pointing at here. As long as code doesnt return from the lua state no other code can run in the same lua state. Even if that very code is sleeping.

1. Chat message is received
2. Lua state creates timed event
3. Timed event is executed
4. Code enters sleep for 10 seconds
5. User sends another message
6. Lua state cant execute because the previous code is still running
7. Lua state resumes because code exits sleep
8. Last message gets processed

and so on and so forth

[Kipstz]

I invite you to test what I have done in Lua. Nothing is blocked during execution.

[OfficialLambdax]

I invite you to test what I have done in Lua. Nothing is blocked during execution.

Ok i have done so.

This will once a second print the date so that we can see the second its printing on. And then after 5 seconds it will create a thread that will block the state with a sleep.

require("libs/threads")

local COUNT = 0

function routine()
    print(os.date())

    COUNT = COUNT + 1
    if COUNT == 5 then
        CreateThread(function()
            print("Starting to block the state for 5 seconds")
            MP.Sleep(5000)
            print("End blocking the state")
        end)
    end
end

function onInit()
    print("Initializing")
    MP.RegisterEvent("routine", "routine")
    MP.CancelEventTimer("routine") -- for hotreload
    MP.CreateEventTimer("routine", 1000) -- fire every second
end

Heres the result. It blocked the state for 5 seconds. Also notice the dual print for second 08. The first is the event that was supposed to trigger at 04 but was blocked until 08.

[boubouleuh]

So, createEventTimer used by createThread doesn’t actually create a new thread, but a coroutine scheduled to run after X seconds

When it executes, it still runs on the same thread, meaning everything shares that single thread.
So there’s no real async here, just cooperative execution

Coroutines ~= Async

(i hope im correct but i think i am)

[Kipstz]

In any case, the ultimate goal is to introduce all of this, so it won't be a problem because the changes will be made in C++, i.e. internally.

[OfficialLambdax]

[...] but a coroutine scheduled to run after X seconds

Awesome that your mentioning it! But no its not a coroutine. But a jobsystem, thats based on coroutines, like the game has is what would have solved this very issue!

Its possible to create a one liner for whats suggested by this issue, i mean trimming two function calls down to 1 for delayed code execution. And then anyone really could just grab the jobsystem from the game and write their code in a coroutine format to help against blocking the thread to much. thats very common todo in lua

In any case, the ultimate goal is to introduce all of this, so it won't be a problem because the changes will be made in C++, i.e. internally.

Hey if you believe you can crack it then feel free to take a go on it!

[Kipstz]

Well, I was waiting to be told whether I should do it or not, but I think I'll do it without waiting.