isaacscript-common 1.0.473 → 1.0.474

package/dist/features/deployJSONRoom.d.ts

@@ -10,10 +10,22 @@ export declare function deployJSONRoomInit(mod: ModUpgraded): void;
  *
  * This function is meant to be used in the PostNewRoom callback.
  *
- * @returns The iterated seed, which can be used in subsequent room deployments. (The seed is used
- * to spawn every entity contained within the custom room.)
+ * @param jsonRoom The JSON room to deploy. In practice, this will be something like:
+ * ```
+ * import customRooms from "./customRooms";
+ *
+ * const firstJSONRoom = customRooms.rooms.room[0];
+ * deployJSONRoom(firstJSONRoom);
+ * ```
+ * @param seed Optional. Specifies the seed that will be used for spawning every entity in the room.
+ * Equal to `Random()` by default.
+ * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ * what the function is doing. False by default.
+ * @returns Before using the seed for spawning each entity, it is iterated with `nextSeed()`. The
+ * function returns the final iterated seed after spawning everything, which can be used in
+ * subsequent room deployments.
  */
-export declare function deployJSONRoom(jsonRoom: JSONRoom, seed?: number): int;
+export declare function deployJSONRoom(jsonRoom: JSONRoom, seed?: number, verbose?: boolean): int;
 /**
  * Helper function to deconstruct a vanilla room and set up a custom room in its place.
  * Specifically, this will clear the current room of all entities and grid entities, and then spawn
@@ -25,10 +37,23 @@ export declare function deployJSONRoom(jsonRoom: JSONRoom, seed?: number): int;
  * properly account for each room weight using the algorithm from:
  * https://stackoverflow.com/questions/1761626/weighted-random-numbers
  *
- * @returns The iterated seed, which can be used in subsequent room deployments. (The seed is used
- * to spawn every entity contained within the custom room.)
+ * @param jsonRooms An array of JSON rooms to randomly select from. In practice, this will be
+ * something like:
+ * ```
+ * import customRooms from "./customRooms";
+ *
+ * const jsonRooms = customRooms.rooms.room;
+ * deployRandomJSONRoom(jsonRooms);
+ * ```
+ * @param seed Optional. Specifies the seed that will be used for determining the random room. After
+ * that, it is also used for spawning every entity in the room. Equal to `Random()` by default.
+ * @param verbose Optional. If specified, will write entries to the "log.txt" file that describe
+ * what the function is doing. False by default.
+ * @returns Before using the seed for spawning each entity, it is iterated with `nextSeed()`. The
+ * function returns the final iterated seed after spawning everything, which can be used in
+ * subsequent room deployments.
  */
