0
# Movement and Physics
1

2
Advanced movement control with physics simulation, pathfinding integration, and precise positioning for sophisticated bot navigation and environmental interaction.
3

4
## Capabilities
5

6
### Basic Movement Control
7

8
Control bot movement through directional states and manual controls.
9

10
```typescript { .api }
11
/**
12
 * Set a movement control state (forward, back, left, right, jump, sprint, sneak)
13
 * @param control - Control state to modify
14
 * @param state - Enable or disable the control
15
 */
16
setControlState(control: ControlState, state: boolean): void;
17

18
/**
19
 * Get the current state of a movement control
20
 * @param control - Control state to check
21
 * @returns True if control is currently active
22
 */
23
getControlState(control: ControlState): boolean;
24

25
/**
26
 * Clear all movement control states
27
 */
28
clearControlStates(): void;
29

30
type ControlState = "forward" | "back" | "left" | "right" | "jump" | "sprint" | "sneak";
31

32
interface ControlStateStatus {
33
  forward: boolean;
34
  back: boolean;
35
  left: boolean;
36
  right: boolean;
37
  jump: boolean;
38
  sprint: boolean;
39
  sneak: boolean;
40
}
41
```
42

43
**Usage Examples:**
44

45
```typescript
46
// Basic movement
47
bot.setControlState("forward", true);
48
setTimeout(() => bot.setControlState("forward", false), 2000); // Move forward for 2 seconds
49

50
// Strafe right while moving forward
51
bot.setControlState("forward", true);
52
bot.setControlState("right", true);
53

54
// Jump and sprint
55
bot.setControlState("jump", true);
56
bot.setControlState("sprint", true);
57

58
// Check current movement state
59
if (bot.getControlState("sneak")) {
60
  console.log("Bot is currently sneaking");
61
}
62

63
// Stop all movement
64
bot.clearControlStates();
65
```
66

67
### Camera and Orientation Control
68

69
Control bot's view direction and camera orientation.
70

71
```typescript { .api }
72
/**
73
 * Look at a specific world position
74
 * @param point - Target position to look at
75
 * @param force - Force looking even if already looking in that direction
76
 * @returns Promise that resolves when look action completes
77
 */
78
lookAt(point: Vec3, force?: boolean): Promise<void>;
79

80
/**
81
 * Look in a specific direction using yaw and pitch
82
 * @param yaw - Horizontal rotation in radians
83
 * @param pitch - Vertical rotation in radians  
84
 * @param force - Force looking even if already in that direction
85
 * @returns Promise that resolves when look action completes
86
 */
87
look(yaw: number, pitch: number, force?: boolean): Promise<void>;
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
// Look at specific coordinates
94
await bot.lookAt(new Vec3(100, 64, 200));
95

96
// Look at nearest player
97
const player = bot.nearestEntity(entity => entity.type === "player");
98
if (player) {
99
  await bot.lookAt(player.position.offset(0, 1.6, 0)); // Look at head level
100
}
101

102
// Look in cardinal directions
103
await bot.look(0, 0);        // North
104
await bot.look(Math.PI/2, 0); // East
105
await bot.look(Math.PI, 0);   // South
106
await bot.look(-Math.PI/2, 0); // West
107

108
// Look up and down
109
await bot.look(0, -Math.PI/2); // Look straight up
110
await bot.look(0, Math.PI/2);  // Look straight down
111
```
112

113
### Advanced Movement Features
114

115
Advanced movement capabilities including elytra flight and special movement modes.
116

117
```typescript { .api }
118
/**
119
 * Activate elytra flight (requires equipped elytra)
120
 * @returns Promise that resolves when elytra activates
121
 */
122
elytraFly(): Promise<void>;
123

124
/**
125
 * Swing the bot's arm
126
 * @param hand - Which hand to swing ("left" or "right")
127
 * @param showHand - Whether to show hand animation to other players
128
 */
129
swingArm(hand: "left" | "right" | undefined, showHand?: boolean): void;
130
```
131

132
### Physics Configuration and State
133

