0
# Entity Management
1

2
Entity tracking, interaction, and management system for comprehensive awareness of players, mobs, items, and other game entities with sophisticated interaction capabilities.
3

4
## Capabilities
5

6
### Entity Discovery and Targeting
7

8
Find and identify entities in the game world for interaction and monitoring.
9

10
```typescript { .api }
11
/**
12
 * Find the nearest entity matching the filter criteria
13
 * @param filter - Optional filter function to match specific entities
14
 * @returns Nearest matching entity or null
15
 */
16
nearestEntity(filter?: (entity: Entity) => boolean): Entity | null;
17

18
/**
19
 * Get the entity at the bot's cursor position
20
 * @param maxDistance - Maximum search distance
21
 * @returns Entity at cursor or null
22
 */
23
entityAtCursor(maxDistance?: number): Entity | null;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
// Find nearest player
30
const nearestPlayer = bot.nearestEntity(entity => entity.type === "player");
31

32
// Find nearest hostile mob
33
const nearestMob = bot.nearestEntity(entity => 
34
  ["zombie", "skeleton", "spider", "creeper"].includes(entity.name || "")
35
);
36

37
// Find nearest item entity
38
const nearestItem = bot.nearestEntity(entity => entity.type === "object");
39

40
// Get entity being looked at
41
const targetEntity = bot.entityAtCursor(10);
42
if (targetEntity) {
43
  console.log(`Looking at ${targetEntity.type}: ${targetEntity.username || targetEntity.name}`);
44
}
45
```
46

47
### Entity Interaction
48

49
Directly interact with entities through various actions.
50

51
```typescript { .api }
52
/**
53
 * Attack/hit an entity
54
 * @param entity - Entity to attack
55
 */
56
attack(entity: Entity): void;
57

58
/**
59
 * Right-click/activate an entity
60
 * @param entity - Entity to activate
61
 * @returns Promise that resolves when activation completes
62
 */
63
activateEntity(entity: Entity): Promise<void>;
64

65
/**
66
 * Activate entity at a specific position on the entity
67
 * @param entity - Entity to activate
68
 * @param position - Specific position on entity
69
 * @returns Promise that resolves when activation completes
70
 */
71
activateEntityAt(entity: Entity, position: Vec3): Promise<void>;
72

73
/**
74
 * Use held item on an entity
75
 * @param targetEntity - Entity to use item on
76
 */
77
useOn(targetEntity: Entity): void;
78
```
79

80
### Vehicle and Mount System
81

82
Mount and control vehicles and rideable entities.
83

84
```typescript { .api }
85
/**
86
 * Mount/ride an entity
87
 * @param entity - Entity to mount (horse, boat, minecart, etc.)
88
 */
89
mount(entity: Entity): void;
90

91
/**
92
 * Dismount from the current vehicle
93
 */
94
dismount(): void;
95

96
/**
97
 * Control vehicle movement
98
 * @param left - Left strafe amount (-1 to 1)
99
 * @param forward - Forward movement amount (-1 to 1)
100
 */
101
moveVehicle(left: number, forward: number): void;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Attack nearest zombie
108
const zombie = bot.nearestEntity(entity => entity.name === "zombie");
109
if (zombie && zombie.position.distanceTo(bot.entity.position) < 4) {
110
  bot.attack(zombie);
111
}
112

113
// Right-click a villager to open trading
114
const villager = bot.nearestEntity(entity => entity.name === "villager");
115
if (villager) {
116
  await bot.activateEntity(villager);
117
}
118

119
// Mount a horse
120
const horse = bot.nearestEntity(entity => entity.name === "horse");
121
if (horse) {
122
  bot.mount(horse);
123
  
124
  // Control the horse
125
  bot.moveVehicle(0, 1); // Move forward
126
  
127
  // Dismount after some time
128
  setTimeout(() => {
129
    bot.dismount();
130
  }, 5000);
131
}
132

133
// Use saddle on pig
134
const pig = bot.nearestEntity(entity => entity.name === "pig");
135
const saddle = bot.inventory.items().find(item => item.name === "saddle");
136
if (pig && saddle) {
137
  await bot.equip(saddle, "hand");
138
  bot.useOn(pig);
139
}
140
```
141

142
### Entity State Access
143

144
Access comprehensive entity information and properties.
145

146
```typescript { .api }
147
interface Bot {
148
  /** Bot's own entity representation */
149
  entity: Entity;
150
  /** Map of all loaded entities by ID */
151
  entities: { [id: string]: Entity };
152
  /** Map of all players by username */
153
  players: { [username: string]: Player };
154
}
155

156
interface Entity {
157
  /** Unique entity ID */
158
  id: number;
159
  /** Entity type name */
160
  type: string;
161
  /** Entity display name (for named entities) */
162
  displayName?: ChatMessage;
163
  /** Position in world coordinates */
164
  position: Vec3;
165
  /** Velocity vector */
166
  velocity: Vec3;
167
  /** Rotation yaw (horizontal) */
168
  yaw: number;
169
  /** Rotation pitch (vertical) */
170
  pitch: number;
171
  /** Head yaw (for living entities) */
172
  headYaw?: number;
173
  /** Entity height */
174
  height: number;
175
  /** Entity width */
176
  width: number;
177
  /** Entity health (if applicable) */
178
  health?: number;
179
  /** Maximum health (if applicable) */
180
  maxHealth?: number;
181
  /** Equipment slots (for living entities) */
182
  equipment: Item[];
183
  /** Held item (for living entities) */
184
  heldItem?: Item;
185
  /** Entity is valid and loaded */
186
  isValid: boolean;
187
  /** Metadata properties */
188
  metadata: any[];
189
  /** Entity effects (potions) */
190
  effects: { [id: number]: { amplifier: number; duration: number } };
191
}
192

193
interface Player extends Entity {
194
  /** Player UUID */
195
  uuid: string;
196
  /** Player username */
197
  username: string;
198
  /** Formatted display name */
199
  displayName: ChatMessage;
200
  /** Game mode */
201
  gamemode: number;
202
  /** Ping latency */
203
  ping: number;
204
  /** Associated entity reference */
205
  entity: Entity;
206
  /** Skin data */
207
  skinData?: SkinData;
208
  /** Profile keys for chat signing */
209
  profileKeys?: {
210
    publicKey: Buffer;
211
    signature: Buffer;
212
  };
213
}
214

215
interface SkinData {
216
  /** Skin texture URL */
217
  url: string;
218
  /** Skin model type */
219
  model: string | null;
220
}
221
```
222

