isaacscript-common 2.2.0 → 2.3.0

package/src/functions/cards.ts

@@ -0,0 +1,267 @@
+import { Card, ItemConfigCardType } from "isaac-typescript-definitions";
+import { itemConfig } from "../cachedClasses";
+import {
+  FIRST_CARD,
+  FIRST_MODDED_CARD,
+  LAST_CARD,
+  MAX_VANILLA_CARD,
+} from "../constantsFirstLast";
+import {
+  CARD_DESCRIPTIONS,
+  DEFAULT_CARD_DESCRIPTION,
+} from "../objects/cardDescriptions";
+import { CARD_NAMES, DEFAULT_CARD_NAME } from "../objects/cardNames";
+import { CARD_TYPES, DEFAULT_CARD_TYPE } from "../objects/cardTypes";
+import { getEnumValues } from "./enums";
+import { getRandomSeed } from "./rng";
+import { addSetsToSet, getRandomSetElement } from "./set";
+import { irange } from "./utils";
+
+const CARD_TYPE_TO_CARDS_MAP: Map<ItemConfigCardType, Set<Card>> = new Map();
+
+/**
+ * Contains all of the entries in the `Card` enum with the following types:
+ * - ItemConfigCardType.TAROT
+ * - ItemConfigCardType.SUIT
+ * - ItemConfigCardType.SPECIAL
+ * - ItemConfigCardType.TAROT_REVERSE
+ */
+const CARD_SET: Set<Card> = new Set();
+
+function initCardObjects() {
+  // The card type to cards map should be valid for every card type, so we initialize it with empty
+  // sets.
+  for (const cardType of getEnumValues(ItemConfigCardType)) {
+    CARD_TYPE_TO_CARDS_MAP.set(cardType, new Set<Card>());
+  }
+
+  for (const card of getAllCards()) {
+    const cardType = getCardType(card);
+    const cardTypeSet = CARD_TYPE_TO_CARDS_MAP.get(cardType);
+    if (cardTypeSet === undefined) {
+      error(`Failed to get the card set for card type: ${cardType}`);
+    }
+    cardTypeSet.add(card);
+  }
+
+  // i.e. everything except for:
+  // - ItemConfigCardType.RUNE
+  // - ItemConfigCardType.SPECIAL_OBJECT
+  // - ItemConfigCardType.MODDED
+  const cards = getCardsOfType(
+    ItemConfigCardType.TAROT,
+    ItemConfigCardType.SUIT,
+    ItemConfigCardType.SPECIAL,
+    ItemConfigCardType.TAROT_REVERSE,
+  );
+  addSetsToSet(CARD_SET, cards);
+}
+
+/** Helper function to get an array with every valid card sub-type. This includes modded cards. */
+export function getAllCards(): Card[] {
+  return irange(FIRST_CARD, LAST_CARD) as Card[];
+}
+
+/**
+ * Helper function to get a card description from a Card enum value.
+ *
+ * For example:
+ *
+ * ```ts
+ * const card = Card.FOOL;
+ * const cardDescription = getCardDescription(card); // cardDescription is "Where journey begins"
+ * ```
+ */
+export function getCardDescription(card: Card): string {
+  // "ItemConfigCard.Description" is bugged with vanilla cards on patch v1.7.6, so we use a
+  // hard-coded map as a workaround.
+  const cardDescription = CARD_DESCRIPTIONS[card];
+  if (cardDescription !== undefined) {
+    return cardDescription;
+  }
+
+  const itemConfigCard = itemConfig.GetCard(card);
+  if (itemConfigCard !== undefined) {
+    return itemConfigCard.Description;
+  }
+
+  return DEFAULT_CARD_DESCRIPTION;
+}
+
+/**
+ * Helper function to get a card name from a Card.
+ *
+ * For example:
+ *
+ * ```ts
+ * const card = Card.FOOL;
+ * const cardName = getCardName(card); // cardName is "0 - The Fool"
+ * ```
+ */
+export function getCardName(card: Card): string {
+  // "ItemConfigCard.Name" is bugged with vanilla cards on patch v1.7.6, so we use a hard-coded map
+  // as a workaround.
+  const cardName = CARD_NAMES[card];
+  if (cardName !== undefined && cardName !== DEFAULT_CARD_NAME) {
+    return cardName;
+  }
+
+  const itemConfigCard = itemConfig.GetCard(card);
+  if (itemConfigCard !== undefined) {
+    return itemConfigCard.Name;
+  }
+
+  return DEFAULT_CARD_NAME;
+}
+
+export function getCardType(card: Card): ItemConfigCardType {
+  const cardType = CARD_TYPES[card];
+  return cardType === undefined ? DEFAULT_CARD_TYPE : cardType;
+}
+
+/**
+ * Helper function to get a set of cards matching the type. Also see the `CardType` enum.
+ *
+ * This function is variadic, meaning that you can you can specify N card types to get a set
+ * containing cards that match any of the specified types.
+ */
+export function getCardsOfType(...cardTypes: ItemConfigCardType[]): Set<Card> {
+  if (CARD_TYPE_TO_CARDS_MAP.size === 0) {
+    initCardObjects();
+  }
+
+  const matchingCards = new Set<Card>();
+  for (const cardType of cardTypes) {
+    const cardSet = CARD_TYPE_TO_CARDS_MAP.get(cardType);
+    if (cardSet === undefined) {
+      error(`Failed to get the cards for type: ${cardType}`);
+    }
+
+    for (const card of cardSet.values()) {
+      matchingCards.add(card);
+    }
+  }
+
+  return matchingCards;
+}
+
+/**
+ * Helper function to get an array with every modded card sub-type.
+ *
+ * Returns an empty array if there are no modded cards.
+ */
+export function getModdedCards(): Card[] {
+  if (MAX_VANILLA_CARD === LAST_CARD) {
+    return [];
+  }
+
+  return irange(FIRST_MODDED_CARD, LAST_CARD) as Card[];
+}
+
+/**
+ * Has an equal chance of returning any card (e.g. Fool, Reverse Fool, Wild Card, etc.).
+ *
+ * This will not return:
+ * - any runes
+ * - any objects like Dice Shard
+ * - any modded cards (since there is not a way to distinguish between modded cards and modded
+ *   runes/objects)
+ *
+ * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param exceptions Optional. An array of cards to not select.
+ */
+export function getRandomCard(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  return getRandomSetElement(CARD_SET, seedOrRNG, exceptions);
+}
+
+/**
+ * @param cardType The card type that represents the pool of cards to select from.
+ * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param exceptions Optional. An array of cards to not select.
+ */
+export function getRandomCardOfType(
+  cardType: ItemConfigCardType,
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  const cardSet = getCardsOfType(cardType);
+  return getRandomSetElement(cardSet, seedOrRNG, exceptions);
+}
+
+/**
+ * Has an equal chance of returning any rune (e.g. Rune of Hagalaz, Blank Rune, Black Rune, Soul of
+ * Isaac, etc.). This will never return a Rune Shard.
+ *
+ * @param seedOrRNG Optional. The `Seed` or `RNG` object to use. If an `RNG` object is provided, the
+ *                  `RNG.Next` method will be called. Default is `getRandomSeed()`.
+ * @param exceptions Optional. An array of runes to not select.
+ */
+export function getRandomRune(
+  seedOrRNG: Seed | RNG = getRandomSeed(),
+  exceptions: Card[] = [],
+): Card {
+  const runesSet = getCardsOfType(ItemConfigCardType.RUNE);
+  runesSet.delete(Card.RUNE_SHARD);
+  return getRandomSetElement(runesSet, seedOrRNG, exceptions);
+}
+
+/** Helper function to get an array with every valid vanilla card sub-type. */
+export function getVanillaCards(): Card[] {
+  return irange(FIRST_CARD, MAX_VANILLA_CARD) as Card[];
+}
+
+/**
+ * Returns true for cards that have the following card type:
+ * - CardType.TAROT
+ * - CardType.SUIT
+ * - CardType.SPECIAL
+ * - CardType.TAROT_REVERSE
+ */
+export function isCard(card: Card): boolean {
+  return CARD_SET.has(card);
+}
+
+/** Returns whether or not the given card matches the specified card type. */
+export function isCardType(card: Card, cardType: ItemConfigCardType): boolean {
+  return cardType === getCardType(card);
+}
+
+/** Returns true for cards that have `CardType.MODDED`. */
+export function isModdedCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.MODDED);
+}
+
+/** Returns true for cards that have `CardType.SPECIAL_OBJECT`. */
+export function isPocketItemObject(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SPECIAL_OBJECT);
+}
+
+/** Returns true for cards that have `CardType.TAROT_REVERSE`. */
+export function isReverseTarotCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.TAROT_REVERSE);
+}
+
+/** Returns true for cards that have `CardType.RUNE`. */
+export function isRune(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.RUNE);
+}
+
+/** Returns true for cards that have `CardType.SPECIAL`. */
+export function isSpecialCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SPECIAL);
+}
+
+/** Returns true for cards that have `CardType.SUIT`. */
+export function isSuitCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.SUIT);
+}
+
+/** Returns true for cards that have `CardType.TAROT`. */
+export function isTarotCard(card: Card): boolean {
+  return isCardType(card, ItemConfigCardType.TAROT);
+}

