Attaching to a Player

If you want to automate or control a Player, you have to attach an Actor to that Player. You attach Actor to the local player through IPlayerActor. This gives you an IActor that exposes movement, orientation, and interaction. You can then use the IActor to control the Player.

The basic flow

1. Get the local Player instance
2. Attach an Actor
3. Grab the control interfaces you need
4. Detach from your Player when you're done

Attaching

var player = Minecraft.getInstance().player;
// Make sure player is not null
assert player != null;

var actor = ((IPlayerActor) player).actor$attach();

Now you have attached an Actor.
You should keep track of that IActor instance, as you will use this to control the Player.

WARNING

You should NOT attach multiple Actors to a single Player.
This will result in an error.

Check if an Actor is attached

If you want to find out whether an Actor is already attached to a Player (e.g. because you didn't keep track of your Actor instance), you can use the following method:

var existing = ((IPlayerActor) player).actor$getActor();
if (existing != null)
    // Reuse old
else
    // Attach new

Detaching an Actor

If you're done with your Actor you can just detach from the Player.

When should I detach?

Detach when your feature finishes so the player can regain full control.

((IPlayerActor) player).actor$detach();

WARNING

Make sure you don't use your Actor instance anymore after detaching, as this may result in an error.

API Entry Points

After attaching to a Player and retrieving your IActor instance, you can use these methods to access their respective APIs:

var movement = actor.getMovement();
var orientation = actor.getOrientation();
var interaction = actor.getInteraction();

Actor Priorities

Priorities are an important concept when using Actor.
They decide when to use the Actor's input and when the user's input.

What priorities exist

Priority	What it means
ActorPriority.ACTOR	The Actor's inputs (the things your program controls) are used at all times. The user does NOT have ANY control.
ActorPriority.USER	The User's inputs (e.g. keyboard or mouse inputs) when the Actor does not currently control these specific inputs.

WARNING

You should think about what priority you want to use, as USER may result in a non-deterministic and not fully controllable program, whereas ACTOR doesn't give the User any freedom.

How to use Priorities

By default ((IPlayerActor) player).actor$attach() uses ACTOR as a priority.
If you want to use USER or use custom logic to decide which priority to use, you can attach with a priority like this:

var actor = ((IPlayerActor) player).actor$attach(ActorPriority.USER);
// OR 
var actor = ((IPlayerActor) player).actor$attach(ActorPriority.ACTOR);