Interface CommandCause
- All Superinterfaces:
Contextual
,Subject
,SubjectProxy
CommandCause
represents the Cause
of a command, and
also contains utility methods to obtain key information about said cause.
In line with causes used in events, you may assume that the
Cause.root()
(from cause()
) is the direct
invoker of the command, though it should also be noted that the invoker
and intended target of a command may be different, which
will be indicated by entries in the Cause.context()
It is very important to note that no object in the Cause
is guaranteed to be a traditional "command source" - a plugin may invoke a
command without pushing anything to the cause stack and thus the
PluginContainer
of the plugin in question will be the root of the
cause.
In the case of a command being executed as a "proxy", such as a command
block executing a command by virtue of an entity stepping on a pressure
plate, the direct cause will be the command block. However, the player
in question will also be present in the cause stack, allowing command
providers to obtain richer information about the invocation of their command.
This is inline with how Cause
s work in Sponge and its events, for
more information about how Causes work, see the Cause
and
CauseStackManager
javadocs and associated documentation.
The EventContext
that is attached to Cause.context()
may offer other indications as to how the command should
be handled, in addition to using the provided cause stack:
EventContextKeys.AUDIENCE
, which indicates the where messages that should be sent back to the invoker should be sent to (typically messages indicating the status of the command execution);EventContextKeys.SUBJECT
, which indicates the subject that should be subjected to any permission checks;EventContextKeys.LOCATION
, which indicates the location that the command should be assumed to be executed around;EventContextKeys.ROTATION
, which indicates the rotation that the command should assume the target has; andEventContextKeys.BLOCK_TARGET
, which indicates the block that the command should take into account when executing.
This object acts as a Subject
, and simply redirects all calls
inherited by this interface to the subject returned by subject()
.
There are utility methods on this interface that provide hints as to what
the implementation will select for different tasks, for example, the
implementation will use the result of subject()
for permission
checks. Third party command consumers are under no obligation to use these
utility methods as all methods obtain their information from the
Cause
.
No method on this interface, apart from cause()
, should
be taken a guarantee of what may be present, however, they indicate what
typically would be of interest to command API consumers.
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptiondefault Optional
<?> all()
default <T> List
<T> audience()
Gets theAudience
that should be the target for any messages sent by the command (by default).default Optional
<?> cause()
Gets theCause
of the command invocation.default boolean
default boolean
containsType
(Class<?> target) default EventContext
context()
default Cause
Get the cause describing the current state of this subject.static CommandCause
create()
Creates aCommandCause
from the currentCause
.default <T> Optional
<T> default <T> Optional
<T> location()
Gets theServerLocation
that this command is associated with.default Object
root()
rotation()
Gets theVector3d
rotation that this command is associated with.void
sendMessage
(Identified source, Component message) Sends a message to theAudience
as given byaudience()
.void
sendMessage
(Identity source, Component message) Sends a message to theAudience
as given byaudience()
.void
sendMessage
(Component message) Sends a system message to theAudience
as given byaudience()
.subject()
Get theSubject
that will be selected for permission checks during command execution (by default).Returns the target blockServerLocation
, if applicable.Methods inherited from interface org.spongepowered.api.service.permission.SubjectProxy
associatedObject, asSubjectReference, containingCollection, friendlyIdentifier, hasPermission, hasPermission, hasPermission, identifier, isChildOf, isChildOf, isChildOf, isSubjectDataPersisted, option, option, option, parents, parents, parents, permissionValue, permissionValue, permissionValue, subjectData, transientSubjectData
-
Method Details
-
create
Creates aCommandCause
from the currentCause
.- Returns:
- The
CommandCause
-
cause
Cause cause()Gets theCause
of the command invocation.- Returns:
- The cause of the invocation.
-
contextCause
Description copied from interface:Contextual
Get the cause describing the current state of this subject.This is often not based on current game state, but rather the last known state of this subject. If a subject refers to a game object that is not active in the world, the cause may be a global cause.
- Specified by:
contextCause
in interfaceContextual
- Specified by:
contextCause
in interfaceSubject
- Specified by:
contextCause
in interfaceSubjectProxy
- Returns:
- the active cause
-
context
- Returns:
- The event context
- See Also:
-
root
- Returns:
- The root object cause for this cause
- See Also:
-
first
- Type Parameters:
T
- The type of object being queried for- Parameters:
target
- The class of the target type- Returns:
- The first element of the type, if available
- See Also:
-
last
- Type Parameters:
T
- The type of object being queried for- Parameters:
target
- The class of the target type- Returns:
- The last element of the type, if available
- See Also:
-
before
- Parameters:
clazz
- The class of the object- Returns:
- The object
- See Also:
-
after
- Parameters:
clazz
- The class to type check- Returns:
- The object after, if available
- See Also:
-
containsType
- Parameters:
target
- The object to check if it is contained- Returns:
- True if the object is contained within this cause
- See Also:
-
contains
- Parameters:
object
- The object to check if it is contained- Returns:
- True if the object is contained within this cause
- See Also:
-
allOf
- Type Parameters:
T
- The type of objects to query for- Parameters:
target
- The class of the target type- Returns:
- An immutable list of the objects queried
- See Also:
-
noneOf
- Parameters:
ignoredClass
- The class of object types to ignore- Returns:
- The list of objects not an instance of the provided class
- See Also:
-
all
- Returns:
- An immutable list of all the causes
- See Also:
-
subject
Subject subject()Get theSubject
that will be selected for permission checks during command execution (by default).The
Subject
will be selected in the following way from theCause
incause()
:- The
EventContextKeys.SUBJECT
, if any - The first
Subject
in theCause
- The
SystemSubject
if no subject exists within the cause
This subject may present a different view of default context than calls to
Subject
methods directly on this cause.Note: while it might be tempting to use this as the invoker of the command, the
Cause.root()
and this might be different. Command executors should generally use the root of theCause
as the target of their command.- Specified by:
subject
in interfaceSubjectProxy
- Returns:
- The
Subject
responsible, if any.
- The
-
audience
Audience audience()Gets theAudience
that should be the target for any messages sent by the command (by default).The
Audience
will be selected in the following way from theCause
incause()
:- The
EventContextKeys.AUDIENCE
, if any - An audience containing the first
Audience
in theCause
- The SystemSubject
Audience
Note that this returns a
Audience
and it may not what may be thought of as a traditional entity executing the command. For the object that invoked the command, check theCause.root()
of thecause()
.- Returns:
- The
Audience
to send any messages to.
- The
-
location
Optional<ServerLocation> location()Gets theServerLocation
that this command is associated with.The following are checked in order:
- The
EventContextKeys.LOCATION
, if any targetBlock()
- the location of the first locatable in the
Cause
- Returns:
- The
ServerLocation
, if it exists
- The
-
rotation
Gets theVector3d
rotation that this command is associated with.The following are checked in order:
- The
EventContextKeys.ROTATION
, if any - the rotation of the first
Entity
in theCause
- Returns:
- The
Vector3d
rotation, if it exists
- The
-
targetBlock
Optional<BlockSnapshot> targetBlock()Returns the target blockServerLocation
, if applicable.The following are checked in order:
- The
EventContextKeys.BLOCK_TARGET
, if any - The first
BlockSnapshot
in theCause
- Returns:
- The
BlockSnapshot
if applicable, or an empty optional.
- The
-
sendMessage
Sends a system message to theAudience
as given byaudience()
.- Parameters:
message
- The message to send- See Also:
-
sendMessage
Sends a message to theAudience
as given byaudience()
.- Parameters:
source
- TheIdentified
to send a message from.message
- The message to send.- See Also:
-
sendMessage
Sends a message to theAudience
as given byaudience()
.- Parameters:
source
- TheIdentity
to send a message from.message
- The message to send.- See Also:
-