-export declare function deployRandomJSONRoom(jsonRooms: JSONRoom[], seed?: number): int;
+export declare function deployRandomJSONRoom(jsonRooms: JSONRoom[], seed?: number, verbose?: boolean): int;
 /**
  * Helper function to remove all naturally spawning entities and grid entities from a room. Notably,
  * this will not remove players (1), tears (2), familiars (3), lasers (7), knives (8),

package/dist/features/deployJSONRoom.lua

@@ -15,6 +15,8 @@ local removeAllGridEntitiesExceptFor = ____gridEntity.removeAllGridEntitiesExcep
 local setGridEntityInvisible = ____gridEntity.setGridEntityInvisible
 local ____jsonRoom = require("functions.jsonRoom")
 local getRandomJSONRoom = ____jsonRoom.getRandomJSONRoom
+local ____log = require("functions.log")
+local log = ____log.log
 local ____npc = require("functions.npc")
 local getNPCs = ____npc.getNPCs
 local ____random = require("functions.random")
@@ -91,10 +93,10 @@ function removeSpecificNPCs(self)
     ) do
         do
             if NPC_TYPES_TO_NOT_REMOVE:has(npc.Type) then
-                goto __continue20
+                goto __continue25
             end
             if (npc:HasEntityFlags(EntityFlag.FLAG_CHARM) or npc:HasEntityFlags(EntityFlag.FLAG_FRIENDLY)) or npc:HasEntityFlags(EntityFlag.FLAG_PERSISTENT) then
-                goto __continue20
+                goto __continue25
             end
             npc:ClearEntityFlags(EntityFlag.FLAG_APPEAR)
             npc:Remove()
@@ -103,7 +105,7 @@ function removeSpecificNPCs(self)
                 room:SetGridPath(gridIndex, 0)
             end
         end
-        ::__continue20::
+        ::__continue25::
     end
 end
 function fillRoomWithDecorations(self)
@@ -122,19 +124,22 @@ function fillRoomWithDecorations(self)
             do
                 local existingGridEntity = room:GetGridEntity(gridIndex)
                 if existingGridEntity ~= nil then
-                    goto __continue26
+                    goto __continue31
                 end
                 local position = room:GetGridPosition(gridIndex)
                 local decoration = Isaac.GridSpawn(GridEntityType.GRID_DECORATION, 0, position, true)
                 setGridEntityInvisible(nil, decoration)
                 __TS__ArrayPush(decorationGridIndexes, gridIndex)
             end
-            ::__continue26::
+            ::__continue31::
             gridIndex = gridIndex + 1
         end
     end
 end
-function spawnAllEntities(self, jsonRoom, seed)
+function spawnAllEntities(self, jsonRoom, seed, verbose)
+    if verbose == nil then
+        verbose = false
+    end
     local shouldUnclearRoom = false
     for ____, spawn in ipairs(jsonRoom.spawn) do
         local xString = spawn["$"].x
@@ -171,9 +176,19 @@ function spawnAllEntities(self, jsonRoom, seed)
             )
         end
         if entityType >= 1000 then
+            if verbose then
+                log(
+                    ((((((("Spawning a grid entity " .. tostring(entityType)) .. ".") .. tostring(variant)) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")"
+                )
+            end
             spawnGridEntity(nil, entityType, variant, x, y)
         else
             seed = nextSeed(nil, seed)
+            if verbose then
+                log(
+                    ((((((((("Spawning a normal entity " .. tostring(entityType)) .. ".") .. tostring(variant)) .. ".") .. tostring(subType)) .. " at: (") .. tostring(x)) .. ", ") .. tostring(y)) .. ")"
+                )
+            end
             local entity = spawnNormalEntity(nil, entityType, variant, subType, x, y, seed)
             local npc = entity:ToNPC()
             if (npc ~= nil) and npc.CanShutDoors then
@@ -182,6 +197,9 @@ function spawnAllEntities(self, jsonRoom, seed)
         end
     end
     if shouldUnclearRoom then
+        if verbose then
+            log("Setting the room to be uncleared since there were one or more battle NPCs spawned.")
+        end
         setRoomUncleared(nil)
     end
     return seed
@@ -365,29 +383,50 @@ function ____exports.deployJSONRoomInit(self, mod)
     saveDataManager(nil, "deployJSONRoom", v)
     mod:AddCallback(ModCallbacks.MC_POST_NEW_ROOM, postNewRoom)
 end
-function ____exports.deployJSONRoom(self, jsonRoom, seed)
+function ____exports.deployJSONRoom(self, jsonRoom, seed, verbose)
     if seed == nil then
         seed = Random()
     end
+    if verbose == nil then
+        verbose = false
+    end
     if not initialized then
         local msg = getUpgradeErrorMsg(nil, FEATURE_NAME)
         error(msg)
     end
+    if verbose then
+        log("Starting to empty the room of entities and grid entities.")
+    end
     ____exports.emptyRoom(nil, false)
-    local newSeed = spawnAllEntities(nil, jsonRoom, seed)
+    if verbose then
+        log("Finished emptying the room of entities and grid entities.")
+    end
+    if verbose then
+        log("Starting to spawn all of the new entities and grid entities.")
+    end
+    local newSeed = spawnAllEntities(nil, jsonRoom, seed, verbose)
+    if verbose then
+        log("Finished spawning all of the new entities and grid entities.")
+    end
     fixPitGraphics(nil)
     fillRoomWithDecorations(nil)
     return newSeed
 end
-function ____exports.deployRandomJSONRoom(self, jsonRooms, seed)
+function ____exports.deployRandomJSONRoom(self, jsonRooms, seed, verbose)
     if seed == nil then
         seed = Random()
     end
+    if verbose == nil then
+        verbose = false
+    end
     if not initialized then
         local msg = getUpgradeErrorMsg(nil, FEATURE_NAME)
         error(msg)
     end
-    local randomJSONRoom = getRandomJSONRoom(nil, jsonRooms, seed)
-    return ____exports.deployJSONRoom(nil, randomJSONRoom, seed)
+    local randomJSONRoom = getRandomJSONRoom(nil, jsonRooms, seed, verbose)
+    if verbose then
+        log((((((("Randomly chose JSON room " .. randomJSONRoom["$"].type) .. ".") .. randomJSONRoom["$"].variant) .. ".") .. randomJSONRoom["$"].subtype) .. " with name: ") .. randomJSONRoom["$"].name)
+    end
+    return ____exports.deployJSONRoom(nil, randomJSONRoom, seed, verbose)
 end
 return ____exports

package/dist/functions/jsonRoom.d.ts

@@ -2,4 +2,11 @@
 import { JSONRoom } from "../types/JSONRoom";
 export declare function getJSONRoomOfVariant(jsonRooms: JSONRoom[], variant: int): JSONRoom | undefined;
 export declare function getJSONRoomsOfSubType(jsonRooms: JSONRoom[], subType: int): JSONRoom[];
-export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seed?: number): JSONRoom;
+/**
+ * Helper function to get a random JSON room from an array of JSON rooms.
+ *
+ * Note that this function does not simply choose a random element in the provided array; it will
+ * properly account for each room weight using the algorithm from:
+ * https://stackoverflow.com/questions/1761626/weighted-random-numbers
+ */
+export declare function getRandomJSONRoom(jsonRooms: JSONRoom[], seed?: number, verbose?: boolean): JSONRoom;

