Line 116: |
Line 116: |
| 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. |
| | | |
Line 186: |
Line 186: |
| | | |
| 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 |
Line 255: |
Line 255: |
| <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 |
Line 282: |
Line 286: |
| }; | | }; |
| | | |
− | event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider); | + | event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider); |
| event.addListener(optionalStorage::invalidate); | | event.addListener(optionalStorage::invalidate); |
| } | | } |
Line 340: |
Line 344: |
| === 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>, |
Line 355: |
Line 359: |
| | | |
| 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"> |
Line 378: |
Line 382: |
| </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 |
Line 525: |
Line 529: |
| 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 |