isaacscript-common 84.0.1 → 84.1.1

package/dist/functions/sound.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stopAllSoundEffects = exports.getMusicForStage = void 0;
+const cachedEnumValues_1 = require("../arrays/cachedEnumValues");
+const cachedClasses_1 = require("../core/cachedClasses");
+const stageToMusic_1 = require("../objects/stageToMusic");
+const enums_1 = require("./enums");
+/**
+ * Helper function to get the corresponding music value for a stage and stage type combination.
+ *
+ * @param stage Optional. The stage to get the music for. If not specified, the current stage will
+ *              be used.
+ * @param stageType Optional. The stage type to get the music for. If not specified, the current
+ *                  stage type will be used.
+ */
+function getMusicForStage(stage, stageType) {
+    const level = cachedClasses_1.game.GetLevel();
+    if (stage === undefined) {
+        stage = level.GetStage();
+    }
+    if (stageType === undefined) {
+        stageType = level.GetStageType();
+    }
+    const stageTypeToMusic = stageToMusic_1.STAGE_TO_MUSIC[stage];
+    return stageTypeToMusic[stageType];
+}
+exports.getMusicForStage = getMusicForStage;
+/**
+ * Helper function to manually stop every vanilla sound effect. If you also want to stop custom
+ * sound effects in addition to vanilla ones, then pass the `SoundEffectCustom` enum for your mod.
+ *
+ * @param soundEffectCustom Optional. The enum that represents all of the custom sound effects for
+ *                          your mod.
+ */
+function stopAllSoundEffects(soundEffectCustom) {
+    for (const soundEffect of cachedEnumValues_1.SOUND_EFFECT_VALUES) {
+        cachedClasses_1.sfxManager.Stop(soundEffect);
+    }
+    if (soundEffectCustom !== undefined) {
+        for (const soundEffect of (0, enums_1.getEnumValues)(soundEffectCustom)) {
+            cachedClasses_1.sfxManager.Stop(soundEffect);
+        }
+    }
+}
+exports.stopAllSoundEffects = stopAllSoundEffects;

