Overview

Retrieve player behavior by its public capability type with player.capability(Type.class). Keep these instances with that player and retrieve new ones after creating a replacement.

The capabilities in this section extend PlayerCapability; a provider creates each instance for one player. They cover what a Minecraft client can normally do or see: its connection, the chat it receives, its inventory, the dialogs it is shown. What a server or proxy knows about a player, such as whether the player is on it, the profile it sees, or the backend a proxy connected the player to, belongs to that process's Players capability. General server or proxy control uses the context's process API or a capability owned by the process and backed by its agent, such as Dispatch.

Choose the behavior

For the first journey, use Session to connect, the server's Players to observe arrival, and Messages to trigger commands and check replies. Movement, Inventory, Interaction, Commands, and Dialogs cover additional game actions; Cookies holds the cookies a server stores on the client; Screen and Sounds record the titles, action bars, boss bars and sounds the server shows and plays, and Entities follows the entities the server shows it, such as text above a player. Each capability is optional unless the test or another installed capability requires it.

Packet-backed capabilities operate through the player's protocol library. The built-in capabilities are installed on every MCProtocolLib release Anvil ships, from Minecraft 1.16.5 to 26.3, except Dialogs, which needs a release with dialogs: 1.21.11 and newer, and Cookies, which needs a release with cookies: 1.20.6 and newer.

Install built-in capabilities

The me.whereareiam.anvil.capability.default Gradle plugin includes these player capabilities. For a smaller JUnit setup, this plugin block selects connection and messages behavior, and the process-owned Players capability that reports who is on each server:

plugins {
	java
	id("me.whereareiam.anvil.junit") version "0.0.1"
	id("me.whereareiam.anvil.capability.session") version "0.0.1"
	id("me.whereareiam.anvil.capability.messages") version "0.0.1"
	id("me.whereareiam.anvil.capability.players") version "0.0.1"
	id("me.whereareiam.anvil.platform.paper") version "0.0.1"
}

Keep the repositories, protocol dependency, and anvil configuration from installation. The remaining unit suffixes are movement, inventory, interaction, commands, dialogs, cookies, screen, sounds, and entities. Keep unit versions aligned with Anvil.

Retrieve a capability

In a running test, import me.whereareiam.anvil.capability.messages.Messages and use a connected player:

Messages messages = alice.capability(Messages.class);
messages.chat("hello-from-anvil");

Retrieval fails with CapabilityUnavailableException if the runtime does not supply that capability. Use hasCapability(type) only when absence is an intentional supported branch of the test. If the journey requires messages, let a missing Messages implementation fail rather than silently skipping the assertion.

Anvil selects each player's protocol library before composing its capabilities. Another library needs its own implementations of the capability APIs it supports; the bundled MCProtocol adapters are specific to MCProtocolLib. When the player's worker cannot install a capability, for example because the release lacks a class it needs, retrieval throws CapabilityUnavailableException with that reason while the player's other capabilities keep working.

Add an external capability

Add its consumer wiring artifact to anvilImplementation:

dependencies {
	add("anvilImplementation", "com.example:combat:1.0.0")
}

This coordinate is an example; use the artifact supplied by the capability author. See creating capabilities to publish one yourself.