Agent Movement API

Documentation for the movement completion tracking API added to HyperscapeService.

Overview

The HyperscapeService now provides movement completion tracking, allowing actions to wait for movement to finish before proceeding. This is critical for multi-step actions like banking (walk to bank → deposit items).

API Reference

`waitForMovementComplete(timeoutMs?: number): Promise<void>`

Wait for the current movement to complete. Resolves immediately if not moving. Parameters:

timeoutMs (optional): Maximum time to wait in milliseconds (default: 15000)

Returns: Promise that resolves when movement completes or timeout expires Example:

// Walk to bank
await service.executeMove({ target: bankPosition, runMode: false });

// Wait for movement to complete before depositing
await service.waitForMovementComplete();

// Now we're at the bank, safe to deposit
await service.bankDeposit('logs', 10);

`isMoving: boolean`

Read-only property indicating if the character is currently moving. Example:

if (service.isMoving) {
  console.log('Character is moving, waiting...');
  await service.waitForMovementComplete();
}

Implementation Details

Movement State Tracking

The service tracks movement state using two internal properties:

_isMoving: Boolean flag set when executeMove() is called
_movementResolve: Promise resolver called when tileMovementEnd packet received

Packet Flow

Movement Start:

service.executeMove({ target: [x, y, z], runMode: false });
// Sets _isMoving = true
// Sends moveRequest packet to server

Server Processing:
- Server validates movement
- Sends tileMovementStart packet
- Sends entityTileUpdate packets during movement
- Sends tileMovementEnd packet when complete

Movement Complete:

// tileMovementEnd packet received
// Sets _isMoving = false
// Calls _movementResolve() to resolve waiting promises

Timeout Handling

If movement doesn’t complete within the timeout period:

Promise resolves anyway (doesn’t reject)
_isMoving flag is cleared
Prevents actions from hanging indefinitely

Use Cases

Banking Actions

Banking requires the character to be at the bank before depositing:

// Old way (broken - deposits before arriving)
await service.executeMove({ target: bankPosition });
await service.bankDeposit('logs', 10);  // ❌ Executes immediately

// New way (correct - waits for arrival)
await service.executeMove({ target: bankPosition });
await service.waitForMovementComplete();  // ✅ Waits for movement
await service.bankDeposit('logs', 10);    // ✅ Executes after arrival

Resource Gathering

Approach a resource before gathering:

// Walk to tree
await service.executeMove({ target: treePosition });
await service.waitForMovementComplete();

// Now we're in range, start chopping
await service.executeGatherResource({ resourceEntityId: treeId });

Combat Positioning

Move into attack range before attacking:

// Move to attack range
await service.executeMove({ target: mobPosition });
await service.waitForMovementComplete();

// Now we're in range, attack
await service.executeAttack({ targetEntityId: mobId });

Action Lock Integration

The movement API integrates with the action lock system to prevent LLM ticks during movement:

// Action sets a locked goal
behaviorManager.setGoal({
  type: 'banking',
  description: 'Banking items',
  locked: true,
  lockedBy: 'banking_action',
});

// Execute movement
await service.executeMove({ target: bankPosition });

// Wait for movement (LLM ticks are skipped while moving)
await service.waitForMovementComplete();

// Movement complete, perform banking
await service.bankDepositAll();

// Clear lock to resume autonomous behavior
behaviorManager.clearGoal();

Fast-Tick Mode

After movement completes, the autonomous behavior manager enters “fast-tick mode” for 2 seconds:

Normal tick interval: 10 seconds
Fast-tick interval: 2 seconds
Triggered by: Movement completion, goal changes

This allows quick follow-up actions without waiting for the full tick interval.

Migration Guide

Before (Broken)

// Banking action (old)
async function bankItems(service: HyperscapeService) {
  const bank = findNearestBank();
  await service.executeMove({ target: bank.position });
  await service.bankDepositAll();  // ❌ Executes before arrival
  return { success: true };
}

After (Fixed)

// Banking action (new)
async function bankItems(service: HyperscapeService) {
  const bank = findNearestBank();
  await service.executeMove({ target: bank.position });
  await service.waitForMovementComplete();  // ✅ Wait for arrival
  await service.bankDepositAll();
  return { success: true };
}

This API was added as part of the agent stability improvements (PR #945):

Action locks: Skip LLM ticks during movement
Fast-tick mode: 2s interval after movement/goal changes
Short-circuit LLM: Obvious decisions bypass LLM
Banking protocol: Proper sequence with movement awaiting

See docs/agent-stability-improvements.md for full details.

Configuration

Operations

Agent movement api

Agent Movement API

Overview

API Reference

`waitForMovementComplete(timeoutMs?: number): Promise<void>`

`isMoving: boolean`

Implementation Details

Movement State Tracking

Packet Flow

Timeout Handling

Use Cases

Banking Actions

Resource Gathering

Combat Positioning

Action Lock Integration

Fast-Tick Mode

Migration Guide

Before (Broken)

After (Fixed)

See Also

​Agent Movement API

​Overview

​API Reference

​waitForMovementComplete(timeoutMs?: number): Promise<void>

​isMoving: boolean

​Implementation Details

​Movement State Tracking

​Packet Flow

​Timeout Handling

​Use Cases

​Banking Actions

​Resource Gathering

​Combat Positioning

​Action Lock Integration

​Fast-Tick Mode

​Migration Guide

​Before (Broken)

​After (Fixed)

​Related Changes

​See Also

Agent Movement API

Overview

API Reference

`waitForMovementComplete(timeoutMs?: number): Promise<void>`

`isMoving: boolean`

Implementation Details

Movement State Tracking

Packet Flow

Timeout Handling

Use Cases

Banking Actions

Resource Gathering

Combat Positioning

Action Lock Integration

Fast-Tick Mode

Migration Guide

Before (Broken)

After (Fixed)

Related Changes

See Also