Roblox Globals - iimurpyh/pilot-lua GitHub Wiki

Roblox globals and libraries accessible to microcontrollers.

Table of contents

Default

number tick()

Returns the current time on the server in seconds.

void print(any...)

Prints the arguments given to it to the developer console of the player who locked the Microcontroller.

task

A library for various event scheduling methods, most of which are improved versions of previous globals (i.e. wait().)

string task.wait(number duration=0)

Yields the current thread until the given duration (in seconds) has elapsed, then resumes the thread on the next Heartbeat step. The actual amount of time elapsed is returned.

If no duration is given, it will default to zero (0). This means the thread resumes on the very next step, which is equivalent in behavior to RunService.Heartbeat:Wait()

Unlike the global wait, this function does not throttle and guarantees the resumption of the thread on the first Heartbeat that occurs when it is due. This function also only returns the elapsed time and nothing else.

string task.delay(number duration, function functionOrThread, Variant ...)

Accepts a function or a thread (as returned by coroutine.create) and schedules it to be called/resumed on the next Heartbeat after the given amount of time in seconds has elapsed. Arguments after the second are sent to the function/thread.

This function differs from the global delay function in that no throttling occurs: on the very same Heartbeat step in which enough time has passed, the function is guaranteed to be called/resumed. Providing a duration of zero (0) will guarantee that the function is called on the very next Heartbeat.

You can calculate the actual time passed by calling os.clock upon scheduling and in the scheduled function.

string task.defer(function functionOrThread, Variant ...)

Accepts a function or a thread (as returned by coroutine.create) and defers it until the next resumption cycle, at which point it is resumed with the engine’s scheduler like with task.spawn. Arguments after the first are sent to the function/thread. This function does not return any value, even if the provided function returns one immediately.

This function should be used when a similar behavior to task.spawn is desirable, but the thread does not need to run immediately.

string task.spawn(function functionOrThread, Variant ...)

Accepts a function or a thread (as returned by coroutine.create) and calls/resumes it immediately through the engine’s scheduler. Arguments after the first are sent to the function/thread. This function does not return any value, even if the provided function returns one immediately.

coroutine

A library designed for creating threads. It's not important to understand how threads work on the inside, but it's good to mention that threads are actually very smart.

They don't cost a lot because all Roblox basically does is change where it wants to run code inside of your thread, and then when it's done or when it pauses or errors, Roblox goes back to wherever it needs to be. This means that threads can be used as a way to stitch pieces of code together, but, like they are named, they are also useful for making things that appear to run at once.

thread coroutine.create(function body)

Creates a thread with your function and returns the thread. You can use coroutine.resume with this new thread.

Code example for coroutine.create

-- Spawn a new thread
coroutine.resume(coroutine.create(function()
    wait(1) -- Start waiting for a second, this lets our print below run
    print("After") -- Prints 1 second after before
end))
print("Before") -- Prints before

any... coroutine.resume(thread target, any...)

Resumes the given thread, target. Also passes in any arguments you place after, and returns any stuff the thread returned or yielded with.

any... coroutine.yield(any...)

Works similar to coroutine.resume. Yields (pauses) the current thread, giving your arguments to the resumer thread, the thread that resumed the one calling yield. Once your thread gets resumed again by Roblox, it returns any arguments the new resumer passed.

thread coroutine.wrap(function f)

Creates a new coroutine, with body f. f must be a Lua function. Returns a function that resumes the coroutine each time it is called. Any arguments passed to the function behave as the extra arguments to resume. Returns the same values returned by resume, except the first boolean. In case of error, propagates the error.

string coroutine.status(thread target)

Gets a status string for the thread.

debug

string debug.traceback(string prefix=nil, int level=1)

Creates a stack trace based on a prefix to place before, and a level to get the stack from. For example, level 2 will get the stack trace relative to one function above. You can also use 0 to get the stack at the very root of the script. This is useful for creating debug output.

Code example for debug.traceback

This is a "fancy" way to pcall which puts the stack trace of the error after its message. It uses xpcall to set the error handler to debug.traceback.

Xpcall works the same as pcall, but it allows you to pass a function to handle errors. This function gets called at the location of the error, and whatever it returns gets returned as xpcall's second option (if success is false).

So, when an error message occurs, it returns debug.traceback(errorMessage) getting called where the error is, so, it gets the stack trace of the location of the error, and that means that what you will get is the error message but with a stack trace attached.

local success, errMessage = xpcall(myFunction, debug.traceback)

Deprecated

These globals have been replaced with alternatives.

[Deprecated] number, number wait(float time=1/30)

Waits for a given time (in seconds), or the next Heartbeat if called without arguments. Succeeded by task.wait.

[Deprecated] void delay(optional float time, function callback)

Waits the specified time, then spawns the passed function in a new thread. Succeeded by task.delay.

[Deprecated] void spawn(function callback)

Spawns the passed function in a new thread. Succeeded by task.spawn.