Scene

The Scene global provides fields and functions relating to the Simulo scene.

Fields

Field	Description	Note	Default	Type
Scene.title	The name of the scene		"Untitled Scene"	string
Scene.background_color	The color shown behind the scene		0x34213d	number
Scene.runtime_version	The version of the Simulo Runtime	Read-only		string
Scene.box2d_version	The version of Box2D used in the Simulo runtime	Read-only	3.0.0	string

Functions

note

Make sure to use Scene:function() and not Scene.function(), or you'll get an error

---

Scene:add_box(...)

Adds a new box to the scene. Takes a table as parameter, returns a SimuloObject.

Example

Scene:add_box({
    position = vec2(0, 0),
    size = vec2(1, 1),
    color = 0xe5d3b9,
    is_static = false,
});

Table Fields

Table Field	Description	Note
position Vec2	Where to spawn the box
size Vec2	Size of the box in meters
color number	Color of the box, like 0xe5d3b9
is_static boolean	Should the box be "glued to the background"?
name string	What should the name of the box be? Defaults to "Box"	Optional

---

Scene:add_circle(...)

Adds a new circle to the scene. Takes a table as parameter, returns a SimuloObject.

Example

Scene:add_circle({
    position = vec2(0, 0),
    radius = 1,
    color = 0xe5d3b9,
    is_static = false,
});

Table Fields

Table Field	Description	Note
position Vec2	Where to spawn the circle
radius number	Radius of the circle in meters
color number	Color of the circle, like 0xe5d3b9
is_static boolean	Should the circle be "glued to the background"?
name string	What should the name of the circle be? Defaults to "Circle"	Optional

---

Scene:add_component(...)

Adds a new component to the scene. Takes a table as parameter, returns a Component Hash.

For a detailed explanation, check out the Components section of the API Docs.

Example

Scene:add_component({
    name = "My Component",
    version = "0.1.0",
    id = "@john_doe/test/my_component",

    -- Lua/Luau code
    code = [[
        function on_start()
            print("Hello, worlds!");
        end;
    ]],
});

Table Fields

Table Field	Description	Note
name string	Where to spawn the circle
version string	Component metadata version, defaults to "0.1.0"	Optional
id string	Unique ID for your component, should be something like "@yourname/projectname/componentname"
code string	Luau script for the component

---

Scene:add_simulon(...)

Adds a simulon to the scene, Simulo's mascot. Returns nothing.

This function may be removed by public release, where users will instead be able to spawn simulons just like any other saved object.

Example

Scene:add_simulon({
    position = vec2(0, 0),
    density = 1,
    color = 0xff0000,
});

Table Fields

Table Field	Description	Note
position Vec2	Where to spawn the simulon
density number	Density for the simulon
color number	Simulon color, defaults to 0xa9bc67	Optional

---

Scene:get_object_by_guid(...)

Returns the SimuloObject of the given guid, or nil if it doesn't exist.

Example

local object = Scene:get_object_by_guid(20);

---

Scene:get_all_objects()

Returns a table which is a list of SimuloObjects.

Example

local objects = Scene:get_all_objects();

-- Destroy all objects in scene
for i=1,#objects do
    objs[i]:destroy();
end;

---

Scene:get_gravity()

Returns a Vec2 of the scene's gravity.

Example

local gravity = Scene:get_gravity();

print(tostring(gravity));

---

Scene:set_gravity(...)

Sets the scene's gravity to a Vec2. Returns nothing.

Example

Scene:set_gravity(vec2(0, -15));

---

Scene:overlap_circle(...)

Returns a table which is a list of SimuloObjects that overlap with a circle. Does not actually create any circle shape.

Example

local objects_in_circle = Scene:overlap_circle({
    position = vec2(0, 0),
    radius = 10,
});

-- Print the GUIDs
for i=1,#objects do
    print("Object of GUID " .. tostring(objs[i].guid) .. " was in circle");
end;

Table Fields

Table Field	Description	Note
position Vec2	Center of the circle
radius number	Radius of the circle

---

Scene:add_hinge_at_world_point(...)

Adds a hinge at a world point, connecting two SimuloObjects. Returns a SimuloHinge.

Example

local object_a = Scene:get_object_by_guid(1);
local object_b = Scene:get_object_by_guid(2);

local hinge = Scene:add_hinge_at_world_point({
    point = vec2(0, 0),
    object_a = object_a,
    object_b = object_b,
    motor_enabled = false,
    motor_speed = 1, -- radians per second
    max_motor_torque = 10, -- maximum torque for the motor, in newton-meters
});

hinge:destroy();

Table Fields

Table Field	Description	Note
point Vec2	World point for the hinge
object_a SimuloObject	First object for the hinge
object_b SimuloObject	Second object for the hinge
motor_enabled bool	Should the hinge have a motor? Defaults to false	Optional
motor_speed number	Radians per second	Optional
max_motor_torque number	Maximum torque for the motor, in newton-meters	Optional

---

Scene:explode(...)

Applies an impulse in the scene at a given point to all objects in its radius.

note

The explosion impulse does not depend on distance, all objects in the radius will get the same impulse.

Example

Scene:explode({
    position = vec2(0, 0),
    radius = 10,
    impulse = 10.
});

Table Fields

Table Field	Description	Note
position Vec2	Center of the explosion
radius number	Radius of the explosion
impulse number	Impulse of the explosion