How to substitute built-in APIs

This tutorial shows you how to substitute *some* built in Roblox APIs when coding in normal Lua.

by TheEpikCowman

Author Avatar

There might be some confusion when scripting within normal Lua itself, since Roblox has built in functions for the developers. So, I'll be going over some of them here.

  1. Wait As surprising as it is; since the wait function is one of the most commonly used blocks in the entirety of Roblox scripting itself, Lua does not have a built in wait/sleep command. There are several substitutes for this, however.

First is using the os.execute command to run "sleep"

function wait (sec) --create a function
  os.execute("sleep " ..sec) --adds the "sec" variable to "sleep"
print('hello everybody')

This code uses the operating system (os) to run a certain command, with that being "sleep." Pretty much, os already has commands on its own.

Second, using the os.clock By using the operating system's clock, you can create a substitute to the command.

function wait (sec) 
--create a function
    local s = tonumber(os.clock() + sec); 
--add the "sec" variable to clock time
    while (os.clock()<s) do 
--waits until the clock reaches the time

Even though I've added comments to the code already, It might still be confusing. os.clock is a real time clock, so by adding a certain amount of time to the clock, It will automatically wait until the clock reaches that time.

For example, Time is currently 7:10:00. If the sec variable is 10, the clock will wait until 7:10:10 (s variable)

And last, but not least. using the Socket extension. You need to download SocketLua to use this code. (Please note that Roblox Lua does not have Socket.)

local socket = require("socket") --require the socket extension
function wait (sec) --create a function
  socket.sleep(sec) --make socket.sleep wait a certain amount of seconds

What even is socket? Well, it's an extension that adds functions outside of normal Lua, It has things like TCP (Transfer Control Protocol) or UDP (User Datagram Protocol)

You can totally use this without needing to replace the original with functions, but I honestly like it better this way. Moving on to the next API.

  1. Instance

Roblox has used this to make defining objects easier. However, doing so in regular Lua needs a bit of scripts.

Since Roblox is an object-oriented engine, The objects and their properties are already pre-defined. You will need to set up how your objects work within regular Lua.

local Point = {} --define the "Point" class
Point.__index = Point

function, y)
 --create a function for creating points
  local self = setmetatable({}, Point)
 --create a metatable for the xy positions
  self.x = x
  self.y = y
--adding z is optional, but its far more difficult to use
  return self

--optional: this makes sure the xy positions are related
function Point:distance(other)
 --define the format of the function
  local dx = self.x - other.x
  local dy = self.y - other.y
  return math.sqrt(dx * dx + dy * dy)

--create the points
local p1 =, 0)
local p2 =, 4)

-- print the XY positions of each points
print("Point 1: (" .. p1.x .. ", " .. p1.y .. ")")
print("Point 2: (" .. p2.x .. ", " .. p2.y .. ")")

--calculate the distance
local distance = p1:distance(p2)
print("Distance:", distance) --distance is 5

When you run the script, you will get the following output on the console.

Point 1: (0, 0) Point 2: (3, 4) Distance: 5 Now, theres alot to unpack from just this script alone. I'll explain some of them.

What is self? Simple! It's a special variable used to refer to the object itself whenever there are multiple objects.

The XY positions are metatables, but what are metatables? They are basically just tables. For example you want B to have 3 B1s, 341 B2s, and 727 B3s. This is how it's gonna look.

--define B table
local B = {
  B3 = 3,
  B2 = 347,
  B1 = 727

--define metatable
local mt = {
--use '_index' to create metatable
  __index = function(t, k)
 --t is table, k is key
    return 0
 --must always end with 'return'

--set metatable
setmetatable(B, mt)

Now, what even is __index This is a metamethod used to create metatables, it defines how the metatable behaves.

It uses 2 arguments, in the shown script t is the table that is indexed, and k is the key that the function will use.

In the script, B (the table) is indexed and mt (the key) is used.

Defined elemented will have their assigned value and undefined elements in the table will be nil.

  1. Properties Following the last one, You can add other properties than XY postions to the points. These properties are fields to the variable, as shown below.
--set up properties for the objects
p.color = "pink" = "super epic point"
p.type = "coool"

--print the properties

When you run the script, you will get the following output.

pink super epic point coool Or if you want to change the properties you can use the following code.

function Point:setColor(color)
  self.color = color

-- change the color of the point

When you run the script, you will get the following output.


Roblox APIs are built-in to the game to make it far more easier for creating, But however in regular Lua some features are missing. Like the "wait" command or the objects and properties itself. Most of the time you need to make it all from scratch or use extensions to help.

To substitute the 'wait' command, you need to use the os or other extensions to replace the 'wait' command.

To substitute Instances, you need to define a class, and add a function to create it. And usually using metatables when adding properties.

To substitute Properties, you need to add fields to the objects, and add a function to change it.

Hope this helps!

View in-game to comment, award, and more!