package/dist/functions/spawnCollectible.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnEmptyCollectible = exports.spawnCollectibleFromPool = exports.spawnCollectible = void 0;
+const isaac_typescript_definitions_1 = require("isaac-typescript-definitions");
+const cachedClasses_1 = require("../core/cachedClasses");
+const constants_1 = require("../core/constants");
+const collectibleTag_1 = require("./collectibleTag");
+const collectibles_1 = require("./collectibles");
+const entitiesSpecific_1 = require("./entitiesSpecific");
+const players_1 = require("./players");
+const rng_1 = require("./rng");
+/**
+ * Helper function to spawn a collectible.
+ *
+ * Use this instead of the `Game.Spawn` method because it handles the cases of Tainted Keeper
+ * collectibles costing coins and prevents quest items from being rotated by Tainted Isaac's
+ * rotation mechanic.
+ *
+ * If you want to spawn an unseeded collectible, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * @param collectibleType The collectible type to spawn.
+ * @param positionOrGridIndex The position or grid index to spawn the collectible at.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param options Optional. Set to true to make the collectible a "There's Options" style
+ *                collectible. Default is false.
+ * @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
+ *                      Tainted Keeper. Default is false.
+ * @param spawner Optional.
+ */
+function spawnCollectible(collectibleType, positionOrGridIndex, seedOrRNG, options = false, forceFreeItem = false, spawner) {
+    if (seedOrRNG === undefined) {
+        seedOrRNG = (0, rng_1.getRandomSeed)();
+    }
+    const seed = (0, rng_1.isRNG)(seedOrRNG) ? seedOrRNG.Next() : seedOrRNG;
+    const collectible = (0, entitiesSpecific_1.spawnPickupWithSeed)(isaac_typescript_definitions_1.PickupVariant.COLLECTIBLE, collectibleType, positionOrGridIndex, seed, constants_1.VectorZero, spawner);
+    if ((0, collectibleTag_1.isQuestCollectible)(collectible)) {
+        (0, collectibles_1.preventCollectibleRotation)(collectible);
+    }
+    if (options) {
+        collectible.OptionsPickupIndex = 1;
+    }
+    if ((0, players_1.anyPlayerIs)(isaac_typescript_definitions_1.PlayerType.KEEPER_B) &&
+        !(0, collectibleTag_1.isQuestCollectible)(collectibleType) &&
+        !forceFreeItem) {
+        // When playing Tainted Keeper, collectibles are supposed to have a price, and manually spawned
+        // items will not have a price, so we have to set it manually.
+        // Setting the shop item ID in this way prevents the bug where the item will sometimes change to
+        // 99 cents.
+        collectible.ShopItemId = -1;
+        // We can set the price to any arbitrary value; it will auto-update to the true price on the
+        // next frame.
+        collectible.Price = 15;
+    }
+    return collectible;
+}
+exports.spawnCollectible = spawnCollectible;
+/**
+ * Helper function to spawn a collectible from a specific item pool.
+ *
+ * Use this instead of the `Game.Spawn` method because it handles the cases of Tainted Keeper
+ * collectibles costing coins and prevents quest items from being rotated by Tainted Isaac's
+ * rotation mechanic.
+ *
+ * If you want to spawn an unseeded collectible, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * In order to use this function, you must upgrade your mod with `ISCFeature.SPAWN_COLLECTIBLE`.
+ *
+ * @param itemPoolType The item pool to draw the collectible type from.
+ * @param positionOrGridIndex The position or grid index to spawn the collectible at.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ * @param options Optional. Set to true to make the collectible a "There's Options" style
+ *                collectible. Default is false.
+ * @param forceFreeItem Optional. Set to true to disable the logic that gives the item a price for
+ *                      Tainted Keeper. Default is false.
+ * @param spawner Optional.
+ */
+function spawnCollectibleFromPool(itemPoolType, positionOrGridIndex, seedOrRNG, options = false, forceFreeItem = false, spawner) {
+    const itemPool = cachedClasses_1.game.GetItemPool();
+    const collectibleType = itemPool.GetCollectible(itemPoolType);
+    return spawnCollectible(collectibleType, positionOrGridIndex, seedOrRNG, options, forceFreeItem, spawner);
+}
+exports.spawnCollectibleFromPool = spawnCollectibleFromPool;
+/**
+ * Helper function to spawn an empty collectible. Doing this is tricky since spawning a collectible
+ * with `CollectibleType.NULL` will result in spawning a collectible with a random type from the
+ * current room's item pool.
+ *
+ * Instead, this function arbitrarily spawns a collectible with `CollectibleType.BROKEN_SHOVEL_1`,
+ * and then converts it to an empty pedestal afterward. (Broken Shovel is used instead of e.g. Sad
+ * Onion because it is a quest collectible and quest collectibles will prevent Damocles from
+ * duplicating the pedestal.)
+ *
+ * If you want to spawn an unseeded collectible, you must explicitly pass `undefined` to the
+ * `seedOrRNG` parameter.
+ *
+ * @param positionOrGridIndex The position or grid index to spawn the empty collectible at.
+ * @param seedOrRNG The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. If `undefined` is provided, it will default to
+ *                  a random seed.
+ */
+function spawnEmptyCollectible(positionOrGridIndex, seedOrRNG) {
+    const collectible = spawnCollectible(isaac_typescript_definitions_1.CollectibleType.BROKEN_SHOVEL_1, positionOrGridIndex, seedOrRNG, false, true);
+    (0, collectibles_1.setCollectibleEmpty)(collectible);
+    return collectible;
+}
+exports.spawnEmptyCollectible = spawnEmptyCollectible;

