0
# World Interaction
1

2
Comprehensive world interaction capabilities including block querying, manipulation, spatial analysis, and environmental awareness for sophisticated bot-world interaction.
3

4
## Capabilities
5

6
### Block Querying
7

8
Query and analyze blocks in the world for environmental awareness and decision making.
9

10
```typescript { .api }
11
/**
12
 * Get the block at a specific position
13
 * @param point - World coordinates
14
 * @param extraInfos - Include additional block metadata
15
 * @returns Block instance or null if not loaded
16
 */
17
blockAt(point: Vec3, extraInfos?: boolean): Block | null;
18

19
/**
20
 * Get the block the bot is looking at within line of sight
21
 * @param maxSteps - Maximum ray-casting steps
22
 * @param vectorLength - Length of each ray-casting step
23
 * @returns Block in sight or null
24
 */
25
blockInSight(maxSteps: number, vectorLength: number): Block | null;
26

27
/**
28
 * Get block at cursor position with optional distance and matching
29
 * @param maxDistance - Maximum search distance
30
 * @param matcher - Optional block matching function
31
 * @returns Block at cursor or null
32
 */
33
blockAtCursor(maxDistance?: number, matcher?: (block: Block) => boolean): Block | null;
34

35
/**
36
 * Get block at entity's cursor position
37
 * @param entity - Target entity (defaults to bot)
38
 * @param maxDistance - Maximum search distance
39
 * @param matcher - Optional block matching function
40
 * @returns Block at entity cursor or null
41
 */
42
blockAtEntityCursor(entity?: Entity, maxDistance?: number, matcher?: (block: Block) => boolean): Block | null;
43

44
/**
45
 * Check if the bot can see a specific block
46
 * @param block - Block to check visibility
47
 * @returns True if block is visible
48
 */
49
canSeeBlock(block: Block): boolean;
50
```
51

52
### Block Finding
53

54
Search for blocks matching specific criteria within the loaded world.
55

56
```typescript { .api }
57
/**
58
 * Find the nearest block matching the criteria
59
 * @param options - Search parameters
60
 * @returns First matching block or null
61
 */
62
findBlock(options: FindBlockOptions): Block | null;
63

64
/**
65
 * Find all blocks matching the criteria within range
66
 * @param options - Search parameters
67
 * @returns Array of matching block positions
68
 */
69
findBlocks(options: FindBlockOptions): Vec3[];
70

71
interface FindBlockOptions {
72
  /** Starting search point (defaults to bot position) */
73
  point?: Vec3;
74
  /** Block type(s) to match or matching function */
75
  matching: number | number[] | ((block: Block) => boolean);
76
  /** Maximum search distance in blocks */
77
  maxDistance?: number;
78
  /** Maximum number of blocks to find */
79
  count?: number;
80
  /** Use extra block information for matching */
81
  useExtraInfo?: boolean | ((block: Block) => boolean);
82
}
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
// Find nearest diamond ore
89
const diamondOre = bot.findBlock({
90
  matching: bot.registry.blocksByName.diamond_ore.id,
91
  maxDistance: 64
92
});
93

94
// Find all wood logs within 32 blocks
95
const woodLogs = bot.findBlocks({
96
  matching: (block) => block.name.includes("log"),
97
  maxDistance: 32,
98
  count: 50
99
});
100

101
// Find chest with custom criteria
102
const chest = bot.findBlock({
103
  matching: bot.registry.blocksByName.chest.id,
104
  maxDistance: 16,
105
  useExtraInfo: (block) => {
106
    // Additional chest validation logic
107
    return block.light > 5;
108
  }
109
});
110
```
111

112
### Block Manipulation
113

114
Dig, place, and activate blocks for world modification and interaction.
115

116
```typescript { .api }
117
/**
118
 * Check if the bot can dig a specific block
119
 * @param block - Block to check
120
 * @returns True if block can be dug
121
 */
122
canDigBlock(block: Block): boolean;
123

124
/**
125
 * Calculate time required to dig a block
126
 * @param block - Block to analyze
127
 * @returns Time in milliseconds
128
 */
129
digTime(block: Block): number;
130

131
/**
132
 * Dig/break a block
133
 * @param block - Block to dig
134
 * @param forceLook - Force looking at block, or 'ignore' to skip
135
 * @param digFace - Face to dig from ('auto', Vec3, or 'raycast')
136
 * @returns Promise that resolves when digging completes
137
 */
138
dig(block: Block, forceLook?: boolean | "ignore", digFace?: "auto" | Vec3 | "raycast"): Promise<void>;
139

140
/**
141
 * Stop the current digging operation
142
 */
143
stopDigging(): void;
144

145
/**
146
 * Place a block against a reference block
147
 * @param referenceBlock - Block to place against
148
 * @param faceVector - Face direction for placement
149
 * @returns Promise that resolves when placement completes
150
 */
151
placeBlock(referenceBlock: Block, faceVector: Vec3): Promise<void>;
152

153
/**
154
 * Activate/right-click a block
155
 * @param block - Block to activate
156
 * @param direction - Direction vector for interaction
157
 * @param cursorPos - Precise cursor position on block face
158
 * @returns Promise that resolves when activation completes
159
 */
160
activateBlock(block: Block, direction?: Vec3, cursorPos?: Vec3): Promise<void>;
161
```
162

