14
edits
Changes
mLine 116:
Line 116: − + Line 186:
Line 186: − + Line 255:
Line 255: + + + + Line 282:
Line 286: − + Line 340:
Line 344: − + − + − + Line 355:
Line 359: − + − + − + Line 378:
Line 382: − + Line 525:
Line 529: − +
client -> user
Both capability providers and users need to be able to provide and access capabilities through a common framework,
Both capability providers and users need to be able to provide and access capabilities through a common framework,
otherwise the ideal of dynamic and mod-agnostic would not really exist. For this reason, both capability providers and
otherwise the ideal of dynamic and mod-agnostic would not really exist. For this reason, both capability providers and
capability ''accessors'' (which we define as everything that wants to access a capability), also known as '''clients''',
capability ''accessors'' (which we define as everything that wants to access a capability), also known as '''clients''' or '''users''',
need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.
need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.
Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and
Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and
accessed by clients.
accessed by users.
To do so, a capability provider needs to juggle a couple more moving pieces to ensure that the capability state remains
To do so, a capability provider needs to juggle a couple more moving pieces to ensure that the capability state remains
<code>addListener</code> to check whether the capability should be attached to the current object and perform the
<code>addListener</code> to check whether the capability should be attached to the current object and perform the
desired action.
desired action.
When attaching a capability, the attaching agent should also provide a name in the form of a
<code>ResourceLocation</code>. The name '''must''' be under the attaching agent's namespace, but no restrictions are
placed on the actual name, as long as it is unique inside the given namespace.
Maybe a little counter-intuitively, the process of attaching does not attach a capability nor a capability interface
Maybe a little counter-intuitively, the process of attaching does not attach a capability nor a capability interface
};
};
event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
event.addListener(optionalStorage::invalidate);
event.addListener(optionalStorage::invalidate);
}
}
=== Accessing a Capability ===
=== Accessing a Capability ===
Accessing a Capability is the process by which a client is able to '''query''' a Capability Provider for a specific
Accessing a Capability is the process by which a user is able to '''query''' a Capability Provider for a specific
instance of a capability.
instance of a capability.
This is perhaps the second most important part of the entire capability system, since it is what allows cross-mod
This is perhaps the second most important part of the entire capability system, since it is what allows cross-mod
interaction. To obtain an instance of a Capability, the client must first get a hold of the Capability Provider that
interaction. To obtain an instance of a Capability, the user must first get a hold of the Capability Provider that
should be queried. This can be done in a variety of ways and is outside the scope of this article. The client should
should be queried. This can be done in a variety of ways and is outside the scope of this article. The user should
then invoke the <code>getCapability</code> method passing the unique instance of the capability that should be queried
then invoke the <code>getCapability</code> method passing the unique instance of the capability that should be queried
(see [[#Obtaining a Capability|Obtaining a Capability]] for more information) and the querying <code>Direction</code>,
(see [[#Obtaining a Capability|Obtaining a Capability]] for more information) and the querying <code>Direction</code>,
It is '''highly suggested''' to cache the returned <code>LazyOptional</code> to avoid querying the same provider every
It is '''highly suggested''' to cache the returned <code>LazyOptional</code> to avoid querying the same provider every
time, in order to improve performance. The client should thus register itself to the invalidation listener via the
time, in order to improve performance. The user should thus register itself to the invalidation listener via the
<code>addListener</code> method. This ensures that the client will be able to react to the invalidation of the
<code>addListener</code> method. This ensures that the user will be able to react to the invalidation of the
<code>LazyOptional</code> and remove it from the cache.
<code>LazyOptional</code> and remove it from the cache.
With the above in mind, part of a client may be similar to the following snippet of code:
With the above in mind, part of an user may be similar to the following snippet of code:
<syntaxhighlight lang="java">
<syntaxhighlight lang="java">
</syntaxhighlight>
</syntaxhighlight>
This example implementation of a client is querying via a <code>TileEntity</code> the neighboring capability provider
This example implementation of an user is querying via a <code>TileEntity</code> the neighboring capability provider
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
for an <code>IEnergyStorage</code> capability. Before obtaining the provider, the code performs a cache lookup for the
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
targeted capability. If the check succeeds, then no lookup is performed; if the check fails, the targeted Capability
Much like custom Capabilities, Forge also allows the creation of custom Capability Providers. The main advantage of this
Much like custom Capabilities, Forge also allows the creation of custom Capability Providers. The main advantage of this
is allowing mods to create custom providers for their custom objects, in order to promote not only cross-mod
is allowing mods to create custom providers for their custom objects, in order to promote not only cross-mod
compatibility, but also uniformity in the way clients may interact with different mod APIs.
compatibility, but also uniformity in the way users may interact with different mod APIs.
This section will only give the basic outline of what is necessary to implement a custom Capability Provider: for more
This section will only give the basic outline of what is necessary to implement a custom Capability Provider: for more