isaacscript-common 7.4.1 → 7.5.0

package/src/enums/StatType.ts

@@ -39,9 +39,9 @@ export enum StatType {
   /** Corresponds to `CacheFlag.LUCK` (1 << 10) and `EntityPlayer.Luck`. */
   LUCK,
 
-  // - `CacheFlag.SIZE` (1 << 12) does not have a corresponding `EntityPlayer` field. (After picking
-  //   up Magic Mushroom, the values of `EntityPlayer.Size` and `EntityPlayer.SizeMulti` do not
-  //   change.)
+  /** Corresponds to `CacheFlag.SIZE` (1 << 11) and `EntityPlayer.SpriteScale`. */
+  SIZE,
+
   // - `CacheFlag.COLOR` (1 << 12) does not have a corresponding `EntityPlayer` field.
   // - `CacheFlag.PICKUP_VISION` (1 << 13) does not have a corresponding `EntityPlayer` field.
 }

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,10 +14,10 @@ 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 { isCustomGridEntity } from "../customGridEntity";
 import { spawnCustomTrapdoor } from "../customTrapdoor/exports";
 import { DEFAULT_BASE_STAGE } from "./exports";
 import v from "./v";
@@ -34,14 +33,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 +62,10 @@ export function setCustomRockGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityRock = gridEntity.ToRock();
   if (gridEntityRock === undefined) {
     return;
@@ -92,6 +93,10 @@ export function setCustomPitGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityPit = gridEntity.ToPit();
   if (gridEntityPit === undefined) {
     return;
@@ -116,6 +121,10 @@ export function setCustomDoorGraphics(
     return;
   }
 
+  if (isCustomGridEntity(gridEntity)) {
+    return;
+  }
+
   const gridEntityDoor = gridEntity.ToDoor();
   if (gridEntityDoor === undefined) {
     return;

package/src/functions/dev.ts

@@ -0,0 +1,31 @@
+import { ModUpgraded } from "../classes/ModUpgraded";
+import { enableExtraConsoleCommands } from "../features/extraConsoleCommands/exports";
+import { removeFadeIn } from "../features/fadeInRemover";
+import { enableFastReset } from "../features/fastReset";
+import { saveDataManagerSetGlobal } from "../features/saveDataManager/exports";
+import { setLogFunctionsGlobal } from "./log";
+
+/**
+ * Helper function to enable some IsaacScript features that are useful when developing a mod. They
+ * shouldn't be enabled when your mod goes to production (i.e. it is uploaded to the Steam
+ * Workshop).
+ *
+ * The list of development features that are enabled are as follows:
+ *
+ * - `saveDataManagerSetGlobal` - Sets your local variables registered with the save data manager as
+ *   global variables so you can access them from the in-game console.
+ * - `setLogFunctionsGlobal` - Sets the various log functions global so that you can access them
+ *   from the in-game console.
+ * - `enableExtraConsoleCommands` - Enables many extra in-game console commands that make warping
+ *   around easier (like e.g. `angel` to warp to the Angel Room).
+ * - `enableFastReset` - Makes it so that the r key resets the game instantaneously.
+ * - `removeFadeIn` - Removes the slow fade in that occurs at the beginning of the run, so that you
+ *   can immediately start playing or testing.
+ */
+export function enableDevFeatures(mod: ModUpgraded): void {
+  saveDataManagerSetGlobal();
+  setLogFunctionsGlobal();
+  enableExtraConsoleCommands(mod);
+  enableFastReset();
+  removeFadeIn();
+}

package/src/functions/gridEntities.ts

@@ -1,5 +1,6 @@
 import {
   CrawlSpaceVariant,
+  EffectVariant,
   GridCollisionClass,
   GridEntityType,
   GridEntityXMLType,
@@ -16,12 +17,14 @@ import {
   ROOM_SHAPE_TO_TOP_LEFT_WALL_GRID_INDEX_MAP,
 } from "../maps/roomShapeToTopLeftWallGridIndexMap";
 import { AnyGridEntity } from "../types/AnyGridEntity";
+import { removeEntities } from "./entities";
+import { getEffects } from "./entitiesSpecific";
 import { isCircleIntersectingRectangle } from "./math";
 import { roomUpdateSafe } from "./rooms";
 import { clearSprite } from "./sprites";
 import { asNumber, isNumber } from "./types";
 import { erange } from "./utils";
-import { isVector } from "./vector";
+import { isVector, vectorEquals } from "./vector";
 
 const BREAKABLE_GRID_ENTITY_TYPES_BY_EXPLOSIONS: ReadonlySet<GridEntityType> =
   new Set([
@@ -498,6 +501,9 @@ export function removeGridEntities<T extends AnyGridEntity>(
  * Helper function to remove a grid entity by providing the grid entity object or the grid index
  * inside of the room.
  *
+ * If removing a Devil Statue or an Angel Statue, this will also remove the associated effect
+ * (`EffectVariant.DEVIL` (6) or `EffectVariant.ANGEL` (9), respectively.)
+ *
  * @param gridEntityOrGridIndex The grid entity or grid index to remove.
  * @param updateRoom Whether or not to update the room after the grid entity is removed. This is
  *                   generally a good idea because if the room is not updated, you will be unable to
@@ -511,6 +517,18 @@ export function removeGridEntity(
 ): void {
   const room = game.GetRoom();
 
+  const gridEntity = isNumber(gridEntityOrGridIndex)
+    ? room.GetGridEntity(gridEntityOrGridIndex)
+    : gridEntityOrGridIndex;
+  if (gridEntity === undefined) {
+    // There is no grid entity to remove.
+    return;
+  }
+
+  const gridEntityType = gridEntity.GetType();
+  const variant = gridEntity.GetVariant();
+  const position = gridEntity.Position;
+
   const gridIndex = isNumber(gridEntityOrGridIndex)
     ? gridEntityOrGridIndex
     : gridEntityOrGridIndex.GetGridIndex();
@@ -519,6 +537,20 @@ export function removeGridEntity(
   if (updateRoom) {
     roomUpdateSafe();
   }
+
+  // In the special case of removing a Devil Statue or Angel Statue, we also need to delete the
+  // corresponding effect.
+  if (gridEntityType === GridEntityType.STATUE) {
+    const effectVariant =
+      variant === asNumber(StatueVariant.DEVIL)
+        ? EffectVariant.DEVIL
+        : EffectVariant.ANGEL;
+    const effects = getEffects(effectVariant);
+    const effectsOnTile = effects.filter((effect) =>
+      vectorEquals(effect.Position, position),
+    );
+    removeEntities(effectsOnTile);
+  }
 }
 
 /**

package/src/functions/playerStats.ts

@@ -21,5 +21,6 @@ export function getPlayerStat<T extends StatType>(
     [StatType.TEAR_COLOR]: player.TearColor, // 1 << 6
     [StatType.FLYING]: player.CanFly, // 1 << 7
     [StatType.LUCK]: player.Luck, // 1 << 10
+    [StatType.SIZE]: player.SpriteScale, // 1 << 11
   }[statType];
 }

package/src/functions/rooms.ts

@@ -4,6 +4,7 @@ import {
   BossID,
   Dimension,
   DoorSlot,
+  DownpourRoomSubType,
   DungeonSubType,
   GridRoom,
   HomeRoomSubType,
@@ -425,6 +426,23 @@ export function inMinibossRoomOf(minibossID: MinibossID): boolean {
   );
 }
 
+/**
+ * Helper function to check if the current room is a "mirror room" in Downpour or Dross. (These
+ * rooms are marked with a specific sub-type.)
+ */
+export function inMirrorRoom(): boolean {
+  const room = game.GetRoom();
+  const roomType = room.GetType();
+  const roomStageID = getRoomStageID();
+  const roomSubType = getRoomSubType();
+
+  return (
+    roomType === RoomType.DEFAULT &&
+    (roomStageID === StageID.DOWNPOUR || roomStageID === StageID.DROSS) &&
+    roomSubType === asNumber(DownpourRoomSubType.MIRROR)
+  );
+}
+
 /**
  * Helper function for checking if the room is a secret shop (from the Member Card collectible).
  *