163
### Sign and Text Interaction
164

165
Update signs and other text-based blocks.
166

167
```typescript { .api }
168
/**
169
 * Update text on a sign block
170
 * @param block - Sign block to update
171
 * @param text - New text content (newlines supported)
172
 * @param back - Update back side of sign (1.20+ hanging signs)
173
 */
174
updateSign(block: Block, text: string, back?: boolean): void;
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
// Basic block digging
181
const stone = bot.blockAt(bot.entity.position.offset(1, 0, 0));
182
if (stone && bot.canDigBlock(stone)) {
183
  console.log(`Digging will take ${bot.digTime(stone)}ms`);
184
  await bot.dig(stone);
185
  console.log("Stone mined!");
186
}
187

188
// Place a block
189
const dirt = bot.inventory.items().find(item => item.name === "dirt");
190
if (dirt) {
191
  const referenceBlock = bot.blockAt(bot.entity.position.offset(0, -1, 0));
192
  if (referenceBlock) {
193
    await bot.placeBlock(referenceBlock, new Vec3(0, 1, 0));
194
    console.log("Dirt placed!");
195
  }
196
}
197

198
// Activate a door
199
const door = bot.findBlock({
200
  matching: (block) => block.name.includes("door"),
201
  maxDistance: 4
202
});
203
if (door) {
204
  await bot.activateBlock(door);
205
  console.log("Door toggled!");
206
}
207

208
// Update a sign
209
const sign = bot.findBlock({
210
  matching: (block) => block.name.includes("sign"),
211
  maxDistance: 5
212
});
213
if (sign) {
214
  bot.updateSign(sign, "Hello World!\nBot was here");
215
}
216
```
217

218
### World State Access
219

220
Access the underlying world state and chunk information.
221

222
```typescript { .api }
223
interface Bot {
224
  /** World state and block access */
225
  world: world.WorldSync;
226
}
227

228
// World events for monitoring changes
229
interface BotEvents {
230
  /** Block changed in the world */
231
  blockUpdate(oldBlock: Block | null, newBlock: Block): void;
232
  /** Specific block position updated */
233
  "blockUpdate:(x, y, z)"(oldBlock: Block | null, newBlock: Block | null): void;
234
  /** Chunk column loaded */
235
  chunkColumnLoad(chunkPos: Vec3): void;
236
  /** Chunk column unloaded */
237
  chunkColumnUnload(chunkPos: Vec3): void;
238
}
239
```
240

241
### Break Progress and Animation Events
242

243
Monitor block breaking progress and animations.
244

245
```typescript { .api }
246
interface BotEvents {
247
  /** Observe block break progress from other players */
248
  blockBreakProgressObserved(block: Block, destroyStage: number): void;
249
  /** Block break progress ended */
250
  blockBreakProgressEnd(block: Block): void;
251
  /** Bot completed digging a block */
252
  diggingCompleted(block: Block): void;
253
  /** Bot stopped digging a block */
254
  diggingAborted(block: Block): void;
255
}
256
```
257

258
**Usage Examples:**
259

260
```typescript
261
// Monitor world changes
262
bot.on("blockUpdate", (oldBlock, newBlock) => {
263
  if (oldBlock?.name !== newBlock?.name) {
264
    console.log(`Block changed from ${oldBlock?.name || "air"} to ${newBlock?.name || "air"} at ${newBlock?.position}`);
265
  }
266
});
267

268
// Track digging progress
269
bot.on("diggingCompleted", (block) => {
270
  console.log(`Successfully mined ${block.name} at ${block.position}`);
271
});
272

273
bot.on("diggingAborted", (block) => {
274
  console.log(`Stopped mining ${block.name} at ${block.position}`);
275
});
276

277
// Monitor other players breaking blocks
278
bot.on("blockBreakProgressObserved", (block, stage) => {
279
  console.log(`Block ${block.name} at ${block.position} is ${stage}/10 broken`);
280
});
281
```
282

283
## Block Data Types
284

285
```typescript { .api }
286
interface Block {
287
  /** Numeric block type ID */
288
  type: number;
289
  /** Block name (e.g., "stone", "diamond_ore") */
290
  name: string;
291
  /** Block position in world coordinates */
292
  position: Vec3;
293
  /** Block metadata/damage value */
294
  metadata: number;
295
  /** Block light level */
296
  light: number;
297
  /** Sky light level at block */
298
  skyLight: number;
299
  /** Block hardness (mining difficulty) */
300
  hardness: number;
301
  /** Material category */
302
  material: string;
303
  /** Block state properties */
304
  getProperties(): { [key: string]: any };
305
  /** Check if block can be harvested with current tool */
306
  canHarvest(heldItemType?: number): boolean;
307
  /** Get drops when mined with current tool */
308
  drops(heldItemType?: number, enchants?: any[]): Item[];
309
}
310

311
interface Vec3 {
312
  x: number;
313
  y: number;
314
  z: number;
315
  offset(dx: number, dy: number, dz: number): Vec3;
316
  distanceTo(other: Vec3): number;
317
  equals(other: Vec3): boolean;
318
}
319
```