Beyhan Oğur
18 KiB
18 KiB
Movement Commands
**Referenced Files in This Document** - [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs) - [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs) - [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs) - [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs) - [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs) - [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs) - [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs) - [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs) - [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs) - [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs) - [ActionPacketQueueItem.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueueItem.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document provides comprehensive documentation for Movement macro commands that control character navigation and positioning. It covers movement primitives such as directional movement, pathfinding, teleportation, and mount control. The guide includes method signatures with parameters for coordinates, directions, and movement options; examples of complex movement patterns; guidance on path optimization and collision avoidance; and details about movement queuing, timing synchronization, and performance considerations for automated navigation.
Project Structure
The movement functionality is implemented across shared data and UO networking layers:
- Macro command implementations define the user-facing API for movement operations.
- Hotkey command implementations provide quick-access equivalents for common movements.
- Network packets encapsulate client-server communication for movement requests and updates.
- Data models represent directions, enums, and mobile entities used by movement logic.
graph TB
subgraph "Macro Layer"
MC["Macros/MovementCommands.cs"]
HKC["Hotkeys/Commands/MovementCommands.cs"]
end
subgraph "UO Networking"
MPK["Packets/MovementRequest.cs"]
MMV["Packets/MobileMoving.cs"]
PF["Data/Gumps/Packets/Pathfind.cs"]
APQ["Network/ActionPacketQueue.cs"]
end
subgraph "UO Data & Objects"
DIR["Data/Direction.cs"]
ENM["Data/Enums.cs"]
PMOB["Objects/PlayerMobile.cs"]
MOB["Objects/Mobile.cs"]
end
MC --> MPK
HKC --> MPK
MC --> PF
MC --> APQ
MC --> PMOB
MC --> MOB
MPK --> DIR
MPK --> ENM
MMV --> DIR
PF --> DIR
Diagram sources
- MovementCommands.cs
- MovementCommands.cs
- MovementRequest.cs
- MobileMoving.cs
- Pathfind.cs
- Direction.cs
- Enums.cs
- PlayerMobile.cs
- Mobile.cs
- ActionPacketQueue.cs
Section sources
- MovementCommands.cs
- MovementCommands.cs
- MovementRequest.cs
- MobileMoving.cs
- Pathfind.cs
- Direction.cs
- Enums.cs
- PlayerMobile.cs
- Mobile.cs
- ActionPacketQueue.cs
Core Components
- Macro Movement Commands: Provide high-level movement operations (move to coordinates, move relative, pathfind, teleport, toggle mount).
- Hotkey Movement Commands: Offer quick actions like step forward/backward or turn left/right.
- Movement Packets: Serialize movement requests and handle incoming movement updates.
- Direction and Enums: Define supported directions and movement-related enumerations.
- Mobile Entities: Represent player and other mobiles, including mounted state and position.
- Action Packet Queue: Batches and schedules outgoing movement packets for smooth automation.
Key responsibilities:
- Validate inputs (coordinates, direction validity, mount state).
- Construct and send appropriate network packets.
- Manage queued movement actions to avoid flooding the server.
- Synchronize with incoming movement updates to confirm progress.
Section sources
- MovementCommands.cs
- MovementCommands.cs
- MovementRequest.cs
- MobileMoving.cs
- Direction.cs
- Enums.cs
- PlayerMobile.cs
- Mobile.cs
- ActionPacketQueue.cs
Architecture Overview
The movement system integrates macro commands with the game’s networking layer:
- Macro commands parse parameters and call into movement helpers.
- Helpers validate and construct movement packets using Direction and Enums.
- Packets are enqueued via ActionPacketQueue and transmitted to the server.
- Incoming MobileMoving packets update local entity positions and states.
- Pathfinding uses specialized packets to request routes from the server.
- Mount control toggles mounted state and adjusts movement behavior accordingly.
sequenceDiagram
participant Macro as "Macro Command"
participant Helper as "Movement Helper"
participant Queue as "ActionPacketQueue"
participant Net as "Network Layer"
participant Server as "Game Server"
participant Update as "Incoming MobileMoving"
Macro->>Helper : "MoveTo(x,y)"
Helper->>Helper : "Validate coordinates/direction"
Helper->>Queue : "Enqueue MovementRequest"
Queue->>Net : "Send packet"
Net->>Server : "MovementRequest"
Server-->>Update : "MobileMoving update"
Update-->>Macro : "Position updated"
Diagram sources
Detailed Component Analysis
Macro Movement Commands
High-level methods exposed to macros for navigation and positioning:
- Move to absolute coordinates
- Move relative to current position
- Pathfind to a target coordinate
- Teleport to a coordinate (if permitted)
- Toggle mount state
- Step in a given direction
- Turn to face a direction
Method signatures and parameters:
- MoveTo(int x, int y, bool usePathfinding = true, int timeoutMs = 0)
- Parameters:
- x: Target X coordinate -y: Target Y coordinate
- usePathfinding: Whether to request a path from the server
- timeoutMs: Optional wait time for completion
- Parameters:
- MoveRelative(int dx, int dy, int steps = 1)
- Parameters:
- dx: Change in X
- dy: Change in Y
- steps: Number of steps to take
- Parameters:
- PathfindTo(int x, int y, int maxHops = 0)
- Parameters:
- x: Target X
- y: Target Y
- maxHops: Maximum hops allowed
- Parameters:
- TeleportTo(int x, int y)
- Parameters:
- x: Destination X
- y: Destination Y
- Parameters:
- ToggleMounted(bool? mounted = null)
- Parameters:
- mounted: True to mount, False to dismount, null to toggle
- Parameters:
- StepInDirection(Direction dir, int steps = 1)
- Parameters:
- dir: Direction enum value
- steps: Number of steps
- Parameters:
- FaceDirection(Direction dir)
- Parameters:
- dir: Direction to face
- Parameters:
Behavioral notes:
- Coordinates are validated against map bounds and obstacles when applicable.
- Pathfinding requests may be rejected if blocked; fallbacks can retry with adjusted offsets.
- Teleportation may require specific permissions or conditions.
- Mount control affects movement speed and collision rules.
Complex movement patterns:
- Zigzag traversal: alternate between two adjacent cells while advancing along an axis.
- Spiral search: expand radius incrementally around a center point.
- Corridor navigation: follow walls by turning at intersections based on obstacle checks.
Path optimization:
- Prefer direct paths when possible; fall back to pathfinding only when necessary.
- Use small incremental moves to reduce path recalculation overhead.
- Batch multiple steps into a single queue operation where supported.
Collision avoidance:
- Check tile flags and statics before moving into a cell.
- Adjust destination by ±1 in X/Y to bypass narrow passages.
- Use pathfinding results to avoid known blocked tiles.
Movement queuing and timing:
- Enqueue movement actions via ActionPacketQueue to prevent flooding.
- Introduce delays between steps to match server tick rates.
- Monitor incoming MobileMoving updates to synchronize macro flow.
Examples:
- Navigate through a maze by following right-hand rule.
- Patrol a rectangular route by cycling through four waypoints.
- Approach a vendor, stop at a safe distance, then interact.
Section sources
Hotkey Movement Commands
Quick-access commands for immediate movement actions:
- StepForward()
- StepBackward()
- TurnLeft()
- TurnRight()
These commands typically wrap Direction-based movement and are designed for low-latency usage. They integrate with the same packet pipeline and queueing mechanisms as macro commands.
Section sources
Movement Packets and Updates
- MovementRequest: Encodes direction or coordinate-based movement requests sent to the server.
- MobileMoving: Represents incoming updates reflecting character position changes.
- Pathfind: Handles pathfinding requests and responses for navigating complex environments.
Data structures:
- Direction: Enumerates cardinal and intercardinal directions.
- Movement-related enums: Include flags for movement modes and constraints.
Processing logic:
- On sending MovementRequest, the client expects subsequent MobileMoving updates.
- Pathfind requests return a sequence of directions or waypoints to follow.
- Collision checks rely on tile data and static objects to determine walkability.
Section sources
Mobile Entities and State
- PlayerMobile: Represents the local player, including position, facing direction, and mounted state.
- Mobile: Base class for all mobile entities, providing common properties and behaviors.
State synchronization:
- Position updates arrive via MobileMoving packets.
- Mounted state influences movement capabilities and speed.
- Facing direction is updated independently of positional movement.
Section sources
Action Packet Queue
- ActionPacketQueue: Manages outgoing movement packets, ensuring they are sent in order and throttled appropriately.
- ActionPacketQueueItem: Represents individual queued actions with metadata such as timestamps and priorities.
Queue behavior:
- Prevents overwhelming the server with rapid movement requests.
- Supports batching similar actions to reduce overhead.
- Integrates with timers to enforce minimum intervals between steps.
Section sources
Dependency Analysis
Movement commands depend on several core components:
- Direction and Enums define valid movement vectors and flags.
- Packets serialize movement requests and updates.
- Mobile entities provide state context for movement decisions.
- ActionPacketQueue orchestrates timing and ordering of network calls.
classDiagram
class MovementCommand {
+MoveTo(x, y, usePathfinding, timeoutMs)
+MoveRelative(dx, dy, steps)
+PathfindTo(x, y, maxHops)
+TeleportTo(x, y)
+ToggleMounted(mounted)
+StepInDirection(dir, steps)
+FaceDirection(dir)
}
class Direction {
<<enum>>
}
class MovementRequest {
+Serialize()
+Deserialize()
}
class MobileMoving {
+X
+Y
+Direction
+IsMounted
}
class ActionPacketQueue {
+Enqueue(item)
+Flush()
}
class PlayerMobile {
+X
+Y
+Facing
+IsMounted
}
MovementCommand --> Direction : "uses"
MovementCommand --> MovementRequest : "creates"
MovementCommand --> ActionPacketQueue : "enqueues"
MovementCommand --> PlayerMobile : "reads/writes state"
MobileMoving --> Direction : "updates"
Diagram sources
- MovementCommands.cs
- Direction.cs
- MovementRequest.cs
- MobileMoving.cs
- ActionPacketQueue.cs
- PlayerMobile.cs
Section sources
- MovementCommands.cs
- Direction.cs
- MovementRequest.cs
- MobileMoving.cs
- ActionPacketQueue.cs
- PlayerMobile.cs
Performance Considerations
- Throttle movement requests to match server tick rates to avoid rejection or lag spikes.
- Prefer batched moves over many individual steps when possible.
- Use pathfinding selectively; frequent recalculations can be expensive.
- Cache obstacle information locally to minimize repeated checks.
- Monitor incoming updates to detect stalls and adjust strategies dynamically.
- Avoid unnecessary mount toggling; keep consistent movement mode during long sequences.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Movement not progressing:
- Verify coordinates are within map bounds and not blocked.
- Check if pathfinding was requested and whether it returned a valid route.
- Ensure ActionPacketQueue is not empty and packets are being sent.
- Character stuck or jittering:
- Reduce step frequency; increase delay between moves.
- Confirm MobileMoving updates are received and processed.
- Teleport failures:
- Confirm destination is valid and teleportation is permitted in the region.
- Mount issues:
- Validate current mounted state and ensure required items or skills are present.
Debugging tips:
- Log outgoing MovementRequest packets and incoming MobileMoving updates.
- Inspect Direction values and ensure they correspond to intended movement vectors.
- Review ActionPacketQueue item timestamps to identify bottlenecks.
Section sources
Conclusion
Movement commands provide robust tools for automating character navigation and positioning. By combining directional movement, pathfinding, teleportation, and mount control with careful queuing and timing, users can implement efficient and reliable automated navigation. Understanding the underlying packets, entity states, and queue mechanics enables advanced techniques such as collision avoidance and path optimization.
[No sources needed since this section summarizes without analyzing specific files]
Appendices
Method Reference Summary
- MoveTo(int x, int y, bool usePathfinding = true, int timeoutMs = 0)
- MoveRelative(int dx, int dy, int steps = 1)
- PathfindTo(int x, int y, int maxHops = 0)
- TeleportTo(int x, int y)
- ToggleMounted(bool? mounted = null)
- StepInDirection(Direction dir, int steps = 1)
- FaceDirection(Direction dir)
Section sources