| Line 118: |
Line 118: |
| | === Obtaining a Capability === | | === Obtaining a Capability === |
| | | | |
| − | Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object | + | Before being able to work with a capability, it is necessary to obtain an instance of the <code>Capability</code> object itself. |
| − | 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'''.
| |
| − | | |
| − | ==== Getting the Capability ====
| |
| | | | |
| | 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 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. |
| Line 135: |
Line 130: |
| | 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>CapabilityItemHandler</code>. |
| − |
| |
| − | ==== Declaring a Callback ====
| |
| − |
| |
| − | Another option is to declare a callback method, meaning a method that will be called with the value of the desired
| |
| − | <code>Capability</code> once the instance is available. This gives more flexibility since the method may perform a
| |
| − | number of arbitrary actions with the received instance prior to storing it in a field, or may even discard the
| |
| − | capability entirely if wanted. Nevertheless, the usage of a field instead of a method is encouraged as a matter of
| |
| − | style.
| |
| − |
| |
| − | To use a method as a callback, the method must be declared as <code>static</code> and accepting a single parameter of
| |
| − | type <code>Capability<T></code>, where <code>T</code> represents the capability interface. The method should also
| |
| − | be annotated with <code>@CapabilityInject(T.class)</code>.
| |
| − |
| |
| − | For a more practical example, consider the following snippet:
| |
| − |
| |
| − | <syntaxhighlight lang="java">
| |
| − | public static Capability<IEnergyStorage> ENERGY = null;
| |
| − |
| |
| − | @CapabilityInject(IEnergyStorage.class)
| |
| − | private static void onEnergyStorageInit(Capability<IEnergyStorage> capability) {
| |
| − | LOGGER.info("Received IEnergyStorage capability '{}': enabling Forge Energy support", capability);
| |
| − | ENERGY = capability;
| |
| − | }
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | The above code declares a callback method that will be invoked when a <code>Capability</code> instance for
| |
| − | <code>IEnergyStorage</code> is available. The callback then prints a log message and stores the capability into a
| |
| − | <code>public</code> field for accessibility. The field is initialized to <code>null</code> to provide a reasonable
| |
| − | fallback in case the capability does not exist.
| |
| − |
| |
| − | This callback is, for obvious reasons, redundant, since that capability is also available through
| |
| − | <code>CapabilityEnergy</code>.
| |
| | | | |
| | === Exposing a Capability === | | === Exposing a Capability === |