0
# Inventory and Items
1

2
Complete inventory management system with equipment handling, item manipulation, crafting capabilities, and container interaction for sophisticated resource management and gameplay automation.
3

4
## Capabilities
5

6
### Equipment Management
7

8
Equip and unequip items to various equipment slots for combat, protection, and functionality.
9

10
```typescript { .api }
11
/**
12
 * Equip an item to a specific equipment destination
13
 * @param item - Item to equip or item type ID
14
 * @param destination - Where to equip the item
15
 * @returns Promise that resolves when equipment completes
16
 */
17
equip(item: Item | number, destination: EquipmentDestination | null): Promise<void>;
18

19
/**
20
 * Unequip item from a specific equipment destination
21
 * @param destination - Equipment slot to clear
22
 * @returns Promise that resolves when unequip completes
23
 */
24
unequip(destination: EquipmentDestination | null): Promise<void>;
25

26
/**
27
 * Get the slot number for an equipment destination
28
 * @param destination - Equipment destination name
29
 * @returns Slot number for the destination
30
 */
31
getEquipmentDestSlot(destination: string): number;
32

33
type EquipmentDestination = "hand" | "head" | "torso" | "legs" | "feet" | "off-hand";
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
// Equip armor
40
const helmet = bot.inventory.items().find(item => item.name.includes("helmet"));
41
if (helmet) {
42
  await bot.equip(helmet, "head");
43
}
44

45
const sword = bot.inventory.items().find(item => item.name.includes("sword"));
46
if (sword) {
47
  await bot.equip(sword, "hand");
48
}
49

50
// Equip by item type ID
51
await bot.equip(bot.registry.itemsByName.diamond_pickaxe.id, "hand");
52

53
// Unequip items
54
await bot.unequip("hand");  // Unequip held item
55
await bot.unequip("head");  // Remove helmet
56
```
57

58
### Item Manipulation
59

60
Throw, drop, and move items within inventory and hotbar.
61

62
```typescript { .api }
63
/**
64
 * Toss/throw an entire item stack
65
 * @param item - Item stack to toss
66
 * @returns Promise that resolves when toss completes
67
 */
68
tossStack(item: Item): Promise<void>;
69

70
/**
71
 * Toss a specific amount of an item type
72
 * @param itemType - Item type ID to toss
73
 * @param metadata - Item metadata/damage value
74
 * @param count - Number of items to toss
75
 * @returns Promise that resolves when toss completes
76
 */
77
toss(itemType: number, metadata: number | null, count: number | null): Promise<void>;
78

79
/**
80
 * Select a hotbar slot
81
 * @param slot - Hotbar slot number (0-8)
82
 */
83
setQuickBarSlot(slot: number): void;
84

85
/**
86
 * Update the held item reference
87
 */
88
updateHeldItem(): void;
89
```
90

91
### Item Usage and Consumption
92

93
Use and consume items for various effects and interactions.
94

95
```typescript { .api }
96
/**
97
 * Consume the held item (eat food, drink potion, etc.)
98
 * @returns Promise that resolves when consumption completes
99
 */
100
consume(): Promise<void>;
101

102
/**
103
 * Activate/use the held item
104
 * @param offhand - Use offhand item instead of main hand
105
 */
106
activateItem(offhand?: boolean): void;
107

108
/**
109
 * Stop using the held item
110
 */
111
deactivateItem(): void;
112

113
/**
114
 * Start fishing (requires fishing rod in hand)
115
 * @returns Promise that resolves when fishing completes
116
 */
117
fish(): Promise<void>;
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
// Eat food when hungry
124
if (bot.food < 18) {
125
  const food = bot.inventory.items().find(item => 
126
    ["bread", "apple", "cooked_beef", "cooked_porkchop"].includes(item.name)
127
  );
128
  if (food) {
129
    await bot.equip(food, "hand");
130
    await bot.consume();
131
  }
132
}
133

134
// Use a bow
135
const bow = bot.inventory.items().find(item => item.name === "bow");
136
if (bow) {
137
  await bot.equip(bow, "hand");
138
  bot.activateItem(); // Start drawing bow
139
  
140
  setTimeout(() => {
141
    bot.deactivateItem(); // Release arrow
142
  }, 1000);
143
}
144

145
// Go fishing
146
const fishingRod = bot.inventory.items().find(item => item.name === "fishing_rod");
147
if (fishingRod) {
148
  await bot.equip(fishingRod, "hand");
149
  await bot.fish();
150
}
151
```
152