package/src/functions/challenges.ts

@@ -0,0 +1,11 @@
+import { Challenge } from "isaac-typescript-definitions";
+import {
+  CHALLENGE_NAMES,
+  DEFAULT_CHALLENGE_NAME,
+} from "../objects/challengeNames";
+
+/** Get the proper name for a `Challenge` enum. This will only work for vanilla challenges. */
+export function getChallengeName(challenge: Challenge): string {
+  const challengeName = CHALLENGE_NAMES[challenge];
+  return challengeName === undefined ? DEFAULT_CHALLENGE_NAME : challengeName;
+}

package/src/functions/character.ts

@@ -0,0 +1,124 @@
+import { PlayerType } from "isaac-typescript-definitions";
+import { LAST_VANILLA_CHARACTER } from "../constantsFirstLast";
+import {
+  CHARACTER_NAMES,
+  DEFAULT_CHARACTER_NAME,
+} from "../objects/characterNames";
+import { CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET } from "../sets/charactersThatStartWithAnActiveItemSet";
+import { CHARACTERS_WITH_BLACK_HEART_FROM_ETERNAL_HEART_SET } from "../sets/charactersWithBlackHeartFromEternalHeartSet";
+import { CHARACTERS_WITH_FREE_DEVIL_DEALS_SET } from "../sets/charactersWithFreeDevilDealsSet";
+import { CHARACTERS_WITH_NO_RED_HEARTS_SET } from "../sets/charactersWithNoRedHeartsSet";
+import { CHARACTERS_WITH_NO_SOUL_HEARTS_SET } from "../sets/charactersWithNoSoulHeartsSet";
+import { LOST_STYLE_CHARACTERS_SET } from "../sets/lostStyleCharactersSet";
+
+/**
+ * Helper function to determine if the given character can have red heart containers. Returns true
+ * for characters like Isaac, Magdalene, or Cain. Returns true for Keeper and Tainted Keeper, even
+ * though coin containers are not technically the same as red heart containers. Returns false for
+ * characters like Blue Baby. Returns false for The Lost and Tainted Lost.
+ */
+export function characterCanHaveRedHearts(character: PlayerType): boolean {
+  return !CHARACTERS_WITH_NO_RED_HEARTS_SET.has(character);
+}
+
+/**
+ * Helper function to determine if the given character can have soul hearts. Returns true for
+ * characters like Isaac, Magdalene, or Cain. Returns false for characters like Bethany. Returns
+ * false for The Lost and Tainted Lost.
+ */
+export function characterCanHaveSoulHearts(character: PlayerType): boolean {
+  return !CHARACTERS_WITH_NO_SOUL_HEARTS_SET.has(character);
+}
+
+/**
+ * Helper function for determining whether the given character can take free Devil Deals. (e.g. The
+ * Lost, Tainted Lost, etc.)
+ */
+export function characterCanTakeFreeDevilDeals(character: PlayerType): boolean {
+  return CHARACTERS_WITH_FREE_DEVIL_DEALS_SET.has(character);
+}
+
+/**
+ * Normally, characters get a red heart container upon reaching a new floor with an eternal heart,
+ * but some characters grant a black heart instead. Returns true for Dark Judas and Tainted Judas.
+ * Otherwise, returns false.
+ */
+export function characterGetsBlackHeartFromEternalHeart(
+  character: PlayerType,
+): boolean {
+  return CHARACTERS_WITH_BLACK_HEART_FROM_ETERNAL_HEART_SET.has(character);
+}
+
+/**
+ * Helper function to determine if the specified character starts with an active item.
+ *
+ * For the purposes of this function, the save file is considered to be fully unlocked (e.g. Isaac
+ * is considered to starts with the D6, but this is not the case on a brand new save file).
+ */
+export function characterStartsWithActiveItem(character: PlayerType): boolean {
+  return CHARACTERS_THAT_START_WITH_AN_ACTIVE_ITEM_SET.has(character);
+}
+
+/**
+ * - Most characters have a 56 frame death animation (i.e. the "Death" animation).
+ * - The Lost and Tainted Lost have a 38 frame death animation (i.e. the "LostDeath" animation).
+ * - Tainted Forgotten have a 20 frame death animation (i.e. the "ForgottenDeath" animation).
+ */
+export function getCharacterDeathAnimationName(character: PlayerType): string {
+  if (LOST_STYLE_CHARACTERS_SET.has(character)) {
+    return "LostDeath";
+  }
+
+  if (character === PlayerType.THE_FORGOTTEN_B) {
+    return "ForgottenDeath";
+  }
+
+  return "Death";
+}
+
+/**
+ * Returns the maximum heart containers that the provided character can have. Normally, this is 12,
+ * but with Keeper it is 3, and with Tainted Keeper it is 2. This does not account for Birthright or
+ * Mother's Kiss; use the `getPlayerMaxHeartContainers` helper function for that.
+ */
+export function getCharacterMaxHeartContainers(character: PlayerType): int {
+  // 14
+  if (character === PlayerType.KEEPER) {
+    return 3;
+  }
+
+  // 16
+  if (character === PlayerType.THE_FORGOTTEN) {
+    return 6;
+  }
+
+  // 17
+  if (character === PlayerType.THE_SOUL) {
+    return 6;
+  }
+
+  // 33
+  if (character === PlayerType.KEEPER_B) {
+    return 2;
+  }
+
+  return 12;
+}
+
+/** Helper function to get the name of a character. Returns "unknown" for modded characters. */
+export function getCharacterName(character: PlayerType): string {
+  if (isVanillaCharacter(character)) {
+    return "unknown";
+  }
+
+  const characterName = CHARACTER_NAMES[character];
+  return characterName === undefined ? DEFAULT_CHARACTER_NAME : characterName;
+}
+
+export function isModdedCharacter(character: PlayerType): boolean {
+  return !isVanillaCharacter(character);
+}
+
+export function isVanillaCharacter(character: PlayerType): boolean {
+  return character <= LAST_VANILLA_CHARACTER;
+}

