Handling Events

Events are a small part of Nature2D that come to a lot of use. They make a lot of things easier to handle without polling or other bad practices. As of now there are 8 available events. 5 for the Engine and 3 for RigidBodies. Let's have a look at them and how you can use them in your code.

Let's start with the Touched and CanvasEdgeTouched events for RigidBodies! RigidBody.Touched fires the moment a RigidBody is touching another RigidBody. Similarly RigidBody.CanvasEdgeTouched fires if the RigidBody is touching any edge of the canvas (Top, Left, Right and Bottom). The Touched event returns the unique ID of the RigidBody while the CanvasEdgeTouched event returns the name of the edge the RigidBody collided with. The RigidBody.TouchEnded event fires the moment two RigidBodies stop colliding with each other. This event also returns the id of the other RigidBody.

Take in account that CanvasEdgeTouched event only fires if RigidBody.KeepInCanvas is set to true. Let's take this example. Suppose you have a kill part. If a RigidBody touches this killpart, the rigidbody is destroyed!

local killPart = Engine:Create("RigidBody", {
    Object = KillPartObjectHere,
    Collidable = true,
    Anchored = true
})

killPart.Touched:Connect(function(id)
    local body = Engine:GetBodyById(id)

    if body then 
       body:Destroy()
    end
end)

killPart.TouchEnded:Connect(function(id)
    print("Touch ended!")
end)

Similarly, let's take another example. Say you want to change the color of the RigidBody object if it collides with the left edge of the canvas.

local body = Engine:Create("RigidBody", {
    Object = BodyObject,
    Collidable = true,
    Anchored = false
})

body.CanvasEdgeTouched:Connect(function(edgeName)
    if edgeName == "Left" then 
       body:GetFrame().BackgroundColor3 = Color3.new(1, 0, 0) -- red
    end 
end)

That is all for RigidBody events! Now for the events of the Engine.

The first two events we'll be taking a look at are Engine.Started and Engine.Stopped. These events fire when you call Engine:Start() and Engine:Stop(). Say you wish to display if the engine is running or not on a textlabel on the user's screen.

local Engine = Nature2D.init(screenGuiInstance)

local Label = Instance.new("TextLabel")
Label.AnchorPoint = Vector2.new(0.5, 0.5)
Label.Position = UDim2.fromScale(0.5, 0.5)
Label.Parent = screenGuiInstance

Engine.Started:Connect(function()
    Label.Text = "Engine is Running"
end)

Engine.Stopped:Connect(function()
    Label.Text = "Engine is not Running"
end)

There are two more events for the Engine. Engine.ObjectAdded and Engine.ObjectRemoved! They are similar to how Instance.ChildAdded and Instance.ChildRemoved work. Whenever a RigidBody, Point or Constraint is added using the :Create() method, the ObjectAdded event is called and also returns the object added. When a RigidBody or Constraint is destroyed, ObjectRemoved event is called and it also returns the object removed.

Engine.ObjectAdded:Connect(function(object)
    print(object:GetId())
end)

Engine.ObjectRemoved:Connect(function(object)
    print(object:GetId())
end)

local newBody = Engine:Create("RigidBody", {
    Object = SomeInstance,
    Collidable = false,
    Anchored = false,
    Friction = 0.03
}) -- ObjectAdded is fired

newBody:Destroy() -- ObjectRemoved is fired

Engine.Updated fires each frame. It fires the moment all physics objects have been updated and rendered on screen.

Engine.Updated:Connect(function()
    -- do something
end)