PhysicsService
PhysicsService primarily contains methods for working with collision groups which define whether a set of parts may or may not collide with parts in other collision groups. You can register a collision group through RegisterCollisionGroup() and assign parts to it by setting those parts' CollisionGroup property to the name of the collision group.
Creating, deleting, and modifying collision relationships between collision groups is limited to server-side Scripts.
See Collision Filtering for usage details in Studio and within scripts.
Summary
Methods
Sets the collision status between two groups.
Returns whether the two groups will collide.
Returns the maximum number of collision groups.
Returns a table with info on all of the place's collision groups.
Checks if a collision group is registered.
Registers a new collision group with the given name.
Renames specified collision group.
Unregisters the collision group for the given name.
Properties
Methods
CollisionGroupSetCollidable
Sets the collision status between two groups. This method will throw an error if either of the groups is unregistered, so it's recommended that you confirm each group's registration through PhysicsService:IsCollisionGroupRegistered() before making this call.
Parameters
Returns
CollisionGroupsAreCollidable
Returns whether the two specified collision groups will collide. This method will also return true if either of the groups are unregistered, as the default collision mask collides with all groups.
Parameters
Returns
GetMaxCollisionGroups
Returns the maximum number of collision groups the engine supports. This value is currently 32.
Returns
GetRegisteredCollisionGroups
Returns a table with info on all of the place's collision groups. Each value in the returned table is itself a table and containing two members:
| Member | Type | Description |
|---|---|---|
| mask | integer | The collision group's mask; only for internal use. |
| name | string | Name of the collision group. |
Returns
IsCollisionGroupRegistered
Checks if a collision group is registered. It's recommended that you call this method before calling methods that throw errors for unregistered collision groups, such as PhysicsService:CollisionGroupSetCollidable().
Parameters
Returns
RegisterCollisionGroup
Registers a new collision group with the given name. The name cannot be "Default".
Note that this method has a slight performance overhead based on the number of BaseParts in the workspace, so it's recommended that you register all collision groups at edit time through the Studio editor and call UnregisterCollisionGroup() and RenameCollisionGroup() as infrequently as possible.
Parameters
Returns
Code Samples
local PhysicsService = game:GetService("PhysicsService")
local collisionGroupBall = "CollisionGroupBall"
local collisionGroupDoor = "CollisionGroupDoor"
-- Register collision groups
PhysicsService:RegisterCollisionGroup(collisionGroupBall)
PhysicsService:RegisterCollisionGroup(collisionGroupDoor)
-- Assign parts to collision groups
script.Parent.BallPart.CollisionGroup = collisionGroupBall
script.Parent.DoorPart.CollisionGroup = collisionGroupDoor
-- Set groups as non-collidable with each other and check the result
PhysicsService:CollisionGroupSetCollidable(collisionGroupBall, collisionGroupDoor, false)
print(PhysicsService:CollisionGroupsAreCollidable(collisionGroupBall, collisionGroupDoor)) --> false
RenameCollisionGroup
Renames the specified registered collision group, but does not rename the CollisionGroup property of parts that utilize the group. The first argument of this method is the name of the group to rename, the second argument is the new name for the group. If the specified group does not exist, this method will not do anything. The naming conventions for the new name follow the same rules as if the group was being created with RegisterCollisionGroup().
This method will throw a runtime error in the following circumstances:
- Invalid or empty name provided for either argument.
- The method is called from a client.
Note that this method has a slight performance overhead based on the number of BaseParts in the workspace, so it's recommended that you register all collision groups at edit time through the Studio editor and rename them as infrequently as possible.
Parameters
Returns
UnregisterCollisionGroup
Unregisters the collision group for the given name, with the following behaviors:
- If an invalid name is provided, the method will not do anything.
- If the reserved name "Default" is provided or if the method is called from a client, it will throw an error.
- If there are any parts in the collision group when it is removed, those parts will still maintain the same collision group name. The physical behavior of parts in a removed group is undefined, so it's recommended to move any parts in a removed group to another group, such as the "Default" group.
Note that this method has a slight performance overhead based on the number of BaseParts in the workspace, so it's recommended that you register all collision groups at edit time through the Studio editor and call this method as infrequently as possible.