isaacscript-common 3.17.0 → 4.0.2

package/functions/color.ts

@@ -0,0 +1,128 @@
+import { SerializationBrand } from "../enums/private/SerializationBrand";
+import { SerializationType } from "../enums/SerializationType";
+import { isaacAPIClassEquals, isIsaacAPIClassOfType } from "./isaacAPIClass";
+import { copyValuesToTable, getNumbersFromTable, tableHasKeys } from "./table";
+import { isTable } from "./types";
+
+type SerializedColor = LuaTable<string, unknown> & {
+  readonly __serializedColorBrand: unique symbol;
+};
+
+interface CopyColorReturn {
+  [SerializationType.NONE]: Color;
+  [SerializationType.SERIALIZE]: SerializedColor;
+  [SerializationType.DESERIALIZE]: Color;
+}
+
+const KEYS = ["R", "G", "B", "A", "RO", "GO", "BO"];
+const OBJECT_NAME = "Color";
+
+export function colorEquals(color1: Color, color2: Color): boolean {
+  return isaacAPIClassEquals(color1, color2, KEYS);
+}
+
+/**
+ * Helper function to copy a `Color` object.
+ *
+ * @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`.
+ */
+export function copyColor<
+  C extends Color | SerializedColor,
+  S extends SerializationType,
+>(color: C, serializationType: S): CopyColorReturn[S];
+export function copyColor<C extends Color | SerializedColor>(
+  color: C,
+): CopyColorReturn[SerializationType.NONE];
+export function copyColor(
+  color: Color | SerializedColor,
+  serializationType = SerializationType.NONE,
+): CopyColorReturn[keyof CopyColorReturn] {
+  switch (serializationType) {
+    case SerializationType.NONE: {
+      if (!isColor(color)) {
+        error(
+          `Failed to copy a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+        );
+      }
+
+      return Color(
+        color.R,
+        color.G,
+        color.B,
+        color.A,
+        color.RO,
+        color.GO,
+        color.BO,
+      );
+    }
+
+    case SerializationType.SERIALIZE: {
+      if (!isColor(color)) {
+        error(
+          `Failed to serialize a ${OBJECT_NAME} object since the provided object was not a userdata ${OBJECT_NAME} class.`,
+        );
+      }
+
+      const colorTable = new LuaTable<string, unknown>();
+      copyValuesToTable(color, KEYS, colorTable);
+      colorTable.set(SerializationBrand.COLOR, "");
+      return colorTable as SerializedColor;
+    }
+
+    case SerializationType.DESERIALIZE: {
+      if (!isTable(color)) {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object was not a Lua table.`,
+        );
+      }
+
+      const [r, g, b, a, ro, go, bo] = getNumbersFromTable(
+        color as LuaTable<string, unknown>,
+        OBJECT_NAME,
+        ...KEYS,
+      );
+
+      if (r === undefined) {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: r`,
+        );
+      }
+      if (g === undefined) {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: g`,
+        );
+      }
+      if (b === undefined) {
+        error(
+          `Failed to deserialize a ${OBJECT_NAME} object since the provided object did not have a value for: b`,
+        );
+      }
+
+      return Color(r, g, b, a, ro, go, bo);
+    }
+  }
+}
+
+/** Returns `Color(1, 1, 1)`. */
+export function getDefaultColor(): Color {
+  return Color(1, 1, 1);
+}
+
+/** Helper function to check if something is an instantiated Color object. */
+export function isColor(object: unknown): object is Color {
+  return isIsaacAPIClassOfType(object, OBJECT_NAME);
+}
+
+/**
+ * Used to determine is the given table is a serialized `Color` object created by the save data
+ * manager and/or the `deepCopy` function.
+ */
+export function isSerializedColor(object: unknown): object is SerializedColor {
+  if (!isTable(object)) {
+    return false;
+  }
+
+  return tableHasKeys(object, ...KEYS) && object.has(SerializationBrand.COLOR);
+}

package/functions/debug.lua

@@ -24,7 +24,7 @@ end
 -- This function uses the `package` global variable as a proxy to determine if the "--luadebug" flag
 -- is enabled or not.
 function ____exports.isLuaDebugEnabled(self)
-    return package ~= nil
+    return _G.package ~= nil
 end
 --- Helper function to print a stack trace to the "log.txt" file, similar to JavaScript's
 -- `console.trace` function.
@@ -36,7 +36,7 @@ function ____exports.traceback(self)
     log(tracebackOutput)
 end
 local function setDebugFunctionsGlobal(self)
-    if debug == nil and sandboxGetTraceback == nil then
+    if _G.debug == nil and sandboxGetTraceback == nil then
         return
     end
     local globals = _G

