Skip to main content

CharacterUtils

A set of utility functions for working with characters.

Functions​

GetCharacter​

</>
CharacterUtils:GetCharacter(
player: Player | string,--

The player to get the character of or the name of the player

shouldYield: boolean?--

Whether or not to yield until the character exists (will still return nil if the player leaves the game)

) → Model?--

The character of the player if it exists

Get the character of a player and optionally yield until it exists

GetLocalCharacter​

This item only works when running on the client. Client
</>
CharacterUtils:GetLocalCharacter(
shouldYield: boolean?--

Whether or not to yield until the character exists

) → Model?--

The character of the local player if it exists

Get the character of the local player and optionally yield until it exists

GetAllCharacters​

</>
CharacterUtils:GetAllCharacters() → {Model}--

The characters of all players

Get all characters of players

GetAllNonLocalCharacters​

This item only works when running on the client. Client
</>
CharacterUtils:GetAllNonLocalCharacters() → {Model}--

The characters of all players

Get all characters of players

OnCharacterSpawned​

</>
CharacterUtils:OnCharacterSpawned(
player: Player,--

The player to add the callback for

callback: function,--

The callback to run when the player spawns

callbackName: string,--

The name of the callback to add (optional)

priority: number?--

The priority of the callback, lower numbers run first (optional, defaults to 0)

) → ()

Add a callback for when the player spawns and provide a maid for cleaning up any connections or running functions when the player dies.

This will run the callback immediately if the player is already spawned.

OnAnyCharacterSpawned​

</>
CharacterUtils:OnAnyCharacterSpawned(
callback: (
character: Model,
characterMaid: Maid,
player: Player
) → (),
callbackName: string?,--

The name of the callback to add (optional)

priority: number?
) → ()

Adds a callback for any player, existing and future, that spawns.

OnLocalCharacterSpawned​

This item only works when running on the client. Client
</>
CharacterUtils:OnLocalCharacterSpawned(
callback: function(character: Model,characterMaid: Maid) → (),--

The callback to run when the player spawns

callbackName: string?,--

The name of the callback to add (optional)

priority: number?
) → ()

Add a callback for when the local player spawns and provide a maid for cleaning up any connections or running functions when the player dies.

RemoveOnSpawnedCallback​

</>
CharacterUtils:RemoveOnSpawnedCallback(
player: Player,--

The player to remove the callback for

callbackName: string--

The name of the callback to remove

) → ()

Remove a callback for when the player spawns

RemoveLocalOnSpawnedCallback​

This item only works when running on the client. Client
</>
CharacterUtils:RemoveLocalOnSpawnedCallback(
callbackName: string--

The name of the callback to remove

) → ()

Remove a callback for when the local player spawns

RemoveOnAnySpawnedCallback​

</>
CharacterUtils:RemoveOnAnySpawnedCallback(
callbackName: string--

The name of the callback to remove

) → ()

Remove a callback for all players when they spawn, future and existing

RemoveAllCallbacksForPlayer​

</>
CharacterUtils:RemoveAllCallbacksForPlayer(
player: Player--

The player to remove the callbacks for

) → ()

Remove all callbacks for when the player spawns

RemoveAllLocalCallbacks​

This item only works when running on the client. Client
</>
CharacterUtils:RemoveAllLocalCallbacks() → ()

Remove all callbacks for when the local player spawns

GetCharacterMaid​

</>
CharacterUtils:GetCharacterMaid(
player: Player--

The player to get the CharacterMaid for

) → table--

The CharacterMaid for the player

Get the maid for the player's character

GetLocalCharacterMaid​

This item only works when running on the client. Client
</>
CharacterUtils:GetLocalCharacterMaid() → table--

The CharacterMaid for the local player

Get the maid for the local player's character

GetChildFromCharacter​

</>
CharacterUtils:GetChildFromCharacter(
player: Model | Player,--

The player to get the child from or alternatively their character

childName: stringThenameofthechildtoget,
shouldYield: boolean?
) → Instance?InstanceThechildifitexists

Retrieves a child from a player's character

GetChildFromLocalCharacter​

This item only works when running on the client. Client
</>
CharacterUtils:GetChildFromLocalCharacter(
childName: string,--

The name of the child to get

shouldYield: boolean?
) → Instance?--

The child if it exists

