bloxd-types 0.1.0

package/types/@plugins/debug/index.d.ts

@@ -0,0 +1,3 @@
+declare function debugLog(message: string): void;
+
+export { debugLog };

package/types/@plugins/helpers/index.d.ts

@@ -0,0 +1,67 @@
+import { PlayerId } from '@bloxd';
+
+declare const __brand: unique symbol;
+type Branded<T, B> = T & {
+    [__brand]: B;
+};
+type TimeoutId = Branded<number, "TimeoutId">;
+type IntervalId = Branded<number, "IntervalId">;
+/**
+ * Registers a function to be called after a delay.
+ * @param callback - The callback to call when the timeout expires
+ * @param delay - The delay in milliseconds before the callback is called
+ * @param playerId - Optional playerId to tie the timeout to. If the player leaves, this timeout will be cleared
+ * @returns The timeout id
+ */
+declare function setTimeout(callback: () => void, delay: number, playerId?: PlayerId): TimeoutId;
+/**
+ * Registers a function to be called repeatedly every interval.
+ * @param callback - The callback to call when the interval expires
+ * @param interval - The interval in milliseconds before the callback is called
+ * @param playerId - Optional playerId to tie the interval to. If the player leaves, this interval will be stopped
+ * @returns The interval id
+ */
+declare function setInterval(callback: () => void, interval: number, playerId?: PlayerId): IntervalId;
+/**
+ * Clears a timeout.
+ * @param id - The id of the timeout to clear
+ */
+declare function clearTimeout(id: TimeoutId): void;
+/**
+ * Clears an interval.
+ * @param id - The id of the interval to clear
+ */
+declare function clearInterval(id: IntervalId): void;
+
+/**
+ * Forces a chunk to be loaded.
+ * @param x - The x coordinate of the chunk
+ * @param y - The y coordinate of the chunk
+ * @param z - The z coordinate of the chunk
+ * @param onLoaded - The function to call when the chunk is loaded
+ */
+declare function forceLoadChunk(x: number, y: number, z: number, onLoaded: () => void): void;
+
+/**
+ * Generates a random integer between min and max, inclusive.
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @param includeMax - Whether to include the max value in the range. Defaults to false.
+ * @returns A random integer between min and max, inclusive.
+ */
+declare function randomInt(min: number, max: number, includeMax?: boolean): number;
+/**
+ * Shuffles an array in place.
+ * @param array - The array to shuffle.
+ * @returns The shuffled array.
+ */
+declare function shuffleArray<T>(array: T[]): T[];
+/**
+ * Gets a random item from an array.
+ * @param array - The array to get a random item from.
+ * @returns A random item from the array.
+ */
+declare function getRandomItem<T extends readonly any[]>(array: T): T[number];
+
+export { clearInterval, clearTimeout, forceLoadChunk, getRandomItem, randomInt, setInterval, setTimeout, shuffleArray };
+export type { IntervalId, TimeoutId };

package/types/@plugins/sessionBasedGame/index.d.ts

