isaacscript-common 31.5.0 → 31.7.0

package/dist/index.rollup.d.ts

@@ -1194,6 +1194,16 @@ export declare function asPillEffect(num: number): PillEffect;
  */
 export declare function asPlayerType(num: number): PlayerType;
 
+/**
+ * Helper function to throw an error (using the `error` Lua function) if the provided value is equal
+ * to `undefined`.
+ *
+ * This is useful to have TypeScript narrow a `T | undefined` value to `T` in a concise way.
+ */
+export declare function assertDefined<T>(value: T, ...[msg]: [undefined] extends [T] ? [string] : [
+"The assertion is useless because the provided value does not contain undefined."
+]): asserts value is Exclude<T, undefined>;
+
 /**
  * Helper function to safely cast an enum to a `string`. (This is better than using the `as`
  * TypeScript keyword to do a type assertion, since that can obfuscate compiler errors. )
@@ -1530,6 +1540,8 @@ export declare function clearRoomDisplayFlags(roomGridIndex: int): void;
  * This function will still work identically if PNG file does not exist, but it will cause a
  * spurious error to appear in the "log.txt" file. If silencing these errors is desired, you can
  * create a transparent 1 pixel PNG file in your mod's resources folder at `EMPTY_PNG_PATH`.
+ *
+ * @allowEmptyVariadic
  */
 export declare function clearSprite(sprite: Sprite, ...layerIDs: int[]): void;
 
@@ -3347,6 +3359,8 @@ export declare class DefaultMap<Key, Value, Args extends unknown[] = []> extends
     /**
      * If the key exists, this will return the same thing as the normal `Map.get` method. Otherwise,
      * it will set a default value for the provided key, and then return the default value.
+     *
+     * @allowEmptyVariadic
      */
     getAndSetDefault(key: Key, ...args: Args): Value;
     /**
@@ -3410,6 +3424,8 @@ export declare function defaultMapGetNPC<V, Args extends unknown[]>(map: Default
  *   player.MoveSpeed = defaultMapGetPlayer(v.run.playersSpeedBoost, player);
  * }
  * ```
+ *
+ * @allowEmptyVariadic
  */
 export declare function defaultMapGetPlayer<V, Args extends unknown[]>(map: DefaultMap<PlayerIndex, V, Args>, player: EntityPlayer, ...extraArgs: Args): V;
 
@@ -5263,10 +5279,10 @@ export declare function getEnumEntries<T>(transpiledEnum: T): Array<[key: string
  * For a more in depth explanation, see:
  * https://isaacscript.github.io/main/gotchas#iterating-over-enums
  */
-export declare function getEnumKeys<T>(transpiledEnum: T): string[];
+export declare function getEnumKeys(transpiledEnum: Record<string | number, string | number>): string[];
 
 /** Helper function to get the amount of entries inside of an enum. */
-export declare function getEnumLength<T>(transpiledEnum: T): int;
+export declare function getEnumLength(transpiledEnum: Record<string | number, string | number>): int;
 
 /**
  * TypeScriptToLua will transpile TypeScript enums to Lua tables that have a double mapping. Thus,
@@ -5486,8 +5502,8 @@ export declare function getHeartsUIWidth(): int;
 /**
  * Helper function to get the enum value with the highest value.
  *
- * Note that this is not necessarily the enum value that is declared last, since there is no way to
- * infer that at run-time.
+ * Note that this is not necessarily the enum value that is declared last in the code, since there
+ * is no way to infer that at run-time.
  */
 export declare function getHighestEnumValue<T>(transpiledEnum: T): T[keyof T];
 
@@ -5628,6 +5644,9 @@ export declare function getLasers(laserVariant?: LaserVariant | -1, subType?: nu
  * Helper function to return the last element of an array.
  *
  * If the array is empty, this will return undefined.
+ *
+ * (Note that TSTL does not support `Array.at(-1)`, which would make this helper function largely
+ * unnecessary.)
  */
 export declare function getLastElement<T>(array: T[]): T | undefined;
 
@@ -5673,7 +5692,7 @@ export declare function getMapPartialMatch<T>(searchText: string, map: ReadonlyM
  */
 export declare function getMatchingGridEntities(gridEntityType: GridEntityType, variant: int): GridEntity[];
 
-export declare function getMoveActions(): ReadonlySet<ButtonAction>;
+export declare function getMoveActions(controllerIndex: ControllerIndex): ButtonAction[];
 
 /**
  * Helper function to get the corresponding music value for a stage and stage type combination.
@@ -6918,7 +6937,7 @@ export declare function getScreenTopRightPos(): Readonly<Vector>;
  */
 export declare function getSetCombinations<T>(set: Set<T> | ReadonlySet<T>, includeEmptyArray: boolean): ReadonlyArray<ReadonlySet<T>>;
 
-export declare function getShootActions(): ReadonlySet<ButtonAction>;
+export declare function getShootActions(controllerIndex: ControllerIndex): ButtonAction[];
 
 /**
  * Helper function to get the corresponding "Siren Helper" entity for a stolen familiar.
@@ -8281,6 +8300,9 @@ export declare function isEntity(variable: unknown): variable is Entity;
  */
 export declare function isEntityMoving(entity: Entity, threshold?: number): boolean;
 
+/** Helper function to validate that a particular value exists inside of an enum. */
+export declare function isEnumValue(value: number | string, transpiledEnum: Record<string | number, string | number>): boolean;
+
 export declare function isEven(num: int): boolean;
 
 /** Helper function to detect if a variable is of type `EntityFamiliar`. */
@@ -13053,6 +13075,8 @@ export declare class ModFeature {
     uninit(): void;
 }
 
+export declare const MODIFIER_KEYS: readonly [Keyboard.LEFT_SHIFT, Keyboard.LEFT_CONTROL, Keyboard.LEFT_ALT, Keyboard.LEFT_SUPER, Keyboard.RIGHT_SHIFT, Keyboard.RIGHT_CONTROL, Keyboard.RIGHT_ALT, Keyboard.RIGHT_SUPER];
+
 /**
  * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
  * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
@@ -13146,6 +13170,8 @@ export declare class ModUpgraded implements Mod {
  */
 declare type ModUpgradedWithFeatures<T extends readonly ISCFeature[] = []> = ModUpgraded & ISCFeaturesToKeys<T>;
 
+export declare const MOVEMENT_ACTIONS: readonly [ButtonAction.LEFT, ButtonAction.RIGHT, ButtonAction.UP, ButtonAction.DOWN];
+
 export declare const MOVEMENT_ACTIONS_SET: ReadonlySet<ButtonAction>;
 
 /**
@@ -16004,6 +16030,8 @@ export declare function setUnseeded(): void;
  */
 export declare const sfxManager: SFXManager;
 
+export declare const SHOOTING_ACTIONS: readonly [ButtonAction.SHOOT_LEFT, ButtonAction.SHOOT_RIGHT, ButtonAction.SHOOT_UP, ButtonAction.SHOOT_DOWN];
+
 export declare const SHOOTING_ACTIONS_SET: ReadonlySet<ButtonAction>;
 
 declare function shouldFireCollectibleType(fireArgs: [player: EntityPlayer, collectibleType: CollectibleType], optionalArgs: [collectibleType?: CollectibleType]): boolean;