153
### Inventory Access and State
154

155
Access inventory contents and state information.
156

157
```typescript { .api }
158
interface Bot {
159
  /** Bot's inventory window */
160
  inventory: Window<StorageEvents>;
161
  /** Currently held item */
162
  heldItem: Item | null;
163
  /** Whether bot is using held item */
164
  usingHeldItem: boolean;
165
  /** Selected hotbar slot (0-8) */
166
  quickBarSlot: number;
167
}
168

169
interface Window<T = any> {
170
  /** Window type */
171
  type: string;
172
  /** Window ID */
173
  id: number;
174
  /** Window title */
175
  title: string;
176
  /** Number of slots */
177
  slotCount: number;
178
  /** Get all items in window */
179
  items(): Item[];
180
  /** Get item in specific slot */
181
  slots: Array<Item | null>;
182
  /** Get slot by ID */
183
  slot(slot: number): Item | null;
184
  /** Count items of specific type */
185
  count(itemType: number, metadata?: number): number;
186
  /** Find items matching criteria */
187
  findItems(itemType: number, metadata?: number, notFull?: boolean): Item[];
188
  /** Find item by name */
189
  findItem(name: string): Item | null;
190
}
191

192
interface StorageEvents {
193
  /** Window opened */
194
  open(): void;
195
  /** Window closed */
196
  close(): void;
197
  /** Slot updated */
198
  updateSlot(slot: number, oldItem: Item | null, newItem: Item | null): void;
199
}
200

201
interface Item {
202
  /** Item type ID */
203
  type: number;
204
  /** Item count in stack */
205
  count: number;
206
  /** Item metadata/damage value */
207
  metadata: number;
208
  /** Item name */
209
  name: string;
210
  /** Display name with formatting */
211
  displayName: string;
212
  /** Maximum stack size */
213
  stackSize: number;
214
  /** Durability used (for tools/armor) */
215
  durabilityUsed?: number;
216
  /** Maximum durability */
217
  maxDurability?: number;
218
  /** Enchantments on item */
219
  enchants: Enchant[];
220
  /** NBT data */
221
  nbt?: NBT;
222
  /** Slot number in inventory */
223
  slot: number;
224
}
225

226
interface Enchant {
227
  /** Enchantment type */
228
  name: string;
229
  /** Enchantment level */
230
  level: number;
231
}
232
```
233

234
### Inventory Window Management
235

236
Interact with inventory slots and manage window operations.
237

238
```typescript { .api }
239
/**
240
 * Click a window slot
241
 * @param slot - Slot number to click
242
 * @param mouseButton - Mouse button (0=left, 1=right, 2=middle)
243
 * @param mode - Click mode (0=click, 1=shift-click, etc.)
244
 * @returns Promise that resolves when click completes
245
 */
246
clickWindow(slot: number, mouseButton: number, mode: number): Promise<void>;
247

248
/**
249
 * Move item from one slot to another
250
 * @param sourceSlot - Source slot number
251
 * @param destSlot - Destination slot number
252
 * @returns Promise that resolves when move completes
253
 */
254
moveSlotItem(sourceSlot: number, destSlot: number): Promise<void>;
255

256
/**
257
 * Put away item from a slot to available inventory space
258
 * @param slot - Slot number to put away
259
 * @returns Promise that resolves when operation completes
260
 */
261
putAway(slot: number): Promise<void>;
262

263
/**
264
 * Transfer items between slots with advanced options
265
 * @param options - Transfer configuration
266
 * @returns Promise that resolves when transfer completes
267
 */
268
transfer(options: TransferOptions): Promise<void>;
269

270
interface TransferOptions {
271
  /** Target window */
272
  window: Window;
273
  /** Item type to transfer */
274
  itemType: number;
275
  /** Item metadata filter */
276
  metadata: number | null;
277
  /** Number of items to transfer */
278
  count?: number;
279
  /** Source slot range start */
280
  sourceStart: number;
281
  /** Source slot range end */
282
  sourceEnd: number;
283
  /** Destination slot range start */
284
  destStart: number;
285
  /** Destination slot range end */
286
  destEnd: number;
287
}
288
```
289

