isaacscript-common 21.9.0 → 23.0.0

package/dist/index.rollup.d.ts

@@ -619,6 +619,14 @@ declare interface AddCallbackParametersCustom {
  */
 export declare function addCharge(player: EntityPlayer, activeSlot?: ActiveSlot, numCharges?: number, playSoundEffect?: boolean): int;
 
+/**
+ * Helper function to add one or more collectibles to a player.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * add.
+ */
+export declare function addCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): void;
+
 export declare function addCollectibleCostume(player: EntityPlayer, collectibleType: CollectibleType): void;
 
 /**
@@ -3876,7 +3884,7 @@ export declare function find<T>(array: T[], func: (value: T, index: number, arra
  * @param minimumDistance Optional. If specified, will ensure that the randomly generated position
  *                        is equal to or greater than the distance provided.
  */
-export declare function findFreePosition(startingPosition: Vector, avoidActiveEntities?: boolean, minimumDistance?: float): Vector;
+export declare function findFreePosition(startingPosition: Vector, avoidActiveEntities?: boolean, minimumDistance?: float): Readonly<Vector>;
 
 declare type FireArgs<T extends ModCallbackCustom> = Parameters<AddCallbackParametersCustom[T][0]>;
 
@@ -4397,6 +4405,14 @@ export declare function getCharacterName(character: PlayerType): string;
 /** Helper function to get an array containing the characters of all of the current players. */
 export declare function getCharacters(): PlayerType[];
 
+/**
+ * Helper function to get the collectibles that are granted to a particular character at the
+ * beginning of a run.
+ *
+ * Note that this will return an empty array for Eden and Tainted Eden.
+ */
+export declare function getCharacterStartingItems(character: PlayerType): readonly CollectibleType[];
+
 /**
  * Helper function to get the amount of charges away from the maximum charge that a particular
  * player is.
@@ -5111,7 +5127,7 @@ export declare function getHorsePillColors(): PillColor[];
  * - If the user does not have a HUD offset configured, this function will return `Vector(0, 0)`.
  * - If the user has a HUD offset of 1.0 configured, this function will return `Vector(20, 12)`.
  */
-export declare function getHUDOffsetVector(): Vector;
+export declare function getHUDOffsetVector(): Readonly<Vector>;
 
 /**
  * Helper function to get the name of a class from the Isaac API. This is contained within the
@@ -5871,7 +5887,7 @@ export declare function getRandomArrayIndex<T>(array: T[] | readonly T[], seedOr
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
  * @param alpha Optional. The alpha value to use. Default is 1.
  */
-export declare function getRandomColor(seedOrRNG?: Seed | RNG, alpha?: number): Color;
+export declare function getRandomColor(seedOrRNG?: Seed | RNG, alpha?: number): Readonly<Color>;
 
 /**
  * Helper function to get a random value from the provided enum.
@@ -5985,7 +6001,7 @@ export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seedOrRNG?: See
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
  * @param alpha Optional. The alpha value to use. Default is 1.
  */
-export declare function getRandomKColor(seedOrRNG?: Seed | RNG, alpha?: number): KColor;
+export declare function getRandomKColor(seedOrRNG?: Seed | RNG, alpha?: number): Readonly<KColor>;
 
 /**
  * Helper function to get a random `Seed` value to be used in spawning entities and so on. Use this
@@ -6014,7 +6030,7 @@ export declare function getRandomSetElement<T>(set: Set<T> | ReadonlySet<T>, see
  * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
  *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
  */
-export declare function getRandomVector(seedOrRNG?: Seed | RNG): Vector;
+export declare function getRandomVector(seedOrRNG?: Seed | RNG): Readonly<Vector>;
 
 /**
  * Helper function to get a read-only copy of the room descriptor for every room on the level. This
@@ -6443,19 +6459,19 @@ export declare function getRoomVisitedCount(roomGridIndex?: int): int;
  */
 export declare function getSacks(sackSubType?: SackSubType): EntityPickupSack[];
 
-export declare function getScreenBottomCenterPos(): Vector;
+export declare function getScreenBottomCenterPos(): Readonly<Vector>;
 
-export declare function getScreenBottomLeftPos(): Vector;
+export declare function getScreenBottomLeftPos(): Readonly<Vector>;
 
