Capabilities - Revision history

SizableShrimp at 16:08, 2 July 2023

2023-07-02T16:08:25Z

Dpeter99: /* Attaching a Capability */

2023-07-02T10:16:11Z

Attaching a Capability

Dpeter99: /* Working with Capabilities */

2023-07-02T10:08:02Z

Working with Capabilities

Random832: fix code snippet with workaround

2023-03-04T19:49:45Z

fix code snippet with workaround

SizableShrimp: Change back to ForgeCapabilities for cap references since the others are deprecated

2022-09-25T02:31:43Z

Change back to ForgeCapabilities for cap references since the others are deprecated

SizableShrimp: Clean up information about registering cap classes

2022-09-25T02:24:52Z

Clean up information about registering cap classes

Curle: fix factual errors related to ForgeCapabilities vs the capability provider implementations

2022-09-24T19:30:08Z

fix factual errors related to ForgeCapabilities vs the capability provider implementations

Curle: Undo revision 3332 by Nexus-Dino

2022-09-24T19:22:44Z

Undo revision 3332 by Nexus-Dino

Nexus-Dino at 18:07, 24 September 2022

2022-09-24T18:07:56Z

Nexus-Dino: /* The Capability Interface and the Capability Implementation */

2022-09-24T18:06:20Z

The Capability Interface and the Capability Implementation

@@ Line 107: / Line 107: @@
 Both capability providers and users need to be able to provide and access capabilities through a common framework,
-otherwise the idea of dynamic and mod-agnostic system would not really exist. For this reason, both capability providers and
+otherwise the idea of a dynamic and mod-agnostic system 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''' or '''users''',
 need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.

@@ Line 286: / Line 286: @@
 }}
-Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, via etc. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.
+Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, using e.g. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.
 === Accessing a Capability ===

@@ Line 107: / Line 107: @@
 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 idea of dynamic and mod-agnostic system 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''' or '''users''',
 need to work together and with Forge to ensure that the common interface is used sensibly and correctly by all parties.
@@ Line 115: / Line 115: @@
 Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself.
-A <code>Capability</code> can obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.
+A <code>Capability</code> can be obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.
 {{Tabs/Code Snippets

@@ Line 160: / Line 160: @@
 public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
      if (capability == ForgeCapabilities.ITEM_HANDLER
-             && (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
+             && (direction == null {{!}}{{!}} direction == Direction.UP {{!}}{{!}} direction == Direction.DOWN)) {
          return this.inventoryOptional.cast();
+     }

@@ Line 119: / Line 119: @@
 {{Tabs/Code Snippets
 |java=
-public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = CapabilityManager.get(new CapabilityToken<>(){});
+public static Capability<IItemHandler> ITEM_HANDLER = CapabilityManager.get(new CapabilityToken<>(){});
 }}
-The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.
+The above code will let Forge know that the field <code>ITEM_HANDLER</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.
 This is, for obvious reasons, redundant, since that capability is also available through
-<code>CapabilityItemHandler</code>.
+<code>ForgeCapabilities</code>.
 === Exposing a Capability ===
@@ Line 159: / Line 159: @@
 @Override
 public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
-     if (capability == CapabilityItemHandler.ITEM_HANDLER_CAPABILITY
+     if (capability == ForgeCapabilities.ITEM_HANDLER
              && (direction == null || direction == Direction.UP || direction == Direction.DOWN)) {
          return this.inventoryOptional.cast();
@@ Line 225: / Line 225: @@
          @Override
          public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
-             if (cap == CapabilityEnergy.ENERGY) {
+             if (cap == ForgeCapabilities.ENERGY) {
                  return optionalStorage.cast();
+             }
@@ Line 260: / Line 260: @@
      EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
      LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
-     Capability<IEnergyStorage> capability = CapabilityEnergy.ENERGY;
+     Capability<IEnergyStorage> capability = ForgeCapabilities.ENERGY;
      ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
@@ Line 321: / Line 321: @@
      if (targetCapability == null) {
          ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
-         targetCapability = provider.getCapability(CapabilityEnergy.ENERGY, direction.getOpposite());
+         targetCapability = provider.getCapability(ForgeCapabilities.ENERGY, direction.getOpposite());
          cache.put(direction, targetCapability);
          targetCapability.addListener(self -> cache.put(direction, null));
@@ Line 409: / Line 409: @@
 As of Forge 1.19.2-43.1.1, there are two ways to register capabilities.
-==== <code>AutoRegisterCapability</code> annotation ====
+==== AutoRegisterCapability annotation ====
 On Forge 1.19.2-43.1.1 or higher, a quick and easy way to register a capability is by annotating the Capability Interface with <code>@AutoRegisterCapability</code>. This would look like so:

@@ Line 117: / Line 117: @@
 A <code>Capability</code> can obtained at any time using <code>CapabilityManager#get</code>. This takes in an anonymous <code>CapabilityToken</code> to still allow for a soft dependency system while also keeping hold of any generic information needed. As such, you can always obtain a non-null capability.
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 public static Capability<IItemHandler> ITEM_HANDLER_CAPABILITY = CapabilityManager.get(new CapabilityToken<>(){});
-</syntaxhighlight>
+}}
 The above code will let Forge know that the field <code>ITEM_HANDLER_CAPABILITY</code> should be analogous with the <code>IItemHandler</code> capability. Note that this does not mean the capability is accessible or registered. To check if it is, call <code>Capability#isRegistered</code>.
@@ Line 150: / Line 151: @@
 With all of the above in mind, part of a capability provider implementation may be similar to the following snippet:
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 // suppose the presence of a field 'inventory' of type 'IItemHandler'
@@ Line 169: / Line 171: @@
      this.inventoryOptional.invalidate();
+}
-</syntaxhighlight>
+}}
 This possible implementation of a capability provider exposes an <code>IItemHandler</code> capability and restricts
@@ Line 211: / Line 213: @@
 With the above in mind, part of an attaching agent may be similar to the following snippet of code:
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 @SubscribeEvent
 public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
@@ Line 231: / Line 234: @@
      event.addCapability(new ResourceLocation("examplemod", "fe_compatibility"), provider);
+}
-</syntaxhighlight>
+}}
 This example implementation of an attaching agent attaches a <code>IEnergyStorage</code> capability to all