290
### Simple Click Interface
291

292
Simplified mouse clicking for common inventory operations.
293

294
```typescript { .api }
295
interface Bot {
296
  /** Simple click interface */
297
  simpleClick: SimpleClick;
298
}
299

300
interface SimpleClick {
301
  /** Left click a slot */
302
  leftMouse(slot: number): Promise<void>;
303
  /** Right click a slot */
304
  rightMouse(slot: number): Promise<void>;
305
}
306
```
307

308
**Usage Examples:**
309

310
```typescript
311
// Organize inventory - move items around
312
const sword = bot.inventory.findItem("diamond_sword");
313
if (sword && sword.slot !== 0) {
314
  await bot.moveSlotItem(sword.slot, 0); // Move to first hotbar slot
315
}
316

317
// Click operations
318
await bot.simpleClick.leftMouse(10);  // Left click slot 10
319
await bot.simpleClick.rightMouse(15); // Right click slot 15
320

321
// Transfer items to chest
322
const chest = await bot.openChest(chestBlock);
323
await bot.transfer({
324
  window: chest,
325
  itemType: bot.registry.itemsByName.cobblestone.id,
326
  metadata: null,
327
  count: 64,
328
  sourceStart: 0,
329
  sourceEnd: 35,
330
  destStart: 0,
331
  destEnd: 26
332
});
333
```
334

335
### Crafting System
336

337
Craft items and manage recipes for automated production.
338

339
```typescript { .api }
340
/**
341
 * Get recipes that produce a specific item
342
 * @param itemType - Target item type ID
343
 * @param metadata - Item metadata
344
 * @param minResultCount - Minimum result count
345
 * @param craftingTable - Crafting table block or boolean
346
 * @returns Array of matching recipes
347
 */
348
recipesFor(
349
  itemType: number,
350
  metadata: number | null,
351
  minResultCount: number | null,
352
  craftingTable: Block | boolean | null
353
): Recipe[];
354

355
/**
356
 * Get all recipes for an item type
357
 * @param itemType - Target item type ID
358
 * @param metadata - Item metadata
359
 * @param craftingTable - Crafting table block or boolean
360
 * @returns Array of all recipes
361
 */
362
recipesAll(
363
  itemType: number,
364
  metadata: number | null,
365
  craftingTable: Block | boolean | null
366
): Recipe[];
367

368
/**
369
 * Craft an item using a recipe
370
 * @param recipe - Recipe to craft
371
 * @param count - Number of times to craft (default: 1)
372
 * @param craftingTable - Crafting table block for 3x3 recipes
373
 * @returns Promise that resolves when crafting completes
374
 */
375
craft(recipe: Recipe, count?: number, craftingTable?: Block): Promise<void>;
376

377
interface Recipe {
378
  /** Recipe ID */
379
  id: number;
380
  /** Result item */
381
  result: Item;
382
  /** Recipe ingredients */
383
  ingredients: Array<Item | null>;
384
  /** Requires crafting table */
385
  requiresTable: boolean;
386
  /** Recipe delta (net item changes) */
387
  delta: Item[];
388
}
389
```
390

391
**Usage Examples:**
392

