Skip to main content

Region

Types

RegionInstance

</>
type RegionInstance = BasePart | Model

The 3D representation of the Region's boundaries. It can either be a single BasePart or a Model composed of several BaseParts that all represent one Region.

Properties

name

</>
Region.name: string

The name of the Region. This is used when calling tostring() on the Region instance.

(Default: "Region")

instance

</>
Region.instance: RegionInstance

A reference to the regionInstance argument pass when constructing

entered

</>
Region.entered: RBXScriptSignal

Fired when an instance in the whitelist enters the Region.

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region.entered:Connect(function(instance: Instance)
	print(instance, "entered the region")
end)

left

</>
Region.left: RBXScriptSignal

Fired when an instance in the whitelist leaves the Region.

Usage:

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region.left:Connect(function(instance: Instance)
	print(instance, "left the region")
end)

Functions

new

</>
Region.new(regionInstance: RegionInstance) → Region

Constructs a new Region instance.

You can either pass in a Model or a BasePart which will represent the Region's boundaries in the Workspace.

When using a Model, it must contain BaseParts as children.

A Region's BaseParts are known as "segments." Every Region must have at least one segment, and when a segment is collided with by instances in the whitelist certain events will be triggered. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

is

</>
Region.is(other: any) → boolean--

Returns true if other is a Region, false otherwise

Static function for checking if the given argument is a Region instance or not.

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

