Skip to main content

API Docs Introduction

Welcome to the Simulo API Docs! From here, you can learn all about the various parts of Simulo's Luau scripting API.

These docs currently assume an understanding of Lua fundamentals. If you're not familiar with Lua, please follow a Lua tutorial first, then come back here when you're ready. You may however still be able to follow if you're familiar with programming in general.

Welcome

Getting Started​

You probably want to create either a Tool, a Component, or an Attachment.

Tools​

We can create powerful custom tools in Lua (all the built-in tools are also made in Lua).

Components​

We can also make scripts that you add on objects and attachments in right-click.

Attachments​

We can even make visible gadgets, like a Hinge Tool's hinge, which you can right-click, and tweak its settings.

Script Box​

For everything except making custom tools, we can prototype it in the Script Box if we want.

To get it, use File → Toggle Scripter UI in-game.

Simulo Script Box

What if I need it to stay?​

If you don't want to do that every time, do File → Open Simulo Folder and open config.toml and change the umm yeah its in there. You'll know when you see it

Script Box Features​

The Simulo Script Box has the following features:

  • ✅ Luau syntax highlighting
  • ✅ Line numbers
  • ✅ Display of errors

The Simulo Script Box does NOT currently have the following features:

  • ⛔ Static analysis
  • ⛔ IntelliSense
  • ⛔ Multiple files
  • ✅ Display of print logs

print will work again soon! Really soon! Super soon!

Your First Script​

The Script Box runs one-shot global scripts on the scene. This means we run the code in the script once, in contrast to Components, which can run code every Update.

Unfortunately for now, print won't show anything in-game. Will be fixed soon but for now, use return. If you want fake print, paste this in the box:

local console = "";

function print(msg)
    console = console .. tostring(msg) .. "\n";
end;

-- your code here

return console;

It's annoying but we do what it takes to Survive in simuland

Anyway back to Your First Script, do this:

return "Hello, worlds!"; -- The string shows up in the Script Box's output

Vec2​

Simulo uses Vec2 all over the API to represent positions, sizes, velocities, etc. A Vec2 has 2 fields: x and y. We create them using the vec2(x, y) global constructor:

local vec = vec2(5, 5); -- Creates a new Vec2 with `x` and `y` set to 5

return vec; -- (5, 5)

We can perform most math operations on a Vec2:

local console = "";

function print(msg)
    console = console .. tostring(msg) .. "\n";
end;

local a = vec2(1, 0);
local b = vec2(0, 1);

-- Addition
print(a + b); -- (1, 1)
-- Subtraction
print(a - b); -- (1, -1)
-- Multiplication
print(a * 2); -- (2, 0)
-- Division
print(a / 2); -- (0.5, 0)
-- Negation
print(-a); -- (-1, 0)

return console;

Vec2 also has a :magnitude() function:

-- We have to use `:` and not `.` here!
local vec = vec2(1, 1);
return vec:magnitude(); -- 1.41421...

-- more Vec2 functions coming soon

Why : instead of .?​

Someone very new to Lua might wonder why we have to use : instead of . to call the magnitude() function on a Vec2, as in most programming languages that isn't the case.

The answer is, the : operator passes the Vec2 into the function as a hidden parameter. Here's an example:

local vec = vec2(0, 0);

-- Writing this:
vec:magnitude();
-- Is the same as writing this:
vec.magnitude(vec);

-- The first one passes in itself as a hidden parameter to the `magnitude` function,
-- and in the second one, we use `.` (which doesn't do that) but we manually pass in `vec`.

-- Thus, if we try to use `.` without passing in `vec`, we will get an error.
vec.magnitude(); -- ⛔ This will cause an error

Adding Boxes​

We can add boxes to the scene with the Scene:add_box function. It takes a table with fields like position, size, etc.

-- Add a red box to the scene

Scene:add_box({
    position = vec2(0, 0),
    size = vec2(1, 1),
    body_type = BodyType.Dynamic, -- or BodyType.Static for unmoving
    color = 0xff0000, -- Hex color
});

If you paste this code in Simulo's Script Box and press Run, you should see a red box appear. If the game isn't paused, it will fall to the ground.

Scene:add_box returns an Object. We can store this in a variable:

local box = Scene:add_box({
    position = vec2(0, 0),
    size = vec2(1, 1),
    body_type = BodyType.Dynamic,
    color = 0xff0000,
});

box:set_color(0x00ff00); -- Change color to green after creating

Running the above code should produce a green box, even though we initially made it red. Insane

Rest Of The Owl​

Now you may have some questions about how to accomplish specific things in the API, such as getting a reference to a specific object in the scene, getting a list of all the objects in the scene, etc.

You can find all the Scene API functions in the Scene section of the API Docs.

Components​

As said earlier, the Simulo Script Box can only run one-shot scripts. However, Simulo also provides Components, which allow placing scripts on objects, such as boxes, polygons, circles, etc.

Components are very powerful and allow doing almost anything with scripting, even creating a platformer game in Simulo.

For a guide on how to use components, check out the Components section of the API Docs.