isaacscript-common 3.16.1 → 4.0.1-dev.0

package/types/CollectibleIndex.ts

@@ -0,0 +1,16 @@
+/**
+ * CollectibleIndex is a specific type of string; see the documentation for the
+ * `getCollectibleIndex` function. Mods can signify that data structures handle collectibles by
+ * using this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const collectiblesNameMap = new Map<CollectibleIndex, string>();
+ * ```
+ *
+ * This type is branded for extra type safety.
+ */
+export type CollectibleIndex = string & {
+  readonly __collectibleIndexBrand: unique symbol;
+};

package/types/PickingUpItem.d.ts

@@ -5,21 +5,21 @@
  */
 import { CollectibleType, ItemType, TrinketType } from "isaac-typescript-definitions";
 export declare type PickingUpItem = PickingUpItemNull | PickingUpItemCollectible | PickingUpItemTrinket;
-/** Part of {@link PickingUpItem}. */
+/** Part of `PickingUpItem`. */
 export interface PickingUpItemNull {
     /** Needed so that we can distinguish between picking up a collectible and a trinket. */
     itemType: ItemType.NULL;
     /** Equal to either the collectible type, the trinket type, or 0. */
     subType: 0;
 }
-/** Part of {@link PickingUpItem}. */
+/** Part of `PickingUpItem`. */
 export interface PickingUpItemCollectible {
     /** Needed so that we can distinguish between picking up a collectible and a trinket. */
     itemType: ItemType.PASSIVE | ItemType.ACTIVE | ItemType.FAMILIAR;
     /** Equal to either the collectible type, the trinket type, or 0. */
     subType: CollectibleType;
 }