134
Access and configure physics simulation parameters.
135

136
```typescript { .api }
137
interface Bot {
138
  /** Current physics options */
139
  physics: PhysicsOptions;
140
  /** Whether physics simulation is enabled */
141
  physicsEnabled: boolean;
142
}
143

144
interface PhysicsOptions {
145
  /** Maximum ground movement speed */
146
  maxGroundSpeed: number;
147
  /** Terminal falling velocity */
148
  terminalVelocity: number;
149
  /** Walking acceleration */
150
  walkingAcceleration: number;
151
  /** Gravity force */
152
  gravity: number;
153
  /** Ground friction coefficient */
154
  groundFriction: number;
155
  /** Player collision box width radius */
156
  playerApothem: number;
157
  /** Player height */
158
  playerHeight: number;
159
  /** Jump velocity */
160
  jumpSpeed: number;
161
  /** Yaw rotation speed */
162
  yawSpeed: number;
163
  /** Pitch rotation speed */
164
  pitchSpeed: number;
165
  /** Sprint speed multiplier */
166
  sprintSpeed: number;
167
  /** Maximum speed on soul sand */
168
  maxGroundSpeedSoulSand: number;
169
  /** Maximum speed in water */
170
  maxGroundSpeedWater: number;
171
}
172
```
173

174
### Position and Movement Tracking
175

176
Access current position and movement state information.
177

178
```typescript { .api }
179
interface Bot {
180
  /** Bot's entity with position and movement data */
181
  entity: Entity;
182
  /** Current control states */
183
  controlState: ControlStateStatus;
184
}
185

186
interface Entity {
187
  /** Current world position */
188
  position: Vec3;
189
  /** Current velocity vector */
190
  velocity: Vec3;
191
  /** Horizontal rotation (yaw) in radians */
192
  yaw: number;
193
  /** Vertical rotation (pitch) in radians */
194
  pitch: number;
195
  /** Whether entity is on ground */
196
  onGround: boolean;
197
  /** Whether entity is in water */
198
  inWater: boolean;
199
  /** Whether entity is in lava */
200
  inLava: boolean;
201
  /** Whether entity is in web */
202
  inWeb: boolean;
203
}
204
```
205

206
### Movement Events
207

208
Monitor movement and physics events.
209

210
```typescript { .api }
211
interface BotEvents {
212
  /** Bot moved to a new position */
213
  move(position: Vec3): void;
214
  /** Bot was moved by server (teleport, knockback, etc.) */
215
  forcedMove(): void;
216
  /** Bot mounted a vehicle/entity */
217
  mount(): void;
218
  /** Bot dismounted from vehicle */
219
  dismount(vehicle: Entity): void;
220
  /** Physics simulation tick */
221
  physicsTick(): void;
222
  /** Legacy physics tick event (typo kept for compatibility) */
223
  physicTick(): void;
224
}
225
```
226

227
**Usage Examples:**
228

229
```typescript
230
// Monitor movement
231
bot.on("move", (position) => {
232
  console.log(`Bot moved to: ${position}`);
233
});
234

235
bot.on("forcedMove", () => {
236
  console.log("Bot was teleported or pushed by server");
237
});
238

239
// Track mounting
240
bot.on("mount", () => {
241
  console.log("Bot mounted a vehicle");
242
});
243

244
bot.on("dismount", (vehicle) => {
245
  console.log(`Bot dismounted from ${vehicle.type}`);
246
});
247

248
// Physics simulation monitoring
249
bot.on("physicsTick", () => {
250
  // Called every physics update (20 times per second)
251
  const pos = bot.entity.position;
252
  const vel = bot.entity.velocity;
253
  // console.log(`Position: ${pos}, Velocity: ${vel}`);
254
});
255
```
256

257
### Complex Movement Patterns
258

259
Examples of complex movement behaviors and patterns.
260