print(Region.is(region)) -- true
print(Region.is("string") -- false

setWhitelist

</>
Region:setWhitelist(whitelist: {Instance}) → ()

Sets the instances that can collide with the Region and trigger events.

The whitelist must be defined or the Region will not respond to any instances.

tip

A common use case is to set the whitelist to all the Character models in the Workspace. This allows you to setup a region system where your players can enter and leave specific zones. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region:setWhitelist({
	Players.LocalPlayer.Character
})

getRegionSegments

</>
Region:getRegionSegments() → {BasePart}--

Returns all BaseParts that compose the Region

Get all of the BaseParts that compose the Region's boundary.

info

If you passed in a BasePart when constructing, this will return an array with that BasePart as the only element. If you passed a Model, this will return an array with all BasePart descendants. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

print(region:getRegionSegments())

getInstancesInRegion

</>
Region:getInstancesInRegion() → {Instance}--

Array of whitelisted Instances that are within the Region

Gets all whitelisted Instances that are within the Region.

tip

The below example uses a while loop to print out all whitelisted instances within the Region for illustrative purposes. Usually you will want to respond to the enter and left events. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region:setWhitelist({
	Players.LocalPlayer.Character
})

region:listen()

while task.wait(1) do
	print(region:getInstancesInRegion())
end

isInstanceInRegion

</>
Region:isInstanceInRegion(instance: Instance) → boolean--

Returns true if the Instance is within the Region, false otherwise

Checks if the given Instance is within the Region.

This only applies to instances in the whitelist. If you call this function on an instance that is not whitelisted, it will always return false. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region:setWhitelist({
	workspace.Part
})

region:listen()

while task.wait(1) do
	print(region:isInstanceInRegion(workspace.Part))
end

listen

</>
Region:listen() → ()

Starts a Heartbeat connection to listen for instances in the whitelist colliding with the Region.

This method must be called before instances in the whitelist will be detected within the Region's boundaries. 

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region:setWhitelist({
	Players.LocalPlayer.Character
})

region:listen()

destroy

</>
Region:destroy() → ()

Destroys the Region, cleaning up any connections and destroying Instances that the Region relied on.

Note that this will destroy regionInstance.

local regionInstance = Instance.new("Part")
local region = Region.new(regionInstance)

region:setWhitelist({
	workspace.Part
})

region:listen()

-- Later...

region:destroy()

print(regionInstance.Parent) -- nil
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new Region instance.\n\nYou can either pass in a Model or a BasePart which will represent the\nRegion's boundaries in the Workspace.\n\nWhen using a Model, it must contain BaseParts as children.\n\nA Region's BaseParts are known as \"segments.\" Every Region must have at\nleast one segment, and when a segment is collided with by instances in the\nwhitelist certain events will be triggered.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n```",
            "params": [
                {
                    "name": "regionInstance",
                    "desc": "",
                    "lua_type": "RegionInstance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Region"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 89,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "is",
            "desc": "Static function for checking if the given argument is a Region instance or not.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nprint(Region.is(region)) -- true\nprint(Region.is(\"string\") -- false\n```",
            "params": [
                {
                    "name": "other",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "Returns `true` if `other` is a Region, `false` otherwise",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 124,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "setWhitelist",
            "desc": "Sets the instances that can collide with the Region and trigger events.\n\nThe whitelist must be defined or the Region will not respond to any instances.\n\n:::tip\nA common use case is to set the whitelist to all the Character models in the\nWorkspace. This allows you to setup a region system where your players can\nenter and leave specific zones.\n:::\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n\tPlayers.LocalPlayer.Character\n})\n```",
            "params": [
                {
                    "name": "whitelist",
                    "desc": "",
                    "lua_type": "{ Instance }"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 154,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "getRegionSegments",
            "desc": "Get all of the BaseParts that compose the Region's boundary.\n\n:::info\nIf you passed in a BasePart when constructing, this will return an array\nwith that BasePart as the only element. If you passed a Model, this will\nreturn an array with all BasePart descendants.\n:::\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nprint(region:getRegionSegments())\n```",
            "params": [],
            "returns": [
                {
                    "desc": "Returns all BaseParts that compose the Region",
                    "lua_type": "{ BasePart }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 178,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "getInstancesInRegion",
            "desc": "Gets all whitelisted Instances that are within the Region.\n\n:::tip\nThe below example uses a while loop to print out all whitelisted instances\nwithin the Region for illustrative purposes. Usually you will want to\nrespond to the `enter` and `left` events.\n:::\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n\tPlayers.LocalPlayer.Character\n})\n\nregion:listen()\n\nwhile task.wait(1) do\n\tprint(region:getInstancesInRegion())\nend\n```",
            "params": [],
            "returns": [
                {
                    "desc": "Array of whitelisted Instances that are within the Region",
                    "lua_type": "{ Instance }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 220,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "isInstanceInRegion",
            "desc": "Checks if the given Instance is within the Region.\n\nThis only applies to instances in the whitelist. If you call this function\non an instance that is not whitelisted, it will always return `false`.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n\tworkspace.Part\n})\n\nregion:listen()\n\nwhile task.wait(1) do\n\tprint(region:isInstanceInRegion(workspace.Part))\nend\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "Returns `true` if the Instance is within the Region, `false` otherwise",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 260,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "listen",
            "desc": "Starts a Heartbeat connection to listen for instances in the whitelist\ncolliding with the Region.\n\nThis method must be called before instances in the whitelist will be\ndetected within the Region's boundaries.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n\tPlayers.LocalPlayer.Character\n})\n\nregion:listen()\n```",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 288,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "destroy",
            "desc": "Destroys the Region, cleaning up any connections and destroying Instances that the Region relied on.\n\nNote that this _will_ destroy `regionInstance`.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n\tworkspace.Part\n})\n\nregion:listen()\n\n-- Later...\n\nregion:destroy()\n\nprint(regionInstance.Parent) -- nil\n```",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 328,
                "path": "src/Region.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "name",
            "desc": "The name of the Region. This is used when calling `tostring()` on the Region instance.\n\n(Default: \"Region\")",
            "lua_type": "string",
            "source": {
                "line": 27,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "instance",
            "desc": "A reference to the `regionInstance` argument pass when constructing",
            "lua_type": "RegionInstance",
            "source": {
                "line": 34,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "entered",
            "desc": "Fired when an instance in the whitelist enters the Region.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion.entered:Connect(function(instance: Instance)\n\tprint(instance, \"entered the region\")\nend)\n```",
            "lua_type": "RBXScriptSignal",
            "source": {
                "line": 50,
                "path": "src/Region.lua"
            }
        },
        {
            "name": "left",
            "desc": "Fired when an instance in the whitelist leaves the Region.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion.left:Connect(function(instance: Instance)\n\tprint(instance, \"left the region\")\nend)\n```",
            "lua_type": "RBXScriptSignal",
            "source": {
                "line": 68,
                "path": "src/Region.lua"
            }
        }
    ],
    "types": [
        {
            "name": "RegionInstance",
            "desc": "The 3D representation of the Region's boundaries. It can either be a single\nBasePart or a Model composed of several BaseParts that all represent one\nRegion.",
            "lua_type": "BasePart | Model",
            "source": {
                "line": 18,
                "path": "src/Region.lua"
            }
        }
    ],
    "name": "Region",
    "desc": "",
    "source": {
        "line": 6,
        "path": "src/Region.lua"
    }
}