@@ Line 249: / Line 252: @@
 The previous example reworked to use a Persistent Capability Provider may be similar to the following snippet:
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 @SubscribeEvent
 public void onAttachingCapabilities(final AttachCapabilitiesEvent<BlockEntity> event) {
@@ Line 280: / Line 284: @@
      event.addCapabilities(new ResourceLocation("examplemod", "fe_compatibility"), provider);
+}
-</syntaxhighlight>
+}}
 Note that when using capabilities on entities, you should manually invalidate the capability via <code>invalidateCaps()</code>, via etc. <code>PlayerEvent.Clone</code>. This is due to the fact that players are recreated & copied when moving across dimensions, not simply moved.
@@ Line 307: / Line 311: @@
 With the above in mind, part of an user may be similar to the following snippet of code:
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 // note the use of EnumMap, which is much more performant than HashMap for enum keys
 private final Map<Direction, LazyOptional<IEnergyStorage>> cache = new EnumMap<>(Direction.class);
@@ Line 323: / Line 328: @@
      targetCapability.ifPresent(storage -> storage.receiveEnergy(power, false));
+}
-</syntaxhighlight>
+}}
 This example implementation of an user is querying via a <code>BlockEntity</code> the neighboring capability provider
@@ Line 366: / Line 371: @@
 Capability Implementation:
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
-@AutoRegisterCapability
+|java=
 public interface MyCapability {
      String getValue();
@@ Line 386: / Line 391: @@
+     }
+}
-</syntaxhighlight>
+}}
 Note that in this case, only a single implementation is provided.
@@ Line 397: / Line 402: @@
 to those for more information.
-=== Tying it All Together ===
+=== Registering Capabilities ===
 Once all components of a Capability have been created, they must be registered so that the game is aware of the
-capability's presence. The registration requires specifying only the Capability Interface.
+capability's presence. The registration only requires the Capability Interface.
-The registration can be performed by calling the <code>register</code> method within the <code>RegisterCapabilitiesEvent</code> which is fired on the <code>MOD</code> event bus. The
+==== <code>AutoRegisterCapability</code> annotation ====
-registration will also automatically inject the created Capability into all relevant fields and methods: refer to
+On Forge 1.19.2-43.1.1 or higher, a quick and easy way to register a capability is by annotating the Capability Interface with <code>@AutoRegisterCapability</code>. This would look like so:
-[[#Obtaining a Capability|Obtaining a Capability]] for more information.
-An example of registration can be found in the snippet that follows:
+==== RegisterCapabilitiesEvent ====
-<syntaxhighlight lang="java">
+{{Tabs/Code Snippets
 @SubscribeEvent
 public void registerCaps(RegisterCapabilitiesEvent event) {
      event.register(MyCapability.class);
+}
-</syntaxhighlight>
+}}
 === Class Diagram ===