261
```typescript
262
// Follow a player
263
function followPlayer(username: string, distance: number = 3) {
264
  const player = bot.players[username];
265
  if (!player?.entity) return;
266
  
267
  const target = player.entity.position;
268
  const botPos = bot.entity.position;
269
  const distanceToPlayer = botPos.distanceTo(target);
270
  
271
  if (distanceToPlayer > distance) {
272
    // Move towards player
273
    bot.lookAt(target);
274
    bot.setControlState("forward", true);
275
    
276
    if (distanceToPlayer > distance * 2) {
277
      bot.setControlState("sprint", true);
278
    }
279
  } else {
280
    // Stop when close enough
281
    bot.setControlState("forward", false);
282
    bot.setControlState("sprint", false);
283
  }
284
}
285

286
// Circle around a point
287
async function circleAround(center: Vec3, radius: number, speed: number = 0.1) {
288
  let angle = 0;
289
  
290
  const circleInterval = setInterval(async () => {
291
    const targetX = center.x + Math.cos(angle) * radius;
292
    const targetZ = center.z + Math.sin(angle) * radius;
293
    const target = new Vec3(targetX, center.y, targetZ);
294
    
295
    await bot.lookAt(center); // Look at center while circling
296
    await bot.lookAt(target); // Then look at movement direction
297
    
298
    bot.setControlState("forward", true);
299
    angle += speed;
300
    
301
    if (angle > Math.PI * 2) {
302
      clearInterval(circleInterval);
303
      bot.clearControlStates();
304
    }
305
  }, 50);
306
}
307

308
// Jump across gaps
309
async function jumpGap() {
310
  bot.setControlState("forward", true);
311
  bot.setControlState("sprint", true);
312
  
313
  // Jump when approaching edge
314
  setTimeout(() => {
315
    bot.setControlState("jump", true);
316
  }, 500);
317
  
318
  // Land and stop
319
  setTimeout(() => {
320
    bot.clearControlStates();
321
  }, 1500);
322
}
323

324
// Parkour movement with timing
325
async function parkourJump(direction: ControlState, jumpTiming: number) {
326
  return new Promise<void>((resolve) => {
327
    bot.setControlState(direction, true);
328
    bot.setControlState("sprint", true);
329
    
330
    setTimeout(() => {
331
      bot.setControlState("jump", true);
332
    }, jumpTiming);
333
    
334
    setTimeout(() => {
335
      bot.clearControlStates();
336
      resolve();
337
    }, jumpTiming + 1000);
338
  });
339
}
340
```
341

342
### Utility Functions
343

344
Helper functions for movement calculations and positioning.
345

346
```typescript
347
// Calculate movement direction
348
function getDirectionToTarget(target: Vec3): ControlState[] {
349
  const bot_pos = bot.entity.position;
350
  const dx = target.x - bot_pos.x;
351
  const dz = target.z - bot_pos.z;
352
  
353
  const controls: ControlState[] = [];
354
  
355
  if (Math.abs(dx) > 0.5) {
356
    controls.push(dx > 0 ? "right" : "left");
357
  }
358
  if (Math.abs(dz) > 0.5) {
359
    controls.push(dz > 0 ? "forward" : "back");
360
  }
361
  
362
  return controls;
363
}
364

365
// Check if bot should jump
366
function shouldJump(): boolean {
367
  const frontBlock = bot.blockAt(bot.entity.position.offset(0, 0, 1));
368
  const frontGroundBlock = bot.blockAt(bot.entity.position.offset(0, -1, 1));
369
  
370
  return frontBlock?.type !== 0 && frontGroundBlock?.type !== 0; // Block in front and ground exists
371
}
372

373
// Safe movement with obstacle avoidance
374
function safeMoveTo(target: Vec3) {
375
  const directions = getDirectionToTarget(target);
376
  
377
  directions.forEach(dir => bot.setControlState(dir, true));
378
  
379
  if (shouldJump()) {
380
    bot.setControlState("jump", true);
381
  }
382
  
383
  // Stop when close to target
384
  if (bot.entity.position.distanceTo(target) < 1) {
385
    bot.clearControlStates();
386
  }
387
}
388
```