package/src/functions/charge.ts

@@ -0,0 +1,237 @@
+import {
+  ActiveSlot,
+  CollectibleType,
+  RoomShape,
+  SoundEffect,
+  TrinketType,
+} from "isaac-typescript-definitions";
+import { game, sfxManager } from "../cachedClasses";
+import { getCollectibleMaxCharges } from "./collectibles";
+import { getPlayers } from "./playerIndex";
+
+/**
+ * Helper function to add a charge to a player's active item, emulating what happens when a room is
+ * cleared.
+ *
+ * This function will take the following things into account:
+ * - L rooms and 2x2 rooms granting a double charge
+ * - The Battery
+ * - AAA Battery
+ *
+ * @param player The player to grant the charges to.
+ * @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+ *                                 1x1 room for the purposes of calculating how much charge to
+ *                                 grant. Default is false.
+ */
+export function addRoomClearCharge(
+  player: EntityPlayer,
+  ignoreBigRoomDoubleCharge = false,
+): void {
+  for (const activeSlot of [
+    ActiveSlot.PRIMARY,
+    ActiveSlot.SECONDARY,
+    ActiveSlot.POCKET,
+  ]) {
+    addRoomClearChargeToSlot(player, activeSlot, ignoreBigRoomDoubleCharge);
+  }
+}
+
+/**
+ * Helper function to add a charge to one of a player's active items, emulating what happens when a
+ * room is cleared.
+ *
+ * This function will take the following things into account:
+ * - L rooms and 2x2 rooms granting a double charge
+ * - The Battery
+ * - AAA Battery
+ *
+ * @param player The player to grant the charges to.
+ * @param activeSlot The active item slot to grant the charges to.
+ * @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+ *                                 1x1 room for the purposes of calculating how much charge to
+ *                                 grant. Default is false.
+ */
+export function addRoomClearChargeToSlot(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+  ignoreBigRoomDoubleCharge = false,
+): void {
+  if (!player.NeedsCharge(activeSlot)) {
+    return;
+  }
+
+  const hud = game.GetHUD();
+
+  // Find out the new charge to set on the item.
+  const totalCharge = getTotalCharge(player, activeSlot);
+  const chargesToAdd = getNumChargesToAdd(
+    player,
+    activeSlot,
+    ignoreBigRoomDoubleCharge,
+  );
+  const modifiedChargesToAdd = getNumChargesWithAAAModifier(
+    player,
+    activeSlot,
+    chargesToAdd,
+  );
+  const newCharge = totalCharge + modifiedChargesToAdd;
+
+  player.SetActiveCharge(newCharge, activeSlot);
+  hud.FlashChargeBar(player, activeSlot);
+
+  playChargeSoundEffect(player, activeSlot);
+}
+
+function getNumChargesToAdd(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+  ignoreBigRoomDoubleCharge = false,
+) {
+  const room = game.GetRoom();
+  const roomShape = room.GetRoomShape();
+  const activeItem = player.GetActiveItem(activeSlot);
+  const activeCharge = player.GetActiveCharge(activeSlot);
+  const batteryCharge = player.GetBatteryCharge(activeSlot);
+  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
+  const maxCharges = getCollectibleMaxCharges(activeItem);
+
+  if (!hasBattery && activeCharge === maxCharges) {
+    return 0;
+  }
+
+  if (hasBattery && batteryCharge === maxCharges) {
+    return 0;
+  }
+
+  if (!hasBattery && activeCharge + 1 === maxCharges) {
+    // We are only 1 charge away from a full charge, so only add one charge to avoid an overcharge.
+    // (It is possible to set orange charges without the player actually having The Battery.)
+    return 1;
+  }
+
+  if (hasBattery && batteryCharge + 1 === maxCharges) {
+    // We are only 1 charge away from a full double-charge, so only add one charge to avoid an
+    // overcharge.
+    return 1;
+  }
+
+  if (roomShape >= RoomShape.SHAPE_2x2 && !ignoreBigRoomDoubleCharge) {
+    // 2x2 rooms and L rooms should grant 2 charges.
+    return 2;
+  }
+
+  // Clearing a room grants 1 charge by default.
+  return 1;
+}
+
+/**
+ * The AAA Battery should grant an extra charge when the active item is one away from being fully
+ * charged.
+ */
+function getNumChargesWithAAAModifier(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+  chargesToAdd: int,
+) {
+  const activeItem = player.GetActiveItem(activeSlot);
+  const activeCharge = player.GetActiveCharge(activeSlot);
+  const batteryCharge = player.GetBatteryCharge(activeSlot);
+  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
+  const hasAAABattery = player.HasTrinket(TrinketType.AAA_BATTERY);
+  const maxCharges = getCollectibleMaxCharges(activeItem);
+
+  if (!hasAAABattery) {
+    return chargesToAdd;
+  }
+
+  if (!hasBattery && activeCharge + chargesToAdd === maxCharges - 1) {
+    return maxCharges + 1;
+  }
+
+  if (hasBattery && batteryCharge + chargesToAdd === maxCharges - 1) {
+    return maxCharges + 1;
+  }
+
+  return chargesToAdd;
+}
+
+/**
+ * Helper function to add a charge to every player's active item, emulating what happens when a room
+ * is cleared.
+ *
+ * This function will take the following things into account:
+ * - L rooms and 2x2 rooms granting a double charge
+ * - The Battery
+ * - AAA Battery
+ *
+ * @param ignoreBigRoomDoubleCharge Optional. If set to true, it will treat the current room as a
+ *                                 1x1 room for the purposes of calculating how much charge to
+ *                                 grant. Default is false.
+ */
+export function addRoomClearCharges(ignoreBigRoomDoubleCharge = false): void {
+  for (const player of getPlayers()) {
+    addRoomClearCharge(player, ignoreBigRoomDoubleCharge);
+  }
+}
+
+/**
+ * Helper function to get the combined normal charge and the battery charge for the player's active
+ * item. This is useful because you have to add these two values together when setting the active
+ * charge.
+ */
+export function getTotalCharge(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+): int {
+  const activeCharge = player.GetActiveCharge(activeSlot);
+  const batteryCharge = player.GetBatteryCharge(activeSlot);
+
+  return activeCharge + batteryCharge;
+}
+
+export function isActiveSlotDoubleCharged(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+): boolean {
+  const collectibleType = player.GetActiveItem(activeSlot);
+  const batteryCharge = player.GetBatteryCharge(activeSlot);
+  const maxCharges = getCollectibleMaxCharges(collectibleType);
+
+  return batteryCharge >= maxCharges;
+}
+
+export function playChargeSoundEffect(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+): void {
+  for (const soundEffect of [SoundEffect.BATTERY_CHARGE, SoundEffect.BEEP]) {
+    sfxManager.Stop(soundEffect);
+  }
+
+  const chargeSoundEffect = shouldPlayFullRechargeSound(player, activeSlot)
+    ? SoundEffect.BATTERY_CHARGE
+    : SoundEffect.BEEP;
+  sfxManager.Play(chargeSoundEffect);
+}
+
+function shouldPlayFullRechargeSound(
+  player: EntityPlayer,
+  activeSlot: ActiveSlot,
+) {
+  const activeItem = player.GetActiveItem(activeSlot);
+  const activeCharge = player.GetActiveCharge(activeSlot);
+  const batteryCharge = player.GetBatteryCharge(activeSlot);
+  const hasBattery = player.HasCollectible(CollectibleType.BATTERY);
+  const maxCharges = getCollectibleMaxCharges(activeItem);
+
+  if (!hasBattery) {
+    // Play the full recharge sound if we are now fully charged.
+    return !player.NeedsCharge(activeSlot);
+  }
+
+  // Play the full recharge sound if we are now fully charged or we are exactly half-way charged.
+  return (
+    !player.NeedsCharge(activeSlot) ||
+    (activeCharge === maxCharges && batteryCharge === 0)
+  );
+}