Retrieves a child from the local player's character

PlayAnimationOnCharacter​

</>
CharacterUtils:PlayAnimationOnCharacter(
character: Model | Player,--

The character to play the animation on (can pass a player to play the animation on their character)

animationId: string | number,--

The id of the animation to play, can be a string or number

animTrackOptions: table?,--

The options to pass to the animation track on play as well as whether or not to cache the animation track

shouldYield: boolean?--

Whether or not to yield until the character exists

) → AnimationTrack?--

The animation track if it was successfully played

Plays an animation on a character

PlayAnimationOnLocalCharacter​

This item only works when running on the client. Client
</>
CharacterUtils:PlayAnimationOnLocalCharacter(
animationId: string | number,--

The id of the animation to play, can be a string or number

animTrackOptions: table?,--

The options to pass to the animation track on play as well as whether or not to cache the animation track

shouldYield: boolean?--

Whether or not to yield until the character exists

) → AnimationTrack?--

The animation track if it was successfully played

Plays an animation on the local player's character

Example:

local animationTrack = CharacterUtils:PlayAnimationOnLocalCharacter("rbxassetid://1234567890", {
	fadeTime = 0.1,
	weight = 1,
	speed = 1,
	shouldNotCache = false,
}, true)

GetCharacterFromPart​

</>
CharacterUtils:GetCharacterFromPart(
part: BasePart--

The part to get the character from

) → Model?--

The character if one exists

Gets the character from a part if one exists. Will also return NPCs.

