Skip to main content

CFrameMover

A Types.Mover that steps a pivot with PivotTo, for anchored parts, rigless models and agents that only exist as a position on the server. Exposed as VluxyAI.Movers.CFrame. Each Heartbeat it moves toward the current step at Speed and turns its yaw toward the direction of travel at TurnSpeed; pitch and roll are dropped, so the pivot stays upright.

Follows the two mover rules: Follow fires Arrived(false) for the path it replaces before starting the new one, and the new path is only ever reported from a later Heartbeat.

Types​

MoverNoise​

</>
interface MoverNoise {
Signal: NoiseSignal--

The noise signal a Hearing sense listens to. Fired with the rig as its source.

Interval: number?--

Seconds between noises while moving. Default 0.5.

Loudness: number | (speed: number) → number?--

The loudness fired, or a function of the current speed. Default 1.

}

Functions​

Advance​

</>
CFrameMover.Advance(
pivot: CFrame,--

Where the thing is now.

target: Vector3,--

Where it is going.

speed: number,--

Studs per second.

turnSpeed: number,--

Radians per second of yaw.

deltaTime: number--

Seconds since the last call.

) → (
CFrame,--

The new pivot: moved by at most speed * deltaTime, yaw turned by at most turnSpeed * deltaTime, upright.

boolean--

true when the new pivot sits on target.

)

One frame of movement, as a pure function. Moves straight toward target without overshooting and lands exactly on it when it is within reach. Turns the yaw toward the horizontal direction of travel by the shortest way; pitch and roll in pivot are discarded. A zero-length or purely vertical move keeps the current facing.

new​

</>
CFrameMover.new(
target: PVInstance,--

Anything with GetPivot and PivotTo: a Model or a BasePart.

) → CFrameMover

Types

​

interface CFrameMoverOptions {
Speed: number?--

Studs per second. Default 8.

TurnSpeed: number?--

Radians per second of yaw. Default 10.

HeightOffset: number?--

Added to every step's Y, so a body rides above floor steps. A number is used as given; leave it out and the first Follow measures the pivot's height above the first step (never below 0) and keeps that for the life of the mover. Default: measured.

StepDistance: number?--

Horizontal distance to a step that counts as reached. Default 0.25.

StuckTimeout: number?--

Seconds without getting closer to the current step before giving up with Arrived(false). Default 5. Progress under 0.05 studs per check does not count, so speeds below about 0.01 studs per second read as stuck.

Noise: MoverNoise?--

Fire a Hearing noise signal every Interval seconds while walking, so other agents hear this one coming. Off by default.

Manual: boolean?--

No Heartbeat: the mover only moves when its Step(deltaTime) is called, which Agent:Step does for you. For agents stepped by your own scheduler. Default false.

}

Errors

TypeDescription
string`target` has no `GetPivot`.
"unknown option"A key that is not in `CFrameMoverOptions`.

Follow​

</>
CFrameMover.Follow(
self: CFrameMover,
path: Path
) → ()

Starts along path, replacing any current one. The replaced path gets Arrived(false) before the new one starts; the new one is only ever reported from a later Heartbeat. An empty path is reported as Arrived(false) on the next Heartbeat.

Without a HeightOffset option, the first non-empty path measures it: the pivot's height above path[1], never below 0, kept from then on.

Stop​

</>
CFrameMover.Stop(self: CFrameMover) → ()

Halts where it is. Fires Arrived(false) if a path was in progress.

Face​

</>
CFrameMover.Face(
self: CFrameMover,
position: Vector3?--

Where to face; nil to stop.

) → ()

Turns the yaw toward position at TurnSpeed every Heartbeat while no path is in progress, through Advance with a speed of zero. A path takes over while it runs; the facing resumes when it ends.

SetNudge​

</>
CFrameMover.SetNudge(
self: CFrameMover,
offset: Vector3?--

Added to every step but the last; nil clears.

) → ()

