isaacscript-common 9.20.0 → 10.0.2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+/// <reference types="@typescript-to-lua/language-extensions" />
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="lua-types/5.3" />
-/// <reference types="typescript-to-lua/language-extensions" />
 
 import { ActiveSlot } from 'isaac-typescript-definitions';
 import { BackdropType } from 'isaac-typescript-definitions';
@@ -17,6 +17,7 @@ import { CollectiblePedestalType } from 'isaac-typescript-definitions';
 import { CollectibleType } from 'isaac-typescript-definitions';
 import { Controller } from 'isaac-typescript-definitions';
 import { ControllerIndex } from 'isaac-typescript-definitions';
+import { CopyableIsaacAPIClassType } from 'isaac-typescript-definitions';
 import { CrawlSpaceVariant } from 'isaac-typescript-definitions';
 import { DamageFlag } from 'isaac-typescript-definitions';
 import { DiceFloorSubType } from 'isaac-typescript-definitions';
@@ -915,6 +916,9 @@ export declare function convertDecimalToBinary(number: number, minLength?: int):
  */
 export declare function convertXMLGridEntityType(gridEntityXMLType: GridEntityXMLType, gridEntityXMLVariant: int): [GridEntityType, int] | undefined;
 
+/** A type representing an Isaac API class that can be safely copied or serialized. */
+declare type CopyableIsaacAPIClass = BitSet128 | Color | KColor | RNG | Vector;
+
 /**
  * Helper function to perform a shallow copy.
  *
@@ -936,7 +940,7 @@ export declare function copyColor(color: Color): Color;
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export declare function copyIsaacAPIClass(isaacAPIClass: unknown): unknown;
+export declare function copyIsaacAPIClass<T extends CopyableIsaacAPIClass>(isaacAPIClass: T): T;
 
 /** Helper function to copy a `KColor` Isaac API class. */
 export declare function copyKColor(kColor: KColor): KColor;
@@ -950,8 +954,8 @@ export declare function copyRNG(rng: RNG): RNG;
 /** Helper function to copy a set. (You can also use a Set constructor to accomplish this task.) */
 export declare function copySet<T>(oldSet: Set<T> | ReadonlySet<T>): Set<T>;
 
-/** Helper function to copy specific values from a object to a table. */
-export declare function copyValuesToTable(object: unknown, keys: string[], luaMap: LuaMap<string, unknown>): void;
+/** Helper function to copy specific values from a userdata object (e.g. `Vector`) to a table. */
+export declare function copyUserdataValuesToTable(object: unknown, keys: string[], luaMap: LuaMap<string, unknown>): void;
 
 /** Helper function to copy a `Vector` Isaac API class. */
 export declare function copyVector(vector: Vector): Vector;