package/functions/debug.ts

@@ -0,0 +1,68 @@
+import { log } from "./log";
+
+/**
+ * Helper function to get a stack trace.
+ *
+ * This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+ * enabled.
+ */
+export function getTraceback(): string {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (debug !== undefined) {
+    // The --luadebug launch flag is enabled.
+    return debug.traceback();
+  }
+
+  if (sandboxGetTraceback !== undefined) {
+    return sandboxGetTraceback();
+  }
+
+  return 'stack traceback:\n(the "--luadebug" flag is not enabled)';
+}
+
+/**
+ * Players can boot the game with an launch option called "--luadebug", which will enable additional
+ * functionality that is considered to be unsafe. For more information about this flag, see the
+ * wiki: https://bindingofisaacrebirth.fandom.com/wiki/Launch_Options
+ *
+ * When this flag is enabled, the global environment will be slightly different. The differences are
+ * documented here: https://wofsauge.github.io/IsaacDocs/rep/Globals.html
+ *
+ * This function uses the `package` global variable as a proxy to determine if the "--luadebug" flag
+ * is enabled or not.
+ */
+export function isLuaDebugEnabled(): boolean {
+  // "package" is not always defined like the Lua definitions imply.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return _G.package !== undefined;
+}
+
+/**
+ * Helper function to print a stack trace to the "log.txt" file, similar to JavaScript's
+ * `console.trace` function.
+ *
+ * This will only work if the `--luadebug` launch option is enabled or the Racing+ sandbox is
+ * enabled.
+ */
+export function traceback(): void {
+  const tracebackOutput = getTraceback();
+  log(tracebackOutput);
+}
+
+function setDebugFunctionsGlobal() {
+  // "debug" is not always defined like the Lua definitions imply.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (_G.debug === undefined && sandboxGetTraceback === undefined) {
+    return;
+  }
+
+  const globals = _G as Record<string, unknown>;
+
+  globals["getTraceback"] = getTraceback;
+  globals["traceback"] = traceback;
+}
+
+// If the debug functions will provide useful output, make them global by default.
+if (isLuaDebugEnabled() || sandboxGetTraceback !== undefined) {
+  setDebugFunctionsGlobal();
+}

package/functions/deepCopy.lua

@@ -6,7 +6,7 @@ local __TS__Iterator = ____lualib.__TS__Iterator
 local __TS__ArraySort = ____lualib.__TS__ArraySort
 local __TS__ArraySome = ____lualib.__TS__ArraySome
 local ____exports = {}
-local deepCopyTable, deepCopyDefaultMap, deepCopyMap, deepCopySet, deepCopyTSTLClass, deepCopyArray, deepCopyNormalLuaTable, getCopiedEntries, checkMetatable, deepCopyUserdata, COPYABLE_ISAAC_API_CLASS_TYPES_SET
+local deepCopyTable, deepCopyDefaultMap, getNewDefaultMap, deepCopyMap, deepCopySet, deepCopyTSTLClass, deepCopyArray, deepCopyNormalLuaTable, getCopiedEntries, checkMetatable, deepCopyUserdata, COPYABLE_ISAAC_API_CLASS_TYPES_SET
 local ____DefaultMap = require("classes.DefaultMap")
 local DefaultMap = ____DefaultMap.DefaultMap
 local ____CopyableIsaacAPIClassType = require("enums.private.CopyableIsaacAPIClassType")
@@ -43,7 +43,6 @@ local ____types = require("functions.types")
 local isNumber = ____types.isNumber
 local isPrimitive = ____types.isPrimitive
 local ____utils = require("functions.utils")
-local ensureAllCases = ____utils.ensureAllCases
 local getTraversalDescription = ____utils.getTraversalDescription
 local twoDimensionalSort = ____utils.twoDimensionalSort
 --- `deepCopy` is a semi-generic deep cloner. It will recursively copy all of the values so that none
