isaacscript-common 7.4.3 → 7.6.0

package/src/features/customGridEntity.ts

@@ -2,7 +2,6 @@ import {
   ActiveSlot,
   CollectibleType,
   DamageFlag,
-  EntityFlag,
   EntityType,
   GridCollisionClass,
   GridEntityType,
@@ -13,24 +12,24 @@ import { postGridEntityCustomBrokenFire } from "../callbacks/subscriptions/postG
 import { DefaultMap } from "../classes/DefaultMap";
 import { ModUpgraded } from "../classes/ModUpgraded";
 import { game } from "../core/cachedClasses";
-import { DecorationVariant } from "../enums/DecorationVariant";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
-import { errorIfFeaturesNotInitialized } from "../featuresInitialized";
-import { spawn } from "../functions/entities";
+import {
+  areFeaturesInitialized,
+  errorIfFeaturesNotInitialized,
+} from "../featuresInitialized";
 import { hasFlag } from "../functions/flag";
 import {
   removeGridEntity,
   spawnGridEntityWithVariant,
 } from "../functions/gridEntities";
 import { getRoomListIndex } from "../functions/roomData";
-import { asNumber } from "../functions/types";
+import { isNumber } from "../functions/types";
 import { isVector } from "../functions/vector";
 import { GridEntityCustomData } from "../interfaces/GridEntityCustomData";
 import { runNextGameFrame } from "./runInNFrames";
 import { saveDataManager } from "./saveDataManager/exports";
 
 const FEATURE_NAME = "customGridEntity";
-const GENERIC_PROP_SIZE_MULTIPLIER = 0.66;
 
 const v = {
   level: {
@@ -200,18 +199,24 @@ function postNewRoomReordered() {
  * will reappear if the player leaves and re-enters the room. (It will be manually respawned in the
  * `POST_NEW_ROOM` callback.)
  *
- * This is an IsaacScript feature because the vanilla game does not support any custom grid
- * entities. Under the hood, IsaacScript accomplishes this by using decorations with an arbitrary
- * non-zero variant to represent custom grid entities.
+ * Custom grid entities are built on top of real grid entities. You can use any existing grid entity
+ * type as a base. For example, if you want to create a custom rock that would be breakable like a
+ * normal rock, then you should specify `GridEntityType.ROCK` as the base grid entity type.
  *
  * Once a custom grid entity is spawned, you can take advantage of the custom grid callbacks such as
- * `POST_GRID_ENTITY_CUSTOM_UPDATE`.
+ * `POST_GRID_ENTITY_CUSTOM_UPDATE`. Note that the "normal" grid entities callbacks will not fire
+ * for custom entities. For example, if you had a custom grid entity based on `GridEntityType.ROCK`,
+ * and you also had a subscription to the `POST_GRID_ENTITY_UPDATE` callback, the callback would
+ * only fire for normal rocks and not the custom entity.
+ *
+ * Custom grid entities are an IsaacScript feature because the vanilla game does not support any
+ * custom grid entities.
  *
  * @param gridEntityTypeCustom An integer that identifies what kind of grid entity you are creating.
- *                             It should correspond to a local enum value in your mod. The integer
- *                             can be any unique value and will not correspond to the actual grid
- *                             entity type used. (This integer is used in the various custom grid
- *                             entity callbacks.)
+ *                             It should correspond to a local enum value created in your mod. The
+ *                             integer can be any unique value and will not correspond to the actual
+ *                             grid entity type used. (This integer is used in the various custom
+ *                             grid entity callbacks.)
  * @param gridIndexOrPosition The grid index or position in the room that you want to spawn the grid
  *                            entity at. If a position is specified, the closest grid index will be
  *                            used.
@@ -220,10 +225,10 @@ function postNewRoomReordered() {
  * @param defaultAnimation Optional. The name of the animation to play after the sprite is
  *                         initialized and after the player re-enters a room with this grid entity
  *                         in it. If not specified, the default animation in the anm2 will be used.
- * @param breakable Optional. Whether or not an explosion will be able to break this grid entity.
- *                  False by default. Use the `POST_GRID_ENTITY_CUSTOM_BROKEN` callback to detect
- *                  when it breaks. Due to technical limitations, you can only set the grid entity
- *                  to be breakable if it has a collision class.
+ * @param baseGridEntityType Optional. The type of the grid entity to use as a "base" for this
+ *                           custom grid entity. Default is `GridEntityType.DECORATION`.
+ * @param baseGridEntityVariant Optional. The variant of the grid entity to use as a "base" for this
+ *                              custom grid entity. Default is 0.
  */
 export function spawnCustomGridEntity(
   gridEntityTypeCustom: GridEntityType,
@@ -231,41 +236,28 @@ export function spawnCustomGridEntity(
   gridCollisionClass: GridCollisionClass,
   anm2Path: string,
   defaultAnimation?: string,
-  breakable = false,
+  baseGridEntityType = GridEntityType.DECORATION,
+  baseGridEntityVariant = 0,
 ): GridEntity {
   errorIfFeaturesNotInitialized(FEATURE_NAME);
 
-  if (breakable && gridCollisionClass === GridCollisionClass.NONE) {
-    error(
-      "Failed to spawn a custom grid entity because it is not possible to have breakable custom grid entities with a collision class of: GridCollisionClass.NONE (0)",
-    );
-  }
-
   const room = game.GetRoom();
   const roomListIndex = getRoomListIndex();
   const gridIndex = isVector(gridIndexOrPosition)
     ? room.GetGridIndex(gridIndexOrPosition)
     : gridIndexOrPosition;
 
-  const existingGridEntity = room.GetGridEntity(gridIndex);
-  const isExistingDecoration =
-    existingGridEntity !== undefined &&
-    existingGridEntity.GetType() === GridEntityType.DECORATION &&
-    existingGridEntity.GetVariant() ===
-      asNumber(DecorationVariant.CUSTOM_GRID_ENTITY);
-  const decoration = isExistingDecoration
-    ? existingGridEntity
-    : spawnGridEntityWithVariant(
-        GridEntityType.DECORATION,
-        DecorationVariant.CUSTOM_GRID_ENTITY,
-        gridIndexOrPosition,
-      );
-  if (decoration === undefined) {
-    error("Failed to spawn a decoration for a custom grid entity.");
+  const customGridEntity = spawnGridEntityWithVariant(
+    baseGridEntityType,
+    baseGridEntityVariant,
+    gridIndexOrPosition,
+  );
+  if (customGridEntity === undefined) {
+    error("Failed to spawn a custom grid entity.");
   }
-  decoration.CollisionClass = gridCollisionClass;
+  customGridEntity.CollisionClass = gridCollisionClass;
 
-  const sprite = decoration.GetSprite();
+  const sprite = customGridEntity.GetSprite();
   sprite.Load(anm2Path, true);
   const animationToPlay =
     defaultAnimation === undefined
@@ -286,25 +278,7 @@ export function spawnCustomGridEntity(
     v.level.customGridEntities.getAndSetDefault(roomListIndex);
   roomCustomGridEntities.set(gridIndex, customGridEntityData);
 
-  // We check to see if an explosion touches a custom grid entity by spawning a Dummy on top, and
-  // the monitoring for explosions in the `ENTITY_TAKE_DMG` callback.
-  if (breakable) {
-    const position = room.GetGridPosition(gridIndex);
-    const entity = spawn(EntityType.GENERIC_PROP, 0, 0, position);
-    entity.ClearEntityFlags(EntityFlag.APPEAR);
-    entity.Visible = false;
-
-    // By default, it is larger than a grid tile, so make it a bit smaller.
-    entity.SizeMulti = Vector(
-      GENERIC_PROP_SIZE_MULTIPLIER,
-      GENERIC_PROP_SIZE_MULTIPLIER,
-    );
-
-    const ptrHash = GetPtrHash(entity);
-    v.room.genericPropPtrHashes.add(ptrHash);
-  }
-
-  return decoration;
+  return customGridEntity;
 }
 
 /**
@@ -326,6 +300,8 @@ export function removeCustomGridEntity(
   gridIndexOrPositionOrGridEntity: int | Vector | GridEntity,
   updateRoom = true,
 ): GridEntity | undefined {
+  errorIfFeaturesNotInitialized(FEATURE_NAME);
+
   const room = game.GetRoom();
   const roomListIndex = getRoomListIndex();
 
@@ -371,6 +347,10 @@ export function removeCustomGridEntity(
 export function getCustomGridEntities(): Array<
   [gridEntity: GridEntity, data: GridEntityCustomData]
 > {
+  if (!areFeaturesInitialized()) {
+    return [];
+  }
+
   const roomListIndex = getRoomListIndex();
   const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
   if (roomCustomGridEntities === undefined) {
@@ -388,3 +368,49 @@ export function getCustomGridEntities(): Array<
 
   return customGridEntities;
 }
+
+/**
+ * Helper function to get the custom `GridEntityType` from a `GridEntity` or grid index. Returns
+ * undefined if the provided `GridEntity` is not a custom grid entity, or if there was not a grid
+ * entity on the provided grid index.
+ */
+export function getCustomGridEntityType(
+  gridEntityOrGridIndex: GridEntity | int,
+): GridEntityType | undefined {
+  if (!areFeaturesInitialized()) {
+    return undefined;
+  }
+
+  const gridIndex = isNumber(gridEntityOrGridIndex)
+    ? gridEntityOrGridIndex
+    : gridEntityOrGridIndex.GetGridIndex();
+
+  const roomListIndex = getRoomListIndex();
+  const roomCustomGridEntities = v.level.customGridEntities.get(roomListIndex);
+  if (roomCustomGridEntities === undefined) {
+    return undefined;
+  }
+
+  for (const [_gridIndex, data] of roomCustomGridEntities.entries()) {
+    if (data.gridIndex === gridIndex) {
+      return data.gridEntityTypeCustom;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Helper function to check if a `GridEntity` is a custom grid entity or if a grid index has a
+ * custom grid entity.
+ */
+export function isCustomGridEntity(
+  gridEntityOrGridIndex: GridEntity | int,
+): boolean {
+  if (!areFeaturesInitialized()) {
+    return false;
+  }
+
+  const gridEntityTypeCustom = getCustomGridEntityType(gridEntityOrGridIndex);
+  return gridEntityTypeCustom !== undefined;
+}

package/src/features/customStage/customStageGridEntities.ts

@@ -5,7 +5,6 @@ import {
   LevelStage,
   TrinketType,
 } from "isaac-typescript-definitions";
-import { DecorationVariant } from "../../enums/DecorationVariant";
 import { removeEntities } from "../../functions/entities";
 import { getNPCs } from "../../functions/entitiesSpecific";
 import { removeGridEntity } from "../../functions/gridEntities";
@@ -15,11 +14,13 @@ import {
   getTrinkets,
 } from "../../functions/pickupsSpecific";
 import { calculateStageType } from "../../functions/stage";
-import { asNumber } from "../../functions/types";
 import { vectorEquals } from "../../functions/vector";
 import { CustomStage } from "../../interfaces/private/CustomStage";
-import { TrapdoorDestination } from "../../types/TrapdoorDestination";
-import { spawnCustomTrapdoor } from "../customTrapdoor/exports";
+import { isCustomGridEntity } from "../customGridEntity";
+import {
+  spawnCustomTrapdoor,
+  spawnCustomTrapdoorToVanilla,
+} from "../customTrapdoor/exports";
 import { DEFAULT_BASE_STAGE } from "./exports";
 import v from "./v";
 
@@ -34,14 +35,12 @@ export function setCustomDecorationGraphics(
     return;
   }
 
-  const gridEntityType = gridEntity.GetType();
-  if (gridEntityType !== GridEntityType.DECORATION) {
+  if (isCustomGridEntity(gridEntity)) {
     return;
   }
 
-  // Ignore custom grid entities. (They are represented as decorations with a non-zero variant.)
-  const variant = gridEntity.GetVariant();
-  if (variant !== asNumber(DecorationVariant.VANILLA_DECORATION)) {
+  const gridEntityType = gridEntity.GetType();
+  if (gridEntityType !== GridEntityType.DECORATION) {
     return;
   }
 
@@ -65,6 +64,10 @@ export function setCustomRockGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityRock = gridEntity.ToRock();
   if (gridEntityRock === undefined) {
     return;
@@ -92,6 +95,10 @@ export function setCustomPitGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityPit = gridEntity.ToPit();
   if (gridEntityPit === undefined) {
     return;
@@ -116,6 +123,10 @@ export function setCustomDoorGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityDoor = gridEntity.ToDoor();
   if (gridEntityDoor === undefined) {
     return;
@@ -194,20 +205,22 @@ export function convertVanillaTrapdoors(
 
   removeGridEntity(gridEntity, true);
 
-  // - If we are on the first floor of a custom stage, then the destination will be the second floor
-  //   of the custom stage. (e.g. Caves 1 to Caves 2)
-  // - If we are on the second floor of a custom stage, then the destination will be the vanilla
-  //   floor equivalent to 2 floors after the floor used as a basis for the custom stage.
-  const baseStage =
-    customStage.baseStage === undefined
-      ? DEFAULT_BASE_STAGE
-      : customStage.baseStage;
-  const vanillaNextStage = (baseStage + 2) as LevelStage;
-  const vanillaNextStageType = calculateStageType(vanillaNextStage);
-  const destination: TrapdoorDestination = v.run.firstFloor
-    ? [customStage.name, 2]
-    : [vanillaNextStage, vanillaNextStageType];
-  spawnCustomTrapdoor(gridEntity.Position, destination);
+  if (v.run.firstFloor) {
+    // If we are on the first floor of a custom stage, then the destination will be the second floor
+    // of the custom stage. (e.g. Caves 1 to Caves 2)
+    spawnCustomTrapdoor(gridEntity.Position, customStage.name, 2);
+  } else {
+    // If we are on the second floor of a custom stage, then the destination will be the vanilla
+    // floor equivalent to 2 floors after the floor used as a basis for the custom stage.
+    const baseStage =
+      customStage.baseStage === undefined
+        ? DEFAULT_BASE_STAGE
+        : customStage.baseStage;
+    const stage = (baseStage + 2) as LevelStage;
+    const stageType = calculateStageType(stage);
+
+    spawnCustomTrapdoorToVanilla(gridEntity.Position, stage, stageType);
+  }
 }
 
 /**

package/src/features/customStage/customStageUtils.ts

@@ -2,7 +2,10 @@ import { sumArray } from "../../functions/array";
 import { log } from "../../functions/log";
 import { getRandomFloat } from "../../functions/random";
 import { getRandomSeed } from "../../functions/rng";
-import { CustomStageRoomMetadata } from "../../interfaces/CustomStageLua";
+import {
+  CustomStageBossPoolEntry,
+  CustomStageRoomMetadata,
+} from "../../interfaces/CustomStageTSConfig";
 
 /**
  * Helper function to get a random custom stage room from an array of custom stage rooms.
@@ -52,3 +55,51 @@ function getCustomStageRoomWithChosenWeight(
     `Failed to get a custom stage room with chosen weight: ${chosenWeight}`,
   );
 }
+
+export function getRandomBossRoomFromPool(
+  roomsMetadata: readonly CustomStageRoomMetadata[],
+  bossPool: readonly CustomStageBossPoolEntry[],
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  verbose = false,
+): CustomStageRoomMetadata {
+  const totalWeight = getTotalWeightOfBossPool(bossPool);
+  if (verbose) {
+    log(`Total weight of the custom stage boss pool provided: ${totalWeight}`);
+  }
+
+  const chosenWeight = getRandomFloat(0, totalWeight, seedOrRNG);
+  if (verbose) {
+    log(`Randomly chose weight for custom stage boss pool: ${chosenWeight}`);
+  }
+
+  const bossEntry = getBossEntryWithChosenWeight(bossPool, chosenWeight);
+
+  const roomsMetadataForBoss = roomsMetadata.filter(
+    (roomMetadata) => roomMetadata.subType === bossEntry.subType,
+  );
+  return getRandomCustomStageRoom(roomsMetadataForBoss, seedOrRNG, verbose);
+}
+
+function getTotalWeightOfBossPool(
+  bossPool: readonly CustomStageBossPoolEntry[],
+): float {
+  const weights = bossPool.map((bossEntry) => bossEntry.weight);
+  return sumArray(weights);
+}
+
+function getBossEntryWithChosenWeight(
+  bossPool: readonly CustomStageBossPoolEntry[],
+  chosenWeight: float,
+): CustomStageBossPoolEntry {
+  for (const bossEntry of bossPool) {
+    if (chosenWeight < bossEntry.weight) {
+      return bossEntry;
+    }
+
+    chosenWeight -= bossEntry.weight;
+  }
+
+  error(
+    `Failed to get a custom stage boss entry with chosen weight: ${chosenWeight}`,
+  );
+}

package/src/features/customStage/exports.ts

@@ -8,7 +8,7 @@
  */
 
 import {
-  EntityType,
+  DoorSlot,
   LevelStage,
   RoomShape,
   RoomType,
@@ -16,7 +16,7 @@ import {
 } from "isaac-typescript-definitions";
 import { reorderedCallbacksSetStageInternal } from "../../callbacks/reorderedCallbacks";
 import { game } from "../../core/cachedClasses";
-import { getEntityIDFromConstituents } from "../../functions/entities";
+import { doorSlotFlagsToDoorSlots } from "../../functions/doors";
 import { logError } from "../../functions/log";
 import { newRNG } from "../../functions/rng";
 import {
@@ -25,13 +25,13 @@ import {
 } from "../../functions/rooms";
 import { setStage } from "../../functions/stage";
 import { asNumber } from "../../functions/types";
+import { CustomStageRoomMetadata } from "../../interfaces/CustomStageTSConfig";
 import { CustomStage } from "../../interfaces/private/CustomStage";
-import { getRandomCustomStageRoom } from "./customStageUtils";
-import v, {
-  customBossPNGPaths,
-  customStageCachedRoomData,
-  customStagesMap,
-} from "./v";
+import {
+  getRandomBossRoomFromPool,
+  getRandomCustomStageRoom,
+} from "./customStageUtils";
+import v, { customStageCachedRoomData, customStagesMap } from "./v";
 
 export const DEFAULT_BASE_STAGE = LevelStage.BASEMENT_2;
 export const DEFAULT_BASE_STAGE_TYPE = StageType.ORIGINAL;
@@ -135,8 +135,8 @@ function setStageRoomsData(
     const roomType = room.Data.Type;
     const roomShapeMap = customStage.roomTypeMap.get(roomType);
     if (roomShapeMap === undefined) {
-      // Only show errors for non-default room types. (By default, we won't replace shops and other
-      // special rooms.)
+      // Only show errors for non-default room types. (We do not require that end-users provide
+      // custom rooms for shops and other special rooms inside of their XML file.)
       if (roomType === RoomType.DEFAULT) {
         logError(
           `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) for custom stage: ${customStage.name}`,
@@ -160,10 +160,32 @@ function setStageRoomsData(
       logError(
         `Failed to find any custom rooms for RoomType.${RoomType[roomType]} (${roomType}) + RoomShape.${RoomShape[roomShape]} (${roomShape}) + DoorSlotFlags ${doorSlotFlags} for custom stage: ${customStage.name}`,
       );
+
+      const header = `For reference, a DoorSlotFlags of ${doorSlotFlags} is equal to the following doors being enabled:\n`;
+      const doorSlots = doorSlotFlagsToDoorSlots(doorSlotFlags);
+      const doorSlotLines = doorSlots.map(
+        (doorSlot) => `- DoorSlot.${DoorSlot[doorSlot]} (${doorSlot})`,
+      );
+      const explanation = header + doorSlotLines.join("\n");
+      logError(explanation);
       continue;
     }
 
-    const randomRoom = getRandomCustomStageRoom(roomsMetadata, rng, verbose);
+    let randomRoom: CustomStageRoomMetadata;
+    if (roomType === RoomType.BOSS) {
+      if (customStage.bossPool === undefined) {
+        continue;
+      }
+
+      randomRoom = getRandomBossRoomFromPool(
+        roomsMetadata,
+        customStage.bossPool,
+        rng,
+        verbose,
+      );
+    } else {
+      randomRoom = getRandomCustomStageRoom(roomsMetadata, rng, verbose);
+    }
 
     let newRoomData = customStageCachedRoomData.get(randomRoom.variant);
     if (newRoomData === undefined) {
@@ -187,40 +209,6 @@ function setStageRoomsData(
   }
 }
 
-/**
- * By default, unknown bosses will be drawn on the boss "versus" screen as "???". If your custom
- * stage has custom bosses, you can use this function to register the corresponding graphic file
- * files for them.
- *
- * For reference:
- * - The vanilla name sprite for Monstro is located at:
- *   `resources/gfx/ui/boss/bossname_20.0_monstro.png`
- * - The vanilla portrait sprite for Monstro is located at:
- *   `resources/gfx/ui/boss/portrait_20.0_monstro.png`
- *
- * (Note that boss metadata like this cannot be specified with the rest of the custom stage metadata
- * in the "tsconfig.json" file because there is not a way to retrieve the name of an entity at
- * run-time.)
- *
- * @param entityType The entity type of the custom boss.
- * @param variant The variant of the custom boss.
- * @param subType The sub-type of the custom boss.
- * @param namePNGPath The full path to the PNG file that contains the name of the boss that will be
- *                    displayed on the top of the boss "versus" screen.
- * @param portraitPNGPath The full path to the PNG file that contains the portrait of the boss that
- *                        will be displayed on the right side of the boss "versus" screen.
- */
-export function registerCustomBoss(
-  entityType: EntityType,
-  variant: int,
-  subType: int,
-  namePNGPath: string,
-  portraitPNGPath: string,
-): void {
-  const entityID = getEntityIDFromConstituents(entityType, variant, subType);
-  customBossPNGPaths.set(entityID, [namePNGPath, portraitPNGPath]);
-}
-
 /**
  * Helper function to disable the custom stage. This is typically called before taking the player to
  * a vanilla floor.

package/src/features/customStage/init.ts

@@ -13,7 +13,7 @@ import { hasFlag, removeFlag } from "../../functions/flag";
 import {
   CustomStageLua,
   CustomStageRoomMetadata,
-} from "../../interfaces/CustomStageLua";
+} from "../../interfaces/CustomStageTSConfig";
 import { CustomStage, RoomTypeMap } from "../../interfaces/private/CustomStage";
 import { saveDataManager } from "../saveDataManager/exports";
 import { setCustomStageBackdrop } from "./backdrop";

package/src/features/customStage/v.ts

@@ -40,9 +40,3 @@ export const customStagesMap = new Map<string, CustomStage>();
 
 /** Indexed by room variant. */
 export const customStageCachedRoomData = new Map<int, Readonly<RoomConfig>>();
-
-/** Indexed by entity ID. */
-export const customBossPNGPaths = new Map<
-  string,
-  [namePNGPath: string, portraitPNGPath: string]
->();