-export declare function getScreenBottomRightPos(): Vector;
+export declare function getScreenBottomRightPos(): Readonly<Vector>;
 
-export declare function getScreenCenterPos(): Vector;
+export declare function getScreenCenterPos(): Readonly<Vector>;
 
-export declare function getScreenTopCenterPos(): Vector;
+export declare function getScreenTopCenterPos(): Readonly<Vector>;
 
-export declare function getScreenTopLeftPos(): Vector;
+export declare function getScreenTopLeftPos(): Readonly<Vector>;
 
-export declare function getScreenTopRightPos(): Vector;
+export declare function getScreenTopRightPos(): Readonly<Vector>;
 
 /**
  * Helper function to get all possible combinations of the given set. This includes the combination
@@ -6817,7 +6833,7 @@ export declare const GRID_INDEX_CENTER_OF_1X1_ROOM = 67;
  *
  * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
  */
-export declare function gridCoordinatesToWorldPosition(x: int, y: int): Vector;
+export declare function gridCoordinatesToWorldPosition(x: int, y: int): Readonly<Vector>;
 
 declare class GridEntityCollisionDetection extends Feature {
     v: {
@@ -6909,14 +6925,14 @@ declare class GridEntityUpdateDetection extends Feature {
  * For example, in a 1x1 room, grid index 0 is equal to "Vector(-1, -1) and grid index 16 is equal
  * to "Vector(0, 0)".
  */
-export declare function gridIndexToGridPosition(gridIndex: int, roomShape: RoomShape): Vector;
+export declare function gridIndexToGridPosition(gridIndex: int, roomShape: RoomShape): Readonly<Vector>;
 
 /**
  * Helper function to convert a grid position `Vector` to a world position `Vector`.
  *
  * For example, the coordinates of (0, 0) are equal to `Vector(80, 160)`.
  */
-export declare function gridPositionToWorldPosition(gridPosition: Vector): Vector;
+export declare function gridPositionToWorldPosition(gridPosition: Vector): Readonly<Vector>;
 
 /**
  * Helper function to see if a particular entity has armor. In this context, armor refers to the
@@ -6926,6 +6942,14 @@ export declare function gridPositionToWorldPosition(gridPosition: Vector): Vecto
  */
 export declare function hasArmor(entity: Entity): boolean;
 
+/**
+ * Helper function to check to see if a player has one or more collectibles.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * check for. Returns true if the player has any of the supplied collectible types.
+ */
+export declare function hasCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): boolean;
+
 export declare function hasCurse(curse: LevelCurse): boolean;
 
 /**
@@ -6950,6 +6974,14 @@ export declare function hasFlag<T extends BitFlag | BitFlag128>(flags: T | BitFl
 
 export declare function hasFlyingTransformation(player: EntityPlayer): boolean;
 
+/**
+ * Helper function to check to see if a player has one or more transformations.
+ *
+ * This function is variadic, meaning that you can supply as many transformations as you want to
+ * check for. Returns true if the player has any of the supplied transformations.
+ */
+export declare function hasForm(player: EntityPlayer, ...playerForms: PlayerForm[]): boolean;
+
 /** Helper type to check if an object or class has one or more functions/methods. */
 export declare type HasFunction<T> = Record<string, unknown> extends {
     [K in keyof T as T[K] extends Function ? K : never]-?: 1;
@@ -7015,7 +7047,7 @@ export declare enum HealthType {
  * @param hexString A hex string like "#ffffff" or "ffffff". (The "#" character is optional.)
  * @param alpha Optional. Range is from 0 to 1. Default is 1. (The same as the `Color` constructor.)
  */
-export declare function hexToColor(hexString: string, alpha?: number): Color;
+export declare function hexToColor(hexString: string, alpha?: number): Readonly<Color>;
 
 /**
  * Converts a hex string like "#33aa33" to a Color object.
@@ -7023,7 +7055,7 @@ export declare function hexToColor(hexString: string, alpha?: number): Color;
  * @param hexString A hex string like "#ffffff" or "ffffff". (The "#" character is optional.)
  * @param alpha Range is from 0 to 1. Default is 1.
  */
-export declare function hexToKColor(hexString: string, alpha?: number): KColor;
+export declare function hexToKColor(hexString: string, alpha?: number): Readonly<KColor>;
 
 /**
  * Helper type to make the given array/map/set/object recursively read-only.
@@ -7723,7 +7755,7 @@ export declare function isEntityMoving(entity: Entity, threshold?: number): bool
 
 export declare function isEven(num: int): boolean;
 
-/** Helper function to detect if a variable is of type `EntityEffect`. */
+/** Helper function to detect if a variable is of type `EntityFamiliar`. */
 export declare function isFamiliar(variable: unknown): variable is EntityFamiliar;
 
 /**
@@ -8617,7 +8649,7 @@ export declare function lockDoor(door: GridEntityDoor): void;
  * @param includeParentFunction Optional. Whether to prefix the message with the function name and
  *                              line number, as shown in the above example. Default is true.
  */
-export declare function log(this: void, msg: string, includeParentFunction?: boolean): void;
+export declare function log(this: void, msg: string | number, includeParentFunction?: boolean): void;
 
 /** Helper function for printing out every entity (or filtered entity) in the current room. */
 export declare function logAllEntities(this: void, includeBackgroundEffects: boolean, entityTypeFilter?: EntityType): void;
@@ -12255,14 +12287,6 @@ export declare const PILL_NAME_TO_EFFECT_MAP: ReadonlyMap<string, PillEffect>;
  */
 export declare function playChargeSoundEffect(player: EntityPlayer, activeSlot?: ActiveSlot): void;
 
-/**
- * Helper function to add one or more collectibles to a player.
- *
- * This function is variadic, meaning that you can supply as many collectible types as you want to
- * add.
- */
-export declare function playerAddCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): void;
-
 declare class PlayerCollectibleDetection extends Feature {
     v: {
         run: {
@@ -12314,22 +12338,6 @@ export declare function playerConvertBlackHeartsToSoulHearts(player: EntityPlaye
 
 export declare function playerConvertSoulHeartsToBlackHearts(player: EntityPlayer): void;
 
-/**
- * Helper function to check to see if a player has one or more collectibles.
- *
- * This function is variadic, meaning that you can supply as many collectible types as you want to
- * check for. Returns true if the player has any of the supplied collectible types.
- */
-export declare function playerHasCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): boolean;
-
-/**
- * Helper function to check to see if a player has one or more transformations.
- *
- * This function is variadic, meaning that you can supply as many transformations as you want to
- * check for. Returns true if the player has any of the supplied transformations.
- */
-export declare function playerHasForm(player: EntityPlayer, ...playerForms: PlayerForm[]): boolean;
-
 /**
  * Helper function to see if the player is out of health.
  *
@@ -13186,6 +13194,14 @@ export declare function removeAllTrinkets(trinketType?: TrinketType, cap?: int):
  */
 export declare function removeCharactersBefore(string: string, substring: string): string;
 
+/**
+ * Helper function to remove one or more collectibles to a player.
+ *
+ * This function is variadic, meaning that you can supply as many collectible types as you want to
+ * remove.
+ */
+export declare function removeCollectible(player: EntityPlayer, ...collectibleTypes: CollectibleType[]): void;
+
 /**
  * Helper function to remove a collectible costume from a player. Use this helper function to avoid
  * having to request the collectible from the item config.
@@ -15651,7 +15667,7 @@ export declare function willReviveFromSpiritShackles(player: EntityPlayer): bool
  *
  * In this context, the grid position of the top-left wall is "Vector(-1, -1)".
  */
-export declare function worldPositionToGridPosition(worldPos: Vector): Vector;
+export declare function worldPositionToGridPosition(worldPos: Vector): Readonly<Vector>;
 
 /**
  * Helper function to convert a world position `Vector` to a grid position `Vector`.
@@ -15660,7 +15676,7 @@ export declare function worldPositionToGridPosition(worldPos: Vector): Vector;
  *
  * This is similar to the `worldPositionToGridPosition` function, but the values are not rounded.
  */
-export declare function worldPositionToGridPositionFast(worldPos: Vector): Vector;
+export declare function worldPositionToGridPositionFast(worldPos: Vector): Readonly<Vector>;
 
 /**
  * Helper function to see if a certain damage amount would deal "permanent" damage to Tainted