isaacscript-common 4.6.1 → 4.7.2

package/features/runInNFrames.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="isaac-typescript-definitions" />
 /**
- * Supply a function to run N game frames from now in the PostUpdate callback.
+ * Supply a function to run N game frames from now in the `POST_UPDATE` callback.
  *
  * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
  * way.
@@ -11,7 +11,7 @@
  */
 export declare function runInNGameFrames(func: () => void, gameFrames: int): void;
 /**
- * Supply a function to run N render frames from now in the PostRender callback.
+ * Supply a function to run N render frames from now in the `POST_RENDER` callback.
  *
  * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
  * way.
@@ -22,7 +22,7 @@ export declare function runInNGameFrames(func: () => void, gameFrames: int): voi
  */
 export declare function runInNRenderFrames(func: () => void, renderFrames: int): void;
 /**
- * Supply a function to run on the next PostUpdate callback.
+ * Supply a function to run on the next `POST_UPDATE` callback.
  *
  * For example:
  *
@@ -51,7 +51,7 @@ export declare function runInNRenderFrames(func: () => void, renderFrames: int):
  */
 export declare function runNextGameFrame(func: () => void): void;
 /**
- * Supply a function to run on the next PostRender callback.
+ * Supply a function to run on the next `POST_RENDER` callback.
  *
  * For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
  * way.
@@ -59,3 +59,37 @@ export declare function runNextGameFrame(func: () => void): void;
  * Note that this function will not handle saving and quitting.
  */
 export declare function runNextRenderFrame(func: () => void): void;
+/**
+ * Supply a function to be repeatedly run on an interval of N game frames in the `POST_UPDATE`
+ * callback. The function will continue to be fired until `false` is returned from the function.
+ *
+ * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+ * corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+ * used to stop the interval.)
+ *
+ * Note that this function will not handle saving and quitting. You must manually restart any
+ * intervals if the player saves and quits in the middle of a run.
+ *
+ * @param func The function to repeatedly run on an interval.
+ * @param gameFrames The amount of game frames to wait between each run.
+ * @param runImmediately Whether or not to execute the function right now before waiting for the
+ *                       interval.
+ */
+export declare function setIntervalGameFrames(func: () => boolean, gameFrames: int, runImmediately: boolean): void;
+/**
+ * Supply a function to be repeatedly run on an interval of N render frames in the `POST_RENDER`
+ * callback. The function will continue to be fired until `false` is returned from the function.
+ *
+ * This is similar to the `setInterval` vanilla JavaScript function, except there is no
+ * corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+ * used to stop the interval.)
+ *
+ * Note that this function will not handle saving and quitting. You must manually restart any
+ * intervals if the player saves and quits in the middle of a run.
+ *
+ * @param func The function to repeatedly run on an interval.
+ * @param renderFrames The amount of game frames to wait between each run.
+ * @param runImmediately Whether or not to execute the function right now before waiting for the
+ *                       interval.
+ */
+export declare function setIntervalRenderFrames(func: () => boolean, renderFrames: int, runImmediately: boolean): void;

package/features/runInNFrames.lua

@@ -1,46 +1,67 @@
 local ____lualib = require("lualib_bundle")
 local __TS__ArrayForEach = ____lualib.__TS__ArrayForEach
-local __TS__ArraySplice = ____lualib.__TS__ArraySplice
 local ____exports = {}
-local postUpdate, postRender, checkExecuteQueuedFunctions, v
+local postUpdate, postRender, checkExecuteQueuedFunctions, checkExecuteIntervalFunctions, getFunctionsThatShouldFireOnThisFrame, v
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local ModCallback = ____isaac_2Dtypescript_2Ddefinitions.ModCallback
 local ____cachedClasses = require("cachedClasses")
 local game = ____cachedClasses.game
 local ____featuresInitialized = require("featuresInitialized")
 local errorIfFeaturesNotInitialized = ____featuresInitialized.errorIfFeaturesNotInitialized
+local ____array = require("functions.array")
+local arrayRemoveIndexInPlace = ____array.arrayRemoveIndexInPlace
 local ____exports = require("features.saveDataManager.exports")
 local saveDataManager = ____exports.saveDataManager
 function postUpdate(self)
     local gameFrameCount = game:GetFrameCount()
     checkExecuteQueuedFunctions(nil, gameFrameCount, v.run.queuedGameFunctionTuples)
+    checkExecuteIntervalFunctions(nil, gameFrameCount, v.run.intervalGameFunctionTuples)
 end
 function postRender(self)
     local renderFrameCount = Isaac.GetFrameCount()
     checkExecuteQueuedFunctions(nil, renderFrameCount, v.run.queuedRenderFunctionTuples)
