isaacscript-common 6.8.0 → 6.10.1

package/src/functions/jsonHelpers.ts

@@ -2,7 +2,7 @@ import * as json from "json";
 import { logError } from "./log";
 
 function tryDecode(this: void, jsonString: string) {
-  return json.decode(jsonString) as LuaTable;
+  return json.decode(jsonString) as LuaMap;
 }
 
 function tryEncode(this: void, luaTable: unknown) {
@@ -17,12 +17,12 @@ function tryEncode(this: void, luaTable: unknown) {
  * continue in cases where users have no current save data or have manually removed their existing
  * save data.)
  */
-export function jsonDecode(jsonString: string): LuaTable<AnyNotNil, unknown> {
+export function jsonDecode(jsonString: string): LuaMap<AnyNotNil, unknown> {
   const [ok, luaTableOrErrMsg] = pcall(tryDecode, jsonString);
   if (!ok) {
     // Instead of throwing an error, continue execution of the callback.
     logError(`Failed to convert the JSON string to a Lua table: ${jsonString}`);
-    return new LuaTable();
+    return new LuaMap();
   }
 
   return luaTableOrErrMsg;

package/src/functions/kColor.ts

@@ -4,7 +4,7 @@ import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedKColor = LuaTable<string, unknown> & {
+type SerializedKColor = LuaMap<string, unknown> & {
   readonly __serializedKColorBrand: symbol;
 };
 
@@ -53,7 +53,7 @@ export function copyKColor(
         );
       }
 
-      const kColorTable = new LuaTable<string, unknown>();
+      const kColorTable = new LuaMap<string, unknown>();
       copyValuesToTable(kColor, KEYS, kColorTable);
       kColorTable.set(SerializationBrand.K_COLOR, "");
       return kColorTable as SerializedKColor;
@@ -67,7 +67,7 @@ export function copyKColor(
       }
 
       const [r, g, b, a] = getNumbersFromTable(
-        kColor as LuaTable<string, unknown>,
+        kColor as LuaMap<string, unknown>,
         OBJECT_NAME,
         ...KEYS,
       );

package/src/functions/log.ts

@@ -640,6 +640,7 @@ export function logTable(
     return;
   }
 
+  let numElements = 0;
   iterateTableInOrder(luaTable, (key, value) => {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     log(`${indentation}${key} --> ${value}`);
@@ -653,12 +654,14 @@ export function logTable(
         logTable(value, parentTables + 1);
       }
     }
+
+    numElements++;
   });
 
   // Put it in an IIFE so that the it will show as "func" instead of "logTable" and align with the
   // other text.
   (() => {
-    log(`${indentation}The size of the table was: ${luaTable.length()}`);
+    log(`${indentation}The size of the table was: ${numElements}`);
   })();
 }
 
@@ -668,8 +671,8 @@ export function logTable(
  */
 export function logTableDifferences<K, V>(
   this: void,
-  table1: LuaTable<K, V>,
-  table2: LuaTable<K, V>,
+  table1: LuaMap<K, V>,
+  table2: LuaMap<K, V>,
 ): void {
   log("Comparing two Lua tables:");
 
@@ -725,7 +728,7 @@ export function logUserdata(this: void, userdata: unknown): void {
   }
 
   const metatable = getmetatable(userdata) as
-    | LuaTable<AnyNotNil, unknown>
+    | LuaMap<AnyNotNil, unknown>
     | undefined;
   if (metatable === undefined) {
     log("Userdata: [no metatable]");

package/src/functions/mergeTests.ts

@@ -8,8 +8,8 @@ import { isSerializedIsaacAPIClass } from "./serialization";
 import { copyVector, isVector } from "./vector";
 
 /**
- * Run the suite of tests that prove that the "merge" helper function works properly. (This function
- * is not exported but is used internally in the save data manager.)
+ * Run the suite of tests that prove that the "merge" function works properly. (This function is not
+ * exported but is used internally in the save data manager.)
  *
  * This function is only useful if you are troubleshooting the save data manager.
  */
@@ -37,10 +37,10 @@ function oldTableHasUpdatedValue() {
   const newValue = "baz";
   const oldTable = {
     foo: oldValue,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const newTable = {
     foo: newValue,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "oldTableHasUpdatedValue");
 
@@ -56,10 +56,10 @@ function newTableHasSameValue() {
   const newValue = "baz";
   const oldTable = {
     foo: oldValue,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const newTable = {
     foo: newValue,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "newTableHasSameValue");
 
@@ -74,10 +74,10 @@ function oldTableHasUpdatedValueFromNull() {
   const newValue = "baz";
   const oldTable = {
     foo: null as string | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const newTable = {
     foo: newValue,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "oldTableHasUpdatedValueFromNull");
 
@@ -109,13 +109,13 @@ function oldTableHasFilledChildTable() {
   const newValue = "baz";
   const oldTable = {
     foo: null as Foo | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const foo: Foo = {
     bar: newValue,
   };
   const newTable = {
     foo,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "oldTableHasFilledChildTable");
 
@@ -148,8 +148,8 @@ function oldTableHasFilledMap() {
   const serializedSaveData = deepCopy(saveData, SerializationType.SERIALIZE);
 
   merge(
-    v as unknown as LuaTable,
-    serializedSaveData as LuaTable,
+    v as unknown as LuaMap,
+    serializedSaveData as LuaMap,
     "oldTableHasFilledMap",
   );
 
@@ -216,8 +216,8 @@ function oldTableHasFilledDefaultMap() {
   const serializedSaveData = deepCopy(saveData, SerializationType.SERIALIZE);
 
   merge(
-    v as unknown as LuaTable,
-    serializedSaveData as LuaTable,
+    v as unknown as LuaMap,
+    serializedSaveData as LuaMap,
     "oldTableHasFilledDefaultMap",
   );
 
@@ -278,13 +278,13 @@ function oldTableHasVector() {
   const newValue = Vector(x, y);
   const oldTable = {
     foo: null as Foo | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const foo: Foo = {
     bar: newValue,
   };
   const newTable = {
     foo,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "oldTableHasVector");
 
@@ -319,18 +319,18 @@ function oldTableHasVectorSerialized() {
   const newValue = Vector(x, y);
   const oldTable = {
     foo: null as Foo | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const foo: Foo = {
     bar: newValue,
   };
   const newTable = {
     foo,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const newTableSerialized = deepCopy(
     newTable,
     SerializationType.SERIALIZE,
     "oldTableHasVectorSerialized",
-  ) as LuaTable<AnyNotNil, unknown>;
+  ) as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTableSerialized, "oldTableHasVectorSerialized");
 
@@ -366,13 +366,13 @@ function oldTableHasRNG() {
   const newValue = newRNG(seed);
   const oldTable = {
     foo: null as Foo | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const foo: Foo = {
     bar: newValue,
   };
   const newTable = {
     foo,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTable, "oldTableHasRNG");
 
@@ -403,18 +403,18 @@ function oldTableHasRNGSerialized() {
   const newValue = newRNG(seed);
   const oldTable = {
     foo: null as Foo | null,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const foo: Foo = {
     bar: newValue,
   };
   const newTable = {
     foo,
-  } as unknown as LuaTable<AnyNotNil, unknown>;
+  } as unknown as LuaMap<AnyNotNil, unknown>;
   const newTableSerialized = deepCopy(
     newTable,
     SerializationType.SERIALIZE,
     "oldTableHasRNGSerialized",
-  ) as LuaTable<AnyNotNil, unknown>;
+  ) as LuaMap<AnyNotNil, unknown>;
 
   merge(oldTable, newTableSerialized, "oldTableHasRNGSerialized");
 

package/src/functions/playerIndex.ts

@@ -64,7 +64,7 @@ export function getPlayerFromIndex(
  * this is not desired, pass true for the `differentiateForgottenAndSoul` argument, and the RNG of
  * Spoon Bender (3) will be used for The Soul.
  *
- * Also note that this index doesn't work in the `POST_PLAYER_INIT` function for players 2 through
+ * Also note that this index does not work in the `POST_PLAYER_INIT` function for players 2 through
  * 4. With that said, in almost all cases, you should be lazy-initializing your data structures in
  * other callbacks, so this should not be an issue.
  */

package/src/functions/rng.ts

@@ -5,7 +5,7 @@ import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedRNG = LuaTable<string, unknown> & {
+type SerializedRNG = LuaMap<string, unknown> & {
   readonly __serializedRNGBrand: symbol;
 };
 
@@ -63,7 +63,7 @@ export function copyRNG(
       }
 
       const seed = rng.GetSeed();
-      const rngTable = new LuaTable<string, unknown>();
+      const rngTable = new LuaMap<string, unknown>();
       rngTable.set("seed", seed);
       rngTable.set(SerializationBrand.RNG, "");
       return rngTable as SerializedRNG;
@@ -77,7 +77,7 @@ export function copyRNG(
       }
 
       const [seedNumber] = getNumbersFromTable(
-        rng as LuaTable<string, unknown>,
+        rng as LuaMap<string, unknown>,
         OBJECT_NAME,
         ...KEYS,
       );

package/src/functions/run.ts

@@ -1,6 +1,7 @@
 import { Challenge, PlayerType } from "isaac-typescript-definitions";
 import { game } from "../cachedClasses";
 import { FIRST_CHARACTER } from "../constantsFirstLast";
+import { runNextRenderFrame } from "../features/runInNFrames";
 import { log } from "./log";
 
 /**
@@ -42,6 +43,19 @@ export function restart(character?: PlayerType): void {
   Isaac.ExecuteCommand(command);
 }
 
+/**
+ * Helper function to restart on the next render frame. Useful because it is impossible to restart
+ * the game inside of the `POST_NEW_ROOM`, `POST_NEW_LEVEL`, or `POST_GAME_STARTED` callbacks when a
+ * run is first starting.
+ *
+ * You can optionally specify a `PlayerType` to restart the game as that character.
+ */
+export function restartNextRenderFrame(character?: PlayerType): void {
+  runNextRenderFrame(() => {
+    restart(character);
+  });
+}
+
 /**
  * Helper function to change the run status to that of an unseeded run with a new random seed.
  *

package/src/functions/table.ts

@@ -1,12 +1,12 @@
 import { isBoolean, isNumber, isString } from "./types";
 
 /**
- * In a Map, you can use the `clear` method to delete every element. However, in a LuaTable, the
+ * In a `Map`, you can use the `clear` method to delete every element. However, in a `LuaMap`, the
  * `clear` method does not exist. Use this helper function as a drop-in replacement for this.
  */
-export function clearTable(luaTable: LuaTable): void {
-  for (const [key] of pairs(luaTable)) {
-    luaTable.delete(key);
+export function clearTable(luaMap: LuaMap): void {
+  for (const [key] of pairs(luaMap)) {
+    luaMap.delete(key);
   }
 }
 
@@ -14,13 +14,13 @@ export function clearTable(luaTable: LuaTable): void {
 export function copyValuesToTable(
   object: unknown,
   keys: string[],
-  luaTable: LuaTable<string, unknown>,
+  luaMap: LuaMap<string, unknown>,
 ): void {
-  const otherTable = object as LuaTable<string, string | number>;
+  const otherTable = object as LuaMap<string, string | number>;
 
   for (const key of keys) {
     const value = otherTable.get(key);
-    luaTable.set(key, value);
+    luaMap.set(key, value);
   }
 }
 
@@ -31,13 +31,13 @@ export function copyValuesToTable(
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
 export function getBooleansFromTable(
-  luaTable: LuaTable<string, unknown>,
+  luaMap: LuaMap<string, unknown>,
   objectName: string,
   ...keys: string[]
 ): boolean[] {
   const booleans: boolean[] = [];
   for (const key of keys) {
-    const value = luaTable.get(key);
+    const value = luaMap.get(key);
     if (value === undefined) {
       error(
         `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
@@ -63,13 +63,13 @@ export function getBooleansFromTable(
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
 export function getNumbersFromTable(
-  luaTable: LuaTable<string, unknown>,
+  luaMap: LuaMap<string, unknown>,
   objectName: string,
   ...keys: string[]
 ): number[] {
   const numbers: number[] = [];
   for (const key of keys) {
-    const value = luaTable.get(key);
+    const value = luaMap.get(key);
     if (value === undefined) {
       error(
         `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
@@ -103,13 +103,13 @@ export function getNumbersFromTable(
  * This function is variadic, meaning that you can specify N arguments to get N values.
  */
 export function getStringsFromTable(
-  luaTable: LuaTable<string, unknown>,
+  luaMap: LuaMap<string, unknown>,
   objectName: string,
   ...keys: string[]
 ): string[] {
   const strings: string[] = [];
   for (const key of keys) {
-    const value = luaTable.get(key);
+    const value = luaMap.get(key);
     if (value === undefined) {
       error(
         `Failed to find a value for "${key}" in a table representing a "${objectName}" object.`,
@@ -136,42 +136,44 @@ export function getStringsFromTable(
  * This function will only work on tables that have number keys or string keys. It will throw a
  * run-time error if it encounters a key of another type.
  *
- * @param luaTable The table to iterate over.
+ * @param luaMap The table to iterate over.
  * @param func The function to run for each iteration.
  * @param inOrder Optional. Whether to iterate in order. True by default. You can dynamically set to
  *                false in situations where iterating randomly would not matter and you need the
  *                extra performance.
  */
 export function iterateTableInOrder<K, V>(
-  luaTable: LuaTable<K, V>,
+  luaMap: LuaMap<K, V>,
   func: (key: K, value: V) => void,
   inOrder = true,
 ): void {
   // First, handle the trivial case of a non-deterministic iteration.
   if (!inOrder) {
-    for (const [key, value] of pairs(luaTable)) {
+    for (const [key, value] of luaMap) {
       func(key, value);
     }
     return;
   }
 
-  const keys = Object.keys(luaTable);
+  const keys = Object.keys(luaMap);
   const hasAllNumberKeys = keys.every((key) => isNumber(key));
   const hasAllStringKeys = keys.every((key) => isString(key));
   if (!hasAllNumberKeys && !hasAllStringKeys) {
     // Since the table has non-homogenous keys, we won't be able to sort it. Revert to
     // non-deterministic iteration in this case.
-    for (const [key, value] of pairs(luaTable)) {
+    for (const [key, value] of luaMap) {
       func(key, value);
     }
     return;
   }
-  keys.sort();
 
+  keys.sort();
   for (const key of keys) {
     const keyIndex = key as unknown as K;
-    const value = luaTable.get(keyIndex);
-    func(keyIndex, value);
+    const value = luaMap.get(keyIndex);
+    if (value !== undefined) {
+      func(keyIndex, value);
+    }
   }
 }
 
@@ -182,8 +184,8 @@ export function iterateTableInOrder<K, V>(
  * for.
  */
 export function tableHasKeys(
-  luaTable: LuaTable<AnyNotNil, unknown>,
+  luaMap: LuaMap<AnyNotNil, unknown>,
   ...keys: string[]
 ): boolean {
-  return keys.every((key) => luaTable.has(key));
+  return keys.every((key) => luaMap.has(key));
 }

package/src/functions/tstlClass.ts

@@ -146,7 +146,7 @@ export function newTSTLClass(oldClass: TSTLClass): TSTLClass {
 
 /** This is a re-implementation of the transpiled "__TS__New" function. */
 function newTSTLClassFromMetatable(metatable: TSTLClassMetatable): TSTLClass {
-  const newClass = new LuaTable<AnyNotNil, unknown>();
+  const newClass = new LuaMap<AnyNotNil, unknown>();
   const newClassMetatable = setmetatable(
     newClass,
     metatable.constructor.prototype,

package/src/functions/types.ts

@@ -27,7 +27,9 @@ export function isString(variable: unknown): variable is string {
   return type(variable) === "string";
 }
 
-export function isTable(variable: unknown): variable is LuaTable {
+export function isTable(
+  variable: unknown,
+): variable is LuaMap<AnyNotNil, unknown> {
   return type(variable) === "table";
 }
 

package/src/functions/vector.ts

@@ -6,7 +6,7 @@ import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
 import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
 import { isTable } from "./types";
 
-type SerializedVector = LuaTable<string, unknown> & {
+type SerializedVector = LuaMap<string, unknown> & {
   readonly __serializedVectorBrand: symbol;
 };
 
@@ -55,7 +55,7 @@ export function copyVector(
         );
       }
 
-      const vectorTable = new LuaTable<string, unknown>();
+      const vectorTable = new LuaMap<string, unknown>();
       copyValuesToTable(vector, KEYS, vectorTable);
       vectorTable.set(SerializationBrand.VECTOR, "");
       return vectorTable as SerializedVector;
@@ -69,7 +69,7 @@ export function copyVector(
       }
 
       const [x, y] = getNumbersFromTable(
-        vector as LuaTable<string, unknown>,
+        vector as LuaMap<string, unknown>,
         OBJECT_NAME,
         ...KEYS,
       );

package/src/interfaces/SaveData.ts

@@ -15,7 +15,7 @@
  * - `Set`
  * - serializable Isaac API classes (such as `Color`)
  * - TSTL classes (i.e. classes that you made yourself)
- * - sub-objects or a `LuaTable` that contains the above values
+ * - sub-objects or a `LuaMap` that contains the above values
  *
  * (Unfortunately, it is not possible to create a recursive type definition that matches these
  * properties. This means that the TypeScript compiler will not be able to validate that you are

package/src/interfaces/private/TSTLClassMetatable.ts

@@ -3,6 +3,6 @@ export interface TSTLClassMetatable {
   __index: unknown;
   constructor: {
     name: string;
-    prototype: LuaMetatable<LuaTable<AnyNotNil, unknown>>;
+    prototype: LuaMetatable<LuaMap<AnyNotNil, unknown>>;
   };
 }

package/src/types/PlayerIndex.ts

@@ -1,6 +1,7 @@
 /**
- * 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.
+ * PlayerIndex is a specific type of number that represents a unique identifier for a player. Mods
+ * can signify that data structures handle `EntityPlayer` by using this type. For more information,
+ * see the documentation for the `getPlayerIndex` function.
  *
  * For example:
  *

package/src/types/private/IsaacAPIClass.ts

@@ -1,3 +1,3 @@
-export type IsaacAPIClass = LuaTable<string, unknown> & {
+export type IsaacAPIClass = LuaMap<string, unknown> & {
   readonly __isaacAPIClassBrand: symbol;
 };

package/src/types/private/SerializedIsaacAPIClass.ts

@@ -1,3 +1,3 @@
-export type SerializedIsaacAPIClass = LuaTable<string, unknown> & {
+export type SerializedIsaacAPIClass = LuaMap<string, unknown> & {
   readonly __serializedIsaacAPIClassBrand: symbol;
 };

package/src/types/private/TSTLClass.ts

@@ -1,3 +1,3 @@
-export type TSTLClass = LuaTable<AnyNotNil, unknown> & {
+export type TSTLClass = LuaMap<AnyNotNil, unknown> & {
   readonly __tstlClassBrand: symbol;
 };

package/dist/features/saveDataManager/serializationBrand.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"serializationBrand.d.ts","sourceRoot":"","sources":["../../../src/features/saveDataManager/serializationBrand.ts"],"names":[],"mappings":"AASA,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAM1D"}