393
```typescript
394
// Find and craft wooden planks
395
const logType = bot.registry.itemsByName.oak_log.id;
396
const plankRecipes = bot.recipesFor(bot.registry.itemsByName.oak_planks.id, null, null, false);
397

398
if (plankRecipes.length > 0) {
399
  const recipe = plankRecipes[0];
400
  const hasLogs = bot.inventory.count(logType) > 0;
401
  
402
  if (hasLogs) {
403
    await bot.craft(recipe, 4); // Craft 4 times
404
    console.log("Crafted wooden planks!");
405
  }
406
}
407

408
// Craft tools at crafting table
409
const craftingTable = bot.findBlock({
410
  matching: bot.registry.blocksByName.crafting_table.id,
411
  maxDistance: 16
412
});
413

414
if (craftingTable) {
415
  const pickaxeRecipes = bot.recipesFor(
416
    bot.registry.itemsByName.wooden_pickaxe.id,
417
    null,
418
    null,
419
    craftingTable
420
  );
421
  
422
  if (pickaxeRecipes.length > 0) {
423
    await bot.craft(pickaxeRecipes[0], 1, craftingTable);
424
    console.log("Crafted wooden pickaxe!");
425
  }
426
}
427
```
428

429
### Inventory Events
430

431
Monitor inventory changes and item updates.
432

433
```typescript { .api }
434
interface BotEvents {
435
  /** Window opened */
436
  windowOpen(window: Window): void;
437
  /** Window closed */
438
  windowClose(window: Window): void;
439
  /** Experience gained */
440
  experience(): void;
441
}
442

443
// Storage events (emitted on inventory window)
444
bot.inventory.on("updateSlot", (slot, oldItem, newItem) => {
445
  if (oldItem?.name !== newItem?.name) {
446
    console.log(`Slot ${slot}: ${oldItem?.name || "empty"} -> ${newItem?.name || "empty"}`);
447
  }
448
});
449
```
450

451
### Advanced Inventory Management
452

453
Complex inventory management patterns and utilities.
454

455
```typescript
456
// Auto-organize inventory
457
async function organizeInventory() {
458
  const items = bot.inventory.items();
459
  const itemGroups = new Map<string, Item[]>();
460
  
461
  // Group items by type
462
  items.forEach(item => {
463
    if (!itemGroups.has(item.name)) {
464
      itemGroups.set(item.name, []);
465
    }
466
    itemGroups.get(item.name)!.push(item);
467
  });
468
  
469
  // Stack items together
470
  for (const [itemName, itemList] of itemGroups) {
471
    if (itemList.length > 1) {
472
      const firstItem = itemList[0];
473
      for (let i = 1; i < itemList.length; i++) {
474
        if (firstItem.count < firstItem.stackSize) {
475
          await bot.moveSlotItem(itemList[i].slot, firstItem.slot);
476
        }
477
      }
478
    }
479
  }
480
}
481

482
// Keep essential items in hotbar
483
async function maintainHotbar() {
484
  const essentialItems = ["sword", "pickaxe", "axe", "shovel", "food"];
485
  
486
  for (let slot = 0; slot < 9; slot++) {
487
    const currentItem = bot.inventory.slot(slot);
488
    if (!currentItem) {
489
      // Find essential item to put in empty slot
490
      for (const essential of essentialItems) {
491
        const item = bot.inventory.items().find(item => 
492
          item.name.includes(essential) && item.slot >= 9
493
        );
494
        if (item) {
495
          await bot.moveSlotItem(item.slot, slot);
496
          break;
497
        }
498
      }
499
    }
500
  }
501
}
502

503
// Auto-eat when hungry
504
bot.on("health", () => {
505
  if (bot.food < 16) {
506
    const food = bot.inventory.items().find(item => 
507
      item.name.includes("bread") || 
508
      item.name.includes("apple") || 
509
      item.name.includes("cooked")
510
    );
511
    
512
    if (food) {
513
      bot.equip(food, "hand").then(() => {
514
        return bot.consume();
515
      }).catch(console.error);
516
    }
517
  }
518
});
519
```