59
edits
Changes
mLine 107:
Line 107: − + Line 115:
Line 115: − + − + − + − + Line 159:
Line 159: − + − + Line 225:
Line 225: − + Line 260:
Line 260: − + Line 286:
Line 286: − + Line 321:
Line 321: − + Line 409:
Line 409: − +
no edit summary
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 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''',
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.
Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself.
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
{{Tabs/Code Snippets
|java=
|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
This is, for obvious reasons, redundant, since that capability is also available through
<code>CapabilityItemHandler</code>.
<code>ForgeCapabilities</code>.
=== Exposing a Capability ===
=== Exposing a Capability ===
@Override
@Override
public <T> LazyOptional<T> getCapability(Capability<T> capability, @Nullable Direction direction) {
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)) {
&& (direction == null {{!}}{{!}} direction == Direction.UP {{!}}{{!}} direction == Direction.DOWN)) {
return this.inventoryOptional.cast();
return this.inventoryOptional.cast();
}
}
@Override
@Override
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
public <T> LazyOptional<T> getCapability(Capability<T> cap, @Nullable Direction direction) {
if (cap == CapabilityEnergy.ENERGY) {
if (cap == ForgeCapabilities.ENERGY) {
return optionalStorage.cast();
return optionalStorage.cast();
}
}
EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
EnergyStorage backend = new EnergyStorage(((EnergyBasedBlockEntity) event.getObject()).capacity);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
LazyOptional<IEnergyStorage> optionalStorage = LazyOptional.of(() -> backend);
Capability<IEnergyStorage> capability = CapabilityEnergy.ENERGY;
Capability<IEnergyStorage> capability = ForgeCapabilities.ENERGY;
ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
ICapabilityProvider provider = new ICapabilitySerializable<IntTag>() {
}}
}}
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 ===
=== Accessing a Capability ===
if (targetCapability == null) {
if (targetCapability == null) {
ICapabilityProvider provider = level.getBlockEntity(pos.relative(direction));
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);
cache.put(direction, targetCapability);
targetCapability.addListener(self -> cache.put(direction, null));
targetCapability.addListener(self -> cache.put(direction, null));
As of Forge 1.19.2-43.1.1, there are two ways to register capabilities.
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:
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: