Changes

m
client -> user
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