/**
 * 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;