Skip to main content

Tree

Functions​

Find​

</>
Tree.Find(
parent: Instance,
path: string,
assertIsA: string?
) → Instance

Similar to FindFirstChild, with a few key differences:

  • An error is thrown if the instance is not found
  • A path to the instance can be provided, delimited by forward slashes (e.g. Path/To/Child)
  • Optionally, the instance's type can be asserted using IsA
-- Find "Child" directly under parent:
local instance = Tree.Find(parent, "Child")

-- Find "Child" descendant:
local instance = Tree.Find(parent, "Path/To/Child")

-- Find "Child" descendant and assert that it's a BasePart:
local instance = Tree.Find(parent, "Path/To/Child", "BasePart") :: BasePart

Exists​

</>
Tree.Exists(
parent: Instance,
path: string,
assertIsA: string?
) → boolean

Returns true if the instance is found. Similar to Tree.Find, except this returns true|false. No error is thrown unless the path is invalid.

-- Check if "Child" exists directly in `parent`:
if Tree.Exists(parent, "Child") then ... end

-- Check if "Child" descendant exists at `parent.Path.To.Child`:
if Tree.Exists(parent, "Path/To/Child") then ... end

-- Check if "Child" descendant exists at `parent.Path.To.Child` and is a BasePart:
if Tree.Exists(parent, "Path/To/Child", "BasePart") then ... end

Await​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
Tree.Await(
parent: Instance,
path: string,
timeout: number?,
assertIsA: string?
) → Instance

Waits for the path to exist within the parent instance. Similar to Tree.Find, except WaitForChild is used internally. An optional timeout can be supplied, which is passed along to each call to WaitForChild.

An error is thrown if the path fails to resolve. This will only happen if the path is invalid or if the supplied timeout is reached.

Indefinite Yield Possible

If the timeout parameter is not supplied, then the internal call to WaitForChild will yield indefinitely until the child is found. It is good practice to supply a timeout parameter. 

local child = Tree.Await(parent, "Path/To/Child", 30)
Show raw api
{
    "functions": [
        {
            "name": "Find",
            "desc": "Similar to FindFirstChild, with a few key differences:\n- An error is thrown if the instance is not found\n- A path to the instance can be provided, delimited by forward slashes (e.g. `Path/To/Child`)\n- Optionally, the instance's type can be asserted using `IsA`\n\n```lua\n-- Find \"Child\" directly under parent:\nlocal instance = Tree.Find(parent, \"Child\")\n\n-- Find \"Child\" descendant:\nlocal instance = Tree.Find(parent, \"Path/To/Child\")\n\n-- Find \"Child\" descendant and assert that it's a BasePart:\nlocal instance = Tree.Find(parent, \"Path/To/Child\", \"BasePart\") :: BasePart\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "path",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "assertIsA",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 29,
                "path": "modules/tree/init.luau"
            }
        },
        {
            "name": "Exists",
            "desc": "Returns `true` if the instance is found. Similar to `Tree.Find`, except this returns `true|false`. No error is thrown unless the path is invalid.\n\n```lua\n-- Check if \"Child\" exists directly in `parent`:\nif Tree.Exists(parent, \"Child\") then ... end\n\n-- Check if \"Child\" descendant exists at `parent.Path.To.Child`:\nif Tree.Exists(parent, \"Path/To/Child\") then ... end\n\n-- Check if \"Child\" descendant exists at `parent.Path.To.Child` and is a BasePart:\nif Tree.Exists(parent, \"Path/To/Child\", \"BasePart\") then ... end\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "path",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "assertIsA",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 69,
                "path": "modules/tree/init.luau"
            }
        },
        {
            "name": "Await",
            "desc": "Waits for the path to exist within the parent instance. Similar to `Tree.Find`, except `WaitForChild`\nis used internally. An optional `timeout` can be supplied, which is passed along to each call to\n`WaitForChild`.\n\nAn error is thrown if the path fails to resolve. This will only happen if the path is invalid _or_ if\nthe supplied timeout is reached.\n\n:::caution Indefinite Yield Possible\nIf the `timeout` parameter is not supplied, then the internal call to `WaitForChild` will yield\nindefinitely until the child is found. It is good practice to supply a timeout parameter.\n:::\n\n```lua\nlocal child = Tree.Await(parent, \"Path/To/Child\", 30)\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "path",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "timeout",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "assertIsA",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance\n"
                }
            ],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 111,
                "path": "modules/tree/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Tree",
    "desc": "",
    "source": {
        "line": 10,
        "path": "modules/tree/init.luau"
    }
}