{"id":"vocksel/complex-regions","name":"complex-regions","scope":"vocksel","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"4554915e55d22a7e2a253d9bba3848ecec66b59c78df8065adf769d071dfbc7d","likes":0,"downloads":0,"install":"forest install vocksel/complex-regions","url":"https://forest.dev/p/roblox/vocksel/complex-regions","files":"https://api.forest.dev/ai/package/roblox/vocksel/complex-regions/files","readme":"# ComplexRegions\n\n[![CI](https://github.com/vocksel/complex-regions/actions/workflows/ci.yml/badge.svg)](https://github.com/vocksel/complex-regions/actions/workflows/ci.yml)\n\nThis is a package that allows you to define regions in an experience out of BaseParts of any shape or size.\n\n![A character within a region composed of rectangles and a sphere](example/example.png)\n\n## Installation\n\n### Wally\n\nIf you are using [Wally](https://github.com/UpliftGames/wally), add the following to your `wally.toml` and run `wally install` to get a copy of the package.\n\n```\n[dependencies]\nComplexRegions = \"vocksel/complex-regions@0.1.0\n```\n\n### Roblox Studio\n\n* Download a copy of the rbxm from the [releases page](https://github.com/vocksel/complex-regions/releases/latest) under the Assets section. \n* Drag and drop the file into Roblox Studio to add it to your experience.\n\n## Creating a Region\n\nA region can be a singular BasePart instance, or a Model/Folder containing several BaseParts that make up the region. The latter is where this package shines.\n\nTo create a region add a new Model into the Workspace, rename it to Region, and add some Parts inside of it. Make sure to set `CanCollide = false` for each Part so that other instances can enter the region.\n\nNext, create a new LocalScript in StarterPlayerScripts with the following contents:\n\n```lua\nlocal Players = game:GetService(\"Players\")\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\n\nlocal ComplexRegions = require(ReplicatedStorage.Packages.ComplexRegions)\n\nlocal region = ComplexRegions.Region.new(workspace.Region)\n\n-- The whitelist determines which instances can interact with the region. In\n-- this case, we will respond when our Character enters.\nregion:setWhitelist({\n    Players.LocalPlayer.Character\n})\n\n-- This starts up a Heartbeat connection and is required for the region to\n-- respond to instances in the whitelist entering and leaving.\nregion:listen()\n\nregion.entered:Connect(function(character: Model)\n    print(character, \"entered\", region)\nend)\n\nregion.left:Connect(function(character: Model)\n    print(character, \"left\", region)\nend)\n```\n\nNow when you start the experience and walk in and out of the region messages will print in the output.\n\n## API\n\n`createRegion(regionInstance: Model | BasePart, whitelist: { Instance }): Region`\n\nThis is a helper function that will create a Region, set its whitelist, and also listen for instances entering and leaving.\n\nUsage:\n\n```lua\nlocal region = ComplexRegions.createRegion(workspace.Region, {\n    Players.LocalPlayer.Character\n})\n\nregion.entered:Connect(function(instance: Instance)\n    print(instance, \"entered the region\")\nend)\n\nregion.left:Connect(function(instance: Instance)\n    print(instance, \"left the region\")\nend)\n```\n\n### Region\n\n**`Region.new(regionInstance: Model | BasePart): Region`**\n\nCreates a new Region where `regionInstance` represents the boundaries of the Region.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n```\n\n**`Region.is(other: any): boolean`**\n\nChecks if the given argument is a Region instance or not.\n\nUsage:\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```\n\n**`Region.name: string = \"Region\"`**\n\nThe name of the Region. This is used when calling `tostring()` on the Region instance.\n\n**`Region.instance: Model | BasePart`**\n\nReference to the `regionInstance` that was passed in when constructing.\n\n**`Region:setWhitelist(whitelist: { Instance }): nil`**\n\nSets the list of instances that can trigger the Region's `entered` and `left` events.\n\nThe whitelist must be defined, or else the Region will not respond to any instances.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n    Players.LocalPlayer.Character\n})\n```\n\n**`Region:listen(): nil`**\n\nStarts a Heartbeat connection to listen for instances in the whitelist entering and leaving the Region.\n\nThis method must be called before instances in the whitelist will be detected within the Region's boundaries.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n    Players.LocalPlayer.Character\n})\n\nregion:listen()\n```\n\n**`Region:getRegionSegments(): { BasePart }`**\n\nReturns an array of all BaseParts that compose the Region.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nprint(region:getRegionSegments())\n```\n\n**`Region:getInstancesInRegion(): { Instance }`**\n\nReturns an array of all Instances that are currently within the Region. This only applies to instances in the whitelist.\n\nUsage:\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n    Players.LocalPlayer.Character\n})\n\nregion:listen()\n\nwhile task.wait(1) do\n    print(region:getInstancesInRegion())\nend\n```\n\n**`Region:isInstanceInRegion(instance: Instance): boolean`**\n\nChecks if the given Instance is within the Region's boundaries. This only applies to instances in the whitelist.\n\n```lua\nlocal regionInstance = Instance.new(\"Part\")\nlocal region = Region.new(regionInstance)\n\nregion:setWhitelist({\n    workspace.Part\n})\n\nregion:listen()\n\nwhile task.wait(1) do\n    print(region:isInstanceInRegion(workspace.Part))\nend\n```\n\n**`Region:destroy(): nil`**\n\nDestroys 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    workspace.Part\n})\n\nregion:listen()\n\n-- Later...\n\nregion:destroy()\n\nprint(regionInstance.Parent) -- nil\n```\n\n**`Region.entered(instance: Instance): RBXScriptConnection`**\n\nFired when an instance in the whitelist enters the Region.\n\nUsage:\n\n```lua\nlocal region = Region.new(workspace.Region)\n\nregion.entered:Connect(function(instance: Instance)\n    print(instance, \"entered the region\")\nend)\n```\n\n**`Region.left(instance: Instance): RBXScriptConnection`**\n\nFired when an instance in the whitelist leaves the Region.\n\nUsage:\n\n```lua\nlocal region = Region.new(workspace.Region)\n\nregion.left:Connect(function(instance: Instance)\n    print(instance, \"left the region\")\nend)\n```\n\n## Contributing\n\nSee the [contributing guide](CONTRIBUTING.md).\n\n## License\n\n[MIT License](LICENSE)","readmeTruncated":false}