-/** Part of {@link PickingUpItem}. */
+/** Part of `PickingUpItem`. */
 export interface PickingUpItemTrinket {
     /** Needed so that we can distinguish between picking up a collectible and a trinket. */
     itemType: ItemType.TRINKET;

package/types/PickingUpItem.ts

@@ -0,0 +1,89 @@
+/* eslint-disable sort-exports/sort-exports */
+
+/**
+ * This is the type that is fed to the `PRE_ITEM_PICKUP` and `POST_ITEM_PICKUP` custom callbacks.
+ *
+ * @module
+ */
+
+import {
+  CollectibleType,
+  ItemType,
+  TrinketType,
+} from "isaac-typescript-definitions";
+
+export type PickingUpItem =
+  | PickingUpItemNull
+  | PickingUpItemCollectible
+  | PickingUpItemTrinket;
+
+/** Part of `PickingUpItem`. */
+export interface PickingUpItemNull {
+  /** Needed so that we can distinguish between picking up a collectible and a trinket. */
+  itemType: ItemType.NULL;
+
+  /** Equal to either the collectible type, the trinket type, or 0. */
+  subType: 0;
+}
+
+/** Part of `PickingUpItem`. */
+export interface PickingUpItemCollectible {
+  /** Needed so that we can distinguish between picking up a collectible and a trinket. */
+  itemType: ItemType.PASSIVE | ItemType.ACTIVE | ItemType.FAMILIAR;
+
+  /** Equal to either the collectible type, the trinket type, or 0. */
+  subType: CollectibleType;
+}
+
+/** Part of `PickingUpItem`. */
+export interface PickingUpItemTrinket {
+  /** Needed so that we can distinguish between picking up a collectible and a trinket. */
+  itemType: ItemType.TRINKET;
+
+  /** Equal to either the collectible type, the trinket type, or 0. */
+  subType: TrinketType;
+}
+
+const DEFAULT_ITEM_TYPE = ItemType.NULL;
+const DEFAULT_SUB_TYPE = CollectibleType.NULL;
+
+/** @internal */
+export function newPickingUpItem(): PickingUpItem {
+  return {
+    itemType: DEFAULT_ITEM_TYPE,
+    subType: DEFAULT_SUB_TYPE,
+  };
+}
+
+/** @internal */
+export function resetPickingUpItem(pickingUpItem: PickingUpItem): void {
+  pickingUpItem.itemType = DEFAULT_ITEM_TYPE;
+  pickingUpItem.subType = DEFAULT_SUB_TYPE;
+}
+
+const COLLECTIBLE_ITEM_TYPES: ReadonlySet<ItemType> = new Set([
+  ItemType.PASSIVE, // 1
+  ItemType.ACTIVE, // 3
+  ItemType.FAMILIAR, // 4
+]);
+
+/** Helper function to narrow the type of `PickingUpItem`. */
+export function pickingUpItemIsNull(
+  pickingUpItem: PickingUpItem,
+): pickingUpItem is PickingUpItemTrinket {
+  return pickingUpItem.itemType === ItemType.NULL;
+}
+
+/** Helper function to narrow the type of `PickingUpItem`. */
+export function pickingUpItemIsCollectible(
+  pickingUpItem: PickingUpItem,
+): pickingUpItem is PickingUpItemCollectible {
+  return COLLECTIBLE_ITEM_TYPES.has(pickingUpItem.itemType);
+}
+
+/** Helper function to narrow the type of `PickingUpItem`. */
+export function pickingUpItemIsTrinket(
+  pickingUpItem: PickingUpItem,
+): pickingUpItem is PickingUpItemTrinket {
+  return pickingUpItem.itemType === ItemType.TRINKET;
+}

package/types/PlayerIndex.d.ts

@@ -12,5 +12,5 @@
  * This type is branded for extra type safety.
  */
 export declare type PlayerIndex = int & {
-    __playerIndexBrand: void;
+    readonly __playerIndexBrand: unique symbol;
 };

package/types/PlayerIndex.ts

@@ -0,0 +1,13 @@
+/**
+ * PlayerIndex is a specific type of string; see the documentation for the `getPlayerIndex`
+ * function. Mods can signify that data structures handle `EntityPlayer` by using this type.
+ *
+ * For example:
+ *
+ * ```ts
+ * const playersNameMap = new Map<PlayerIndex, string>();
+ * ```
+ *
+ * This type is branded for extra type safety.
+ */
+export type PlayerIndex = int & { readonly __playerIndexBrand: unique symbol };

package/types/private/IsaacAPIClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type IsaacAPIClass = LuaTable<string, unknown> & {
-    __isaacAPIClassBrand: void;
+    readonly __isaacAPIClassBrand: unique symbol;
 };

package/types/private/IsaacAPIClass.ts

@@ -0,0 +1,3 @@
+export type IsaacAPIClass = LuaTable<string, unknown> & {
+  readonly __isaacAPIClassBrand: unique symbol;
+};

package/types/private/SerializedIsaacAPIClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type SerializedIsaacAPIClass = LuaTable<string, unknown> & {
-    __serializedIsaacAPIClassBrand: void;
+    readonly __serializedIsaacAPIClassBrand: unique symbol;
 };

package/types/private/SerializedIsaacAPIClass.ts

@@ -0,0 +1,3 @@
+export type SerializedIsaacAPIClass = LuaTable<string, unknown> & {
+  readonly __serializedIsaacAPIClassBrand: unique symbol;
+};

package/types/private/TSTLClass.d.ts

@@ -1,4 +1,4 @@
 /// <reference types="typescript-to-lua/language-extensions" />
 export declare type TSTLClass = LuaTable<AnyNotNil, unknown> & {
-    __tstlClassBrand: void;
+    readonly __tstlClassBrand: unique symbol;
 };

package/types/private/TSTLClass.ts

@@ -0,0 +1,3 @@
+export type TSTLClass = LuaTable<AnyNotNil, unknown> & {
+  readonly __tstlClassBrand: unique symbol;
+};

package/upgradeMod.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="isaac-typescript-definitions" />
 import { ModUpgraded } from "./classes/ModUpgraded";
 /**
- * Use this function to enable the {@link ModCallbackCustom custom callbacks} and other optional
- * features provided by `isaacscript-common`.
+ * Use this function to enable the custom callbacks and other optional features provided by
+ * `isaacscript-common`.
  *
  * For example:
  *

package/upgradeMod.lua

@@ -17,8 +17,8 @@ local initFeaturesMajor = ____initFeatures.initFeaturesMajor
 local initFeaturesMinor = ____initFeatures.initFeaturesMinor
 local ____patchErrorFunctions = require("patchErrorFunctions")
 local patchErrorFunction = ____patchErrorFunctions.patchErrorFunction
---- Use this function to enable the {@link ModCallbackCustomcustom callbacks} and other optional
--- features provided by `isaacscript-common`.
+--- Use this function to enable the custom callbacks and other optional features provided by
+-- `isaacscript-common`.
 -- 
 -- For example:
 -- 

package/upgradeMod.ts

@@ -0,0 +1,55 @@
+import { postNewRoomEarlyCallbackInit } from "./callbacks/postNewRoomEarly";
+import { ModUpgraded } from "./classes/ModUpgraded";
+import { saveDataManagerInit } from "./features/saveDataManager/main";
+import {
+  areFeaturesInitialized,
+  setFeaturesInitialized,
+} from "./featuresInitialized";
+import { initCustomCallbacks } from "./initCustomCallbacks";
+import { initFeaturesMajor, initFeaturesMinor } from "./initFeatures";
+import { patchErrorFunction } from "./patchErrorFunctions";
+
+/**
+ * Use this function to enable the custom callbacks and other optional features provided by
+ * `isaacscript-common`.
+ *
+ * For example:
+ *
+ * ```ts
+ * const modVanilla = RegisterMod("My Mod", 1);
+ * const mod = upgradeMod(modVanilla);
+ *
+ * // Subscribe to vanilla callbacks.
+ * mod.AddCallback(ModCallback.POST_UPDATE, postUpdate);
+ *
+ * // Subscribe to custom callbacks.
+ * mod.AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup);
+ * ```
+ *
+ * @param modVanilla The mod object returned by the `RegisterMod` function.
+ * @returns The upgraded mod object.
+ */
+export function upgradeMod(modVanilla: Mod): ModUpgraded {
+  patchErrorFunction();
+
+  const mod = new ModUpgraded(modVanilla);
+
+  if (!areFeaturesInitialized()) {
+    setFeaturesInitialized();
+
+    // We initialize the PostNewRoomEarly callback first since it is used by the save data manager.
+    postNewRoomEarlyCallbackInit(mod);
+
+    // We initialized the save data manager second since it is used by the other custom callbacks
+    // and features.
+    saveDataManagerInit(mod);
+
+    // We initialize custom callbacks next since some features use custom callbacks.
+    initCustomCallbacks(mod);
+
+    initFeaturesMajor(mod);
+    initFeaturesMinor(mod);
+  }
+
+  return mod;
+}