Show raw api
{
    "functions": [
        {
            "name": "GetCharacter",
            "desc": "Get the character of a player and optionally yield until it exists",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to get the character of or the name of the player",
                    "lua_type": "Player | string"
                },
                {
                    "name": "shouldYield",
                    "desc": "Whether or not to yield until the character exists (will still return nil if the player leaves the game)",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The character of the player if it exists",
                    "lua_type": "Model?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 245,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetLocalCharacter",
            "desc": "Get the character of the local player and optionally yield until it exists",
            "params": [
                {
                    "name": "shouldYield",
                    "desc": "Whether or not to yield until the character exists",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The character of the local player if it exists",
                    "lua_type": "Model?"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 281,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetAllCharacters",
            "desc": "Get all characters of players",
            "params": [],
            "returns": [
                {
                    "desc": "The characters of all players",
                    "lua_type": "{Model}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 296,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetAllNonLocalCharacters",
            "desc": "Get all characters of players",
            "params": [],
            "returns": [
                {
                    "desc": "The characters of all players",
                    "lua_type": "{Model}"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 316,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "OnCharacterSpawned",
            "desc": "Add a callback for when the player spawns and provide a maid for\ncleaning up any connections or running functions when the player dies.\n\nThis will run the callback immediately if the player is already spawned.",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to add the callback for",
                    "lua_type": "Player"
                },
                {
                    "name": "callback",
                    "desc": "The callback to run when the player spawns",
                    "lua_type": "function"
                },
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to add (optional)",
                    "lua_type": "string"
                },
                {
                    "name": "priority",
                    "desc": "The priority of the callback, lower numbers run first (optional, defaults to 0)",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 345,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "OnAnyCharacterSpawned",
            "desc": "Adds a callback for any player, existing and future, that spawns.",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(character: Model, characterMaid: Maid, player: Player) -> ()"
                },
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to add (optional)",
                    "lua_type": "string?"
                },
                {
                    "name": "priority",
                    "desc": "",
                    "lua_type": "number?\n"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 390,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "OnLocalCharacterSpawned",
            "desc": "Add a callback for when the local player spawns and provide a maid for\ncleaning up any connections or running functions when the player dies.",
            "params": [
                {
                    "name": "callback",
                    "desc": "The callback to run when the player spawns",
                    "lua_type": "function(character: Model, characterMaid: Maid) -> ()"
                },
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to add (optional)",
                    "lua_type": "string?"
                },
                {
                    "name": "priority",
                    "desc": "",
                    "lua_type": "number?\n"
                }
            ],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 421,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "RemoveOnSpawnedCallback",
            "desc": "Remove a callback for when the player spawns",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to remove the callback for",
                    "lua_type": "Player"
                },
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to remove",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 442,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "RemoveLocalOnSpawnedCallback",
            "desc": "Remove a callback for when the local player spawns",
            "params": [
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to remove",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 470,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "RemoveOnAnySpawnedCallback",
            "desc": "Remove a callback for all players when they spawn, future and existing",
            "params": [
                {
                    "name": "callbackName",
                    "desc": "The name of the callback to remove",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 485,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "RemoveAllCallbacksForPlayer",
            "desc": "Remove all callbacks for when the player spawns",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to remove the callbacks for",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 501,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "RemoveAllLocalCallbacks",
            "desc": "Remove all callbacks for when the local player spawns",
            "params": [],
            "returns": [],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 509,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetCharacterMaid",
            "desc": "Get the maid for the player's character",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to get the CharacterMaid for",
                    "lua_type": "Player"
                }
            ],
            "returns": [
                {
                    "desc": "The CharacterMaid for the player",
                    "lua_type": "table"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 526,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetLocalCharacterMaid",
            "desc": "Get the maid for the local player's character",
            "params": [],
            "returns": [
                {
                    "desc": "The CharacterMaid for the local player",
                    "lua_type": "table"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 545,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetChildFromCharacter",
            "desc": "Retrieves a child from a player's character",
            "params": [
                {
                    "name": "player",
                    "desc": "The player to get the child from or alternatively their character",
                    "lua_type": "Model | Player"
                },
                {
                    "name": "childName",
                    "desc": "",
                    "lua_type": "string The name of the child to get"
                },
                {
                    "name": "shouldYield",
                    "desc": "",
                    "lua_type": "boolean?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance? Instance The child if it exists"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 562,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetChildFromLocalCharacter",
            "desc": "Retrieves a child from the local player's character",
            "params": [
                {
                    "name": "childName",
                    "desc": "The name of the child to get",
                    "lua_type": "string"
                },
                {
                    "name": "shouldYield",
                    "desc": "",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The child if it exists",
                    "lua_type": "Instance?"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 590,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "PlayAnimationOnCharacter",
            "desc": "Plays an animation on a character",
            "params": [
                {
                    "name": "character",
                    "desc": "The character to play the animation on (can pass a player to play the animation on their character)",
                    "lua_type": "Model | Player"
                },
                {
                    "name": "animationId",
                    "desc": "The id of the animation to play, can be a string or number",
                    "lua_type": "string | number"
                },
                {
                    "name": "animTrackOptions",
                    "desc": "The options to pass to the animation track on play as well as whether or not to cache the animation track",
                    "lua_type": "table?"
                },
                {
                    "name": "shouldYield",
                    "desc": "Whether or not to yield until the character exists",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The animation track if it was successfully played",
                    "lua_type": "AnimationTrack?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 609,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "PlayAnimationOnLocalCharacter",
            "desc": "Plays an animation on the local player's character\n\nExample:\n```lua\nlocal animationTrack = CharacterUtils:PlayAnimationOnLocalCharacter(\"rbxassetid://1234567890\", {\n\tfadeTime = 0.1,\n\tweight = 1,\n\tspeed = 1,\n\tshouldNotCache = false,\n}, true)\n```",
            "params": [
                {
                    "name": "animationId",
                    "desc": "The id of the animation to play, can be a string or number",
                    "lua_type": "string | number"
                },
                {
                    "name": "animTrackOptions",
                    "desc": "The options to pass to the animation track on play as well as whether or not to cache the animation track",
                    "lua_type": "table?"
                },
                {
                    "name": "shouldYield",
                    "desc": "Whether or not to yield until the character exists",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The animation track if it was successfully played",
                    "lua_type": "AnimationTrack?"
                }
            ],
            "function_type": "method",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 704,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        },
        {
            "name": "GetCharacterFromPart",
            "desc": "Gets the character from a part if one exists.  Will also return NPCs.",
            "params": [
                {
                    "name": "part",
                    "desc": "The part to get the character from",
                    "lua_type": "BasePart"
                }
            ],
            "returns": [
                {
                    "desc": "The character if one exists",
                    "lua_type": "Model?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 724,
                "path": "src/shared/core/lib/CharacterUtils.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "CharacterUtils",
    "desc": "A set of utility functions for working with characters.",
    "source": {
        "line": 222,
        "path": "src/shared/core/lib/CharacterUtils.luau"
    }
}