isaacscript-common 84.0.1 → 84.1.0

package/dist/functions/console.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printEnabled = exports.isVanillaConsoleCommand = void 0;
+const consoleCommandsSet_1 = require("../sets/consoleCommandsSet");
+/**
+ * Helper function to see if a particular command is a vanilla console command. This is useful
+ * because the `EXECUTE_CMD` callback will not fire for any vanilla commands.
+ */
+function isVanillaConsoleCommand(commandName) {
+    return consoleCommandsSet_1.CONSOLE_COMMANDS_SET.has(commandName);
+}
+exports.isVanillaConsoleCommand = isVanillaConsoleCommand;
+/** Helper function to print whether something was enabled or disabled to the in-game console. */
+function printEnabled(enabled, description) {
+    const enabledText = enabled ? "Enabled" : "Disabled";
+    print(`${enabledText} ${description}.`);
+}
+exports.printEnabled = printEnabled;

package/dist/functions/curses.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasCurse = exports.getCurseIDByName = void 0;
+const cachedClasses_1 = require("../core/cachedClasses");
+const flag_1 = require("./flag");
+/**
+ * Helper function to get the actual bit flag for modded curses.
+ *
+ * Will throw a run-time error if the provided curse does not exist.
+ *
+ * Use this over the `Isaac.GetCurseIdByName` method because that will return an integer instead of
+ * a bit flag.
+ */
+function getCurseIDByName(name) {
+    const curseID = Isaac.GetCurseIdByName(name);
+    if (curseID === -1) {
+        error(`Failed to get the curse ID corresponding to the curse name of "${curseID}". Does this name match what you put in the "content/curses.xml" file?`);
+    }
+    // For example, the final vanilla curse is "Curse of the Giant", which has an ID of 8. This
+    // corresponds to `LevelCurse.GIANT`, which has a value of `1 << 7`.
+    return (1 << (curseID - 1));
+}
+exports.getCurseIDByName = getCurseIDByName;
+/**
+ * Helper function to check if the current floor has a particular curse.
+ *
+ * This function is variadic, meaning that you can specify as many curses as you want. The function
+ * will return true if the level has one or more of the curses.
+ *
+ * Under the hood, this function uses the `Level.GetCurses` method.
+ */
+function hasCurse(...curses) {
+    const level = cachedClasses_1.game.GetLevel();
+    const levelCurses = level.GetCurses();
+    return curses.some((curse) => (0, flag_1.hasFlag)(levelCurses, curse));
+}
+exports.hasCurse = hasCurse;

package/dist/functions/debugFunctions.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceback = exports.isLuaDebugEnabled = exports.getTraceback = exports.getTime = exports.getElapsedTimeSince = void 0;
+const log_1 = require("./log");
+/**
+ * Helper function to get the amount of elapsed time for benchmarking / profiling purposes.
+ *
+ * For more information, see the documentation for the `getTime` helper function.
+ *
+ * @param time The milliseconds (int) or fractional seconds (float).
+ * @param useSocketIfAvailable Optional. Whether to use the `socket.gettime` method, if available.
+ *                             Default is true. If set to false, the `Isaac.GetTime()` method will
+ *                             always be used.
+ */
+function getElapsedTimeSince(time, useSocketIfAvailable = true) {
+    return getTime(useSocketIfAvailable) - time;
+}
+exports.getElapsedTimeSince = getElapsedTimeSince;
+/**
+ * Helper function to get the current time for benchmarking / profiling purposes.
+ *
+ * The return value will either be in seconds or milliseconds, depending on if the "--luadebug" flag
+ * is turned on.
+ *
+ * If the "--luadebug" flag is present, then this function will use the `socket.gettime` method,
+ * which returns the epoch timestamp in seconds (e.g. "1640320492.5779"). This is preferable over
+ * the more conventional `Isaac.GetTime` method, since it has one extra decimal point of precision.
+ *
+ * If the "--luadebug" flag is not present, then this function will use the `Isaac.GetTime` method,
+ * which returns the number of milliseconds since the computer's operating system was started (e.g.
+ * "739454963").
+ *
+ * @param useSocketIfAvailable Optional. Whether to use the `socket.gettime` method, if available.
+ *                             Default is true. If set to false, the `Isaac.GetTime()` method will
+ *                             always be used.
+ */
+function getTime(useSocketIfAvailable = true) {
+    if (useSocketIfAvailable) {
+        if (SandboxGetTime !== undefined) {
+            return SandboxGetTime();
+        }
+        if (isLuaDebugEnabled()) {
+            // eslint-disable-next-line unicorn/prefer-module
+            const [ok, requiredSocket] = pcall(require, "socket");
+            if (ok) {
+                const socket = requiredSocket;
+                return socket.gettime();
+            }
+        }
+    }
+    // We could divide the result by 1000 in order to unify the return type with `socket.gettime`.
+    // However, this causes floating point inaccuracies in the number when subtracting, so it is
+    // better to keep it as an integer.
+    return Isaac.GetTime();
+}
+exports.getTime = getTime;
+/**
+ * Helper function to get a stack trace.
+ *
+ * This will only work if the `--luadebug` launch option is enabled. If it isn't, then a error
+ * string will be returned.
+ */
+function getTraceback() {
+    if (SandboxGetTraceback !== undefined) {
+        return SandboxGetTraceback();
+    }
+    // "debug" will be equal to undefined if the "--luadebug" launch flag is not present.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (debug !== undefined) {
+        // The --luadebug launch flag is enabled.
+        return debug.traceback();
+    }
+    return 'stack traceback:\n(the "--luadebug" flag is not enabled)';
+}
+exports.getTraceback = getTraceback;
+/**
+ * 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.
+ *
+ * Note that this function will return false if the Racing+ sandbox is enabled, even if the
+ * "--luadebug" flag is really turned on. If checking for this case is needed, check for the
+ * presence of the `sandboxGetTraceback` function.
+ */
+function isLuaDebugEnabled() {
+    // "package" is not always defined like the Lua definitions imply.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return _G.package !== undefined;
+}
+exports.isLuaDebugEnabled = isLuaDebugEnabled;
+/**
+ * Helper function to log 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. If it isn't, then a error
+ * string will be logged.
+ */
+function traceback() {
+    const tracebackOutput = getTraceback();
+    (0, log_1.log)(tracebackOutput);
+}
+exports.traceback = traceback;