223
### Entity Events
224

225
Monitor entity state changes and interactions.
226

227
```typescript { .api }
228
interface BotEvents {
229
  /** New entity spawned */
230
  entitySpawn(entity: Entity): void;
231
  /** Entity removed from world */
232
  entityGone(entity: Entity): void;
233
  /** Entity moved to new position */
234
  entityMoved(entity: Entity): void;
235
  /** Entity state updated */
236
  entityUpdate(entity: Entity): void;
237
  /** Entity attached to vehicle */
238
  entityAttach(entity: Entity, vehicle: Entity): void;
239
  /** Entity detached from vehicle */
240
  entityDetach(entity: Entity, vehicle: Entity): void;
241
  
242
  /** Entity performed action */
243
  entitySwingArm(entity: Entity): void;
244
  entityHurt(entity: Entity, source: Entity): void;
245
  entityDead(entity: Entity): void;
246
  entityEquip(entity: Entity): void;
247
  entitySleep(entity: Entity): void;
248
  entityWake(entity: Entity): void;
249
  entityEat(entity: Entity): void;
250
  entityCrouch(entity: Entity): void;
251
  entityUncrouch(entity: Entity): void;
252
  
253
  /** Potion effect applied to entity */
254
  entityEffect(entity: Entity, effect: Effect): void;
255
  /** Potion effect ended on entity */
256
  entityEffectEnd(entity: Entity, effect: Effect): void;
257
  /** Entity attributes changed */
258
  entityAttributes(entity: Entity): void;
259
  
260
  /** Player-specific events */
261
  playerJoined(player: Player): void;
262
  playerLeft(player: Player): void;
263
  playerUpdated(player: Player): void;
264
  
265
  /** Item collection events */
266
  itemDrop(entity: Entity): void;
267
  playerCollect(collector: Entity, collected: Entity): void;
268
}
269

270
interface Effect {
271
  /** Effect type ID */
272
  id: number;
273
  /** Effect amplifier level */
274
  amplifier: number;
275
  /** Remaining duration in ticks */
276
  duration: number;
277
}
278
```
279

280
**Usage Examples:**
281

282
```typescript
283
// Monitor entity spawns
284
bot.on("entitySpawn", (entity) => {
285
  console.log(`${entity.type} spawned at ${entity.position}`);
286
  
287
  if (entity.type === "player") {
288
    const player = bot.players[entity.username!];
289
    console.log(`Player ${player.username} joined the game`);
290
  }
291
});
292

293
// Track entity deaths
294
bot.on("entityDead", (entity) => {
295
  console.log(`${entity.type} died at ${entity.position}`);
296
});
297

298
// Monitor item drops
299
bot.on("itemDrop", (entity) => {
300
  console.log(`Item dropped: ${entity.name} at ${entity.position}`);
301
});
302

303
// Track player actions
304
bot.on("entitySwingArm", (entity) => {
305
  if (entity.type === "player") {
306
    console.log(`${entity.username} swung their arm`);
307
  }
308
});
309

310
// Monitor potion effects
311
bot.on("entityEffect", (entity, effect) => {
312
  console.log(`Entity ${entity.type} got effect ${effect.id} level ${effect.amplifier}`);
313
});
314

315
// Access entity information
316
console.log(`Bot position: ${bot.entity.position}`);
317
console.log(`Bot health: ${bot.entity.health}/${bot.entity.maxHealth}`);
318
console.log(`Players online: ${Object.keys(bot.players).length}`);
319

320
// Check equipment
321
const nearbyPlayer = Object.values(bot.players)[0];
322
if (nearbyPlayer?.entity.equipment[0]) {
323
  console.log(`${nearbyPlayer.username} is holding: ${nearbyPlayer.entity.equipment[0].name}`);
324
}
325
```
326

327
### Entity Filtering and Analysis
328

329
Advanced entity filtering and analysis utilities.
330

331
```typescript { .api }
332
// Common entity filter examples
333
const isPlayer = (entity: Entity) => entity.type === "player";
334
const isHostile = (entity: Entity) => ["zombie", "skeleton", "spider", "creeper", "enderman"].includes(entity.name || "");
335
const isPassive = (entity: Entity) => ["cow", "sheep", "pig", "chicken", "horse"].includes(entity.name || "");
336
const isItem = (entity: Entity) => entity.type === "object";
337
const inRange = (maxDistance: number) => (entity: Entity) => 
338
  entity.position.distanceTo(bot.entity.position) <= maxDistance;
339

340
// Usage examples
341
const nearbyPlayers = Object.values(bot.entities).filter(isPlayer).filter(inRange(20));
342
const hostileMobs = Object.values(bot.entities).filter(isHostile).filter(inRange(16));
343
const nearbyItems = Object.values(bot.entities).filter(isItem).filter(inRange(8));
344
```