+    checkExecuteIntervalFunctions(nil, renderFrameCount, v.run.intervalRenderFunctionTuples)
 end
 function checkExecuteQueuedFunctions(self, frameCount, functionTuples)
-    local functionsToFire = {}
-    local indexesToRemove = {}
+    local firingFunctions = getFunctionsThatShouldFireOnThisFrame(nil, frameCount, functionTuples)
+    for ____, ____value in ipairs(firingFunctions) do
+        local i = ____value[1]
+        local func = ____value[2]
+        func(nil)
+        arrayRemoveIndexInPlace(nil, functionTuples, i)
+    end
+end
+function checkExecuteIntervalFunctions(self, frameCount, functionTuples)
+    local firingFunctions = getFunctionsThatShouldFireOnThisFrame(nil, frameCount, functionTuples)
+    for ____, ____value in ipairs(firingFunctions) do
+        local i = ____value[1]
+        local func = ____value[2]
+        local numIntervalFrames = ____value[3]
+        local returnValue = func(nil)
+        arrayRemoveIndexInPlace(nil, functionTuples, i)
+        if numIntervalFrames ~= nil and returnValue ~= false then
+            local nextFireFrame = frameCount + numIntervalFrames
+            local tuple = {nextFireFrame, func, numIntervalFrames}
+            functionTuples[#functionTuples + 1] = tuple
+        end
+    end
+end
+function getFunctionsThatShouldFireOnThisFrame(self, frameCount, functionTuples)
+    local firingFunctionTuples = {}
     __TS__ArrayForEach(
         functionTuples,
         function(____, functionTuple, i)
-            local frame, func = table.unpack(functionTuple)
-            if frameCount >= frame then
-                functionsToFire[#functionsToFire + 1] = func
-                indexesToRemove[#indexesToRemove + 1] = i
+            local frameCountToFire, func, numIntervalFrames = table.unpack(functionTuple)
+            if frameCount >= frameCountToFire then
+                local firingFunctionTuple = {i, func, numIntervalFrames}
+                firingFunctionTuples[#firingFunctionTuples + 1] = firingFunctionTuple
             end
         end
     )
-    for ____, indexToRemove in ipairs(indexesToRemove) do
-        __TS__ArraySplice(functionTuples, indexToRemove, 1)
-    end
-    for ____, func in ipairs(functionsToFire) do
-        func(nil)
-    end
+    return firingFunctionTuples
 end
 local FEATURE_NAME = "runInNFrames"
-v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}}}
+v = {run = {queuedGameFunctionTuples = {}, queuedRenderFunctionTuples = {}, intervalGameFunctionTuples = {}, intervalRenderFunctionTuples = {}}}
 ---
 -- @internal
 function ____exports.runInNFramesInit(self, mod)
@@ -53,7 +74,7 @@ function ____exports.runInNFramesInit(self, mod)
     mod:AddCallback(ModCallback.POST_UPDATE, postUpdate)
     mod:AddCallback(ModCallback.POST_RENDER, postRender)
 end
---- Supply a function to run N game frames from now in the PostUpdate callback.
+--- Supply a function to run N game frames from now in the `POST_UPDATE` callback.
 -- 
 -- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
 -- way.
@@ -69,7 +90,7 @@ function ____exports.runInNGameFrames(self, func, gameFrames)
     local ____v_run_queuedGameFunctionTuples_0 = v.run.queuedGameFunctionTuples
     ____v_run_queuedGameFunctionTuples_0[#____v_run_queuedGameFunctionTuples_0 + 1] = tuple
 end
---- Supply a function to run N render frames from now in the PostRender callback.
+--- Supply a function to run N render frames from now in the `POST_RENDER` callback.
 -- 
 -- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
 -- way.
@@ -85,7 +106,7 @@ function ____exports.runInNRenderFrames(self, func, renderFrames)
     local ____v_run_queuedRenderFunctionTuples_1 = v.run.queuedRenderFunctionTuples
     ____v_run_queuedRenderFunctionTuples_1[#____v_run_queuedRenderFunctionTuples_1 + 1] = tuple
 end
---- Supply a function to run on the next PostUpdate callback.
+--- Supply a function to run on the next `POST_UPDATE` callback.
 -- 
 -- For example:
 -- 
@@ -115,7 +136,7 @@ function ____exports.runNextGameFrame(self, func)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     ____exports.runInNGameFrames(nil, func, 1)
 end
---- Supply a function to run on the next PostRender callback.
+--- Supply a function to run on the next `POST_RENDER` callback.
 -- 
 -- For a usage example, see the documentation for the `runNextGameFrame`, which is used in a similar
 -- way.
@@ -125,4 +146,54 @@ function ____exports.runNextRenderFrame(self, func)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     ____exports.runInNRenderFrames(nil, func, 1)
 end
+--- Supply a function to be repeatedly run on an interval of N game frames in the `POST_UPDATE`
+-- callback. The function will continue to be fired until `false` is returned from the function.
+-- 
+-- This is similar to the `setInterval` vanilla JavaScript function, except there is no
+-- corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+-- used to stop the interval.)
+-- 
+-- Note that this function will not handle saving and quitting. You must manually restart any
+-- intervals if the player saves and quits in the middle of a run.
+-- 
+-- @param func The function to repeatedly run on an interval.
+-- @param gameFrames The amount of game frames to wait between each run.
+-- @param runImmediately Whether or not to execute the function right now before waiting for the
+-- interval.
+function ____exports.setIntervalGameFrames(self, func, gameFrames, runImmediately)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local gameFrameCount = game:GetFrameCount()
+    local functionFireFrame = gameFrameCount + gameFrames
+    local tuple = {functionFireFrame, func, gameFrames}
+    local ____v_run_intervalGameFunctionTuples_2 = v.run.intervalGameFunctionTuples
+    ____v_run_intervalGameFunctionTuples_2[#____v_run_intervalGameFunctionTuples_2 + 1] = tuple
+    if runImmediately then
+        func(nil)
+    end
+end
+--- Supply a function to be repeatedly run on an interval of N render frames in the `POST_RENDER`
+-- callback. The function will continue to be fired until `false` is returned from the function.
+-- 
+-- This is similar to the `setInterval` vanilla JavaScript function, except there is no
+-- corresponding `clearInterval` function. (Instead, the return value from the supplied function is
+-- used to stop the interval.)
+-- 
+-- Note that this function will not handle saving and quitting. You must manually restart any
+-- intervals if the player saves and quits in the middle of a run.
+-- 
+-- @param func The function to repeatedly run on an interval.
+-- @param renderFrames The amount of game frames to wait between each run.
+-- @param runImmediately Whether or not to execute the function right now before waiting for the
+-- interval.
+function ____exports.setIntervalRenderFrames(self, func, renderFrames, runImmediately)
+    errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
+    local renderFrameCount = Isaac.GetFrameCount()
+    local functionFireFrame = renderFrameCount + renderFrames
+    local tuple = {functionFireFrame, func, renderFrames}
+    local ____v_run_intervalGameFunctionTuples_3 = v.run.intervalGameFunctionTuples
+    ____v_run_intervalGameFunctionTuples_3[#____v_run_intervalGameFunctionTuples_3 + 1] = tuple
+    if runImmediately then
+        func(nil)
+    end
+end
 return ____exports

package/index.d.ts

@@ -26,7 +26,7 @@ export { anyPlayerUsingPony, isPlayerUsingPony, } from "./features/ponyDetection
 export { preventCollectibleRotation } from "./features/preventCollectibleRotation";
 export { registerHotkey, unregisterHotkey } from "./features/registerHotkey";
 export { getRoomClearGameFrame, getRoomClearRoomFrame, } from "./features/roomClearFrame";
-export { runInNGameFrames, runInNRenderFrames, runNextGameFrame, runNextRenderFrame, } from "./features/runInNFrames";
+export { runInNGameFrames, runInNRenderFrames, runNextGameFrame, runNextRenderFrame, setIntervalGameFrames, setIntervalRenderFrames, } from "./features/runInNFrames";
 export * from "./features/saveDataManager/exports";
 export { hasSirenStolenFamiliar, setFamiliarNoSirenSteal, } from "./features/sirenHelpers";
 export { getStageHistory, hasVisitedStage } from "./features/stageHistory";

package/index.lua

@@ -210,10 +210,14 @@ do
     local runInNRenderFrames = ____runInNFrames.runInNRenderFrames
     local runNextGameFrame = ____runInNFrames.runNextGameFrame
     local runNextRenderFrame = ____runInNFrames.runNextRenderFrame
+    local setIntervalGameFrames = ____runInNFrames.setIntervalGameFrames
+    local setIntervalRenderFrames = ____runInNFrames.setIntervalRenderFrames
     ____exports.runInNGameFrames = runInNGameFrames
     ____exports.runInNRenderFrames = runInNRenderFrames
     ____exports.runNextGameFrame = runNextGameFrame
     ____exports.runNextRenderFrame = runNextRenderFrame
+    ____exports.setIntervalGameFrames = setIntervalGameFrames
+    ____exports.setIntervalRenderFrames = setIntervalRenderFrames
 end
 do
     local ____export = require("features.saveDataManager.exports")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "4.6.1",
+  "version": "4.7.2",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",