Skip to main content

Straight

A Types.Pathfinder that only succeeds when the agent can walk straight to the target: a Spherecast the width of the body from from to to, and optionally a floor ray every few studs along the way. Meant as the first rung of a Ladder, so a target in plain sight costs no navmesh query.

Name is "Straight", which Ladder uses in its reasons.

Functions​

new​

</>
Straight.new(options: StraightOptions?) → Straight

Types

​

interface StraightOptions {
AgentRadius: number?--

Radius of the swept sphere, the agent's half width. Must be below AgentHeight / 2 or the sweep scrapes the floor. Default 2.

AgentHeight: number?--

The agent's height; the sweep runs AgentHeight / 2 above the floor. Default 5.

FloorCheck: boolean?--

Require floor under the segment and project the endpoints onto it. Default true.

FloorSpacing: number?--

Studs between floor samples along the segment, capped at AgentRadius so a gap the body could fall through is always sampled. Default 4, which with the default radius means a ray every 2 studs; a long straight leg costs that many rays per plan.

MaxDrop: number?--

Studs the floor may be below a sample, and below the previous sample's floor. Default 6.

AvoidSafeAreas: boolean?--

Refuse a line with any point inside an enabled SafeAreas area, checked every couple of studs a stud above the floor. Default true.

Ignore: ((agent: Agent) → {Instance})?--

Instances the casts pass through. Default: Straight.DefaultIgnore, the agent's entity and every player's character.

}

Errors

TypeDescription
"unknown option"A key that is not in `StraightOptions`.

Sample​

</>
Straight.Sample(
from: Vector3,
to: Vector3,
spacing: number--

Must be positive.

) → {Vector3}--

Points every spacing studs after from, ending with to itself.

The floor sample points along a segment. from is never included; to always is, exactly once, so a zero-length segment gives { to }. Pure.

Errors

TypeDescription
"spacing must be positive"

DefaultIgnore​

</>
Straight.DefaultIgnore(agent: Agent) → {Instance}--

The agent's entity (when it has one) and every player's character.

The default Ignore. Call it from your own Ignore to extend the list rather than replace it.

FindPath​

</>
Straight.FindPath(
self: Straight,
from: Vector3,--

Any height; the floor under it is used.

to: Vector3,--

Any height; the floor under it is used.

agent: Agent--

Handed to Ignore.

) → (
Path?,--

Two Walk steps, the floor positions under from and to, when the way is clear.

string?--

blocked by <full name> when the sweep hits or the body already overlaps something, no floor at <point> when a floor ray misses, floor drops <studs> at <point> when the floor falls more than MaxDrop between two samples.

)

Destroy​

</>
Straight.Destroy(self: Straight) → ()

Nothing to release; present so the pathfinder contract is complete.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "",
            "params": [
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "StraightOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Straight"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"unknown option\"",
                    "desc": "A key that is not in `StraightOptions`."
                }
            ],
            "source": {
                "line": 111,
                "path": "lib/Pathfinders/Straight.luau"
            }
        },
        {
            "name": "Sample",
            "desc": "The floor sample points along a segment. `from` is never included; `to` always is, exactly\nonce, so a zero-length segment gives `{ to }`. Pure.",
            "params": [
                {
                    "name": "from",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "to",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "spacing",
                    "desc": "Must be positive.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "Points every `spacing` studs after `from`, ending with `to` itself.",
                    "lua_type": "{ Vector3 }"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "\"spacing must be positive\"",
                    "desc": ""
                }
            ],
            "source": {
                "line": 142,
                "path": "lib/Pathfinders/Straight.luau"
            }
        },
        {
            "name": "DefaultIgnore",
            "desc": "The default `Ignore`. Call it from your own `Ignore` to extend the list rather than replace it.",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                }
            ],
            "returns": [
                {
                    "desc": "The agent's entity (when it has one) and every player's character.",
                    "lua_type": "{ Instance }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 172,
                "path": "lib/Pathfinders/Straight.luau"
            }
        },
        {
            "name": "FindPath",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Straight"
                },
                {
                    "name": "from",
                    "desc": "Any height; the floor under it is used.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "to",
                    "desc": "Any height; the floor under it is used.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "agent",
                    "desc": "Handed to `Ignore`.",
                    "lua_type": "Agent"
                }
            ],
            "returns": [
                {
                    "desc": "Two Walk steps, the floor positions under `from` and `to`, when the way is clear.",
                    "lua_type": "Path?"
                },
                {
                    "desc": "`blocked by <full name>` when the sweep hits or the body already overlaps something, `no floor at <point>` when a floor ray misses, `floor drops <studs> at <point>` when the floor falls more than `MaxDrop` between two samples.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 197,
                "path": "lib/Pathfinders/Straight.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Nothing to release; present so the pathfinder contract is complete.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Straight"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 314,
                "path": "lib/Pathfinders/Straight.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "StraightOptions",
            "desc": "",
            "fields": [
                {
                    "name": "AgentRadius",
                    "lua_type": "number?",
                    "desc": "Radius of the swept sphere, the agent's half width. Must be below `AgentHeight / 2` or the sweep scrapes the floor. Default `2`."
                },
                {
                    "name": "AgentHeight",
                    "lua_type": "number?",
                    "desc": "The agent's height; the sweep runs `AgentHeight / 2` above the floor. Default `5`."
                },
                {
                    "name": "FloorCheck",
                    "lua_type": "boolean?",
                    "desc": "Require floor under the segment and project the endpoints onto it. Default `true`."
                },
                {
                    "name": "FloorSpacing",
                    "lua_type": "number?",
                    "desc": "Studs between floor samples along the segment, capped at `AgentRadius` so a gap the body could fall through is always sampled. Default `4`, which with the default radius means a ray every 2 studs; a long straight leg costs that many rays per plan."
                },
                {
                    "name": "MaxDrop",
                    "lua_type": "number?",
                    "desc": "Studs the floor may be below a sample, and below the previous sample's floor. Default `6`."
                },
                {
                    "name": "AvoidSafeAreas",
                    "lua_type": "boolean?",
                    "desc": "Refuse a line with any point inside an enabled [SafeAreas] area, checked every couple of studs a stud above the floor. Default `true`."
                },
                {
                    "name": "Ignore",
                    "lua_type": "((agent: Agent) -> { Instance })?",
                    "desc": "Instances the casts pass through. Default: [Straight.DefaultIgnore], the agent's entity and every player's character."
                }
            ],
            "source": {
                "line": 61,
                "path": "lib/Pathfinders/Straight.luau"
            }
        }
    ],
    "name": "Straight",
    "desc": "A [Types.Pathfinder] that only succeeds when the agent can walk straight to the target: a\n`Spherecast` the width of the body from `from` to `to`, and optionally a floor ray every few\nstuds along the way. Meant as the first rung of a [Ladder], so a target in plain sight costs no\nnavmesh query.\n\n`Name` is `\"Straight\"`, which [Ladder] uses in its reasons.",
    "source": {
        "line": 104,
        "path": "lib/Pathfinders/Straight.luau"
    }
}