@@ -119,11 +118,6 @@ function ____exports.deepCopy(self, value, serializationType, traversalDescripti
                 return deepCopyUserdata(nil, value, serializationType, traversalDescription)
             end
         end
-        do
-            do
-                return ensureAllCases(nil, valueType)
-            end
-        end
     until true
 end
 function deepCopyTable(self, luaTable, serializationType, traversalDescription)
@@ -163,48 +157,16 @@ function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescri
         ____isDefaultMap_result_0 = nil
     end
     local constructorArg = ____isDefaultMap_result_0
-    local newDefaultMap
-    repeat
-        local ____switch23 = serializationType
-        local ____cond23 = ____switch23 == SerializationType.NONE
-        if ____cond23 then
-            do
-                newDefaultMap = __TS__New(DefaultMap, constructorArg)
-                break
-            end
-        end
-        ____cond23 = ____cond23 or ____switch23 == SerializationType.SERIALIZE
-        if ____cond23 then
-            do
-                if not isPrimitive(nil, constructorArg) then
-                    return deepCopyMap(nil, defaultMap, serializationType, traversalDescription)
-                end
-                newDefaultMap = {}
-                newDefaultMap[SerializationBrand.DEFAULT_MAP] = ""
-                newDefaultMap[SerializationBrand.DEFAULT_MAP_VALUE] = constructorArg
-                break
-            end
-        end
-        ____cond23 = ____cond23 or ____switch23 == SerializationType.DESERIALIZE
-        if ____cond23 then
-            do
-                if isDefaultMap(nil, defaultMap) then
-                    error(("The deep copy function failed to deserialize a default map of \"" .. traversalDescription) .. "\", since it was not a Lua table.")
-                end
-                local defaultMapValue = defaultMap[SerializationBrand.DEFAULT_MAP_VALUE]
-                if defaultMapValue == nil then
-                    error((("The deep copy function failed to deserialize a default map of \"" .. traversalDescription) .. "\", since there was no serialization brand of: ") .. SerializationBrand.DEFAULT_MAP_VALUE)
-                end
-                newDefaultMap = __TS__New(DefaultMap, defaultMapValue)
-                break
-            end
-        end
-        do
-            do
-                return ensureAllCases(nil, serializationType)
-            end
-        end
-    until true
+    if serializationType == SerializationType.SERIALIZE and not isPrimitive(nil, constructorArg) then
+        return deepCopyMap(nil, defaultMap, serializationType, traversalDescription)
+    end
+    local newDefaultMap = getNewDefaultMap(
+        nil,
+        defaultMap,
+        serializationType,
+        traversalDescription,
+        constructorArg
+    )
     local ____getCopiedEntries_result_1 = getCopiedEntries(nil, defaultMap, serializationType, traversalDescription)
     local entries = ____getCopiedEntries_result_1.entries
     local convertedNumberKeysToStrings = ____getCopiedEntries_result_1.convertedNumberKeysToStrings
@@ -226,6 +188,39 @@ function deepCopyDefaultMap(self, defaultMap, serializationType, traversalDescri
     end
     return newDefaultMap
 end
+function getNewDefaultMap(self, defaultMap, serializationType, traversalDescription, constructorArg)
+    repeat
+        local ____switch31 = serializationType
+        local ____cond31 = ____switch31 == SerializationType.NONE
+        if ____cond31 then
+            do
+                return __TS__New(DefaultMap, constructorArg)
+            end
+        end
+        ____cond31 = ____cond31 or ____switch31 == SerializationType.SERIALIZE
+        if ____cond31 then
+            do
+                local newDefaultMap = {}
+                newDefaultMap[SerializationBrand.DEFAULT_MAP] = ""
+                newDefaultMap[SerializationBrand.DEFAULT_MAP_VALUE] = constructorArg
+                return newDefaultMap
+            end
+        end
+        ____cond31 = ____cond31 or ____switch31 == SerializationType.DESERIALIZE
+        if ____cond31 then
+            do
+                if isDefaultMap(nil, defaultMap) then
+                    error(("The deep copy function failed to deserialize a default map of \"" .. traversalDescription) .. "\", since it was not a Lua table.")
+                end
+                local defaultMapValue = defaultMap[SerializationBrand.DEFAULT_MAP_VALUE]
+                if defaultMapValue == nil then
+                    error((("The deep copy function failed to deserialize a default map of \"" .. traversalDescription) .. "\", since there was no serialization brand of: ") .. SerializationBrand.DEFAULT_MAP_VALUE)
+                end
+                return __TS__New(DefaultMap, defaultMapValue)
+            end
+        end
+    until true
+end
 function deepCopyMap(self, map, serializationType, traversalDescription)
     local newMap
     if serializationType == SerializationType.SERIALIZE then
@@ -358,14 +353,14 @@ function getCopiedEntries(self, object, serializationType, traversalDescription)
         local value = ____value[2]
         do
             if isSerializationBrand(nil, key) then
-                goto __continue79
+                goto __continue78
             end
             traversalDescription = getTraversalDescription(nil, key, traversalDescription)
             local newValue = ____exports.deepCopy(nil, value, serializationType, traversalDescription)
             local keyToUse = convertNumberKeysToStrings and tostring(key) or key
             copiedEntries[#copiedEntries + 1] = {keyToUse, newValue}
         end
-        ::__continue79::
+        ::__continue78::
     end
     return {entries = copiedEntries, convertedNumberKeysToStrings = convertNumberKeysToStrings}
 end