@@ -1545,7 +1549,9 @@ export declare interface CustomStageTSConfig {
  * @param insideMap Optional. Tracks whether or not the deep copy function is in the process of
  *                  recursively copying a TSTL Map. Default is false.
  */
-export declare function deepCopy(value: unknown, serializationType?: SerializationType, traversalDescription?: string, insideMap?: boolean): unknown;
+export declare function deepCopy<T>(value: T, serializationType?: SerializationType.NONE, traversalDescription?: string, insideMap?: boolean): T;
+
+export declare function deepCopy(value: unknown, serializationType: SerializationType, traversalDescription?: string, insideMap?: boolean): unknown;
 
 export declare const DEFAULT_BASE_STAGE = LevelStage.BASEMENT_2;
 
@@ -1701,16 +1707,21 @@ export declare function deleteSetsFromSet<T>(mainSet: Set<T>, ...setsToRemove: A
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in the provided JSON room.
  *
+ * You can create JSON rooms by using the `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json
+ * my-rooms.xml`).
+ *
  * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *
  * For example:
  *
  * ```ts
  *
- * import customRooms from "./customRooms";
+ * import customRooms from "./customRooms.json";
  *
- * const firstJSONRoom = customRooms.rooms.room[0];
- * deployJSONRoom(firstJSONRoom);
+ * export function postNewRoom(): void {
+ *   const firstJSONRoom = customRooms.rooms.room[0];
+ *   deployJSONRoom(firstJSONRoom);
+ * }
  * ```
  *
  * @param jsonRoom The JSON room to deploy. *
@@ -1726,6 +1737,9 @@ export declare function deployJSONRoom(jsonRoom: JSONRoom | Readonly<JSONRoom>,
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
  * all of the entries and grid entities in one of the provided JSON rooms.
  *
+ * You can create JSON rooms by using the `convert-xml-to-json` tool (e.g. `npx convert-xml-to-json
+ * my-rooms.xml`).
+ *
  * This function is meant to be used in the `POST_NEW_ROOM` callback.
  *
  * Note that this function does not simply choose a random element in the provided array; it will
@@ -1735,10 +1749,12 @@ export declare function deployJSONRoom(jsonRoom: JSONRoom | Readonly<JSONRoom>,
  * For example:
  *
  * ```ts
- * import customRooms from "./customRooms";
+ * import customRooms from "./customRooms.json";
  *
- * const jsonRooms = customRooms.rooms.room;
- * deployRandomJSONRoom(jsonRooms);
+ * export function postNewRoom(): void {
+ *   const jsonRooms = customRooms.rooms.room;
+ *   deployRandomJSONRoom(jsonRooms);
+ * }
  * ```
  *
  * @param jsonRooms An array of JSON rooms to randomly select from. In practice, this will be
@@ -1769,7 +1785,7 @@ export declare function deserializeColor(color: SerializedColor): Color;
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export declare function deserializeIsaacAPIClass(serializedIsaacAPIClass: unknown): unknown;
+export declare function deserializeIsaacAPIClass<SerializedT extends SerializedIsaacAPIClass>(serializedIsaacAPIClass: SerializedT): IsaacAPIClassTypeToType[SerializedT["__kind"]];
 
 /**
  * Helper function to convert a `SerializedKColor` object to a normal `KColor` object. (This is used
@@ -2157,6 +2173,8 @@ export declare function find<T>(array: T[], func: (value: T, index: number, arra
  * @param startingPosition The position to start searching from. If this position is not overlapping
  *                         with anything, then it will be returned.
  * @param avoidActiveEntities Optional. Default is false.
+ * @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;
 
@@ -2899,7 +2917,7 @@ export declare function getCrawlSpaces(crawlSpaceVariant?: CrawlSpaceVariant): G
 /**
  * Helper function to get the actual bit flag for modded curses.
  *
- * Will throw a runtime error if the provided curse does not exist.
+ * Will throw a run-time error if the provided curse does not exist.
  *
  * Use this over the `Isaac.GetCurseIdByName` method because that will return an integer instead of
  * a bit flag.
@@ -4451,6 +4469,9 @@ export declare function getRandomEnumValue<T>(transpiledEnum: T, seedOrRNG?: See
  */
 export declare function getRandomFloat(min: int, max: int, seedOrRNG?: Seed | RNG): float;
 
+/** Get a random value from a `WeightedArray`. (The second element in the array is the weight.) */
+export declare function getRandomFromWeightedArray<T>(weightedArray: WeightedArray<T>, seedOrRNG?: Seed | RNG): T;
+
 /**
  * This returns a random integer between min and max. It is inclusive on both ends.
  *
@@ -5667,6 +5688,22 @@ export declare function irange(start: int, end?: int): int[];
  */
 export declare function isaacAPIClassEquals(object1: unknown, object2: unknown, keys: string[]): boolean;
 
+declare interface IsaacAPIClassTypeToSerializedType {
+    [CopyableIsaacAPIClassType.BIT_SET_128]: SerializedBitSet128;
+    [CopyableIsaacAPIClassType.COLOR]: SerializedColor;
+    [CopyableIsaacAPIClassType.K_COLOR]: SerializedKColor;
+    [CopyableIsaacAPIClassType.RNG]: SerializedRNG;
+    [CopyableIsaacAPIClassType.VECTOR]: SerializedVector;
+}
+
+declare interface IsaacAPIClassTypeToType {
+    [CopyableIsaacAPIClassType.BIT_SET_128]: BitSet128;
+    [CopyableIsaacAPIClassType.COLOR]: Color;
+    [CopyableIsaacAPIClassType.K_COLOR]: KColor;
+    [CopyableIsaacAPIClassType.RNG]: RNG;
+    [CopyableIsaacAPIClassType.VECTOR]: Vector;
+}
+
 /** Iterates over all inputs to determine if a particular button is pressed (i.e. held down). */
 export declare function isActionPressedOnAnyInput(buttonAction: ButtonAction): boolean;
 
@@ -5834,6 +5871,14 @@ export declare function isCollectibleUnlocked(collectibleType: CollectibleType,
 /** Helper function to check if something is an instantiated `Color` object. */
 export declare function isColor(object: unknown): object is Color;
 
+/**
+ * Helper function to generically check if a given object is a copyable Isaac API class. (This is
+ * used by the save data manager when determining what is safe to copy.)
+ *
+ * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
+ */
+export declare function isCopyableIsaacAPIClass(object: unknown): object is CopyableIsaacAPIClass;
+
 /**
  * Helper function to check if a `GridEntity` is a custom grid entity or if a grid index has a
  * custom grid entity.
@@ -6475,7 +6520,7 @@ export declare const itemConfig: ItemConfig;
  *                false in situations where iterating randomly would not matter and you need the
  *                extra performance.
  */
-export declare function iterateTableInOrder<K, V>(luaMap: LuaMap<K, V>, func: (key: K, value: V) => void, inOrder?: boolean): void;
+export declare function iterateTableInOrder<K extends AnyNotNil, V>(luaMap: LuaMap<K, V>, func: (key: K, value: V) => void, inOrder?: boolean): void;
 
 /**
  * Helper function for non-TypeScript users to convert an array to a string with the specified
@@ -6824,7 +6869,7 @@ export declare function logTable(luaTable: unknown, parentTables?: number): void
  * Helper function to print out the differences between the entries of two tables. Note that this
  * will only do a shallow comparison.
  */
-export declare function logTableDifferences<K, V>(table1: LuaMap<K, V>, table2: LuaMap<K, V>): void;
+export declare function logTableDifferences<K extends AnyNotNil, V>(table1: LuaMap<K, V>, table2: LuaMap<K, V>): void;
 
 /** Helper function for printing out every tear flag that is turned on. Useful when debugging. */
 export declare function logTearFlags(flags: TearFlag | BitFlags<TearFlag>): void;
@@ -10387,7 +10432,7 @@ export declare const SECOND_IN_MILLISECONDS = 1000;
  * The recursive nature of this type is based on the `Immutable` type:
  * https://stackoverflow.com/questions/41879327/deepreadonly-object-typescript
  */
-declare type Serializable<T> = T extends SerializablePrimitive ? T : T extends SerializableIsaacAPIClass ? T : T extends IsaacAPIClass ? ErrorIsaacAPIClassIsNotSerializable : T extends Array<infer U> ? SerializableArray<U> : T extends ReadonlyArray<infer U> ? SerializableReadonlyArray<U> : T extends Map<infer K, infer V> ? SerializableMap<K, V> : T extends ReadonlyMap<infer K, infer V> ? SerializableReadonlyMap<K, V> : T extends Set<infer V> ? SerializableSet<V> : T extends ReadonlySet<infer V> ? SerializableReadonlySet<V> : SerializableObject<T>;
+declare type Serializable<T> = T extends SerializablePrimitive ? T : T extends CopyableIsaacAPIClass ? T : T extends IsaacAPIClass ? ErrorIsaacAPIClassIsNotSerializable : T extends Array<infer U> ? SerializableArray<U> : T extends ReadonlyArray<infer U> ? SerializableReadonlyArray<U> : T extends Map<infer K, infer V> ? SerializableMap<K, V> : T extends ReadonlyMap<infer K, infer V> ? SerializableReadonlyMap<K, V> : T extends Set<infer V> ? SerializableSet<V> : T extends ReadonlySet<infer V> ? SerializableReadonlySet<V> : SerializableObject<T>;
 
 declare type SerializableArray<T> = Array<SerializableInsideArrayOrMap<T>>;
 
@@ -10395,9 +10440,7 @@ declare type SerializableArray<T> = Array<SerializableInsideArrayOrMap<T>>;
  * This is mostly copied from the `Serializable` type. The difference is that we want to disallow
  * classes with methods.
  */
-declare type SerializableInsideArrayOrMap<T> = T extends SerializablePrimitive ? T : T extends SerializableIsaacAPIClass ? T : T extends IsaacAPIClass ? ErrorIsaacAPIClassIsNotSerializable : T extends Array<infer U> ? SerializableArray<U> : T extends ReadonlyArray<infer U> ? SerializableReadonlyArray<U> : T extends Map<infer K, infer V> ? SerializableMap<K, V> : T extends ReadonlyMap<infer K, infer V> ? SerializableReadonlyMap<K, V> : T extends Set<infer V> ? SerializableSet<V> : T extends ReadonlySet<infer V> ? SerializableReadonlySet<V> : T extends HasMethods<T> ? ErrorCustomClassNotSerializable : T extends Function ? FunctionIsNotSerializable : SerializableObject<T>;
-
-declare type SerializableIsaacAPIClass = BitSet128 | Color | KColor | RNG | Vector;
+declare type SerializableInsideArrayOrMap<T> = T extends SerializablePrimitive ? T : T extends CopyableIsaacAPIClass ? T : T extends IsaacAPIClass ? ErrorIsaacAPIClassIsNotSerializable : T extends Array<infer U> ? SerializableArray<U> : T extends ReadonlyArray<infer U> ? SerializableReadonlyArray<U> : T extends Map<infer K, infer V> ? SerializableMap<K, V> : T extends ReadonlyMap<infer K, infer V> ? SerializableReadonlyMap<K, V> : T extends Set<infer V> ? SerializableSet<V> : T extends ReadonlySet<infer V> ? SerializableReadonlySet<V> : T extends HasMethods<T> ? ErrorCustomClassNotSerializable : T extends Function ? FunctionIsNotSerializable : SerializableObject<T>;
 
 declare type SerializableMap<K, V> = Map<SerializableInsideArrayOrMap<K>, SerializableInsideArrayOrMap<V>>;
 
@@ -10436,32 +10479,35 @@ export declare function serializeColor(color: Color): SerializedColor;
 
 export declare type SerializedBitSet128 = LuaMap<string, unknown> & {
     readonly __serializedBitSet128Brand: symbol;
+    readonly __kind: CopyableIsaacAPIClassType.BIT_SET_128;
 };
 
 export declare type SerializedColor = LuaMap<string, unknown> & {
     readonly __serializedColorBrand: symbol;
+    readonly __kind: CopyableIsaacAPIClassType.COLOR;
 };
 
 /**
- * This is a type representing an Isaac API class like `Color` or `RNG` that has been written to the
+ * A type representing an Isaac API class like `Color` or `RNG` that has been written to the
  * "save#.dat" file. It is used by the save data manager when reading and writing to that file.
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export declare type SerializedIsaacAPIClass = LuaMap<string, unknown> & {
-    readonly __serializedIsaacAPIClassBrand: symbol;
-};
+declare type SerializedIsaacAPIClass = SerializedBitSet128 | SerializedColor | SerializedKColor | SerializedRNG | SerializedVector;
 
 export declare type SerializedKColor = LuaMap<string, unknown> & {
     readonly __serializedKColorBrand: symbol;
+    readonly __kind: CopyableIsaacAPIClassType.K_COLOR;
 };
 
 export declare type SerializedRNG = LuaMap<string, unknown> & {
     readonly __serializedRNGBrand: symbol;
+    readonly __kind: CopyableIsaacAPIClassType.RNG;
 };
 
 export declare type SerializedVector = LuaMap<string, unknown> & {
     readonly __serializedVectorBrand: symbol;
+    readonly __kind: CopyableIsaacAPIClassType.VECTOR;
 };
 
 /**
@@ -10470,7 +10516,7 @@ export declare type SerializedVector = LuaMap<string, unknown> & {
  *
  * For the list of supported classes, see the `CopyableIsaacAPIClassType` enum.
  */
-export declare function serializeIsaacAPIClass(isaacAPIClass: unknown): unknown;
+export declare function serializeIsaacAPIClass<T extends CopyableIsaacAPIClass>(isaacAPIClass: T): IsaacAPIClassTypeToSerializedType[T["__kind"]];
 
 /**
  * Helper function to convert a `KColor` object to a `SerializedKColor` object. (This is used by the
@@ -12030,6 +12076,9 @@ export declare function vectorToString(vector: Vector, round?: boolean): string;
  */
 export declare const VectorZero: Readonly<Vector>;
 
+/** An array where each element is paired with a number indicating that elements 'weight'. */
+export declare type WeightedArray<T> = Array<[T, float]>;
+
 /**
  * Assuming that we are on the frame of fatal damage, this function returns whether or not
  * Mysterious Paper would rotate to Missing Poster on the frame that the "Game Over" screen would