package/dist/functions/decorators.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * If you decide to structure your mod as a set of feature classes, you can use decorators to
+ * automatically register callbacks.
+ *
+ * Currently, there are two decorators:
+ * - `@Callback`
+ * - `@CallbackCustom`
+ *
+ * For example:
+ *
+ * ```ts
+ * export class MyFeature extends ModFeature {
+ *   @Callback(ModCallback.POST_GAME_STARTED)
+ *   postGameStarted(isContinued: boolean): void {
+ *     Isaac.DebugString(`Callback fired: POST_GAME_STARTED`);
+ *   }
+ * }
+ * ```
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriorityCallbackCustom = exports.PriorityCallback = exports.CallbackCustom = exports.Callback = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const ModFeature_1 = require("../classes/ModFeature");
+const tstlClass_1 = require("./tstlClass");
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `Mod.AddCallback`.
+ *
+ * @allowEmptyVariadic
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+function Callback(modCallback, ...optionalArgs) {
+    return PriorityCallback(modCallback, isaac_typescript_definitions_1.CallbackPriority.DEFAULT, ...optionalArgs);
+}
+exports.Callback = Callback;
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `ModUpgraded.AddCallbackCustom`.
+ *
+ * @allowEmptyVariadic
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+function CallbackCustom(modCallbackCustom, ...optionalArgs) {
+    return PriorityCallbackCustom(modCallbackCustom, isaac_typescript_definitions_1.CallbackPriority.DEFAULT, ...optionalArgs);
+}
+exports.CallbackCustom = CallbackCustom;
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `Mod.AddPriorityCallback`.
+ *
+ * @allowEmptyVariadic
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+function PriorityCallback(modCallback, priority, ...optionalArgs) {
+    return (target, propertyKey, _descriptor) => {
+        // First, prepare the arguments for the `Mod.AddPriorityCallback` method.
+        const methodName = propertyKey;
+        const method = target[methodName];
+        const callbackTuple = [modCallback, priority, method, optionalArgs];
+        // Since the decorator runs prior to instantiation, we only have access to get and set static
+        // properties, which are located on the "constructor" table. Thus, we store the callback
+        // arguments for later.
+        const constructor = target.constructor;
+        if (constructor === undefined) {
+            const tstlClassName = (0, tstlClass_1.getTSTLClassName)(target) ?? "Unknown";
+            error(`Failed to get the constructor for class "${tstlClassName}". Did you decorate a static method? You can only decorate non-static class methods, because the "Mod" object is not present before the class is instantiated.`);
+        }
+        if (!constructor.has(ModFeature_1.MOD_FEATURE_CALLBACKS_KEY)) {
+            constructor.set(ModFeature_1.MOD_FEATURE_CALLBACKS_KEY, []);
+        }
+        const callbackTuples = constructor.get(ModFeature_1.MOD_FEATURE_CALLBACKS_KEY);
+        callbackTuples.push(callbackTuple);
+    };
+}
+exports.PriorityCallback = PriorityCallback;
+/**
+ * A decorator function that signifies that the decorated class method should be automatically
+ * registered with `ModUpgraded.AddCallbackCustom`.
+ *
+ * @allowEmptyVariadic
+ * @ignore
+ */
+// We tell TypeDoc to ignore this function because it generates a bunch of spam.
+function PriorityCallbackCustom(modCallbackCustom, priority, ...optionalArgs) {
+    return (target, propertyKey, _descriptor) => {
+        // First, prepare the arguments for the `Mod.AddCallbackCustom` method.
+        const methodName = propertyKey;
+        const method = target[methodName];
+        const callbackTuple = [modCallbackCustom, priority, method, optionalArgs];
+        // Since the decorator runs prior to instantiation, we only have access to get and set static
+        // properties, which are located on the "constructor" table. Thus, we store the callback
+        // arguments for later.
+        const constructor = target.constructor;
+        if (constructor === undefined) {
+            const tstlClassName = (0, tstlClass_1.getTSTLClassName)(target) ?? "Unknown";
+            error(`Failed to get the constructor for class "${tstlClassName}". Did you decorate a static method? You can only decorate non-static class methods, because the "Mod" object is not present before the class is instantiated.`);
+        }
+        if (!constructor.has(ModFeature_1.MOD_FEATURE_CUSTOM_CALLBACKS_KEY)) {
+            constructor.set(ModFeature_1.MOD_FEATURE_CUSTOM_CALLBACKS_KEY, []);
+        }
+        const callbackTuples = constructor.get(ModFeature_1.MOD_FEATURE_CUSTOM_CALLBACKS_KEY);
+        callbackTuples.push(callbackTuple);
+    };
+}
+exports.PriorityCallbackCustom = PriorityCallbackCustom;