@@ -0,0 +1,185 @@
+import * as _bloxd from '@bloxd';
+import { PNull, PlayerId, CustomTextStyling, BlockName, ChatTags, Pos, RecursiveReadonly } from '@bloxd';
+
+declare class SessionBasedGame<TeamInfo extends BaseTeamInfo, MapInfo extends BaseMapInfo<TeamInfo>, Player extends SessionBasedPlayer<TeamInfo, MapInfo>> {
+    readonly gameOptions: Required<SessionBasedGameSetupOptions<TeamInfo, MapInfo, Player>>;
+    gamePhase: "beforeGame" | "inGame" | "gameFinished";
+    private startingRound;
+    private players;
+    map: PNull<MapInfo>;
+    private gameStartTime;
+    private startGameAt;
+    private endGameAt;
+    private mapVoter;
+    messageColours: {
+        error: string;
+        success: string;
+        info: string;
+    };
+    private get playersForFullLobby();
+    private get playerCount();
+    constructor(gameOptions: Required<SessionBasedGameSetupOptions<TeamInfo, MapInfo, Player>>);
+    /**
+     * Gets the player object for a given player ID.
+     * @param playerId The player ID to get the player for
+     */
+    getPlayer(playerId: PlayerId): Player;
+    /**
+     * Gets all the players in the game, including spectators.
+     * @returns An iterator of all the players in the game.
+     */
+    getPlayers(): Generator<Player>;
+    getStartingInText(): string | CustomTextStyling;
+    /**
+     * Gives all players coloured armour based on their team name. Spectators will get black armour.
+     * If their team name is not a valid colour, they will be skipped.
+     */
+    giveColouredArmourToEveryone(): void;
+    onPlayerJoin(playerId: PlayerId): void;
+    onPlayerLeave(playerId: PlayerId): void;
+    onPlayerDie(playerId: PlayerId): void;
+    checkWin(): void;
+    onPlayerChat(playerId: PlayerId, message: string): _bloxd.ChatTags;
+    onPlayerBoughtShopItem(playerId: PlayerId, categoryKey: string, itemKey: string): void;
+    tick(): void;
+    private getTeamsAlive;
+    private updateTimeTillStart;
+    private setStartGame;
+    private checkGameTransition;
+    private sendRightInfoText;
+    private loadMapFromRect;
+    private startGame;
+    /**
+     * Whether spectators should render faded. gamePhase can't be read directly: it only flips to
+     * "inGame" once startGame() has started every player, and the sit-out spectators it makes
+     * along the way need fading too.
+     */
+    spectatorsAreFaded(): boolean;
+    private assignTeams;
+    /**
+     * Manually sets a team to win the game. Will begin the game reset timer to restart the game.#
+     * Automatically called when there is only one team left.
+     * @param winningTeam - The team object that won the game.
+     */
+    makeTeamWin(winningTeam: PNull<TeamInfo>): void;
+    private resetGame;
+    onBlockStandStart(playerId: PlayerId, x: number, y: number, z: number, blockName: BlockName): void;
+    private placeTeamPad;
+    private placeTeamPads;
+}
+
+declare class SessionBasedPlayer<TeamInfo extends BaseTeamInfo, MapInfo extends BaseMapInfo<TeamInfo>> {
+    readonly playerId: PlayerId;
+    readonly game: SessionBasedGame<TeamInfo, MapInfo, SessionBasedPlayer<TeamInfo, MapInfo>>;
+    isSpectating: boolean;
+    team: PNull<TeamInfo>;
+    requestedTeam: PNull<TeamInfo>;
+    qTextId: PNull<string>;
+    constructor(playerId: PlayerId, game: SessionBasedGame<TeamInfo, MapInfo, SessionBasedPlayer<TeamInfo, MapInfo>>);
+    private spawn;
+    /**
+     * Sets the player as playing the game, setting their health, shields, and other settings.
+     * Automatically called at the start of a game for players assigned to a team.
+     */
+    startPlaying(): void;
+    /**
+     * Sets the player as spectating the game, resetting their health, shields, and other settings.
+     * Automatically called at the start of a game for players not assigned to a team.
+     * Call this function to turn a player into a spectator (for example, once they die).
+     */
+    startSpectating(): void;
+    private updateOtherEntitySettings;
+    onMessage(): ChatTags;
+    onRespawnRequest(): Pos | undefined;
+    /**
+     * Gets the position of the player relative to the play area.
+     * @returns The position of the player relative to the play area.
+     */
+    getPositionInPlayArea(): Pos;
+}
+
+type BaseTeamInfo = RecursiveReadonly<{
+    name: string;
+    maxPlayers: number;
+    colour: string;
+}>;
+type BaseMapInfo<TeamInfo extends BaseTeamInfo> = RecursiveReadonly<{
+    /** The name of the map */
+    name: string;
+    /** The icon of the map - used in the Map Voting Shop UI */
+    icon: string;
+    /** Block coordinates representing the start and the end of the map. These will be rounded outwards to the nearest chunk boundary */
+    source: {
+        rect: [Pos, Pos];
+    };
+}> & {
+    readonly teams: Record<TeamInfo["name"], RecursiveReadonly<{
+        spawn: Pos;
+        spawnFacing: Pos;
+    }>>;
+};
+type Constructor<T> = new (...args: any[]) => T;
+type TeamPadInfo = RecursiveReadonly<{
+    rect: [Pos, Pos];
+    emptyBlock: BlockName;
+    fullBlock: BlockName;
+}>;
+type SessionBasedGameSetupOptions<TeamInfo extends BaseTeamInfo, MapInfo extends BaseMapInfo<TeamInfo>, Player extends SessionBasedPlayer<TeamInfo, MapInfo>> = {
+    teams: readonly TeamInfo[];
+    maps: readonly MapInfo[];
+    /** Lobby area information */
+    lobby: RecursiveReadonly<{
+        /** Block coordinates representing the start and the end of the lobby area. */
+        source: {
+            rect: [Pos, Pos];
+        };
+        spawn: Pos;
+        spawnFacing: Pos;
+    }> & {
+        /** Block coordinates representing the start and the end of the team pads. Offset from the lowest corner of the map (after rounding outwards). If not provided, team choosing will be disabled. */
+        teamPads?: Record<TeamInfo["name"], TeamPadInfo>;
+    };
+    /** Block coordinates representing the start and the end of the play area. These will be rounded outwards to the nearest chunk boundary */
+    playAreaRect: readonly [Pos, Pos];
+    /** Maximum number of spectators allowed in the game */
+    maxSpectators?: number;
+    /** The number of seconds to wait before resetting the game after the game finishes */
+    emptyLobbyStartInSecs?: number;
+    /** The number of seconds to wait before starting the game when the lobby is full */
+    fullLobbyStartInSecs?: number;
+    /** The number of seconds to wait before resetting the game after the game finishes */
+    gameResetInSecs?: number;
+    /** Enable Map Voting - If enabled, players will be able to vote for the next map to play. */
+    mapVotingEnabled?: boolean;
+    /** Function to call when the game starts */
+    onStart?: () => void;
+    /** Function to call when the game finishes */
+    onFinish?: (winningTeam: TeamInfo) => void;
+    /** Function to get the RightInfoText for a player */
+    getRightInfoText?: (player: SessionBasedPlayer<TeamInfo, MapInfo>) => PNull<string | CustomTextStyling>;
+    /** The constructor for the player class. This should be a class that extends SessionBasedPlayer */
+    playerConstructor?: Constructor<Player>;
+};
+
+/**
+ * Create a new SessionBasedGame.
+ * @param opts - The options for the game.
+ * @param opts.teams - The teams for the game. This should include the team name, max players for this team, and hex colour.
+ * @param opts.maps - The maps for the game. This should include the map name, source rectangle, and the spawn positions for each team.
+ * @param opts.lobby - The lobby area. This should include the source rectangle, spawn info, and team pads for team choosing.
+ * @param opts.playAreaRect - The play area rectangle. These will be rounded outwards to the nearest chunk boundary
+ * @param opts.maxSpectators - The maximum number of spectators allowed in the game.
+ * @param opts.emptyLobbyStartInSecs - The number of seconds to wait for the game to start when the lobby isn't full yet.
+ * @param opts.fullLobbyStartInSecs - The number of seconds to wait for the game to start when the lobby is full.
+ * @param opts.gameResetInSecs - The number of seconds to wait before resetting the game after the game finishes.
+ * @param opts.mapVotingEnabled - Whether to enable map voting.
+ * @param opts.onStart - The function to call when the game starts.
+ * @param opts.onFinish - The function to call when the game finishes.
+ * @param opts.getRightInfoText - The function to call to get the RightInfoText for the game.
+ * @param opts.playerConstructor - The constructor for the player class. This should be a class that extends SessionBasedPlayer
+ * @returns The game instance
+ */
+declare function createGame<TeamInfo extends BaseTeamInfo, MapInfo extends BaseMapInfo<TeamInfo>, Player extends SessionBasedPlayer<TeamInfo, MapInfo>>(opts: SessionBasedGameSetupOptions<TeamInfo, MapInfo, Player>): SessionBasedGame<TeamInfo, MapInfo, Player>;
+
+export { SessionBasedGame, SessionBasedPlayer, createGame };
+export type { BaseMapInfo, BaseTeamInfo, SessionBasedGameSetupOptions };