Skip to main content

PlayerUtil

This module contains utility methods that handle players joining and leaving. As well as utility functions for character access.

Characters Folder

The module works best when a folder named "Characters" exists within workspace. Ideally you create this folder within your project JSON file so that it exists ahead of time.

Functions​

getCharactersFolder​

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
</>
PlayerUtil.getCharactersFolder() → Folder--

The characters folder

Returns the characters folder, creating it if it doesn't exist. This folder is used to store all characters in the game. This folder is created on the server and waited for on the client.

promiseCharacter​

</>
PlayerUtil.promiseCharacter(
plr: Player,--

The player to get the character of

timeOut?: number?--

The amount of time to wait before rejecting the promise

) → Promise<Character>--

A promise that resolves when the character is retrieved

Returns a promise that resolves with the character of the specified player once their character is within the proper folder.

getPlayerFromCharacterDescendant​

</>
PlayerUtil.getPlayerFromCharacterDescendant(
descendant: Instance--

The descendant to get the player of

) → Player?--

The player that owns the character

Returns the player that owns the specified descendant of a character. Returns nil if the descendant is not a descendant of a character.

getAllLoadedCharacters​

</>
PlayerUtil.getAllLoadedCharacters() → {Character}--

A table of all the fully loaded characters

forEachCharacter​

</>
PlayerUtil.forEachCharacter(
func: (
char: Character,
janitor: Janitor
) → (),--

A passed function to be executed for each character, it is given the character as an argument. Also receives a Janitor object that can be used to clean up any connections made.

player: Player?--

An optional player to only run the function for their character.

) → Connection--

A connection that can be Disconnected or Destroyed to stop method's activities.

Takes a function that will be run for every player in the game as well as any future players until the returned connection is disconnected.

forEachPlayer​

</>
PlayerUtil.forEachPlayer(
func: (
player: Player,
janitor: Janitor
) → ()--

A passed function to be executed for each player, it is given the player as an argument.

) → Connection--

A connection that can be Disconnected or Destroyed to stop method's activities.

Takes a function that will be run for every player in the game as well as any future players until the returned connection is disconnected.

onPlayerRemoving​

</>
PlayerUtil.onPlayerRemoving(
player: Player,
func: () → ()--

The function to be run when the player disconnects.

) → Connection--

A connection that can be Disconnected or Destroyed to stop method's activities.

Takes a function that will be run for a specified player when they leave.

Show raw api
{
    "functions": [
        {
            "name": "getCharactersFolder",
            "desc": "Returns the characters folder, creating it if it doesn't exist.\nThis folder is used to store all characters in the game.\nThis folder is created on the server and waited for on the client.",
            "params": [],
            "returns": [
                {
                    "desc": "The characters folder",
                    "lua_type": "Folder"
                }
            ],
            "function_type": "static",
            "yields": true,
            "source": {
                "line": 113,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "promiseCharacter",
            "desc": "Returns a promise that resolves with the character of the specified player once\ntheir character is within the proper folder.",
            "params": [
                {
                    "name": "plr",
                    "desc": "The player to get the character of",
                    "lua_type": "Player"
                },
                {
                    "name": "timeOut?",
                    "desc": "The amount of time to wait before rejecting the promise",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "A promise that resolves when the character is retrieved",
                    "lua_type": "Promise<Character>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 144,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "getPlayerFromCharacterDescendant",
            "desc": "Returns the player that owns the specified descendant of a character.\nReturns nil if the descendant is not a descendant of a character.",
            "params": [
                {
                    "name": "descendant",
                    "desc": "The descendant to get the player of",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "The player that owns the character",
                    "lua_type": "Player?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 184,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "getAllLoadedCharacters",
            "desc": "",
            "params": [],
            "returns": [
                {
                    "desc": "A table of all the fully loaded characters",
                    "lua_type": "{Character}"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 195,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "forEachCharacter",
            "desc": "Takes a function that will be run for every player in the game as well as any future players\nuntil the returned connection is disconnected.",
            "params": [
                {
                    "name": "func",
                    "desc": "A passed function to be executed for each character, it is given the character as an argument. Also receives a Janitor object that can be used to clean up any connections made.",
                    "lua_type": "(char: Character, janitor: Janitor) -> ()"
                },
                {
                    "name": "player",
                    "desc": "An optional player to only run the function for their character.",
                    "lua_type": "Player?"
                }
            ],
            "returns": [
                {
                    "desc": "A connection that can be Disconnected or Destroyed to stop method's activities.",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 207,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "forEachPlayer",
            "desc": "Takes a function that will be run for every player in the game as well as any future players\nuntil the returned connection is disconnected.",
            "params": [
                {
                    "name": "func",
                    "desc": "A passed function to be executed for each player, it is given the player as an argument.",
                    "lua_type": "(player: Player, janitor: Janitor) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "A connection that can be Disconnected or Destroyed to stop method's activities.",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 283,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        },
        {
            "name": "onPlayerRemoving",
            "desc": "Takes a function that will be run for a specified player when they leave.",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                },
                {
                    "name": "func",
                    "desc": "The function to be run when the player disconnects.",
                    "lua_type": "() -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "A connection that can be Disconnected or Destroyed to stop method's activities.",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 318,
                "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "PlayerUtil",
    "desc": "This module contains utility methods that handle players joining and leaving.\nAs well as utility functions for character access.\n\n:::caution Characters Folder\nThe module works best when a folder named \"Characters\" exists within workspace.\nIdeally you create this folder within your project JSON file so that it exists ahead of time.\n:::",
    "source": {
        "line": 15,
        "path": "src/railutils/src/RailUtil/PlayerUtil.lua"
    }
}