package/dist/functions/sprites.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.texelEquals = exports.spriteEquals = exports.setSpriteOpacity = exports.newSprite = exports.getLastFrameOfAnimation = exports.clearSprite = void 0;
+const constants_1 = require("../core/constants");
+const color_1 = require("./color");
+const kColor_1 = require("./kColor");
+const utils_1 = require("./utils");
+/**
+ * Helper function to clear all layers or specific layers from a sprite without unloading the
+ * attached anm2 file.
+ *
+ * This function is variadic, which means you can pass as many layer IDs as you want to clear. If no
+ * specific layers are passed, the function will clear every layer.
+ *
+ * If you want to clear all of the layers of a sprite and don't care about unloading the attached
+ * anm2 file, then use the `Sprite.Reset` method instead.
+ *
+ * Since there is no official API method to clear specific layers from a sprite, we work around it
+ * by setting the spritesheet to a transparent PNG file corresponding to the `EMPTY_PNG_PATH`
+ * constant.
+ *
+ * This function will still work identically if PNG file does not exist, but it will cause a
+ * spurious error to appear in the "log.txt" file. If silencing these errors is desired, you can
+ * create a transparent 1 pixel PNG file in your mod's resources folder at `EMPTY_PNG_PATH`.
+ *
+ * @allowEmptyVariadic
+ */
+function clearSprite(sprite, ...layerIDs) {
+    if (layerIDs.length === 0) {
+        const numLayers = sprite.GetLayerCount();
+        layerIDs = (0, utils_1.eRange)(numLayers);
+    }
+    for (const layerID of layerIDs) {
+        sprite.ReplaceSpritesheet(layerID, constants_1.EMPTY_PNG_PATH);
+    }
+    sprite.LoadGraphics();
+}
+exports.clearSprite = clearSprite;
+/**
+ * Helper function that returns the number of the final frame in a particular animation for a
+ * sprite. By default, it will use the currently playing animation, but you can also specify a
+ * specific animation to check.
+ *
+ * Note that this function is bugged with the Stop Watch or the Broken Watch, since using the
+ * `Sprite.SetFrame` method will reset the internal accumulator used to slow down the playback speed
+ * of the animation. (The `PlaybackSpeed` field of the sprite is not used.) Thus, it is only safe to
+ * use this function on animations that are not slowed down by Stop Watch or Broken Watch, such as
+ * player animations.
+ */
+function getLastFrameOfAnimation(sprite, animation) {
+    // Record the current sprite status.
+    const currentAnimation = sprite.GetAnimation();
+    const currentFrame = sprite.GetFrame();
+    // Get the final frame.
+    if (animation !== undefined && animation !== currentAnimation) {
+        sprite.SetAnimation(animation);
+    }
+    sprite.SetLastFrame();
+    const finalFrame = sprite.GetFrame();
+    // Set the sprite back to the way it was.
+    if (animation !== undefined && animation !== currentAnimation) {
+        sprite.Play(currentAnimation, true);
+    }
+    sprite.SetFrame(currentFrame);
+    return finalFrame;
+}
+exports.getLastFrameOfAnimation = getLastFrameOfAnimation;
+/**
+ * Helper function to load a new sprite and play its default animation.
+ *
+ * @param anm2Path The path to the "anm2" file that should be loaded.
+ * @param pngPath Optional. The path to a custom PNG file that should be loaded on layer 0 of the
+ *                sprite.
+ */
+function newSprite(anm2Path, pngPath) {
+    const sprite = Sprite();
+    if (pngPath === undefined) {
+        sprite.Load(anm2Path, true);
+    }
+    else {
+        sprite.Load(anm2Path, false);
+        sprite.ReplaceSpritesheet(0, pngPath);
+        sprite.LoadGraphics();
+    }
+    const defaultAnimation = sprite.GetDefaultAnimation();
+    sprite.Play(defaultAnimation, true);
+    return sprite;
+}
+exports.newSprite = newSprite;
+/**
+ * Helper function to keep a sprite's color the same values as it already is but set the opacity to
+ * a specific value.
+ *
+ * @param sprite The sprite to set.
+ * @param alpha A value between 0 and 1 that represents the fade amount.
+ */
+function setSpriteOpacity(sprite, alpha) {
+    const fadedColor = (0, color_1.copyColor)(sprite.Color);
+    fadedColor.A = alpha;
+    sprite.Color = fadedColor;
+}
+exports.setSpriteOpacity = setSpriteOpacity;
+/**
+ * Helper function to check if two sprite layers have the same sprite sheet by using the
+ * `Sprite.GetTexel` method.
+ *
+ * Since checking every single texel in the entire sprite is very expensive, this function requires
+ * that you provide a range of specific texels to check.
+ */
+function spriteEquals(sprite1, sprite2, layerID, xStart, xFinish, xIncrement, yStart, yFinish, yIncrement) {
+    // Iterate over N texels, checking for equality at each step. The center of the sprite is equal to
+    // the "pivot" point in the anm2 file.
+    for (let x = xStart; x <= xFinish; x += xIncrement) {
+        for (let y = yStart; y <= yFinish; y += yIncrement) {
+            const position = Vector(x, y);
+            if (!texelEquals(sprite1, sprite2, position, layerID)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+exports.spriteEquals = spriteEquals;
+/** Helper function to check if two texels on a sprite are equivalent to each other. */
+function texelEquals(sprite1, sprite2, position, layerID) {
+    const kColor1 = sprite1.GetTexel(position, constants_1.VectorZero, 1, layerID);
+    const kColor2 = sprite2.GetTexel(position, constants_1.VectorZero, 1, layerID);
+    return (0, kColor_1.kColorEquals)(kColor1, kColor2);
+}
+exports.texelEquals = texelEquals;