User:TheSilkMiner/Capabilities - Revision history

TheSilkMiner: Redirect to actual page; we don't want to break links that are already bookmarked or shared around

2021-05-06T08:28:58Z

Redirect to actual page; we don't want to break links that are already bookmarked or shared around

Show changes

TheSilkMiner: client -> user

2021-05-06T08:26:12Z

client -> user

TheSilkMiner: Finish Capability docs

2021-05-01T20:40:47Z

Finish Capability docs

Show changes

TheSilkMiner: Add description on how to attach a capability

2021-02-15T14:56:13Z

Add description on how to attach a capability

TheSilkMiner: Finish Capability Exposure documentation

2021-01-10T15:28:44Z

Finish Capability Exposure documentation

TheSilkMiner: Additional edits

2021-01-10T14:52:29Z

Additional edits

TheSilkMiner: Add descriptions for the various Forge provided capabilities

2021-01-10T13:24:40Z

Add descriptions for the various Forge provided capabilities

TheSilkMiner: Reword Terminology section and titles to make more sense

2021-01-08T13:24:28Z

Reword Terminology section and titles to make more sense

TheSilkMiner: Set up structure for the page

2021-01-08T13:15:28Z

Set up structure for the page

TheSilkMiner: Start rewrite of Capability page

2021-01-08T11:34:07Z

Start rewrite of Capability page

@@ Line 116: / Line 116: @@
 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
-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.
@@ Line 186: / Line 186: @@
 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
@@ Line 255: / Line 255: @@
 <code>addListener</code> to check whether the capability should be attached to the current object and perform the
 desired action.
 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);
