Skip to main content

Engine

The Engine or the core of the library handles all the RigidBodies, constraints and points. It's responsible for the simulation of these elements and handling all tasks related to the library.

Functions

Engine.init()

This method is used to initialize basic configurations of the engine and allocate memory for future tasks. The function takes in 1 parameter, a ScreenGui. It is a must, in order to handle Offsets produced by ScreenGui.IgnoreGuiInset without any visual bugs.

  • parameters - screengui: ScreenGui
  • returns - Engine

Engine:Create()

This method is used to create new physics objects like Points, Constraints and RigidBodies.

  • parameters - object: string, propertyTable: table
  • returns - newObject: Point | RigidBody | Constraint

Creating new Points

  • objectName - "Point"
  • valid properties - Position: Vector2, Snap: boolean | nil, Visible: boolean | nil, KeepInCanvas: boolean | nil, Color: Color3 | nil, Radius: number | nil
"Must Have" Properties

Position: Vector2

Engine:Create("Point", {
    Position = Vector2.new(100, 100),
    Visible = false,
    Snap = true
})

Creating new Constraints

  • objectName - "Constraint"
  • valid properties - Type: string, Point1: Point, Point2: Point, Visible: boolean | nil, Thickness: number | nil, RestLength: number | nil, SpringConstant: number | nil, Color: Color3 | nil,
  • valid types - Spring, Rod, Rope
"Must Have" Properties

Type: string Point1: Point Point2: Point

Engine:Create("Constraint", {
    Type = "Rope",
    Point1 = SomePoint1,
    Point2 = SomePoint2,
    Visible = true,
    RestLength = 100
})

Creating new RigidBodies

  • objectName - "RigidBody"
  • valid properties - Structure: table | nil, Object: GuiObject, Mass: number|nil, Collidable: boolean | nil, Anchored: boolean | nil, LifeSpan: number | nil, KeepInCanvas: boolean | nil, Gravity: Vector2 | nil, Friction: number | nil, AirFriction: number | nil,
"Must Have" Properties

Object: GuiObject

Supported UI Elements
  • Frame
  • ScrollingFrame
  • ImageButton
  • ImageLabel
  • TextLabel
  • TextBox
  • TextButton
  • VideoFrame
  • ViewportFrame
Engine:Create("RigidBody", {
    Mass = 1,
    Object = SomeGuiObject,
    Collidable = true,
    Anchored = false,
})

If you wish to define custom Structures for RigidBodies. Check out the tutorial!

Engine:CreateCanvas()

This function is used to initialize boundaries to which all bodies and constraints obey. An object cannot go past this boundary. By default this canvas is set to the initial screen size (workspace.CurrentCamera.ViewportSize). In order to let bodies go past this boundary use the RigidBody:KeepInCanvas() method. If you wish to render Constraints and Points on screen. Set a frame with the same size as the canvas to engine.canvas.frame.

  • parameters - topLeft: AbsolutePosition (Vector2), size: AbsoluteSize (Vector2)
  • returns - nil

Engine:Start()

This method is used to start simulating rigid bodies and constraints. This method is responsible for updating rigid bodies' and constraints' positions along with collision detection and response according to different configurations. If no rigid bodies or constraints are found when this method is called, a warning is sent in the console.

  • parameters - none
  • returns - nil

Engine:Stop()

This method is used to pause/stop simulating rigid bodies and constraints. The simulation can be resumed any time by calling Engine:Start() again.

Engine:Destroy()

Disconnects all events. Destroy all rigid bodies, points, and constraints, and also makes the engine unusable.

Engine:SetPhysicalProperty()

This method is used to configure universal physical properties possessed by all rigid bodies and constraints. Properties like Gravity, Friction, AirFriction, UniversalMass and CollisionMultiplier can be set using this method.

  • parameters - property: string, value
  • returns - nil
  • valid properties - "Gravity": Vector2, "Friction": number, "AirFriction": number, "CollisionMultiplier": number, "UniversalMass": number

Engine:SetSimulationSpeed()

This method is used to determine the simulation speed of the engine. By default the simulation speed is set to 55.

  • parameters - speed: number
  • returns nil

Engine:UseQuadtrees()

Determines if Quadtrees will be used in collision detection

  • parameters - use: boolean
  • returns - nil

Engine:FrameRateIndependent()

Determines if rendering frame rate does not affect the simulation speed. By default set to true.

  • parameters - independent: boolean
  • returns - nil

Fetch Methods

Engine:GetBodies()

This method is used to fetch all RigidBodies that have been created. Ones that have been destroyed, won't be fetched.

  • parameters - none
  • returns - RigidBodies: table

Engine:GetConstraints()

This method is used to fetch all Constraints that have been created. Ones that have been destroyed, won't be fetched.

  • parameters - none
  • returns - Constraints: table

Engine:GetPoints()

This method is used to fetch all Points that have been created.

  • parameters - none
  • returns - Points: table

Engine:GetBodyById()

This method is used to fetch an individual rigid body from its ID. Every RigidBody has a unique ID which can be fetched using RigidBody:GetId() or RigidBody.id.

  • parameters - id: string
  • returns - RigidBody

Engine:GetConstraintById()

This method is used to fetch an individual constraint body from its ID.

  • parameters - id: string
  • returns - Constraint

Engine:GetDebugInfo()

Returns all debugging information about the Engine.

  • parameters - none
  • returns - info: DebugInfo

Check out the debugging information returned from this method here

Engine:GetCurrentCanvas()

Deprecation Warning

This method is deprecated. It can no longer be used. Use Engine:GetDebugInfo() instead.

Returns current canvas the engine adheres to.

  • parameters - none
  • returns - { frame: Frame, topLeft: Vector2, size: Vector2 }

Engine:SetConstraintIterations()

Used to configure constraint iterations for the Engine.

  • parameters - iterations: number
  • returns - nil

Engine:SetCollisionIterations()

NOTE:

Collision iterations can only be increased if the Engine is using Quadtrees in collision detection. You can turn this on by using Engine:UseQuadtrees(true).

Used to configure collision iterations for the Engine.

  • parameters - iterations: number
  • returns - nil

Events

Engine.Started

This event is fired when the engine starts the simulation.

Engine.Stopped

This event is fired when the engine stops the simulation.

Engine.ObjectAdded

Fires when a new Point, Constraint or RigidBody is created.

  • returns - newObject: RigidBody | Constraint | Point

Engine.ObjectRemoved

Fires when a new Point, Constraint or RigidBody is destroyed.

  • returns - destroyedObject: RigidBody | Constraint | Point

Engine.Updated

Fires the moment all physics objects have been updated and rendered on screen.