@rbxts/player-hooks

Player Hooks

Player (hooks) is a more complexed class designated to wrap around the general Player interface found on Roblox's API, feel free to add more features through PRs!

Installation

📦 — NPM:

npm i @rbxts/player-hooks

🧶 — Yarn:

yarn add @rbxts/player-hooks

📀 — pnPM:

pnpm add @rbxts/player-hooks

Player Hooks API

Types

interface Destroyable {
	Destroy(): void;
}

type Object =
	| never
	| undefined
	| ((this: defined) => void)
	| ((_: defined) => void)
	| ExtractKeys<defined, () => void>
	| thread
	| RBXScriptConnection
	| globalThis.Player
	| Player
	| PlayerHook.Destroyable;

Constructor

const player: PlayerHook = new Player(localPlayer);

player.RetrieveCharacter

public RetrieveCharacter(): Model;

Return the player's character.

player.RetrieveHumanoid

public RetrieveHumanoid(): Humanoid;

Return the player's character's humanoid.

player.WaitForCharacter

public WaitForCharacter(Callback?: Callback): Model | boolean;

Wait for and return the player's character (cancels by default if five attempts fail).

player.WaitForHumanoid

public WaitForHumanoid(Callback?: Callback): Humanoid | boolean;

Wait for and return the player's characters' humanoid (cancels by default if five attempts fail).

player.RetrieveName

RetrieveName(): string;

Return the player's name.

player.RetrievePlayer

public RetrievePlayer(): Player;

Return the player's Player object.

player.RetrieveUserId

public RetrieveUserId(): number ;

Return the player's unique UserId.

player.CharacterAdded

public CharacterAdded(Callback?: Callback): defined;

Run the specified callback function on the addition of the player's character.

player.HumanoidAdded

public HumanoidAdded(Callback?: Callback): defined;

Run the specified callback function on the addition of the player's humanoid.

player.SetJumpPower

public SetJumpPower(power: number): defined;

Set the player's jump-power.

player.UseJumpPower

public UseJumpPower(value: boolean): defined;

Set whether or not to use the player's jump-power for jump-related adjustments.

player.SetJumpHeight

public SetJumpHeight(height: number): defined;

Set the player's jump-height.

player.SetMaxSlopeAngle

public SetMaxSlopeAngle(angle: number): defined;

Set the player's maximum slope angle.

player.SetWalkSpeed

public SetWalkSpeed(speed: number): defined;

Kick the player.

player.Kick

public Kick(reason: string): boolean;

Set the player's walking speed.

player.Destroy

public Destroy(): void;

Destroy and cleanup a player-hook (making it and not the player unusable).

Example

// Services
import { Players } from "@rbxts/services";

// Modules
import { PlayerHook } from "./";

// Variables
const PLAYER_CACHE: Array<Player> = [];

// Functions
function onPlayerAdded(localPlayer: Player) {
	if (PLAYER_CACHE.indexOf(localPlayer) !== undefined) {
		return;
	}

	function characterCallback() {
		print(`The character has been added!`);
	}

	function humanoidCallback() {
		print(`The humanoid has been added!`);
	}

	const player: PlayerHook = new PlayerHook<typeof localPlayer>(localPlayer);

	player.CharacterAdded(characterCallback);
	player.HumanoidAdded(humanoidCallback);

	player.WaitForCharacter(function (...args: Array<Model | boolean>) {
		print(...args); // --> Model | Model.Name

		print(player.RetrieveCharacter().Name); // --> Model.Name
	});

	player.WaitForHumanoid(function (...args: Array<Humanoid | boolean>) {
		print(...args); // --> Humanoid | Humanoid.Name

		player.SetWalkSpeed(1e1); // --> 10
		print(player.RetrieveHumanoid().WalkSpeed); // --> 10

		player.SetWalkSpeed(1e2); // --> 100
		print(player.RetrieveHumanoid().WalkSpeed); // --> 100
	});
}

function onPlayerRemoving(localPlayer: Player) {
	if (PLAYER_CACHE.indexOf(localPlayer) === undefined) {
		return;
	} else {
		const player = PLAYER_CACHE.indexOf(localPlayer) as unknown as PlayerHook;

		PLAYER_CACHE.indexOf(localPlayer) === undefined;

		player.Destroy();
	}
}

Players.PlayerAdded.Connect(onPlayerAdded);
Players.PlayerRemoving.Connect(onPlayerRemoving);