isaacscript-common 30.12.8 → 30.12.10

package/dist/index.rollup.d.ts

@@ -4199,6 +4199,19 @@ export declare function fillLevelWithRedRooms(): void;
  */
 export declare function filter<T>(array: T[], func: (value: T, index: number, array: T[]) => boolean): T[];
 
+/**
+ * Helper function to perform a map and a filter at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because a map will always produce an array with the same amount of
+ * elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ */
+export declare function filterMap<OldT, NewT>(array: OldT[], func: (element: OldT) => NewT | undefined): NewT[];
+
 /**
  * Helper function for non-TypeScript users to find an element in an array.
  *
@@ -7566,16 +7579,16 @@ export declare function inHomeCloset(): boolean;
  * For example:
  *
  * ```ts
- * const features = [
+ * const MOD_FEATURES = [
  *   MyFeature1,
  *   MyFeature2,
  *   MyFeature3,
  * ] as const;
- * initModFeatures(mod, modFeatures);
+ * initModFeatures(mod, MOD_FEATURES);
  * ```
  *
  * @returns An array of the instantiated features in the same order that the constructors were
- *          passed in.
+ *          passed in. (In most cases, you probably won't need the returned array.)
  */
 export declare function initModFeatures<T extends ReadonlyArray<typeof ModFeature>>(mod: ModUpgraded, modFeatures: T): {
     [K in keyof T]: InstanceType<T[K]>;
@@ -12798,24 +12811,22 @@ declare class ModdedElementSets extends Feature {
  * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
  * that automatically subscribe to callbacks.
  *
- * When instantiating a mod feature class, you must pass your upgraded mod as the first argument to
- * the constructor.
+ * It is recommended that you use the `initModFeatures` helper function to instantiate all of your
+ * mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
+ * are properly registered with the save data manager; see below.
  *
- * If your feature has variables that are managed by the save data manager, you need to explicitly
- * register them with the save data manager yourself in your class constructor. (It can't be
- * automatically done because parent classes don't have access to child class properties.)
+ * If you are manually instantiating a mod feature yourself, then:
  *
- * In almost all cases, you will want the callback functions to be immediately subscribed after
- * instantiating the class. However, if this is not the case, you can pass `false` as the optional
- * second argument to the constructor.
+ * - You must pass your upgraded mod as the first argument to the constructor.
+ * - In almost all cases, you will want the callback functions to be immediately subscribed after
+ *   instantiating the class. However, if this is not the case, you can pass `false` as the optional
+ *   second argument to the constructor.
  *
  * If your mod feature has a property called `v`, it will be assumed that these are variables that
- * should be managed by the save data manager. Subsequently, they will automatically be registered
- * with the save data manager upon initialization. Unfortunately, due to technical limitations with
- * classes, this registration will only occur if you initialize the class with the `init` boolean
- * argument set to false, and then explicitly call the `ModFeature.init` method yourself after the
- * class is constructed. (This is because the parent class does not have access to the child's
- * properties upon first construction.)
+ * should be managed by the save data manager. Unfortunately, due to technical limitations with
+ * classes, this registration will only occur if you initialize the class with the `initModFeatures`
+ * helper function. (This is because the parent class does not have access to the child's properties
+ * upon first construction.)
  */
 export declare class ModFeature {
     private readonly mod;
@@ -15169,21 +15180,20 @@ declare class SaveDataManager extends Feature {
      *    desired).
      * 2. Automatic saving and loading of all tracked data to the "save#.dat" file.
      *
-     * You feed this function with an object containing your variables, and then it will automatically
-     * manage them for you. (See below for an example.)
+     * You provide this function with an object containing your variables, and then it will
+     * automatically manage them for you. (See below for an example.)
      *
      * In order to use this function, you must upgrade your mod with `ISCFeature.SAVE_DATA_MANAGER`.
      * (Upgrade your mod before registering any of your own callbacks so that the save data manager
      * will run before any of your code does.)
      *
      * The save data manager is meant to be called once for each feature of your mod. In other words,
-     * you should not put all of the data for your mod on the same object. Instead, scope your
+     * you should not put all of the variables for your mod on the same object. Instead, scope your
      * variables locally to a single file that contains a mod feature, and then call this function to
      * register them. For example:
      *
      * ```ts
      * // In file: feature1.ts
-     * import { saveDataManager } from "isaacscript-common";
      *
      * // Declare local variables for this file or feature.
      * const v = {
@@ -15207,13 +15217,12 @@ declare class SaveDataManager extends Feature {
      *     foo4: 0,
      *   },
      * };
-     * // Every child object is optional; only create the ones that you need.
+     * // The child objects of "persistent", "run", "level", and "room are optional; only create the
+     * // ones that you need.
      *
-     * // Register the variables with the save data manager. (We need to provide a string key that
-     * // matches the name of this file.)
-     * function feature1Init() {
-     *   saveDataManager("feature1", v);
-     * }
+     * // Now, give `v` to the save data manager, and it will automatically manage the variables for
+     * // you.
+     * mod.saveDataManager("feature1", v);
      *
      * // Elsewhere in the file, use your variables.
      * function feature1Function() {

package/dist/isaacscript-common.lua

@@ -1,6 +1,6 @@
 --[[
 
-isaacscript-common 30.12.8
+isaacscript-common 30.12.10
 
 This is the "isaacscript-common" library, which was created with the IsaacScript tool.
 
@@ -16854,6 +16854,16 @@ end
 function ____exports.emptyArray(self, array)
     __TS__ArraySplice(array, 0, #array)
 end
+function ____exports.filterMap(self, array, func)
+    local newArray = {}
+    for ____, element in ipairs(array) do
+        local newElement = func(nil, element)
+        if newElement ~= nil then
+            newArray[#newArray + 1] = newElement
+        end
+    end
+    return newArray
+end
 function ____exports.getArrayCombinations(self, array, includeEmptyArray, min, max)
     if min == nil or min <= 0 then
         min = 1

package/dist/src/classes/ModFeature.d.ts

@@ -8,24 +8,22 @@ export declare const MOD_FEATURE_CUSTOM_CALLBACKS_KEY = "__customCallbacks";
  * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
  * that automatically subscribe to callbacks.
  *
- * When instantiating a mod feature class, you must pass your upgraded mod as the first argument to
- * the constructor.
+ * It is recommended that you use the `initModFeatures` helper function to instantiate all of your
+ * mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
+ * are properly registered with the save data manager; see below.
  *
- * If your feature has variables that are managed by the save data manager, you need to explicitly
- * register them with the save data manager yourself in your class constructor. (It can't be
- * automatically done because parent classes don't have access to child class properties.)
+ * If you are manually instantiating a mod feature yourself, then:
  *
- * In almost all cases, you will want the callback functions to be immediately subscribed after
- * instantiating the class. However, if this is not the case, you can pass `false` as the optional
- * second argument to the constructor.
+ * - You must pass your upgraded mod as the first argument to the constructor.
+ * - In almost all cases, you will want the callback functions to be immediately subscribed after
+ *   instantiating the class. However, if this is not the case, you can pass `false` as the optional
+ *   second argument to the constructor.
  *
  * If your mod feature has a property called `v`, it will be assumed that these are variables that
- * should be managed by the save data manager. Subsequently, they will automatically be registered
- * with the save data manager upon initialization. Unfortunately, due to technical limitations with
- * classes, this registration will only occur if you initialize the class with the `init` boolean
- * argument set to false, and then explicitly call the `ModFeature.init` method yourself after the
- * class is constructed. (This is because the parent class does not have access to the child's
- * properties upon first construction.)
+ * should be managed by the save data manager. Unfortunately, due to technical limitations with
+ * classes, this registration will only occur if you initialize the class with the `initModFeatures`
+ * helper function. (This is because the parent class does not have access to the child's properties
+ * upon first construction.)
  */
 export declare class ModFeature {
     private readonly mod;

package/dist/src/classes/ModFeature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModFeature.d.ts","sourceRoot":"","sources":["../../../src/classes/ModFeature.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AASpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AACvD,eAAO,MAAM,gCAAgC,sBAAsB,CAAC;AAyBpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CAAC,yBAAyB,EAC/B,CAAC,CAAC,CAAC,SAAS,OAAO,EACjB,OAAO,EAAE,CAAC,EACV,WAAW,EAAE,CAAC,SAAS,IAAI,GAAG,WAAW,GAAG,iBAAiB,EAC7D,GAAG,YAAY,EAAE,OAAO,EAAE,KACvB,OAAO,CAAC,GACb,IAAI,CAAQ;IAEhB;;;;;OAKG;IACI,WAAW,UAAS;gBAEf,GAAG,EAAE,WAAW,EAAE,IAAI,UAAO;IAQzC;;;;;OAKG;IACI,IAAI,CAAC,IAAI,UAAO,GAAG,IAAI;IAqB9B;;;;;OAKG;IACI,MAAM,IAAI,IAAI;CAGtB"}
+{"version":3,"file":"ModFeature.d.ts","sourceRoot":"","sources":["../../../src/classes/ModFeature.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AASpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AACvD,eAAO,MAAM,gCAAgC,sBAAsB,CAAC;AAyBpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CAAC,yBAAyB,EAC/B,CAAC,CAAC,CAAC,SAAS,OAAO,EACjB,OAAO,EAAE,CAAC,EACV,WAAW,EAAE,CAAC,SAAS,IAAI,GAAG,WAAW,GAAG,iBAAiB,EAC7D,GAAG,YAAY,EAAE,OAAO,EAAE,KACvB,OAAO,CAAC,GACb,IAAI,CAAQ;IAEhB;;;;;OAKG;IACI,WAAW,UAAS;gBAEf,GAAG,EAAE,WAAW,EAAE,IAAI,UAAO;IAQzC;;;;;OAKG;IACI,IAAI,CAAC,IAAI,UAAO,GAAG,IAAI;IAqB9B;;;;;OAKG;IACI,MAAM,IAAI,IAAI;CAGtB"}

package/dist/src/classes/ModFeature.lua

@@ -163,24 +163,22 @@ WRAPPED_CUSTOM_CALLBACK_METHODS_KEY = "__wrappedCustomCallbacksMethods"
 -- mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
 -- that automatically subscribe to callbacks.
 -- 
--- When instantiating a mod feature class, you must pass your upgraded mod as the first argument to
--- the constructor.
+-- It is recommended that you use the `initModFeatures` helper function to instantiate all of your
+-- mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
+-- are properly registered with the save data manager; see below.
 -- 
--- If your feature has variables that are managed by the save data manager, you need to explicitly
--- register them with the save data manager yourself in your class constructor. (It can't be
--- automatically done because parent classes don't have access to child class properties.)
+-- If you are manually instantiating a mod feature yourself, then:
 -- 
--- In almost all cases, you will want the callback functions to be immediately subscribed after
--- instantiating the class. However, if this is not the case, you can pass `false` as the optional
--- second argument to the constructor.
+-- - You must pass your upgraded mod as the first argument to the constructor.
+-- - In almost all cases, you will want the callback functions to be immediately subscribed after
+--   instantiating the class. However, if this is not the case, you can pass `false` as the optional
+--   second argument to the constructor.
 -- 
 -- If your mod feature has a property called `v`, it will be assumed that these are variables that
--- should be managed by the save data manager. Subsequently, they will automatically be registered
--- with the save data manager upon initialization. Unfortunately, due to technical limitations with
--- classes, this registration will only occur if you initialize the class with the `init` boolean
--- argument set to false, and then explicitly call the `ModFeature.init` method yourself after the
--- class is constructed. (This is because the parent class does not have access to the child's
--- properties upon first construction.)
+-- should be managed by the save data manager. Unfortunately, due to technical limitations with
+-- classes, this registration will only occur if you initialize the class with the `initModFeatures`
+-- helper function. (This is because the parent class does not have access to the child's properties
+-- upon first construction.)
 ____exports.ModFeature = __TS__Class()
 local ModFeature = ____exports.ModFeature
 ModFeature.name = "ModFeature"

package/dist/src/classes/features/other/SaveDataManager.d.ts

@@ -51,21 +51,20 @@ export declare class SaveDataManager extends Feature {
      *    desired).
      * 2. Automatic saving and loading of all tracked data to the "save#.dat" file.
      *
-     * You feed this function with an object containing your variables, and then it will automatically
-     * manage them for you. (See below for an example.)
+     * You provide this function with an object containing your variables, and then it will
+     * automatically manage them for you. (See below for an example.)
      *
      * In order to use this function, you must upgrade your mod with `ISCFeature.SAVE_DATA_MANAGER`.
      * (Upgrade your mod before registering any of your own callbacks so that the save data manager
      * will run before any of your code does.)
      *
      * The save data manager is meant to be called once for each feature of your mod. In other words,
-     * you should not put all of the data for your mod on the same object. Instead, scope your
+     * you should not put all of the variables for your mod on the same object. Instead, scope your
      * variables locally to a single file that contains a mod feature, and then call this function to
      * register them. For example:
      *
      * ```ts
      * // In file: feature1.ts
-     * import { saveDataManager } from "isaacscript-common";
      *
      * // Declare local variables for this file or feature.
      * const v = {
@@ -89,13 +88,12 @@ export declare class SaveDataManager extends Feature {
      *     foo4: 0,
      *   },
      * };
-     * // Every child object is optional; only create the ones that you need.
+     * // The child objects of "persistent", "run", "level", and "room are optional; only create the
+     * // ones that you need.
      *
-     * // Register the variables with the save data manager. (We need to provide a string key that
-     * // matches the name of this file.)
-     * function feature1Init() {
-     *   saveDataManager("feature1", v);
-     * }
+     * // Now, give `v` to the save data manager, and it will automatically manage the variables for
+     * // you.
+     * mod.saveDataManager("feature1", v);
      *
      * // Elsewhere in the file, use your variables.
      * function feature1Function() {

package/dist/src/classes/features/other/SaveDataManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SaveDataManager.d.ts","sourceRoot":"","sources":["../../../../../src/classes/features/other/SaveDataManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAOzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAsBhD,qBAAa,eAAgB,SAAQ,OAAO;IAC1C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAE1B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAE9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IAEtE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAGvC;IAEJ;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAkC;IAE9E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkC;IAGpE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,qCAAqC,CAAS;IAmCtD,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAU1C;IAGF,OAAO,CAAC,QAAQ,CAAC,cAAc,CA0B7B;IAGF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAa1B;IAGF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAY3B;IAGF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAuB/B;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmGG;IAEI,eAAe,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,EAC3C,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,CAAC,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,EACnC,eAAe,CAAC,EAAE,MAAM,OAAO,GAC9B,IAAI;IAEA,eAAe,CACpB,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,CAAC,EAAE,QAAQ,EACX,eAAe,EAAE,KAAK,GACrB,IAAI;IA6DP;;OAEG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;;;;;;;OASG;IAEI,mBAAmB,IAAI,IAAI;IAIlC;;;;;;OAMG;IAEI,mBAAmB,IAAI,IAAI;IAIlC;;;;;;;OAOG;IAEI,wBAAwB,IAAI,IAAI;IAIvC;;;;;;;;;;;OAWG;IAEI,4BAA4B,CAAC,GAAG,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI;IAcrE;;;;;OAKG;IAEI,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAoB/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IAEI,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,GAAG,IAAI;IAsB3E;;;;;;;;;;;;OAYG;IAEI,qBAAqB,IAAI,OAAO;IAKhC,6BAA6B,IAAI,IAAI;CAQ7C"}
+{"version":3,"file":"SaveDataManager.d.ts","sourceRoot":"","sources":["../../../../../src/classes/features/other/SaveDataManager.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAOzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAsBhD,qBAAa,eAAgB,SAAQ,OAAO;IAC1C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAE1B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAE9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IAEtE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAGvC;IAEJ;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAkC;IAE9E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAkC;IAGpE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,qCAAqC,CAAS;IAmCtD,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAU1C;IAGF,OAAO,CAAC,QAAQ,CAAC,cAAc,CA0B7B;IAGF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAa1B;IAGF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAY3B;IAGF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAuB/B;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiGG;IAEI,eAAe,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,EAC3C,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,CAAC,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,EACnC,eAAe,CAAC,EAAE,MAAM,OAAO,GAC9B,IAAI;IAEA,eAAe,CACpB,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,CAAC,EAAE,QAAQ,EACX,eAAe,EAAE,KAAK,GACrB,IAAI;IA6DP;;OAEG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;;;;;;;OASG;IAEI,mBAAmB,IAAI,IAAI;IAIlC;;;;;;OAMG;IAEI,mBAAmB,IAAI,IAAI;IAIlC;;;;;;;OAOG;IAEI,wBAAwB,IAAI,IAAI;IAIvC;;;;;;;;;;;OAWG;IAEI,4BAA4B,CAAC,GAAG,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI;IAcrE;;;;;OAKG;IAEI,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAoB/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IAEI,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,GAAG,IAAI;IAsB3E;;;;;;;;;;;;OAYG;IAEI,qBAAqB,IAAI,OAAO;IAKhC,6BAA6B,IAAI,IAAI;CAQ7C"}

package/dist/src/functions/array.d.ts

@@ -93,6 +93,18 @@ export declare function combineArrays<T>(...arrays: Array<T[] | readonly T[]>):
 export declare function copyArray<T>(oldArray: T[] | readonly T[], numElements?: int): T[];
 /** Helper function to remove all of the elements in an array in-place. */
 export declare function emptyArray<T>(array: T[]): void;
+/**
+ * Helper function to perform a map and a filter at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because a map will always produce an array with the same amount of
+ * elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ */
+export declare function filterMap<OldT, NewT>(array: OldT[], func: (element: OldT) => NewT | undefined): NewT[];
 /**
  * Helper function to get all possible combinations of the given array. This includes the
  * combination of an empty array.

package/dist/src/functions/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/functions/array.ts"],"names":[],"mappings":"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"}

package/dist/src/functions/array.lua

@@ -290,6 +290,25 @@ end
 function ____exports.emptyArray(self, array)
     __TS__ArraySplice(array, 0, #array)
 end
+--- Helper function to perform a map and a filter at the same time. Similar to `Array.map`, provide a
+-- function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+-- this function cannot be used in situations where `undefined` can be a valid array element.)
+-- 
+-- This function is useful because a map will always produce an array with the same amount of
+-- elements as the original array.
+-- 
+-- This is named `filterMap` after the Rust function:
+-- https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+function ____exports.filterMap(self, array, func)
+    local newArray = {}
+    for ____, element in ipairs(array) do
+        local newElement = func(nil, element)
+        if newElement ~= nil then
+            newArray[#newArray + 1] = newElement
+        end
+    end
+    return newArray
+end
 --- Helper function to get all possible combinations of the given array. This includes the
 -- combination of an empty array.
 -- 

package/dist/src/functions/modFeatures.d.ts

@@ -10,16 +10,16 @@ import type { ModUpgraded } from "../classes/ModUpgraded";
  * For example:
  *
  * ```ts
- * const features = [
+ * const MOD_FEATURES = [
  *   MyFeature1,
  *   MyFeature2,
  *   MyFeature3,
  * ] as const;
- * initModFeatures(mod, modFeatures);
+ * initModFeatures(mod, MOD_FEATURES);
  * ```
  *
  * @returns An array of the instantiated features in the same order that the constructors were
- *          passed in.
+ *          passed in. (In most cases, you probably won't need the returned array.)
  */
 export declare function initModFeatures<T extends ReadonlyArray<typeof ModFeature>>(mod: ModUpgraded, modFeatures: T): {
     [K in keyof T]: InstanceType<T[K]>;

package/dist/src/functions/modFeatures.lua

@@ -10,16 +10,16 @@ local ____exports = {}
 -- For example:
 -- 
 -- ```ts
--- const features = [
+-- const MOD_FEATURES = [
 --   MyFeature1,
 --   MyFeature2,
 --   MyFeature3,
 -- ] as const;
--- initModFeatures(mod, modFeatures);
+-- initModFeatures(mod, MOD_FEATURES);
 -- ```
 -- 
 -- @returns An array of the instantiated features in the same order that the constructors were
--- passed in.
+-- passed in. (In most cases, you probably won't need the returned array.)
 function ____exports.initModFeatures(self, mod, modFeatures)
     local instantiatedModFeatures = {}
     for ____, modFeature in ipairs(modFeatures) do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "30.12.8",
+  "version": "30.12.10",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -25,6 +25,6 @@
   "main": "dist/src/index",
   "types": "dist/index.rollup.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^13.0.21"
+    "isaac-typescript-definitions": "^13.0.23"
   }
 }

package/src/classes/ModFeature.ts

@@ -42,26 +42,23 @@ type ModFeatureConstructor = TSTLClassMetatable["constructor"] & {
  * mod features from this class in order to enable the `@Callback` and `@CustomCallback` decorators
  * that automatically subscribe to callbacks.
  *
- * When instantiating a mod feature class, you must pass your upgraded mod as the first argument to
- * the constructor.
+ * It is recommended that you use the `initModFeatures` helper function to instantiate all of your
+ * mod classes (instead of instantiating them yourself). This is so that any attached `v` objects
+ * are properly registered with the save data manager; see below.
  *
- * If your feature has variables that are managed by the save data manager, you need to explicitly
- * register them with the save data manager yourself in your class constructor. (It can't be
- * automatically done because parent classes don't have access to child class properties.)
+ * If you are manually instantiating a mod feature yourself, then:
  *
- * In almost all cases, you will want the callback functions to be immediately subscribed after
- * instantiating the class. However, if this is not the case, you can pass `false` as the optional
- * second argument to the constructor.
+ * - You must pass your upgraded mod as the first argument to the constructor.
+ * - In almost all cases, you will want the callback functions to be immediately subscribed after
+ *   instantiating the class. However, if this is not the case, you can pass `false` as the optional
+ *   second argument to the constructor.
  *
  * If your mod feature has a property called `v`, it will be assumed that these are variables that
- * should be managed by the save data manager. Subsequently, they will automatically be registered
- * with the save data manager upon initialization. Unfortunately, due to technical limitations with
- * classes, this registration will only occur if you initialize the class with the `init` boolean
- * argument set to false, and then explicitly call the `ModFeature.init` method yourself after the
- * class is constructed. (This is because the parent class does not have access to the child's
- * properties upon first construction.)
+ * should be managed by the save data manager. Unfortunately, due to technical limitations with
+ * classes, this registration will only occur if you initialize the class with the `initModFeatures`
+ * helper function. (This is because the parent class does not have access to the child's properties
+ * upon first construction.)
  */
-
 export class ModFeature {
   private readonly mod: ModUpgraded;
 

package/src/classes/features/other/SaveDataManager.ts

@@ -221,21 +221,20 @@ export class SaveDataManager extends Feature {
    *    desired).
    * 2. Automatic saving and loading of all tracked data to the "save#.dat" file.
    *
-   * You feed this function with an object containing your variables, and then it will automatically
-   * manage them for you. (See below for an example.)
+   * You provide this function with an object containing your variables, and then it will
+   * automatically manage them for you. (See below for an example.)
    *
    * In order to use this function, you must upgrade your mod with `ISCFeature.SAVE_DATA_MANAGER`.
    * (Upgrade your mod before registering any of your own callbacks so that the save data manager
    * will run before any of your code does.)
    *
    * The save data manager is meant to be called once for each feature of your mod. In other words,
-   * you should not put all of the data for your mod on the same object. Instead, scope your
+   * you should not put all of the variables for your mod on the same object. Instead, scope your
    * variables locally to a single file that contains a mod feature, and then call this function to
    * register them. For example:
    *
    * ```ts
    * // In file: feature1.ts
-   * import { saveDataManager } from "isaacscript-common";
    *
    * // Declare local variables for this file or feature.
    * const v = {
@@ -259,13 +258,12 @@ export class SaveDataManager extends Feature {
    *     foo4: 0,
    *   },
    * };
-   * // Every child object is optional; only create the ones that you need.
+   * // The child objects of "persistent", "run", "level", and "room are optional; only create the
+   * // ones that you need.
    *
-   * // Register the variables with the save data manager. (We need to provide a string key that
-   * // matches the name of this file.)
-   * function feature1Init() {
-   *   saveDataManager("feature1", v);
-   * }
+   * // Now, give `v` to the save data manager, and it will automatically manage the variables for
+   * // you.
+   * mod.saveDataManager("feature1", v);
    *
    * // Elsewhere in the file, use your variables.
    * function feature1Function() {

package/src/functions/array.ts

@@ -232,6 +232,33 @@ export function emptyArray<T>(array: T[]): void {
   array.splice(0, array.length);
 }
 
+/**
+ * Helper function to perform a map and a filter at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because a map will always produce an array with the same amount of
+ * elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ */
+export function filterMap<OldT, NewT>(
+  array: OldT[],
+  func: (element: OldT) => NewT | undefined,
+): NewT[] {
+  const newArray: NewT[] = [];
+
+  for (const element of array) {
+    const newElement = func(element);
+    if (newElement !== undefined) {
+      newArray.push(newElement);
+    }
+  }
+
+  return newArray;
+}
+
 /**
  * Helper function to get all possible combinations of the given array. This includes the
  * combination of an empty array.

package/src/functions/modFeatures.ts

@@ -11,16 +11,16 @@ import type { ModUpgraded } from "../classes/ModUpgraded";
  * For example:
  *
  * ```ts
- * const features = [
+ * const MOD_FEATURES = [
  *   MyFeature1,
  *   MyFeature2,
  *   MyFeature3,
  * ] as const;
- * initModFeatures(mod, modFeatures);
+ * initModFeatures(mod, MOD_FEATURES);
  * ```
  *
  * @returns An array of the instantiated features in the same order that the constructors were
- *          passed in.
+ *          passed in. (In most cases, you probably won't need the returned array.)
  */
 export function initModFeatures<T extends ReadonlyArray<typeof ModFeature>>(
   mod: ModUpgraded,