package/src/functions/chargeBar.ts

@@ -0,0 +1,67 @@
+import { VectorZero } from "../constants";
+import { ChargeBarSprites } from "../interfaces/ChargeBarSprites";
+
+const CHARGE_BAR_ANM2 = "gfx/ui/ui_chargebar.anm2";
+
+/**
+ * Constructor for a `ChargeBarSprites` object. For more information, see the `renderChargeBar`
+ * helper function.
+ */
+export function newChargeBarSprites(maxCharges: int): ChargeBarSprites {
+  const back = Sprite();
+  back.Load(CHARGE_BAR_ANM2, true);
+  back.Play("BarEmpty", true);
+
+  const meter = Sprite();
+  meter.Load(CHARGE_BAR_ANM2, true);
+  meter.Play("BarFull", true);
+
+  const meterBattery = Sprite();
+  meterBattery.Load(CHARGE_BAR_ANM2, true);
+  meterBattery.Play("BarFull", true);
+
+  const lines = Sprite();
+  lines.Load(CHARGE_BAR_ANM2, true);
+  lines.Play(`BarOverlay${maxCharges}`, true);
+
+  return {
+    back,
+    meter,
+    meterBattery,
+    lines,
+    maxCharges,
+  };
+}
+
+/**
+ * Helper function to render a charge bar on the screen. First, call the `newChargeBarSprites`
+ * function to initialize the sprites, and then call this function on every render frame.
+ */
+export function renderChargeBar(
+  sprites: ChargeBarSprites,
+  position: Vector,
+  normalCharges: int,
+  batteryCharges: int,
+): void {
+  sprites.back.Render(position, VectorZero, VectorZero);
+
+  const normalChargesClamp = getChargeBarClamp(
+    normalCharges,
+    sprites.maxCharges,
+  );
+  sprites.meter.Render(position, normalChargesClamp, VectorZero);
+
+  const batteryChargesClamp = getChargeBarClamp(
+    batteryCharges,
+    sprites.maxCharges,
+  );
+  sprites.meterBattery.Render(position, batteryChargesClamp, VectorZero);
+
+  sprites.lines.Render(position, VectorZero, VectorZero);
+}
+
+function getChargeBarClamp(charges: int, maxCharges: int) {
+  const meterMultiplier = 24 / maxCharges;
+  const meterClip = 26 - charges * meterMultiplier;
+  return Vector(0, meterClip);
+}