we ball I guess

types/item/backpack.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+/** The player's item backpack (a fixed 20-slot inventory). */
+interface BackpackNamespace {
+  /** `true` when all 20 storage slots are occupied by distinct items. */
+  readonly isFull: boolean;
+
+  /**
+   * Returns the quantity of `itemId` in the backpack (0 if absent).
+   * @param itemId - An `ITEM_ID_*` constant.
+   */
+  getCount(itemId: ItemId): number;
+
+  /**
+   * Returns `true` if `itemId` is present with quantity greater than 0.
+   * @param itemId - An `ITEM_ID_*` constant.
+   */
+  has(itemId: ItemId): boolean;
+
+  /**
+   * Returns `true` if the stack for `itemId` is at maximum quantity (255).
+   * @param itemId - An `ITEM_ID_*` constant.
+   */
+  isItemFull(itemId: ItemId): boolean;
+
+  /**
+   * Sets the quantity of `itemId`; passing 0 removes the stack entirely.
+   * @param itemId   - An `ITEM_ID_*` constant.
+   * @param quantity - New quantity, 0–255.
+   */
+  set(itemId: ItemId, quantity: number): void;
+
+  /**
+   * Adds `quantity` units of `itemId` to the backpack.
+   * @param itemId   - An `ITEM_ID_*` constant.
+   * @param quantity - Amount to add, 1–255.
+   */
+  add(itemId: ItemId, quantity: number): void;
+
+  /**
+   * Removes `itemId` entirely from the backpack.
+   * @param itemId - An `ITEM_ID_*` constant.
+   */
+  remove(itemId: ItemId): void;
+
+  /**
+   * Sorts the backpack contents.
+   * @param sortBy  - `INVENTORY_SORT_BY_ID` or `INVENTORY_SORT_BY_TYPE`.
+   * @param reverse - Optional; pass `true` to reverse the sort order.
+   */
+  sort(sortBy: number, reverse?: boolean): void;
+}
+
+declare var Backpack: BackpackNamespace;
+
+// Inventory sort constants — injected as globals by the engine at startup.
+declare var INVENTORY_SORT_BY_ID: number;
+declare var INVENTORY_SORT_BY_TYPE: number;

types/item/item.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+/** Opaque type alias for item identifier constants. */
+type ItemId = number;
+
+/** Opaque type alias for item type constants. */
+type ItemType = number;
+
+/** Item data lookup. */
+interface ItemNamespace {
+  /**
+   * Returns the string name for the given item ID.
+   * @param itemId - An `ITEM_ID_*` constant.
+   */
+  getName(itemId: ItemId): string;
+
+  /**
+   * Returns the type constant for the given item ID.
+   * @param itemId - An `ITEM_ID_*` constant.
+   * @returns An `ITEM_TYPE_*` constant.
+   */
+  getType(itemId: ItemId): ItemType;
+}
+
+declare var Item: ItemNamespace;
+
+// Item ID constants — injected as globals by the engine at startup.
+declare var ITEM_ID_POTION: ItemId;
+declare var ITEM_ID_POTATO: ItemId;
+declare var ITEM_ID_APPLE: ItemId;
+
+// Item type constants — injected as globals by the engine at startup.
+declare var ITEM_TYPE_MEDICINE: ItemType;
+declare var ITEM_TYPE_FOOD: ItemType;