beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ClassicAssist.Avalonia/.qoder/repowiki/en/content/Macro System/Built-in Commands/Movement Commands.md
T
Beyhan Oğur d5f52cc3d3 first commit
2026-09-03 04:45:36 +03:00

459 lines
18 KiB
Markdown
Raw Permalink Blame History

# Movement Commands
<cite>
**Referenced Files in This Document**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.cs)
</cite>
## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)
## Introduction
This document explains movement commands in the ClassicAssist.Avalonia macro system. It covers walking, running, jumping, mounting/dismounting, and pathfinding commands. It includes parameter specifications (coordinates, directions, speed settings, navigation targets), practical examples for automation, timing considerations, collision detection behavior, performance optimization for large-scale movement, error handling for failed movements, and integration with targeting systems.
## Project Structure
Movement-related functionality spans shared macro/hotkey command implementations, UO data and math utilities, and packet-level pathfinding support:
- Macro and hotkey command definitions expose user-facing commands to macros and hotkeys.
- UO data types provide direction, map, and math helpers used by movement logic.
- Pathfinding packets integrate with the game client/server protocol for advanced routing.
```mermaid
graph TB
subgraph "Macro System"
MC["Macros/MovementCommands.cs"]
HC["Hotkeys/MovementCommands.cs"]
end
subgraph "UO Data & Math"
DIR["Direction.cs"]
MAP["Map.cs"]
MATH["UOMath.cs"]
end
subgraph "Networking"
PF["Packets/Pathfind.cs"]
end
subgraph "Entities"
MOB["Mobile.cs"]
PMOB["PlayerMobile.cs"]
end
subgraph "Targeting"
TM["TargetManager.cs"]
end
MC --> DIR
MC --> MAP
MC --> MATH
MC --> PF
MC --> MOB
MC --> PMOB
HC --> MC
HC --> TM
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
## Core Components
- Macro movement commands: Provide high-level movement primitives usable from macros (walk/run/jump/mount/dismount/pathfind).
- Hotkey movement commands: Bind movement actions to hotkeys and optionally integrate with targeting.
- Direction and map utilities: Represent cardinal directions and coordinate spaces.
- Pathfinding packet support: Encodes path requests for server-side or client-side routing.
- Entity models: Player/mobile state and properties influence movement behavior (e.g., mounted status).
- Targeting integration: Allows moving toward a target or using current target as a destination.
Key responsibilities:
- Validate parameters (coordinates, directions, speed).
- Convert logical inputs into network packets or engine calls.
- Handle timing and retries for robust movement.
- Report errors and success states back to macros/hotkeys.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
## Architecture Overview
The macro/hotkey layer translates user intent into movement actions. For simple steps, it sends direct movement packets; for complex routes, it uses pathfinding. Mounting toggles are handled via dedicated commands. Targeting integration allows dynamic destinations.
```mermaid
sequenceDiagram
participant Macro as "Macro"
participant MC as "Macros/MovementCommands.cs"
participant DIR as "Direction.cs"
participant MAP as "Map.cs"
participant PF as "Packets/Pathfind.cs"
participant MOB as "PlayerMobile.cs"
participant TM as "TargetManager.cs"
Macro->>MC : "MoveTo(x,y,map)"
MC->>MAP : "Validate coordinates"
MC->>DIR : "Compute direction(s)"
alt "Simple step"
MC-->>MOB : "Send movement request"
else "Complex route"
MC->>PF : "Request path"
PF-->>MC : "Path points"
loop "Follow path"
MC->>MOB : "Step along path"
end
end
Note over MC,TM : "Optional : use current target as destination"
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
## Detailed Component Analysis
### Walking and Running
Purpose:
- Move the character one or more steps in a given direction or toward a target.
- Support both walking and running modes where applicable.
Parameters:
- Direction: cardinal or ordinal direction values.
- Distance: number of steps (optional; defaults may apply).
- Mode: walk vs run toggle if supported by the command variant.
Behavior:
- Validates current position and direction.
- Sends movement packets to the server.
- May respect game constraints (combat, stunned, etc.).
Timing:
- Introduce small delays between steps when issuing multiple moves to avoid input flooding.
Error handling:
- Detect invalid directions or blocked tiles and report failure.
Practical example:
- Walk 5 steps north, then run 3 steps east.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
### Jumping
Purpose:
- Execute a jump action, typically to clear obstacles or reach elevated areas.
Parameters:
- Optional target location or relative offset.
- Timing delay before/after jump.
Behavior:
- Issues jump request packet.
- May require line-of-sight or valid landing tile.
Error handling:
- Fails if jump is invalid (blocked, out of bounds).
Practical example:
- Jump forward once to clear a wall segment.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
### Mounting and Dismounting
Purpose:
- Toggle mount state to enable faster travel or specific interactions.
Parameters:
- None (toggle behavior) or explicit mount selection if supported.
Behavior:
- Uses dedicated mount toggle command.
- Integrates with player state to ensure valid transitions.
Error handling:
- Reports failure if no mount available or conditions not met.
Practical example:
- Mount before long-distance travel; dismount near destination.
**Section sources**
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
### Pathfinding and Navigation
Purpose:
- Compute and follow a multi-step route to a target coordinate or entity.
Parameters:
- Destination coordinates (x, y, map).
- Optional target reference (current target or named entity).
- Speed setting (walk/run preference).
- Obstacle avoidance flags (if exposed).
Behavior:
- Requests path via pathfinding packet.
- Iteratively steps along the returned path.
- Replans if blocked or invalidated.
Collision detection:
- Relies on server/client validation; macro layer should detect failures and retry or abort.
Timing:
- Pace steps to match game tick rates; add jitter to reduce synchronization issues.
Error handling:
- On path failure, fallback to direct movement or notify macro.
Practical example:
- Navigate to a waypoint while avoiding obstacles; switch to running after clearing dense areas.
**Section sources**
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
### Integration with Targeting Systems
Purpose:
- Allow movement commands to use the current target as a destination or to move adjacent to a target.
Parameters:
- Target selection mode (current target, nearest, by name).
- Offset distance from target.
Behavior:
- Resolves target coordinates via targeting manager.
- Converts target-based requests into coordinate-based movement.
Error handling:
- If target is invalid or lost, abort or prompt for new target.
Practical example:
- Move within range of current enemy without engaging.
**Section sources**
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
### Class Relationships
```mermaid
classDiagram
class MovementCommands {
+MoveTo(x, y, map)
+Walk(direction, steps)
+Run(direction, steps)
+Jump(offset)
+Pathfind(destination)
+Mount()
+Dismount()
}
class Direction {
+values
+toVector()
}
class Map {
+isValid(x,y)
+getTile(x,y)
}
class PathfindPacket {
+requestPath(start,end)
+parseResponse()
}
class PlayerMobile {
+position
+mounted
+sendMovement()
}
class TargetManager {
+getCurrentTarget()
+resolveCoordinates(target)
}
MovementCommands --> Direction : "uses"
MovementCommands --> Map : "validates"
MovementCommands --> PathfindPacket : "requests"
MovementCommands --> PlayerMobile : "controls"
MovementCommands --> TargetManager : "resolves targets"
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
### Sequence: Pathfinding Follow
```mermaid
sequenceDiagram
participant Macro as "Macro"
participant MC as "Macros/MovementCommands.cs"
participant PF as "Packets/Pathfind.cs"
participant MOB as "PlayerMobile.cs"
Macro->>MC : "Pathfind(destX, destY, map)"
MC->>PF : "Request path"
PF-->>MC : "Path points"
loop "For each point"
MC->>MOB : "Step to next point"
MOB-->>MC : "Status (success/failure)"
alt "Failure"
MC->>PF : "Replan path"
end
end
MC-->>Macro : "Complete or error"
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
### Flowchart: Step Execution
```mermaid
flowchart TD
Start(["Start Step"]) --> Validate["Validate Coordinates/Direction"]
Validate --> Valid{"Valid?"}
Valid --> |No| Error["Return Error"]
Valid --> |Yes| CheckState["Check Player State<br/>Mounted? Combat?"]
CheckState --> CanMove{"Can Move?"}
CanMove --> |No| Error
CanMove --> |Yes| SendMove["Send Movement Packet"]
SendMove --> WaitTick["Wait Game Tick"]
WaitTick --> Success{"Success?"}
Success --> |No| Retry["Retry or Abort"]
Success --> |Yes| Done(["Done"])
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
## Dependency Analysis
- Macro movement commands depend on:
- Direction and Map utilities for spatial reasoning.
- Pathfinding packet interface for complex routing.
- PlayerMobile for sending movement and reading state.
- TargetManager for resolving dynamic destinations.
- Hotkey movement commands wrap macro commands and may add UI/targeting shortcuts.
```mermaid
graph LR
HC["Hotkeys/MovementCommands.cs"] --> MC["Macros/MovementCommands.cs"]
MC --> DIR["Direction.cs"]
MC --> MAP["Map.cs"]
MC --> PF["Packets/Pathfind.cs"]
MC --> MOB["PlayerMobile.cs"]
MC --> TM["TargetManager.cs"]
```
**Diagram sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
## Performance Considerations
- Batch movement: Group multiple steps to reduce overhead; interleave waits to respect server ticks.
- Avoid redundant replanning: Cache paths when possible; only replan on failure or significant deviation.
- Use running selectively: Running may be faster but can increase collision checks; prefer walking in tight spaces.
- Minimize target resolution: Resolve target coordinates once per routine rather than repeatedly.
- Throttle input: Add small random jitter to step timings to prevent lockstep behavior.
[No sources needed since this section provides general guidance]
## Troubleshooting Guide
Common issues and resolutions:
- Invalid coordinates: Ensure x/y/map are within valid ranges; validate before sending.
- Blocked path: If pathfinding fails, fall back to direct movement or adjust destination slightly.
- Mounted state conflicts: Dismount before entering interiors or narrow corridors if required.
- Target loss: Re-resolve target coordinates if the target disappears mid-route.
- Timing errors: Increase wait times between steps; check for combat or stun states that block movement.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
## Conclusion
Movement commands in ClassicAssist.Avalonia provide a robust foundation for automated locomotion. By combining simple step controls with pathfinding, mounting toggles, and targeting integration, macros can implement sophisticated navigation patterns. Proper parameter validation, timing control, and error handling ensure reliable operation across diverse scenarios.
[No sources needed since this section summarizes without analyzing specific files]
## Appendices
### Parameter Reference Summary
- Coordinates: x, y, map identifiers validated against map boundaries.
- Directions: Cardinal/ordinal direction values converted to movement vectors.
- Speed settings: Walk vs run preferences applied per step or route segment.
- Navigation targets: Current target or resolved entities used as destinations.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
### Practical Automation Patterns
- Route planning: Define waypoints; use pathfinding between segments; switch to running on open terrain.
- Obstacle avoidance: Detect failures and reroute; prefer walking in cluttered areas.
- Large-scale movement: Combine mount toggling with batched pathfinding; cache paths; stagger execution.
**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.cs)
Reference in New Issue View Git Blame Copy Permalink