isaacscript-common/dist/functions/playerIndex.d.ts

Helper functions and features for IsaacScript mods.

import type { PlayerIndex } from "../types/PlayerIndex";
/**
 * Helper function to get every player with no restrictions, by using `Game.GetNumPlayers` and
 * `Isaac.GetPlayer`.
 *
 * This function is almost never what you want to use. For most purposes, use the `getPlayers`
 * helper function instead to get a filtered list of players.
 */
export declare function getAllPlayers(): readonly EntityPlayer[];
/**
 * Helper function to get all of the other players in the room besides the one provided. (This
 * includes "child" players.)
 */
export declare function getOtherPlayers(player: EntityPlayer): readonly EntityPlayer[];
/**
 * Helper function to get the corresponding `EntityPlayer` object that corresponds to a
 * `PlayerIndex`.
 */
export declare function getPlayerFromIndex(playerIndex: PlayerIndex): EntityPlayer | undefined;
/**
 * Mods often have to track variables relating to the player. In naive mods, information will only
 * be stored about the first player. However, in order to be robust, mods must handle up to 4
 * players playing at the same time. This means that information must be stored on a map data
 * structure. Finding a good index for these types of map data structures is difficult:
 *
 * - We cannot use the index from `Isaac.GetPlayer(i)` since this fails in the case where there are
 *   two players and the first player leaves the run.
 * - We cannot use `EntityPlayer.ControllerIndex` as an index because it fails in the case of Jacob
 *   & Esau or Tainted Forgotten. It also fails in the case of a player changing their controls
 *   mid-run.
 * - We cannot use `EntityPlayer.GetData().index` because it does not persist across saving and
 *   continuing.
 * - We cannot use `GetPtrHash()` as an index because it does not persist across exiting and
 *   relaunching the game.
 * - We cannot use `EntityPlayer.InitSeed` because it is not consistent with additional players
 *   beyond the first.
 *
 * Instead, we use the `EntityPlayer.GetCollectibleRNG` method with an arbitrary value of Sad Onion
 * (1). This works even if the player does not have any Sad Onions.
 *
 * Note that by default, this returns the same index for both The Forgotten and The Soul. (Even
 * though they are technically different characters, they share the same inventory and `InitSeed`.)
 * If this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG
 * of Spoon Bender (3) will be used for The Soul.
 *
 * Also note that this index does not work in the `POST_PLAYER_INIT` function for players 2 through
 * 4. With that said, in almost all cases, you should be lazy-initializing your data structures in
 * other callbacks, so this should not be an issue.
 */
export declare function getPlayerIndex(player: EntityPlayer, differentiateForgottenAndSoul?: boolean): PlayerIndex;
/**
 * Helper function to return the index of this player with respect to the output of the
 * `Isaac.GetPlayer` method.
 *
 * Note that if you storing information about a player in a data structure, you never want to use
 * this index; use the `getPlayerIndex` function instead.
 */
export declare function getPlayerIndexVanilla(playerToFind: EntityPlayer): int | undefined;
/**
 * This function always excludes players with a non-undefined parent, since they are not real
 * players (e.g. the Strawman Keeper).
 *
 * If this is not desired, use the `getAllPlayers` helper function instead.
 *
 * @param performCharacterExclusions Whether to exclude characters that are not directly controlled
 *                                 by the player (i.e. Esau & Tainted Soul). Default is false.
 */
export declare function getPlayers(performCharacterExclusions?: boolean): readonly EntityPlayer[];
/**
 * Helper function to get a parent `EntityPlayer` object for a given `EntitySubPlayer` object. This
 * is useful because calling the `EntityPlayer.GetSubPlayer` method on a sub-player object will
 * return undefined.
 */
export declare function getSubPlayerParent(subPlayer: EntitySubPlayer): EntityPlayer | undefined;
/**
 * Helper function to detect if a particular player is a "child" player, meaning that they have a
 * non-undefined `EntityPlayer.Parent` field. (For example, the Strawman Keeper.)
 */
export declare function isChildPlayer(player: EntityPlayer): boolean;
/**
 * Helper function to detect if a particular player is the Found Soul player provided by the
 * trinket.
 */
export declare function isFoundSoul(player: EntityPlayer): boolean;
//# sourceMappingURL=playerIndex.d.ts.map