Collision events occur when BaseParts intersect or un-intersect in the 3D world. These events can be detected through the Touched and TouchEnded events respectively.
When considering collision handling on parts, note the following:
- A part's CanCollide property affects whether it will physically collide with other parts and cause forces to act upon them.
- Even if CanCollide is disabled for a part, you can detect intersection and un-intersection through collision events.
- A part's CanTouch property determines whether it triggers collision events. If set to false, neither Touched nor TouchEnded will fire.
The Touched event fires when a part comes in contact with another part. It only fires as a result of physical simulation and will not fire when the part's Position or CFrame is explicitly set such that it overlaps another part.
The following code pattern shows how the Touched event can be connected to a custom onTouched function. Note that the event sends the otherPart argument to the function, indicating the other part involved in the collision.
local part = workspace.Partlocal function onTouched(otherPart)print(part.Name .. " collided with " .. otherPart.Name)endpart.Touched:Connect(onTouched)
The TouchEnded event fires when the entirety of a part exits the collision bounds of another part. It only fires as a result of physical simulation and will not fire when the part's Position or CFrame is explicitly set such that it stops overlapping another part.
local part = workspace.Partlocal function onTouchEnded(otherPart)print(part.Name .. " is no longer touching " .. otherPart.Name)endpart.TouchEnded:Connect(onTouchEnded)
Models such as player characters contain multiple parts. Since a model as a whole cannot be connected to the Touched or TouchEnded events, you'll need to loop through its children and connect the custom onTouched function to each child BasePart.
local model = workspace.Modellocal function onTouched(otherPart)-- Ignore instances of the model coming in contact with itselfif otherPart:IsDescendantOf(model) then return endprint(model.Name .. " collided with " .. otherPart.Name)endfor _, child in pairs(model:GetChildren()) doif child:IsA("BasePart") thenchild.Touched:Connect(onTouched)endend
The CollisionFidelity property, accessible only for MeshParts and UnionOperations, determines how closely the physical hitbox matches its visual representation.
In most cases, the Default setting is suitable, but other settings can be selected based on best performance (Hull or Box) versus accuracy (PreciseConvexDecomposition).