isaacscript-common 20.12.2 → 20.13.0

package/src/functions/logMisc.ts

@@ -31,7 +31,7 @@ import { isTable, isUserdata } from "./types";
 import { vectorToString } from "./vector";
 
 /** Helper function to enumerate all of the values in an array. */
-export function logArray<T>(array: T[] | readonly T[]): void {
+export function logArray<T>(this: void, array: T[] | readonly T[]): void {
   // We do not assume the given array has contiguous values in order to be more permissive about the
   // kinds of arrays that will successfully log without a run-time error.
   if (!isArray(array, false)) {
@@ -43,7 +43,10 @@ export function logArray<T>(array: T[] | readonly T[]): void {
   log(`Array: ${arrayString}`);
 }
 
-export function logCollectibleTypes(collectibleTypes: CollectibleType[]): void {
+export function logCollectibleTypes(
+  this: void,
+  collectibleTypes: CollectibleType[],
+): void {
   log("Collectibles:");
 
   let i = 1;
@@ -54,23 +57,29 @@ export function logCollectibleTypes(collectibleTypes: CollectibleType[]): void {
   }
 }
 
-export function logColor(color: Color): void {
+export function logColor(this: void, color: Color): void {
   log(
     `Color: R${color.R}, G${color.G}, B${color.B}, A${color.A}, RO${color.RO}, BO${color.BO}, GO${color.GO}`,
   );
 }
 
 /** Helper function for printing out every damage flag that is turned on. Useful when debugging. */
-export function logDamageFlags(flags: DamageFlag | BitFlags<DamageFlag>): void {
+export function logDamageFlags(
+  this: void,
+  flags: DamageFlag | BitFlags<DamageFlag>,
+): void {
   logFlags(flags, DamageFlag, "damage");
 }
 
 /** Helper function for printing out every entity flag that is turned on. Useful when debugging. */
-export function logEntityFlags(flags: EntityFlag | BitFlags<EntityFlag>): void {
+export function logEntityFlags(
+  this: void,
+  flags: EntityFlag | BitFlags<EntityFlag>,
+): void {
   logFlags(flags, EntityFlag, "entity");
 }
 
-export function logEntityID(entity: Entity): void {
+export function logEntityID(this: void, entity: Entity): void {
   const entityID = getEntityID(entity);
   log(`Entity: ${entityID}`);
 }
@@ -81,7 +90,7 @@ export function logEntityID(entity: Entity): void {
  * This is useful in situations where using the `error` function would be dangerous (since it
  * prevents all of the subsequent code in the callback from running).
  */
-export function logError(msg: string): void {
+export function logError(this: void, msg: string): void {
   const errorMsg = `Error: ${msg}`;
   log(errorMsg);
   print(errorMsg);
@@ -89,6 +98,7 @@ export function logError(msg: string): void {
 
 /** Helper function for printing out every flag that is turned on. Useful when debugging. */
 export function logFlags<T extends BitFlag | BitFlag128>(
+  this: void,
   flags: T | BitFlags<T>,
   flagEnum: Record<string, T>,
   description = "",
@@ -116,7 +126,7 @@ export function logFlags<T extends BitFlag | BitFlag128>(
 /**
  * Helper function for printing out every game state flag that is turned on. Useful when debugging.
  */
-export function logGameStateFlags(): void {
+export function logGameStateFlags(this: void): void {
   log("Logging game state flags:");
 
   const gameStateFlagEntries = getEnumEntries(GameStateFlag);
@@ -135,7 +145,7 @@ export function logGameStateFlags(): void {
   }
 }
 
-export function logKColor(kColor: KColor): void {
+export function logKColor(this: void, kColor: KColor): void {
   log(
     `Color: R${kColor.Red}, G${kColor.Green}, B${kColor.Blue}, A${kColor.Alpha}`,
   );
@@ -144,7 +154,7 @@ export function logKColor(kColor: KColor): void {
 /**
  * Helper function for printing out every level state flag that is turned on. Useful when debugging.
  */
-export function logLevelStateFlags(): void {
+export function logLevelStateFlags(this: void): void {
   const level = game.GetLevel();
 
   const levelStateFlagEntries = getEnumEntries(LevelStateFlag);
@@ -164,7 +174,7 @@ export function logLevelStateFlags(): void {
   }
 }
 
-export function logMap(map: Map<AnyNotNil, unknown>): void {
+export function logMap(this: void, map: Map<AnyNotNil, unknown>): void {
   if (!isTSTLMap(map) && !isDefaultMap(map)) {
     log("Tried to log a TSTL map, but the given object was not a TSTL map.");
     return;
@@ -184,7 +194,7 @@ export function logMap(map: Map<AnyNotNil, unknown>): void {
   log(`  The size of the map was: ${map.size}`);
 }
 
-export function logPlayerEffects(player: EntityPlayer): void {
+export function logPlayerEffects(this: void, player: EntityPlayer): void {
   const effects = getEffectsList(player);
 
   log("Logging player effects:");
@@ -212,7 +222,7 @@ export function logPlayerEffects(player: EntityPlayer): void {
   });
 }
 
-export function logPlayerHealth(player: EntityPlayer): void {
+export function logPlayerHealth(this: void, player: EntityPlayer): void {
   const playerName = getPlayerName(player);
   const playerHealth = getPlayerHealth(player);
 
@@ -238,13 +248,14 @@ export function logPlayerHealth(player: EntityPlayer): void {
  * Helper function for printing out every projectile flag that is turned on. Useful when debugging.
  */
 export function logProjectileFlags(
+  this: void,
   flags: ProjectileFlag | BitFlags<ProjectileFlag>,
 ): void {
   logFlags(flags, ProjectileFlag, "projectile");
 }
 
 /** Helper function for logging information about the current room. */
-export function logRoom(): void {
+export function logRoom(this: void): void {
   const room = game.GetRoom();
   const bossID = room.GetBossID();
   const roomGridIndex = getRoomGridIndex();
@@ -277,7 +288,7 @@ export function logRoom(): void {
  * Helper function for printing out every seed effect (i.e. Easter Egg) that is turned on for the
  * particular run.
  */
-export function logSeedEffects(): void {
+export function logSeedEffects(this: void): void {
   const seeds = game.GetSeeds();
 
   const seedEffectEntries = getEnumEntries(SeedEffect);
@@ -296,7 +307,10 @@ export function logSeedEffects(): void {
   }
 }
 
-export function logSet(set: Set<AnyNotNil> | ReadonlySet<AnyNotNil>): void {
+export function logSet(
+  this: void,
+  set: Set<AnyNotNil> | ReadonlySet<AnyNotNil>,
+): void {
   if (!isTSTLSet(set)) {
     log("Tried to log a TSTL set, but the given object was not a TSTL set.");
     return;
@@ -314,7 +328,7 @@ export function logSet(set: Set<AnyNotNil> | ReadonlySet<AnyNotNil>): void {
 }
 
 /** Helper function for logging every sound effect that is currently playing. */
-export function logSounds(): void {
+export function logSounds(this: void): void {
   const soundEffects = getEnumEntries(SoundEffect);
 
   for (const [key, soundEffect] of soundEffects) {
@@ -334,9 +348,13 @@ export function logSounds(): void {
  * In order to prevent infinite recursion, this function will not log a sub-table when there are 10
  * or more parent tables.
  */
-export function logTable(luaTable: unknown, parentTables = 0): void {
+export function logTable(
+  this: void,
+  luaTable: unknown,
+  parentTables = 0,
+): void {
   if (parentTables === 0) {
-    log("Printing out a Lua table:");
+    log("Printing out a Lua table:", false);
   } else if (parentTables > 10) {
     return;
   }
@@ -345,14 +363,10 @@ export function logTable(luaTable: unknown, parentTables = 0): void {
   const indentation = " ".repeat(numSpaces);
 
   if (!isTable(luaTable)) {
-    // Put it in an IIFE so that it will show as "func" instead of "logTable" and align with the
-    // other text. We have to use a non-arrow function to prevent Lua language server errors with
-    // the self argument.
-    (function func() {
-      log(
-        `${indentation}n/a (encountered a variable of type "${typeof luaTable}" instead of a table)`,
-      );
-    })();
+    log(
+      `${indentation}n/a (encountered a variable of type "${typeof luaTable}" instead of a table)`,
+      false,
+    );
 
     return;
   }
@@ -360,12 +374,13 @@ export function logTable(luaTable: unknown, parentTables = 0): void {
   let numElements = 0;
   iterateTableInOrder(luaTable, (key, value) => {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
-    log(`${indentation}${key} --> ${value}`);
+    log(`${indentation}${key} --> ${value}`, false);
 
     if (isTable(value)) {
       if (key === "__class") {
         log(
           `${indentation}  (skipping enumerating this key to avoid infinite recursion)`,
+          false,
         );
       } else {
         logTable(value, parentTables + 1);
@@ -375,12 +390,7 @@ export function logTable(luaTable: unknown, parentTables = 0): void {
     numElements++;
   });
 
-  // Put it in an IIFE so that it will show as "func" instead of "logTable" and align with the other
-  // text. We have to use a non-arrow function to prevent Lua language server errors with the self
-  // argument.
-  (function func() {
-    log(`${indentation}The size of the table was: ${numElements}`);
-  })();
+  log(`${indentation}The size of the table was: ${numElements}`, false);
 }
 
 /**
@@ -388,6 +398,7 @@ export function logTable(luaTable: unknown, parentTables = 0): void {
  * will only do a shallow comparison.
  */
 export function logTableDifferences<K extends AnyNotNil, V>(
+  this: void,
   table1: LuaMap<K, V>,
   table2: LuaMap<K, V>,
 ): void {
@@ -428,7 +439,7 @@ export function logTableDifferences<K extends AnyNotNil, V>(
  *
  * This function is useful for tables that have recursive references.
  */
-export function logTableKeys(luaTable: unknown): void {
+export function logTableKeys(this: void, luaTable: unknown): void {
   log("Printing out the keys of a Lua table:");
 
   if (!isTable(luaTable)) {
@@ -449,12 +460,18 @@ export function logTableKeys(luaTable: unknown): void {
 }
 
 /** Helper function for printing out every tear flag that is turned on. Useful when debugging. */
-export function logTearFlags(flags: TearFlag | BitFlags<TearFlag>): void {
+export function logTearFlags(
+  this: void,
+  flags: TearFlag | BitFlags<TearFlag>,
+): void {
   logFlags(flags, TearFlag, "tear");
 }
 
 /** Helper function for printing out every use flag that is turned on. Useful when debugging. */
-export function logUseFlags(flags: UseFlag | BitFlags<UseFlag>): void {
+export function logUseFlags(
+  this: void,
+  flags: UseFlag | BitFlags<UseFlag>,
+): void {
   logFlags(flags, UseFlag, "use");
 }
 
@@ -462,7 +479,7 @@ export function logUseFlags(flags: UseFlag | BitFlags<UseFlag>): void {
  * Helper function to enumerate all of the properties of a "userdata" object (i.e. an object from
  * the Isaac API).
  */
-export function logUserdata(userdata: unknown): void {
+export function logUserdata(this: void, userdata: unknown): void {
   if (!isUserdata(userdata)) {
     log("Userdata: [not userdata]");
     return;
@@ -484,7 +501,7 @@ export function logUserdata(userdata: unknown): void {
   logTable(metatable);
 }
 
-export function logVector(vector: Vector, round = false): void {
+export function logVector(this: void, vector: Vector, round = false): void {
   const vectorString = vectorToString(vector, round);
   log(`Vector: ${vectorString}`);
 }

package/src/functions/revive.ts

@@ -10,11 +10,13 @@ import {
   MAX_TAINTED_SAMSON_BERSERK_CHARGE,
   TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE,
 } from "../core/constants";
+import { MysteriousPaperEffect } from "../enums/MysteriousPaperEffect";
 import { getCharacterDeathAnimationName } from "./characters";
 import { getPlayerMaxHeartContainers } from "./playerHealth";
 import { getPlayerNumHitsRemaining, hasLostCurse, isKeeper } from "./players";
 import { getLastFrameOfAnimation } from "./sprites";
 import { giveTrinketsBack, temporarilyRemoveTrinket } from "./trinketGive";
+import { getMysteriousPaperEffectForFrame } from "./trinkets";
 
 /**
  * Uses the player's current health and other miscellaneous things to determine if incoming damage
@@ -123,7 +125,6 @@ export function isDamageToPlayerFatal(
  * Mysterious Paper be Missing Power is: `gameFrameCount % 4 === 3`
  */
 export function willMysteriousPaperRevive(player: EntityPlayer): boolean {
-  const gameFrameCount = game.GetFrameCount();
   const sprite = player.GetSprite();
 
   // We want to explicitly check the length of the death animation because we might be playing on a
@@ -131,10 +132,17 @@ export function willMysteriousPaperRevive(player: EntityPlayer): boolean {
   const character = player.GetPlayerType();
   const animation = getCharacterDeathAnimationName(character);
   const deathAnimationFrames = getLastFrameOfAnimation(sprite, animation);
-  const frameOfDeath = gameFrameCount + deathAnimationFrames + 1;
-  // (We add 1 because it takes one frame for the death animation to begin.)
+  const frameOfDeath = player.FrameCount + deathAnimationFrames;
+
+  const mysteriousPaperEffect = getMysteriousPaperEffectForFrame(
+    player,
+    frameOfDeath,
+  );
+  if (mysteriousPaperEffect === undefined) {
+    return false;
+  }
 
-  return frameOfDeath % 4 === 3;
+  return mysteriousPaperEffect === MysteriousPaperEffect.MISSING_POSTER;
 }
 
 /**

package/src/functions/trinkets.ts

@@ -10,6 +10,7 @@ import {
   FIRST_TRINKET_TYPE,
   LAST_VANILLA_TRINKET_TYPE,
 } from "../core/constantsFirstLast";
+import { MysteriousPaperEffect } from "../enums/MysteriousPaperEffect";
 import {
   DEFAULT_TRINKET_DESCRIPTION,
   TRINKET_DESCRIPTION_MAP,
@@ -19,6 +20,7 @@ import {
   TRINKET_TYPE_TO_NAME_MAP,
 } from "../maps/trinketTypeToNameMap";
 import { getEntityID } from "./entities";
+import { getEnumLength } from "./enums";
 import { hasFlag } from "./flag";
 import { isTrinket } from "./pickupVariants";
 import { isCharacter } from "./players";
@@ -35,6 +37,8 @@ import { iRange } from "./utils";
  */
 const GOLDEN_TRINKET_ADJUSTMENT = 32768;
 
+const NUM_MYSTERIOUS_PAPER_EFFECTS = getEnumLength(MysteriousPaperEffect);
+
 const TRINKET_ANM2_PATH = "gfx/005.350_trinket.anm2";
 const TRINKET_SPRITE_LAYER = 0;
 
@@ -48,6 +52,41 @@ export function getGoldenTrinketType(trinketType: TrinketType): TrinketType {
   return asNumber(trinketType) + GOLDEN_TRINKET_ADJUSTMENT;
 }
 
+/**
+ * Helper function to get the current effect that the Mysterious Paper trinket is providing to the
+ * player. Returns undefined if the player does not have the Mysterious Paper trinket.
+ *
+ * The Mysterious Paper trinket has four different effects:
+ *
+ * - The Polaroid (collectible)
+ * - The Negative (collectible)
+ * - A Missing Page (trinket)
+ * - Missing Poster (trinket)
+ *
+ * It rotates between these four effects on every frame. Note that Mysterious Paper will cause the
+ * `EntityPlayer.HasCollectible` and `EntityPlayer.HasTrinket` methods to return true for the
+ * respective items on the particular frame, with the exception of the Missing Poster. (The player
+ * will never "have" the Missing Poster, even on the correct corresponding frame.)
+ *
+ * @param player The player to look at.
+ * @param frameCount Optional. The frame count that corresponds to time the effect will be active.
+ *                   Default is the current frame.
+ */
+export function getMysteriousPaperEffectForFrame(
+  player: EntityPlayer,
+  frameCount?: int,
+): MysteriousPaperEffect | undefined {
+  if (frameCount === undefined) {
+    frameCount = player.FrameCount;
+  }
+
+  if (!player.HasTrinket(TrinketType.MYSTERIOUS_PAPER)) {
+    return undefined;
+  }
+
+  return frameCount % NUM_MYSTERIOUS_PAPER_EFFECTS;
+}
+
 /**
  * Returns the slot number corresponding to where a trinket can be safely inserted.
  *

package/src/functions/utils.ts

@@ -174,6 +174,28 @@ export function todo(...args: unknown[]): void {}
  * https://stackoverflow.com/questions/16096872/how-to-sort-2-dimensional-array-by-column-value
  */
 export function twoDimensionalSort<T>(array1: T[], array2: T[]): -1 | 0 | 1 {
+  const type1 = type(array1);
+  const type2 = type(array2);
+  if (type1 !== type2) {
+    error(
+      `Failed to two-dimensional sort since the two elements were disparate types: ${array1} & ${array2} (${type1} & ${type2})`,
+    );
+  }
+
+  if (type1 === "string" || type1 === "number") {
+    if (array1 === array2) {
+      return 0;
+    }
+
+    return array1 < array2 ? -1 : 1;
+  }
+
+  if (type1 !== "table") {
+    error(
+      "Failed to two-dimensional sort since the elements were not a string, number, or table.",
+    );
+  }
+
   const firstElement1 = array1[0];
   const firstElement2 = array2[0];
 
@@ -189,6 +211,14 @@ export function twoDimensionalSort<T>(array1: T[], array2: T[]): -1 | 0 | 1 {
     );
   }
 
+  const elementType1 = type(firstElement1);
+  const elementType2 = type(firstElement2);
+  if (elementType1 !== elementType2) {
+    error(
+      `Failed to two-dimensional sort since the first element of each array were disparate types: ${firstElement1} & ${firstElement2} (${elementType1} & ${elementType2})`,
+    );
+  }
+
   if (firstElement1 === firstElement2) {
     return 0;
   }

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./enums/HealthType";
 export * from "./enums/ISCFeature";
 export * from "./enums/LadderSubTypeCustom";
 export * from "./enums/ModCallbackCustom";
+export * from "./enums/MysteriousPaperEffect";
 export * from "./enums/PocketItemType";
 export * from "./enums/RockAltType";
 export * from "./enums/SaveDataKey";

package/src/lib/jsonLua.lua

@@ -24,6 +24,9 @@
 -- SOFTWARE.
 --
 
+-- The IsaacScript version of this file contains modifications for better error messages, which
+-- assist when debugging.
+
 local json = { _version = "0.1.2" }
 
 -------------------------------------------------------------------------------
@@ -58,9 +61,10 @@ local function encode_nil(val)
 end
 
 
-local function encode_table(val, stack)
+local function encode_table(val, stack, traversalDescription)
   local res = {}
   stack = stack or {}
+  traversalDescription = traversalDescription or ""
 
   -- Circular reference?
   if stack[val] then error("circular reference") end
@@ -72,7 +76,7 @@ local function encode_table(val, stack)
     local n = 0
     for k in pairs(val) do
       if type(k) ~= "number" then
-        error("invalid table: mixed or invalid key types")
+        error("invalid table: mixed or invalid key types for array, excepted number, got: " .. tostring(type(k)))
       end
       n = n + 1
     end
@@ -81,7 +85,8 @@ local function encode_table(val, stack)
     end
     -- Encode
     for i, v in ipairs(val) do
-      table.insert(res, encode(v, stack))
+      local newTraversalDescription = traversalDescription .. tostring(i) .. " - "
+      table.insert(res, encode(v, stack, newTraversalDescription))
     end
     stack[val] = nil
     return "[" .. table.concat(res, ",") .. "]"
@@ -89,10 +94,14 @@ local function encode_table(val, stack)
   else
     -- Treat as an object
     for k, v in pairs(val) do
+      local newTraversalDescription = traversalDescription .. tostring(k) .. " - "
       if type(k) ~= "string" then
-        error("invalid table: mixed or invalid key types")
+        error(
+          "invalid table: mixed or invalid key types for object \"" .. newTraversalDescription .. "\", "
+          .. "excepted string, got: " .. tostring(type(k))
+        )
       end
-      table.insert(res, encode(k, stack) .. ":" .. encode(v, stack))
+      table.insert(res, encode(k, stack, newTraversalDescription) .. ":" .. encode(v, stack, newTraversalDescription))
     end
     stack[val] = nil
     return "{" .. table.concat(res, ",") .. "}"
@@ -123,11 +132,11 @@ local type_func_map = {
 }
 
 
-encode = function(val, stack)
+encode = function(val, stack, traversalDescription)
   local t = type(val)
   local f = type_func_map[t]
   if f then
-    return f(val, stack)
+    return f(val, stack, traversalDescription)
   end
   error("unexpected type '" .. t .. "'")
 end