A sideways push from a steering sense such as Neighbours. Takes effect on the next Heartbeat.

Teleport​

</>
CFrameMover.Teleport(
self: CFrameMover,
position: Vector3--

Where the pivot goes.

) → ()

Drops the current path (Arrived(false) if one was in progress) and moves the pivot to position, keeping its facing.

GetPosition​

</>
CFrameMover.GetPosition(self: CFrameMover) → Vector3--

The pivot's position.

GetPivot​

</>
CFrameMover.GetPivot(self: CFrameMover) → CFrame--

The pivot: position and yaw. What Agent:GetPivot reads on an agent with no entity.

GetSpeed​

</>
CFrameMover.GetSpeed(self: CFrameMover) → number--

Studs per second.

SetSpeed​

</>
CFrameMover.SetSpeed(
self: CFrameMover,
studsPerSecond: number
) → ()

IsMoving​

</>
CFrameMover.IsMoving(self: CFrameMover) → boolean--

true while a path is in progress.

Destroy​

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

Stops, then drops the signals. The target instance is left alone; it is yours.

Show raw api
{
    "functions": [
        {
            "name": "Advance",
            "desc": "One frame of movement, as a pure function. Moves straight toward `target` without overshooting\nand lands exactly on it when it is within reach. Turns the yaw toward the horizontal direction\nof travel by the shortest way; pitch and roll in `pivot` are discarded. A zero-length or purely\nvertical move keeps the current facing.",
            "params": [
                {
                    "name": "pivot",
                    "desc": "Where the thing is now.",
                    "lua_type": "CFrame"
                },
                {
                    "name": "target",
                    "desc": "Where it is going.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "speed",
                    "desc": "Studs per second.",
                    "lua_type": "number"
                },
                {
                    "name": "turnSpeed",
                    "desc": "Radians per second of yaw.",
                    "lua_type": "number"
                },
                {
                    "name": "deltaTime",
                    "desc": "Seconds since the last call.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The new pivot: moved by at most `speed * deltaTime`, yaw turned by at most `turnSpeed * deltaTime`, upright.",
                    "lua_type": "CFrame"
                },
                {
                    "desc": "`true` when the new pivot sits on `target`.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 185,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "new",
            "desc": "",
            "params": [
                {
                    "name": "target",
                    "desc": "Anything with `GetPivot` and `PivotTo`: a Model or a BasePart.",
                    "lua_type": "PVInstance"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "CFrameMoverOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "`target` has no `GetPivot`."
                },
                {
                    "lua_type": "\"unknown option\"",
                    "desc": "A key that is not in `CFrameMoverOptions`."
                }
            ],
            "source": {
                "line": 236,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "Follow",
            "desc": "Starts along `path`, replacing any current one. The replaced path gets `Arrived(false)` before\nthe new one starts; the new one is only ever reported from a later Heartbeat. An empty path is\nreported as `Arrived(false)` on the next Heartbeat.\n\nWithout a `HeightOffset` option, the first non-empty path measures it: the pivot's height above\n`path[1]`, never below `0`, kept from then on.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                },
                {
                    "name": "path",
                    "desc": "",
                    "lua_type": "Path"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 438,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "Halts where it is. Fires `Arrived(false)` if a path was in progress.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 470,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "Face",
            "desc": "Turns the yaw toward `position` at `TurnSpeed` every Heartbeat while no path is in progress,\nthrough `Advance` with a speed of zero. A path takes over while it runs; the facing resumes\nwhen it ends.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                },
                {
                    "name": "position",
                    "desc": "Where to face; `nil` to stop.",
                    "lua_type": "Vector3?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 482,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "SetNudge",
            "desc": "A sideways push from a steering sense such as [Neighbours]. Takes effect on the next\nHeartbeat.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                },
                {
                    "name": "offset",
                    "desc": "Added to every step but the last; `nil` clears.",
                    "lua_type": "Vector3?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 502,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "Teleport",
            "desc": "Drops the current path (`Arrived(false)` if one was in progress) and moves the pivot to\n`position`, keeping its facing.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                },
                {
                    "name": "position",
                    "desc": "Where the pivot goes.",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 513,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "GetPosition",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [
                {
                    "desc": "The pivot's position.",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 524,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "GetPivot",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [
                {
                    "desc": "The pivot: position and yaw. What [Agent:GetPivot] reads on an agent with no entity.",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 532,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "GetSpeed",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [
                {
                    "desc": "Studs per second.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 540,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "SetSpeed",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                },
                {
                    "name": "studsPerSecond",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 548,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "IsMoving",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [
                {
                    "desc": "`true` while a path is in progress.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 559,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Stops, then drops the signals. The target instance is left alone; it is yours.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "CFrameMover"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 568,
                "path": "lib/Movers/CFrameMover.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "CFrameMoverOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Speed",
                    "lua_type": "number?",
                    "desc": "Studs per second. Default `8`."
                },
                {
                    "name": "TurnSpeed",
                    "lua_type": "number?",
                    "desc": "Radians per second of yaw. Default `10`."
                },
                {
                    "name": "HeightOffset",
                    "lua_type": "number?",
                    "desc": "Added to every step's Y, so a body rides above floor steps. A number is used as given; leave it out and the first `Follow` measures the pivot's height above the first step (never below `0`) and keeps that for the life of the mover. Default: measured."
                },
                {
                    "name": "StepDistance",
                    "lua_type": "number?",
                    "desc": "Horizontal distance to a step that counts as reached. Default `0.25`."
                },
                {
                    "name": "StuckTimeout",
                    "lua_type": "number?",
                    "desc": "Seconds without getting closer to the current step before giving up with `Arrived(false)`. Default `5`. Progress under 0.05 studs per check does not count, so speeds below about 0.01 studs per second read as stuck."
                },
                {
                    "name": "Noise",
                    "lua_type": "MoverNoise?",
                    "desc": "Fire a [Hearing] noise signal every `Interval` seconds while walking, so other agents hear this one coming. Off by default."
                },
                {
                    "name": "Manual",
                    "lua_type": "boolean?",
                    "desc": "No Heartbeat: the mover only moves when its `Step(deltaTime)` is called, which [Agent:Step] does for you. For agents stepped by your own scheduler. Default `false`."
                }
            ],
            "source": {
                "line": 107,
                "path": "lib/Movers/CFrameMover.luau"
            }
        },
        {
            "name": "MoverNoise",
            "desc": "",
            "fields": [
                {
                    "name": "Signal",
                    "lua_type": "NoiseSignal",
                    "desc": "The noise signal a [Hearing] sense listens to. Fired with the rig as its source."
                },
                {
                    "name": "Interval",
                    "lua_type": "number?",
                    "desc": "Seconds between noises while moving. Default `0.5`."
                },
                {
                    "name": "Loudness",
                    "lua_type": "number | (speed: number) -> number?",
                    "desc": "The loudness fired, or a function of the current speed. Default `1`."
                }
            ],
            "source": {
                "line": 115,
                "path": "lib/Movers/CFrameMover.luau"
            }
        }
    ],
    "name": "CFrameMover",
    "desc": "A [Types.Mover] that steps a pivot with `PivotTo`, for anchored parts, rigless models and\nagents that only exist as a position on the server. Exposed as `VluxyAI.Movers.CFrame`.\nEach Heartbeat it moves toward the current step at `Speed` and turns its yaw toward the\ndirection of travel at `TurnSpeed`; pitch and roll are dropped, so the pivot stays upright.\n\nFollows the two mover rules: `Follow` fires `Arrived(false)` for the path it replaces before\nstarting the new one, and the new path is only ever reported from a later Heartbeat.",
    "source": {
        "line": 142,
        "path": "lib/Movers/CFrameMover.luau"
    }
}