package/dist/functions/jsonRoom.lua

@@ -2,6 +2,8 @@
 require("lualib_bundle");
 local ____exports = {}
 local getTotalWeightOfJSONRooms, getJSONRoomWithChosenWeight
+local ____log = require("functions.log")
+local log = ____log.log
 local ____random = require("functions.random")
 local getRandomFloat = ____random.getRandomFloat
 function getTotalWeightOfJSONRooms(self, jsonRooms)
@@ -54,12 +56,25 @@ function ____exports.getJSONRoomsOfSubType(self, jsonRooms, subType)
     end
     return jsonRoomsOfSubType
 end
-function ____exports.getRandomJSONRoom(self, jsonRooms, seed)
+function ____exports.getRandomJSONRoom(self, jsonRooms, seed, verbose)
     if seed == nil then
         seed = Random()
     end
+    if verbose == nil then
+        verbose = false
+    end
     local totalWeight = getTotalWeightOfJSONRooms(nil, jsonRooms)
+    if verbose then
+        log(
+            "Total weight of the JSON rooms provided: " .. tostring(totalWeight)
+        )
+    end
     local chosenWeight = getRandomFloat(nil, 0, totalWeight, seed)
+    if verbose then
+        log(
+            "Randomly chose weight: " .. tostring(chosenWeight)
+        )
+    end
     return getJSONRoomWithChosenWeight(nil, jsonRooms, chosenWeight)
 end
 return ____exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "1.0.473",
+  "version": "1.0.474",
   "description": "Helper functions for IsaacScript mods",
   "keywords": [
     "isaac",