+}
@@ Line 340: / Line 344: @@
 === 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.
 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
 (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
-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.
-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">
@@ Line 378: / Line 382: @@
 </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
 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
 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

@@ Line 136: / Line 136: @@
 // suppose the presence of a field 'inventory' of type 'IItemHandler'
-private static final LazyOptional<IItemhandler> INVENTORY_OPTIONAL = LazyOptional.of(() -> inventory);
+private final LazyOptional<IItemhandler> inventoryOptional = LazyOptional.of(() -> this.inventory);
 @Override
@@ Line 142: / Line 142: @@
      if (capability == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY
              && (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
-         return INVENTORY_OPTIONAL.cast();
+         return this.inventoryOptional.cast();
+     }
      return super.getCapability(capability, direction); // See note after snippet
@@ Line 150: / Line 150: @@
 protected void invalidateCaps() {
      super.invalidateCaps();
-     INVENTORY_OPTIONAL.invalidate();
+     this.inventoryOptional.invalidate();
+}
 </syntaxhighlight>
@@ Line 161: / Line 161: @@
 === Attaching a Capability ===
 === Accessing a Capability ===

@@ Line 75: / Line 75: @@
 === Obtaining a Capability ===
-Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself. Since these objects are created by Forge and there is only '''one'' unique instance for each capability that may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such instances: '''injecting''' into a field, or a '''callback method'''.
+Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself. Since these objects are created by Forge and there is only '''one''' unique instance for each capability that may exist, this instance cannot be obtained by "common" means. Forge provides two different methods of obtaining such instances: '''injecting''' into a field, or a '''callback method'''.
 ==== Injecting into a Field ====
@@ Line 119: / Line 119: @@
 === Exposing a Capability ===
-Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and accessed by clients. This is simply done by returning a non-empty <code>LazyOptional</code> when the <code>getCapability</code> method of a capability provider gets invoked.
+Exposing a capability is a voluntary act by a capability provider that allows the capability to be discovered and accessed by clients.
 === Attaching a Capability ===

@@ Line 39: / Line 39: @@
 The default capability providers in a Forge environment are: <code>TileEntity</code>, <code>Entity</code>, <code>ItemStack</code>, <code>World</code>, and <code>Chunk</code>. These are all agnostic providers, since they don't mandate any sort of capability persistency requirements. Rather, it is the job of whoever subclasses these providers to deal with either volatile or non-volatile capabilities.
-The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>, <code>IFluidHandler</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.
+The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>, <code>IFluidHandler</code>, <code>IFluidHandlerItem</code>, <code>IEnergyStorage</code>, and <code>IAnimationStateMachine</code>. Each one of these capabilities will be discussed in the corresponding section.
 === <tt>IItemHandler</tt> ===
@@ Line 46: / Line 46: @@
 This effectively '''replaces''' the vanilla interfaces <code>IInventory</code> and <code>ISidedInventory</code>. These interfaces are in fact retained only to allow vanilla code to compile and should not be used in mod code. This extends to anything that implements those vanilla interfaces, such as <code>LockableLootTileEntity</code>.
 === <tt>IFluidHandler</tt> ===
 The <code>IFluidHandler</code> capability refers to the ability for any capability provider to handle and store fluids in one or multiple fluid tanks. It is effectively the equivalent in terms of fluids of the <code>IItemHandler</code> capability.
 === <tt>IEnergyStorage</tt> ===
 The <code>IEnergyStorage</code> capability refers to the ability for any capability provider to store, consume, and produce energy. This capability is the base capability for what's commonly known in the modded world as Forge Energy (or FE), i.e. the energy system most mods use. Its internal design is heavily based on the (now defunct) Redstone Flux Energy API, supporting both a push and pull system.
 == Working with Capabilities ==
 === Exposing a Capability ===
 === Attaching a Capability ===

@@ Line 31: / Line 31: @@
 The wary reader may note that both ''persistent'' and ''agnostic'' providers are represented the same way in code. In fact, the only difference between them comes from pure semantics in how their serialization methods are designed. This will be further discussed in their respective sections.
 == Forge-provided Capabilities and Providers ==
@@ Line 37: / Line 39: @@
 The default capability providers in a Forge environment are: <code>TileEntity</code>, <code>Entity</code>, <code>ItemStack</code>, <code>World</code>, and <code>Chunk</code>. These are all agnostic providers, since they don't mandate any sort of capability persistency requirements. Rather, it is the job of whoever subclasses these providers to deal with either volatile or non-volatile capabilities.
-The default capabilities that forge provides are <code>IItemHandler</code>, <code>IFluidHandler</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.
+The default capabilities that forge provides are represented by the interfaces <code>IItemHandler</code>, <code>IFluidHandler</code>, and <code>IEnergyStorage</code>. Each one of these capabilities will be discussed in the corresponding section.
-=== <code>IItemHandler</code> ===
+The <code>IFluidHandler</code> capability refers to the ability for any capability provider to handle and store fluids in one or multiple fluid tanks. It is effectively the equivalent in terms of fluids of the <code>IItemHandler</code> capability.
-=== <code>IFluidHandler</code> ===
+=== <tt>IEnergyStorage</tt> ===
-=== <code>IEnergyStorage</code> ===
+The <code>IEnergyStorage</code> capability refers to the ability for any capability provider to store, consume, and produce energy. This capability is the base capability for what's commonly known in the modded world as Forge Energy (or FE), i.e. the energy system most mods use. Its internal design is heavily based on the (now defunct) Redstone Flux Energy API, supporting both a push and pull system.
 == Working with Capabilities ==

@@ Line 21: / Line 21: @@
 In the rest of this article, we will refer to these terms frequently, so make sure you are familiar with them.
-* '''Capability''': the ability to perform something; in-code this is represented by the <code>Capability</code> class.
+* '''Capability''': the ability to perform something. In-code this is represented by the <code>Capability</code> class.
-* '''Capability Provider''': something that is able to support capabilities and provides a mean of accessing them; capability providers come in multiple kinds.
+* '''Capability Provider''': something that is able to support capabilities and provides a mean of accessing them. In-code they are represented by implementations of <code>ICapabilityProvider</code>. There are multiple kinds of capability providers:
 ** ''Volatile Provider'': a provider that doesn't persist data to disk; once the provider ceases to exist for any number of reasons, all capability data gets deleted.
-** ''Persistent Provider'': a provider that requires all capabilities to serialize data to disk, in order to persist data even across game restarts.
+** ''Persistent Provider'': a provider that requires all capabilities to serialize data to disk, in order to persist data even across game restarts. They implement the <code>INBTSerializable</code> interface.
-** ''Agnostic Provider'': a provider that isn't neither volatile nor persistent, rather delegates the decision either to the capability directly or to sub-implementations.
+** ''Agnostic Provider'': a provider that isn't neither volatile nor persistent, rather delegates the decision either to the capability directly or to sub-implementations. They also implement the <code>INBTSerializable</code> interface.
 * '''Capability Interface''': the interface that defines the contract of the capability, so what operations the capability exposes.
 * '''Capability Implementation''': one of the possibly many implementations of the capability interface, that actually carries out the work; one of the various implementations may also be considered the '''default capability implementation'''.
 * '''Capability Storage''': the manager that handles loading and storing persistent capabilities data from and to disk, guaranteeing preservation of information; in-code this is represented by an implementation of the <code>Capability.IStorage</code> interface.
 == Forge-provided Capabilities and Providers ==
@@ Line 43: / Line 45: @@
 === <code>IEnergyStorage</code> ===
-== Operating with Capabilities ==
+== Working with Capabilities ==
-=== Exposing ===
+=== Exposing a Capability ===
-=== Attaching ===
+=== Attaching a Capability ===
 == Creating Custom Capabilities ==
 == Code Examples ==

← Older revision		Revision as of 11:34, 8 January 2021
Line 1:		Line 1:
		+	'''Capabilities''' are a Forge system that allows cross-mod interactions by allowing capability ''providers'' to dynamically respect contracts and provide specialized behavior without requiring the implementation of many interfaces or hard dependencies on mods.
		+
		+	== History ==
		+	In an ideal world, all that would be needed for a mod to provide the equivalent of a capability would be implementing an interface. This is in fact how cross-mod interaction used to work prior to the introduction of capabilities.
		+
		+	The real world, though, is often much more complicated: users wanted to be free to combine mods the way they wanted and saw fit, and developers wanted to be able to declare ''soft'' dependencies on other mods, thus reducing the need of having a huge mod pack just for testing.
		+
		+	The first approach used by Forge was conditional stripping of interfaces and methods, but this proved to be problematic. While the idea works well in theory, in practice the ASM editing of classes relied on complex mechanics and could lead to hard to spot bugs.
		+
		+	For this reason, the entire system was redesigned and the concept of '''capabilities''' was born.
		+
		+	== The Concept ==
		+	A capability allows any capability provider to conditionally expose a certain ability to do something, e.g. accepting power or handling items. A capability provider, moreover, can decide to expose a capability only on certain sides, allowing for easy interactions with hoppers, cables, etc.
		+
		+	Capabilities may also be added and removed dynamically both from the "owner" of the capability provider and other mods, allowing even easier cross-mod interaction. For example, a mod that isn't compatible with
		+	Forge Energy could be converted into one by dynamically attaching the Forge Energy capability and handling the conversion to a third-party energy system without having to alter the original mod.
		+
		+	== Terminology ==
		+	The high flexibility of the system comes with a cost, though, which is terminology. The following section wants to be a dictionary of sorts, defining all the terms that you may come across when dealing with capabilities.
		+
		+	* '''Capability''': the ability to perform something; in-code this is represented by the <code>Capability</code> class.
		+	* '''Capability Provider''':
		+
		+
		+
		+	= OLD SHIT FOLLOWS =
		+
		+
	Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.		Capabilities allow exposing features in a dynamic and flexible way, without having to resort to directly implementing many interfaces.