isaacscript-common 2.0.34 → 2.1.0

package/README.md

@@ -2,6 +2,6 @@
 
 [![npm version](https://img.shields.io/npm/v/isaacscript-common.svg)](https://www.npmjs.com/package/isaacscript-common)
 
-This repository contains helper functions and extra features for IsaacScript mods. You can browse the auto-generated documentation [here](https://isaacscript.github.io/isaacscript-common/index.html).
+This package contains helper functions and extra features for IsaacScript mods. Start by [browsing the auto-generated documentation](https://isaacscript.github.io/docs/api).
 
 For more information about IsaacScript, see the [official website](https://isaacscript.github.io/).

package/classes/DefaultMap.d.ts

@@ -1,8 +1,12 @@
-declare type FactoryFunction<V, Args extends unknown[]> = (...extraArgs: Args) => V;
+/**
+ * A function that creates the value for your default map. For example, if it was a default map
+ * containing a map, the factory function would be: `() => new Map()`
+ */
+export declare type FactoryFunction<V, Args extends unknown[]> = (...extraArgs: Args) => V;
 declare type FirstArg<K, V, Args extends unknown[]> = Iterable<[K, V]> | V | FactoryFunction<V, Args>;
 declare type SecondArg<V, Args extends unknown[]> = V | FactoryFunction<V, Args>;
 /**
- * An extended Map with some new methods:
+ * An extended `Map` with some new methods:
  *
  * - `getAndSetDefault` - If the key exists, this will return the same thing as the `get` method.
  *   Otherwise, it will set a default value to the key, and then return the default value.
@@ -17,15 +21,15 @@ declare type SecondArg<V, Args extends unknown[]> = V | FactoryFunction<V, Args>
  * For example:
  *
  * ```ts
- * // Initializes a new empty DefaultMap with a default value of "foo"
+ * // Initializes a new empty DefaultMap with a default value of "foo".
  * const defaultMapWithPrimitive = new DefaultMap<string, string>("foo");
  *
- * // Initializes a new empty DefaultMap with a default value of a new Map
+ * // Initializes a new empty DefaultMap with a default value of a new Map.
  * const defaultMapWithFactory = new DefaultMap<string, Map<string, string>>(() => {
  *   return new Map();
  * })
  *
- * // Initializes a DefaultMap with some initial values and a default value of "bar"
+ * // Initializes a DefaultMap with some initial values and a default value of "bar".
  * const defaultMapWithInitialValues = new DefaultMap<string, string>([
  *   ["a1", "a2"],
  *   ["b1", "b2"],
@@ -52,8 +56,8 @@ export declare class DefaultMap<K, V, Args extends unknown[] = []> extends Map<K
     private defaultValue;
     private defaultValueFactory;
     /**
-     * See the DefaultMap documentation:
-     * https://isaacscript.github.io/isaacscript-common/classes/types_DefaultMap.DefaultMap.html
+     * See the main `DefaultMap` documentation:
+     * https://isaacscript.github.io/isaacscript-common/classes/classes_DefaultMap.DefaultMap
      */
     constructor(iterableOrDefaultValueOrDefaultValueFactory: FirstArg<K, V, Args>, defaultValueOrDefaultValueFactory?: SecondArg<V, Args>);
     /**

package/enums/ModCallbackCustom.d.ts

@@ -1,6 +1,6 @@
 /**
  * These are the custom callbacks available for use once the mod object has been upgraded. Also see
- * the [[`upgradeMod`]] function.
+ * the `upgradeMod` function.
  */
 export declare enum ModCallbackCustom {
     POST_BOMB_INIT_LATE = 0,

package/features/characterHealthConversion.d.ts

@@ -1,5 +1,5 @@
 import { HeartSubType, PlayerType } from "isaac-typescript-definitions";
-declare type ConversionHeartSubType = HeartSubType.SOUL | HeartSubType.BLACK;
+export declare type ConversionHeartSubType = HeartSubType.SOUL | HeartSubType.BLACK;
 /**
  * Helper function to make a character that has the same health mechanic as Blue Baby (red heart
  * containers --> soul hearts) or Dark Judas (red heart containers --> black hearts).
@@ -7,4 +7,3 @@ declare type ConversionHeartSubType = HeartSubType.SOUL | HeartSubType.BLACK;
  * Call this function once at the beginning of your mod to declare the health conversion type.
  */
 export declare function registerCharacterHealthConversion(playerType: PlayerType, conversionHeartSubType: ConversionHeartSubType): void;
-export {};

package/features/disableInputs.d.ts

@@ -11,7 +11,7 @@ export declare function enableAllInputs(key: string): void;
  * Helper function to disable all inputs. This is useful because `EntityPlayer.ControlsEnabled` can
  * be changed by the game under certain conditions.
  *
- * Use the [[`enableAllInputs`]] helper function to set things back to normal.
+ * Use the `enableAllInputs` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.
@@ -21,7 +21,7 @@ export declare function disableAllInputs(key: string): void;
  * Helper function to enable all inputs besides the ones provided. This is useful because
  * `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
  *
- * Use the [[`enableAllInputs`]] helper function to set things back to normal.
+ * Use the `enableAllInputs` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.
@@ -32,7 +32,7 @@ export declare function enableAllInputsExceptFor(key: string, blacklist: Set<But
  * Helper function to disable all inputs besides the ones provided. This is useful because
  * `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
  *
- * Use the [[`enableAllInputs`]] helper function to set things back to normal.
+ * Use the `enableAllInputs` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.
@@ -44,7 +44,7 @@ export declare function disableAllInputsExceptFor(key: string, whitelist: Set<Bu
  * the UI). This is useful because `EntityPlayer.ControlsEnabled` can be changed by the game under
  * certain conditions.
  *
- * Use the [[`enableAllInputs`]] helper function to set things back to normal.
+ * Use the `enableAllInputs` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.
@@ -54,7 +54,7 @@ export declare function disableMovementInputs(key: string): void;
  * Helper function to disable only the inputs used for shooting tears. This is useful because
  * `EntityPlayer.ControlsEnabled` can be changed by the game under certain conditions.
  *
- * Use the [[`enableAllInputs`]] helper function to set things back to normal.
+ * Use the `enableAllInputs` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.

package/features/disableSound.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helper function to stop muting all sound effects and music.
  *
- * Use this function to set things back to normal after having used [[`disableAllSounds`]].
+ * Use this function to set things back to normal after having used `disableAllSounds`.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.
@@ -10,7 +10,7 @@ export declare function enableAllSound(key: string): void;
 /**
  * Helper function to disable all sound effects and music (by constantly musting them).
  *
- * Use the [[`enableAllSounds`]] helper function to set things back to normal.
+ * Use the `enableAllSounds` helper function to set things back to normal.
  *
  * @param key The name of the mod feature that is requesting the enable/disable. This is needed so
  *            that multiple mod features can work in tandem.

package/features/saveDataManager/exports.d.ts

@@ -1,4 +1,4 @@
-import { SaveData } from "../../types/private/SaveData";
+import { SaveData } from "../../types/SaveData";
 /**
  * This is the entry point to the save data manager, a system which provides two major features:
  *
@@ -59,16 +59,16 @@ import { SaveData } from "../../types/private/SaveData";
  *   can possibly run).
  * - Save data is recorded to disk in the `PRE_GAME_EXIT` callback.
  *
- * Note that before using the save data manager, you must call the [[`upgradeMod`]] function.
+ * Note that before using the save data manager, you must call the `upgradeMod` function.
  *
  * If you want the save data manager to load data before the `POST_PLAYER_INIT` callback (i.e. in
- * the main menu), then you should explicitly call the [[`saveDataManagerLoad`]] function. (The save
+ * the main menu), then you should explicitly call the `saveDataManagerLoad` function. (The save
  * data manager cannot do this on its own because it cannot know when your mod features are finished
  * initializing.)
  *
  * Finally, some features may have variables that need to be automatically reset per run/level, but
  * not saved to disk on game exit. (For example, if they contain functions or other non-serializable
- * data.) For these cases, set a special key of "dontSave" alongside "run", "level", and so forth.
+ * data.) For these cases, set the second argument to `() => false`.
  *
  * @param key The name of the file or feature that is submitting data to be managed by the save data
  *            manager. The save data manager will throw an error if the key is already registered.

package/features/saveDataManager/load.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="typescript-to-lua/language-extensions" />
-import { SaveData } from "../../types/private/SaveData";
+import { SaveData } from "../../types/SaveData";
 export declare function loadFromDisk(mod: Mod, oldSaveData: LuaTable<string, SaveData>): void;

package/features/saveDataManager/main.d.ts

@@ -1,3 +1,3 @@
 import { SaveDataKey } from "../../enums/private/SaveDataKey";
-import { SaveData } from "../../types/private/SaveData";
+import { SaveData } from "../../types/SaveData";
 export declare function restoreDefaultSaveData(subscriberName: string, saveData: SaveData, saveDataKey: SaveDataKey): void;

package/features/saveDataManager/maps.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="typescript-to-lua/language-extensions" />
-import { SaveData } from "../../types/private/SaveData";
+import { SaveData } from "../../types/SaveData";
 /**
  * The save data map is indexed by subscriber name. We use Lua tables instead of TypeScriptToLua
  * Maps for the master map so that we can access the variables via the in-game console when

package/features/saveDataManager/save.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="isaac-typescript-definitions" />
 /// <reference types="typescript-to-lua/language-extensions" />
-import { SaveData } from "../../types/private/SaveData";
+import { SaveData } from "../../types/SaveData";
 export declare function saveToDisk(mod: Mod, saveDataMap: LuaTable<string, SaveData>, saveDataConditionalFuncMap: Map<string, () => boolean>): void;

package/functions/cards.d.ts

@@ -25,7 +25,7 @@ export declare function getCardDescription(card: Card): string;
 export declare function getCardName(card: Card): string;
 export declare function getCardType(card: Card): ItemConfigCardType;
 /**
- * Helper function to get a set of cards matching the type. Also see the [[`CardType`]] enum.
+ * Helper function to get a set of cards matching the type. Also see the `CardType` enum.
  *
  * This function is variadic, meaning that you can you can specify N card types to get a set
  * containing cards that match any of the specified types.

package/functions/chargeBar.d.ts

@@ -1,12 +1,5 @@
 /// <reference types="isaac-typescript-definitions" />
-/** A collection of the four sprites necessary in order to render a charge bar. */
-export interface ChargeBarSprites {
-    back: Sprite;
-    meter: Sprite;
-    meterBattery: Sprite;
-    lines: Sprite;
-    maxCharges: int;
-}
+import { ChargeBarSprites } from "../types/ChargeBarSprites";
 /**
  * Constructor for a `ChargeBarSprites` object. For more information, see the `renderChargeBar`
  * helper function.

package/functions/color.d.ts

@@ -2,13 +2,16 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedColor = LuaTable<string, unknown> & {
-    __serializedColorBrand: unknown;
+    __serializedColorBrand: void;
 };
 interface CopyColorReturn {
     [SerializationType.NONE]: Color;
     [SerializationType.SERIALIZE]: SerializedColor;
     [SerializationType.DESERIALIZE]: Color;
 }
+/**
+ * @category color
+ */
 export declare function colorEquals(color1: Color, color2: Color): boolean;
 /**
  * Helper function to copy a `Color` object.
@@ -16,16 +19,27 @@ export declare function colorEquals(color1: Color, color2: Color): boolean;
  * @param color The Color object to copy. In the case of deserialization, this will actually be a
  *              Lua table instead of an instantiated Color class.
  * @param serializationType Default is `SerializationType.NONE`.
+ * @category color
  */
 export declare function copyColor<C extends Color | SerializedColor, S extends SerializationType>(color: C, serializationType: S): CopyColorReturn[S];
 export declare function copyColor<C extends Color | SerializedColor>(color: C): CopyColorReturn[SerializationType.NONE];
-/** Returns `Color(1, 1, 1)`. */
+/**
+ * Returns `Color(1, 1, 1)`.
+ *
+ * @category color
+ */
 export declare function getDefaultColor(): Color;
-/** Helper function to check if something is an instantiated Color object. */
+/**
+ * Helper function to check if something is an instantiated Color object.
+ *
+ * @category color
+ */
 export declare function isColor(object: unknown): object is Color;
 /**
  * Used to determine is the given table is a serialized `Color` object created by the save data
  * manager and/or the `deepCopy` function.
+ *
+ * @category color
  */
 export declare function isSerializedColor(object: unknown): object is SerializedColor;
 export {};

package/functions/entitySpecific.d.ts

@@ -1,4 +1,4 @@
-import { BombVariant, EffectVariant, EntityType, FamiliarVariant, KnifeVariant, LaserVariant, PickupVariant, ProjectileVariant, SlotVariant, TearVariant } from "isaac-typescript-definitions";
+import { BombVariant, EffectVariant, EntityType, FamiliarVariant, KnifeVariant, LaserVariant, PickupVariant, ProjectilesMode, ProjectileVariant, SlotVariant, TearVariant } from "isaac-typescript-definitions";
 /**
  * Helper function to get all of the `EntityType.BOMB` in the room.
  *
@@ -118,6 +118,20 @@ export declare function getSlots(slotVariant?: SlotVariant, subType?: number): E
  * ```
  */
 export declare function getTears(tearVariant?: TearVariant, subType?: number): EntityTear[];
+/**
+ * The base game `EntityNPC.FireProjectiles` method does not return anything, which is a problem in
+ * situations where you need to work with the fired projectiles. This function invokes that method,
+ * and then returns the projectiles that were spawned.
+ *
+ * @param npc The EntityNPC firing projectiles.
+ * @param position The starting position of the projectiles.
+ * @param velocity The starting velocity of the projectiles.
+ * @param projectilesMode A ProjectilesMode enum value defining how to fire the projectiles.
+ * @param projectileParams A ProjectileParams object containing various parameters for the
+ *                         projectiles.
+ * @returns An array of EntityProjectiles containing all fired projectiles.
+ */
+export declare function npcFireProjectiles(npc: EntityNPC, position: Vector, velocity: Vector, projectilesMode: ProjectilesMode, projectileParams: ProjectileParams): EntityProjectile[];
 /**
  * Helper function to remove all of the `EntityType.BOMB` in the room.
  *

package/functions/entitySpecific.lua

@@ -5,6 +5,7 @@ local ____constants = require("constants")
 local VectorZero = ____constants.VectorZero
 local ____entity = require("functions.entity")
 local getEntities = ____entity.getEntities
+local getFilteredNewEntities = ____entity.getFilteredNewEntities
 local removeEntities = ____entity.removeEntities
 local spawn = ____entity.spawn
 function ____exports.getBombs(self, bombVariant, subType)
@@ -173,6 +174,13 @@ function ____exports.getTears(self, tearVariant, subType)
     end
     return tears
 end
+function ____exports.npcFireProjectiles(self, npc, position, velocity, projectilesMode, projectileParams)
+    local oldEntities = ____exports.getProjectiles(nil)
+    npc:FireProjectiles(position, velocity, projectilesMode, projectileParams)
+    local newEntities = ____exports.getProjectiles(nil)
+    local filteredNewEntities = getFilteredNewEntities(nil, oldEntities, newEntities)
+    return filteredNewEntities
+end
 function ____exports.removeAllBombs(self, bombVariant, subType, cap)
     local bombs = ____exports.getBombs(nil, bombVariant, subType)
     return removeEntities(nil, bombs, cap)

package/functions/kColor.d.ts

@@ -2,7 +2,7 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedKColor = LuaTable<string, unknown> & {
-    __serializedKColorBrand: unknown;
+    __serializedKColorBrand: void;
 };
 interface CopyKColorReturn {
     [SerializationType.NONE]: KColor;

package/functions/rng.d.ts

@@ -2,7 +2,7 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedRNG = LuaTable<string, unknown> & {
-    __serializedRNGBrand: unknown;
+    __serializedRNGBrand: void;
 };
 interface CopyRNGReturn {
     [SerializationType.NONE]: RNG;

package/functions/trinkets.d.ts

@@ -65,9 +65,9 @@ export declare function isGoldenTrinket(trinketType: TrinketType): boolean;
  *
  * @param trinket The trinket whose sprite you want to modify.
  * @param pngPath Equal to either the spritesheet path to load (e.g.
- *                "gfx/items/collectibles/collectibles_001_thesadonion.png") or undefined. If
- *                undefined, the sprite will be removed, making it appear like the collectible has
- *                already been taken by the player.
+ *                "gfx/items/trinkets/trinket_001_swallowedpenny.png") or undefined. If undefined,
+ *                the sprite will be removed, making it appear like the collectible has already been
+ *                taken by the player.
  */
 export declare function setTrinketSprite(trinket: EntityPickup, pngPath: string | undefined): void;
 export declare function trinketHasCacheFlag(trinketType: TrinketType, cacheFlag: CacheFlag): boolean;

package/functions/vector.d.ts

@@ -2,7 +2,7 @@
 import { Direction } from "isaac-typescript-definitions";
 import { SerializationType } from "../enums/SerializationType";
 declare type SerializedVector = LuaTable<string, unknown> & {
-    __serializedVectorBrand: unknown;
+    __serializedVectorBrand: void;
 };
 interface CopyVectorReturn {
     [SerializationType.NONE]: Vector;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "2.0.34",
+  "version": "2.1.0",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",

package/types/ChargeBarSprites.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="isaac-typescript-definitions" />
+/**
+ * A collection of the four sprites necessary in order to render a charge bar.
+ *
+ * Used in the `newChargeBarSprites` and related helper functions.
+ */
+export interface ChargeBarSprites {
+    back: Sprite;
+    meter: Sprite;
+    meterBattery: Sprite;
+    lines: Sprite;
+    maxCharges: int;
+}

package/types/CollectibleIndex.d.ts

@@ -1,6 +1,6 @@
 /**
  * CollectibleIndex is a specific type of string; see the documentation for the
- * [[`getCollectibleIndex`]] function. Mods can signify that data structures handle collectibles by
+ * `getCollectibleIndex` function. Mods can signify that data structures handle collectibles by
  * using this type.
  *
  * For example:
@@ -12,5 +12,5 @@
  * This type is branded for extra type safety.
  */
 export declare type CollectibleIndex = string & {
-    __collectibleIndexBrand: unknown;
+    __collectibleIndexBrand: void;
 };

package/types/PlayerIndex.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
 /**
- * PlayerIndex is a specific type of string; see the documentation for the [[`getPlayerIndex`]]
+ * PlayerIndex is a specific type of string; see the documentation for the `getPlayerIndex`
  * function. Mods can signify that data structures handle `EntityPlayer` by using this type.
  *
  * For example:
@@ -12,5 +12,5 @@
  * This type is branded for extra type safety.
  */
 export declare type PlayerIndex = int & {
-    __playerIndexBrand: unknown;
+    __playerIndexBrand: void;
 };

package/types/{private/SaveData.d.ts → SaveData.d.ts}

@@ -1,14 +1,21 @@
-import { Primitive } from "../Primitive";
-/**
- * I don't know how to create a recursive type definition for only primitive values. For now, this
- * is typed as "unknown", which provides no type safety.
- */
-declare type Serializable = Primitive | unknown;
 /**
  * Each sub-object of save data has a string as a key, without arbitrary data as a value. However,
  * the data has to be serializable (i.e. no `userdata` objects).
+ *
+ * The values of the save data group can only be:
+ * - `boolean`
+ * - `number`
+ * - `string`
+ * - `Map` / `DefaultMap`
+ * - `Set`
+ * - a TSTL class
+ * - serializable Isaac API classes (such as `Color`)
+ * - a sub-object or `LuaTable` that contains the above values
+ *
+ * It is not possible to create a recursive type definition that matches these properties, so this
+ * is typed as "unknown", which provides no type safety.
  */
-declare type SaveDataGroup = Record<string, Serializable>;
+export declare type SaveDataGroup = Record<string, unknown>;
 /**
  * The object that contains all of the variables that will be managed by the save data manager.
  * Depending on which property is used, the variables will be reset at certain times.
@@ -19,4 +26,3 @@ export interface SaveData {
     level?: SaveDataGroup;
     room?: SaveDataGroup;
 }
-export {};

package/types/private/IsaacAPIClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type IsaacAPIClass = LuaTable<string, unknown> & {
-    __isaacAPIClassBrand: unknown;
+    __isaacAPIClassBrand: void;
 };

package/types/private/SerializedIsaacAPIClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type SerializedIsaacAPIClass = LuaTable<string, unknown> & {
-    __serializedIsaacAPIClassBrand: unknown;
+    __serializedIsaacAPIClassBrand: void;
 };

package/types/private/TSTLClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type TSTLClass = LuaTable<AnyNotNil, unknown> & {
-    __tstlClassBrand: unknown;
+    __tstlClassBrand: void;
 };

package/types/Primitive.d.ts

@@ -1 +0,0 @@
-export declare type Primitive = boolean | number | string;