Interface INavigationAutomation
- Namespace
- AcDream.Plugin.Abstractions
- Assembly
- AcDream.Plugin.Abstractions.dll
Reading where the player and nearby objects are, and driving the player's own movement.
public interface INavigationAutomationProperties
GoToReport
The most recent walk the client planned to an object.
PluginGoToReport GoToReport { get; }Property Value
MoveReport
The most recent client-driven move on each channel, and the most recent jump.
PluginMoveReport MoveReport { get; }Property Value
Snapshot
The player's current movement state. Its IsAvailable is false
when no session is in the world.
PluginNavigationSnapshot Snapshot { get; }Property Value
Methods
CaptureObjects()
A detached list of every world object whose position the client can resolve, ordered by object id, for plugin-owned proximity policies such as an automatic door opener. Hosts may return an empty list.
IReadOnlyList<PluginNavigationObject> CaptureObjects()Returns
- IReadOnlyList<PluginNavigationObject>
The objects, or an empty list when no session is in the world or the host does not offer the projection.
CheckRoomAhead(float)
Looks for room to set a body the size of the character down
distanceMeters straight ahead of where it faces: the
room a pet needs before it is summoned. The client asks its own
collision the way it places any object that enters the world, without
letting the body slide aside, so a wall, a building, rising terrain, a
door or any other solid object in that spot blocks it; live creatures
and players standing there do not, as they move on. Ground a little
higher or lower than the character's feet is tried too: up to 70 cm
above and about 66 cm below. Nothing moves; call from the thread that
raises Tick.
PluginRoomAhead CheckRoomAhead(float distanceMeters)Parameters
distanceMetersfloatHow far ahead to look, in metres, above 0 and at most 10. Three metres is a summoned pet's usual distance.
Returns
- PluginRoomAhead
Clear with the spot, Blocked, or Unknown when the client cannot look (see Unknown); the default implementation always answers Unknown, so a plugin that must not stall on a host without the check can treat Unknown as room.
ClearMovementIntent()
Release every movement key the plugin was holding.
PluginNavigationCommandStatus ClearMovementIntent()Returns
- PluginNavigationCommandStatus
Unavailable when no session is in the world, otherwise whether the session took the command.
FaceHeading(float)
Turn the player on the spot to face a compass direction.
PluginNavigationCommandStatus FaceHeading(float headingDegrees)Parameters
headingDegreesfloatThe direction to face, in degrees clockwise from north.
Returns
- PluginNavigationCommandStatus
Unavailable when no session is in the world or the host does not implement turning, which is what the default implementation always returns; otherwise whether the session took the command.
Follow(uint, float)
Follows a player until StopGoTo(), a later walk, the player's own movement
input, or leaving the world ends it. The client walks up behind the player, within
bufferMeters of them, holds there facing them, and plans again as they
move, on the way as well as once there, leaping where the character can. It never gives
up: with no route, or blocked, it tries again a moment later; with the player out of
sight it waits for them; and a player who vanishes beside a portal is followed through
it. Only players can be followed; anything else ends the walk with no route.
GoToReport reports it, walking or waiting, for as long as it lasts.
PluginNavigationCommandStatus Follow(uint playerId, float bufferMeters)Parameters
Returns
GoTo(PluginNavigationPosition, float)
Walks the character to a place the way GoTo(uint, float) walks to
an object: along a route the client plans, ending within
arrivalMeters of position on the floor that
position stands on, and waiting while something else needs the character. A position
on a rock top is arrived at on the rock, or not at all. An elevation of NaN stands the
position on the ground there, for map coordinates given without a height. It does not turn the character to face
anything on arrival. A position with no cell, such as one read from a VTank route
file, is placed by its map coordinates alone. GoToReport reports the
walk with no object id.
PluginNavigationCommandStatus GoTo(PluginNavigationPosition position, float arrivalMeters)Parameters
positionPluginNavigationPositionarrivalMetersfloat
Returns
GoTo(uint, float)
Walks the character to an object along a route the client plans through
what it collides with: around walls and objects, through doorways, and up
and down ramps and stairs. The walk ends within
arrivalMeters of the object, at a spot with no wall
between the character and the object, facing it. When the character
stops making progress the client plans again from where it stands,
keeping out of the spot where it stuck, a few times. A later walk, StopGoTo(), the player
moving the character, or portal space ends it. While the character attacks,
a plugin holds a movement intent, or a plugin that asked with
PauseGoToWhile(Func<string?>) needs the character, the walk stops where the
character stands and waits, then plans again from there and goes on. The
walk steers with client-driven moves, so a plugin's own moves fight it while
it lasts.
PluginNavigationCommandStatus GoTo(uint objectId, float arrivalMeters)Parameters
Returns
Jump(float)
Jumps with power of a full charge, above 0 and at most 1.
PluginNavigationCommandStatus Jump(float power)Parameters
powerfloat
Returns
Move(PluginMoveDirection, PluginMovePace, float, PluginMoveUnit)
Starts a move the client carries out and ends by itself. Moves on
different channels are held together, the way movement keys are, so a
plugin can run while it strafes or turns; a new move replaces only the
move on its own channel. amount counts
unit, and zero keeps going until stopped, for at most
thirty seconds. A turn lands on its exact angle. A move also ends when it
stops making progress or runs out of time, and every move ends when the
player moves the character or it enters portal space.
PluginNavigationCommandStatus Move(PluginMoveDirection direction, PluginMovePace pace, float amount, PluginMoveUnit unit = PluginMoveUnit.MetersOrDegrees)Parameters
directionPluginMoveDirectionpacePluginMovePaceamountfloatunitPluginMoveUnit
Returns
PauseGoToWhile(Func<string?>)
Has walks to objects wait for a plugin that sometimes needs the character,
such as a combat macro. While need returns what the plugin
is doing, such as "fighting a monster", a walk under way stops where
the character stands and reports that it waits on that. Once nothing has
needed the character for a moment, the walk plans again from where the
character stands and goes on. The client asks on the update thread, every
frame a walk is under way, until the result is disposed.
IDisposable PauseGoToWhile(Func<string?> need)Parameters
Returns
PreviewPathAsync(PluginNavigationPosition, float)
Plans a path to a cell-aware position without moving or taking ownership of the character. Call from the thread that raises Tick. An elevation of NaN selects ground at the destination.
Task<PluginNavigationPlan> PreviewPathAsync(PluginNavigationPosition position, float arrivalMeters = 2.5)Parameters
positionPluginNavigationPositionarrivalMetersfloat
Returns
PreviewPathAsync(uint, float)
Plans a path to an object without moving or taking ownership of the character. Call from the thread that raises Tick: the world snapshot is captured before this method returns, then grid building and route search run on a worker. The result may become stale as the world changes.
Task<PluginNavigationPlan> PreviewPathAsync(uint objectId, float arrivalMeters = 2.5)Parameters
Returns
SetMovementIntent(in PluginMovementIntent)
Hold the given movement keys until the intent is replaced or cleared.
PluginNavigationCommandStatus SetMovementIntent(in PluginMovementIntent intent)Parameters
intentPluginMovementIntentThe keys to hold.
Returns
- PluginNavigationCommandStatus
Unavailable when no session is in the world, otherwise whether the session took the command.
StandOn(uint, float)
Walks the character onto an object and stands it on the object's top, the highest
floor on the object a body stands on, the way GoTo(uint, float) walks to
an object: jumping up where the character can, ending within
arrivalMeters of the middle of that top and never on the ground
beside the object. An object with nothing on top a body stands on, or no way up,
ends the walk with no route. StopGoTo() ends it and
GoToReport reports it.
PluginNavigationCommandStatus StandOn(uint objectId, float arrivalMeters)Parameters
Returns
StopGoTo()
Ends the walk to an object under way, if there is one.
PluginNavigationCommandStatus StopGoTo()Returns
StopMoving()
Ends every client-driven move in progress.
PluginNavigationCommandStatus StopMoving()Returns
StopMoving(PluginMoveChannel)
Ends the client-driven move on one channel, if there is one.
PluginNavigationCommandStatus StopMoving(PluginMoveChannel channel)Parameters
channelPluginMoveChannel
Returns
TryFindObject(string, in PluginNavigationPosition, double, out PluginNavigationObject)
Find the object closest to near whose name matches
exactly, ignoring letter case, within the given radius.
bool TryFindObject(string name, in PluginNavigationPosition near, double maximumDistanceMeters, out PluginNavigationObject value)Parameters
namestringThe name to match.
nearPluginNavigationPositionThe position distances are measured from.
maximumDistanceMetersdoubleHow far to search, in meters, measured along the ground.
valuePluginNavigationObjectThe nearest matching object, when one was found.
Returns
- bool
False when nothing matched inside the radius, when the name is blank or the distance is negative or not a number, and on a host that does not implement the search: the default implementation always returns false.
TryGetObject(uint, out PluginNavigationObject)
Look up one world object by its id.
bool TryGetObject(uint objectId, out PluginNavigationObject value)Parameters
objectIduintThe object id to look up.
valuePluginNavigationObjectThe object, when one was found.
Returns
- bool
False when no session is in the world, the id is zero, the object is unknown to the client, or its position cannot be resolved.
Events
SnapshotChanged
Raised when the current navigation snapshot changes. Handlers run on the same thread as Tick. Hosts that do not provide navigation leave this event inert. A subscription does not replay the current snapshot; read Snapshot first when an initial value is required.
event Action<PluginNavigationSnapshot> SnapshotChanged