Skip to main content

CFrameUtils

Useful utility functions involving CFrame values.

Functions​

lookAt​

</>
CFrameUtils.lookAt(
position: Vector3,
target: Vector3,
upVector: Vector3?--

Optional, defaults to (0, 1, 0)

) → CFrame

Makes a CFrame look at a position and target with bias towards the upVector. 

-- orient a hypothetical gun such that it's relative to the root part's upVector
local gunCFrame = CFrameUtils.lookAt(gunPos, gunTarget, rootPart.CFrame.upVector)

redirectLocalAxis​

</>
CFrameUtils.redirectLocalAxis(
cframe: CFrame,
localAxis: Vector3,
worldGoal: Vector3
) → CFrame

Returns a CFrame which is minimally rotated from cframe such that the following condition is true: 

returnedCFrame:VectorToWorldSpace(localAxis) = worldGoal

-- Redirects an axis from world space up, to a spawn block's up vector
-- so we could spawn something there.
cframe = CFrameUtils.redirectLocalAxis(cframe, Vector3.new(0, 1, 0), spawnBlock.CFrame.upVector)
tip

This returns cframe in the scenario where the localAxis is already oriented in exactly the direction as the other option (i.e. it's ambiguous)

axisAngleToCFrame​

</>
CFrameUtils.axisAngleToCFrame(
axisAngle: Vector3,
position: Vector3 | nil
) → CFrame

Returns a CFrame from an axis angle, handling NaN values

fromUpRight​

</>
CFrameUtils.fromUpRight(
position: Vector3,
upVector: Vector3,
rightVector: Vector3
) → CFrame?

Constructs a CFrame from a position, upVector, and rightVector even if these upVector and rightVectors are not orthogonal to each other.

note

upVector and rightVector do not need to be orthogonal. However, if they are parallel, this function returns nil.

Always check to ensure that the value returned is reasonable before continuing.

scalePosition​

</>
CFrameUtils.scalePosition(
cframe: CFrame,
scale: number
) → CFrame

Scales just the positional part of a CFrame.

mirror​

</>
CFrameUtils.mirror(
cframe: CFrame,
point: Vector3?,
normal: Vector3?
) → CFrame

Reflects the CFrame over the given axis

areClose​

</>
CFrameUtils.areClose(
a: CFrame,
b: CFrame,
epsilon: number
) → boolean

Fuzzy comparison between 2 CFrames

Show raw api
{
    "functions": [
        {
            "name": "lookAt",
            "desc": "Makes a CFrame look at a position and target with bias towards the\nupVector.\n\n```lua\n-- orient a hypothetical gun such that it's relative to the root part's upVector\nlocal gunCFrame = CFrameUtils.lookAt(gunPos, gunTarget, rootPart.CFrame.upVector)\n```",
            "params": [
                {
                    "name": "position",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "target",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "upVector",
                    "desc": "Optional, defaults to (0, 1, 0)",
                    "lua_type": "Vector3?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 22,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "redirectLocalAxis",
            "desc": "Returns a CFrame which is minimally rotated from cframe such that\nthe following condition is true:\n\n```\nreturnedCFrame:VectorToWorldSpace(localAxis) = worldGoal\n```\n\n```lua\n-- Redirects an axis from world space up, to a spawn block's up vector\n-- so we could spawn something there.\ncframe = CFrameUtils.redirectLocalAxis(cframe, Vector3.new(0, 1, 0), spawnBlock.CFrame.upVector)\n```\n\n:::tip\nThis returns cframe in the scenario where the localAxis is already oriented in exactly the direction as the other\noption (i.e. it's ambiguous)\n:::",
            "params": [
                {
                    "name": "cframe",
                    "desc": "",
                    "lua_type": "CFrame"
                },
                {
                    "name": "localAxis",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "worldGoal",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 89,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "axisAngleToCFrame",
            "desc": "Returns a CFrame from an axis angle, handling NaN values",
            "params": [
                {
                    "name": "axisAngle",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "position",
                    "desc": "",
                    "lua_type": "Vector3 | nil"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 112,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "fromUpRight",
            "desc": "Constructs a CFrame from a position, upVector, and rightVector\neven if these upVector and rightVectors are not orthogonal to\neach other.\n\n:::note\nupVector and rightVector do not need to be orthogonal.\nHowever, if they are parallel, this function returns\nnil.\n\nAlways check to ensure that the value returned is reasonable\nbefore continuing.\n:::",
            "params": [
                {
                    "name": "position",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "upVector",
                    "desc": "",
                    "lua_type": "Vector3"
                },
                {
                    "name": "rightVector",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 151,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "scalePosition",
            "desc": "Scales just the positional part of a CFrame.",
            "params": [
                {
                    "name": "cframe",
                    "desc": "",
                    "lua_type": "CFrame"
                },
                {
                    "name": "scale",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 170,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "mirror",
            "desc": "Reflects the CFrame over the given axis",
            "params": [
                {
                    "name": "cframe",
                    "desc": "",
                    "lua_type": "CFrame"
                },
                {
                    "name": "point",
                    "desc": "",
                    "lua_type": "Vector3?"
                },
                {
                    "name": "normal",
                    "desc": "",
                    "lua_type": "Vector3?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CFrame"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 191,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        },
        {
            "name": "areClose",
            "desc": "Fuzzy comparison between 2 CFrames",
            "params": [
                {
                    "name": "a",
                    "desc": "",
                    "lua_type": "CFrame"
                },
                {
                    "name": "b",
                    "desc": "",
                    "lua_type": "CFrame"
                },
                {
                    "name": "epsilon",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 212,
                "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "CFrameUtils",
    "desc": "Useful utility functions involving CFrame values.",
    "source": {
        "line": 5,
        "path": "src/cframeutils/src/Shared/CFrameUtils.lua"
    }
}