Capabilities/Attaching - Revision history

ChampionAsh5357: Update to 1.18

2022-01-12T13:52:03Z

Update to 1.18

ChampionAsh5357: 37.0.42 update

2021-08-20T20:08:28Z

37.0.42 update

ChampionAsh5357: Update to 1.17

2021-08-02T20:39:18Z

Update to 1.17

ShrimpBot: Categorize with Category:Data Storage by SizableShrimp#0755

2021-05-19T00:59:47Z

Categorize with Category:Data Storage by SizableShrimp#0755

Unbekannt: Inital Import dokuwiki

2020-10-25T12:22:56Z

Inital Import dokuwiki

New page

As mentioned, attaching capabilities to objects that you have not created can be done using <code>AttachCapabilitiesEvent</code>. The same event is used for all objects that can provide capabilities. <code>AttachCapabilitiesEvent</code> has five valid generic types providing the following events:
* <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>: Fires only for entities.
* <code><nowiki>AttachCapabilitiesEvent<TileEntity></nowiki></code>: Fires only for tile entities.
* <code><nowiki>AttachCapabilitiesEvent<ItemStack></nowiki></code>: Fires only for item stacks.
* <code><nowiki>AttachCapabilitiesEvent<World></nowiki></code>: Fires only for worlds.
* <code><nowiki>AttachCapabilitiesEvent<Chunk></nowiki></code>: Fires only for chunks.

The generic type cannot be more specific than the above types. For example: If you want to attach capabilities to <code>PlayerEntity</code>, you have to subscribe to the <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>, and then determine that the provided object is an <code>PlayerEntity</code> before attaching the capability.

In all cases, the event has a method <code>addCapability</code>, which can be used to attach capabilities to the target object. Instead of adding capabilities themselves to the list, you add capability providers, which have the chance to return capabilities only from certain sides. While the provider only needs to implement <code>ICapabilityProvider</code>, if the capability needs to store data persistently it is possible to implement <code><nowiki>ICapabilitySerializable<T extends INBT></nowiki></code> which, on top of returning the capabilities, will allow providing NBT save/load functions.

For information on how to implement <code>ICapabilityProvider</code>, refer to the [[Capabilities|a Capability]] section.

== Creating Your Own Capability ==
In general terms, a capability is declared and registered through a single method call to <code><nowiki>CapabilityManager#INSTANCE#register</nowiki></code>. One possibility is to define a static <code><nowiki>register</nowiki></code> method inside a dedicated class for the capability, but this is not required by the capability system. For the purpose of this documentation we will be describing each part as a separate named class, although anonymous classes are an option.
<syntaxhighlight lang="java">
CapabilityManager.INSTANCE.register(capability_interface_class, storage, default_implementation_factory);
</syntaxhighlight>
The first parameter to this method, is the type that describes the capability feature. In our example, this will be <code>IExampleCapability.class</code>.

The second parameter is an instance of a class that implements <code><nowiki>Capability.IStorage<T></nowiki></code>, where T is the same class we specified in the first parameter. This storage class will help manage saving and loading for the default implementation, and it can, optionally, also support other implementations.
<syntaxhighlight lang="java">
private static class Storage
implements Capability.IStorage<IExampleCapability> {

@Override
public INBT writeNBT(Capability<IExampleCapability> capability, IExampleCapability instance, Direction side) {
// return an NBT tag
}

@Override
public void readNBT(Capability<IExampleCapability> capability, IExampleCapability instance, Direction side, INBT nbt) {
// load from the NBT tag
}
}
</syntaxhighlight>
The last parameter is a callable factory that will return new instances of the default implementation.
<syntaxhighlight lang="java">
private static class Factory implements Callable<IExampleCapability> {

@Override
public IExampleCapability call() throws Exception {
return new Implementation();
}
}
</syntaxhighlight>
Finally, we will need the default implementation itself, to be able to instantiate it in the factory. Designing this class is up to you, but it should at least provide a basic skeleton that people can use to test the capability, if it’s not a fully usable implementation on itself.

== Persisting Chunk and TileEntity capabilities ==
Unlike <code>Worlds</code>, <code>Entities</code> and <code>ItemStacks</code>, <code>Chunks</code> and <code>TileEntities</code> are only written to disk when they have been marked as dirty. A <code>capability</code> implementation with persistent state for a <code>Chunk</code> or a <code>TileEntity</code> should therefore ensure that whenever its state changes, its owner is marked as dirty.

<code>ItemStackHandler</code>, commonly used for inventories in <code>TileEntities</code>, has an overridable method <code><nowiki>void onContentsChanged(int slot)</nowiki></code> designed to be used to mark the <code>TileEntity</code> as dirty.
<syntaxhighlight lang="java">
public class MyTileEntity extends TileEntity {

private final IItemHandler inventory = new ItemStackHandler(...) {
@Override
protected void onContentsChanged(int slot) {
super.onContentsChanged(slot);
markDirty();
}
}

...
}
</syntaxhighlight>
== Synchronizing Data with Clients ==
By default, Capability data is not sent to clients. In order to change this, the mods have to manage their own synchronization code using packets.

There are three different situation in which you may want to send synchronization packets, all of them optional:
# When the entity spawns in the world, or the block is placed, you may want to share the initialization-assigned values with the clients.
# When the stored data changes, you may want to notify some or all of the watching clients.
# When a new client starts viewing the entity or block, you may want to notify it of the existing data.

Refer to the [[Understanding Networking|Networking]] page for more information on implementing network packets.

== Persisting across Player Deaths ==
By default, the capability data does not persist on death. In order to change this, the data has to be manually copied when the player entity is cloned during the respawn process.

This can be done by handling the <code><nowiki>PlayerEvent.Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.

@@ Line 53: / Line 53: @@
 By default, the capability data does not persist on death. In order to change this, the data has to be manually copied when the player entity is cloned during the respawn process.
-This can be done by handling the <code><nowiki>PlayerEvent$Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
+This can be done by handling the <code><nowiki>PlayerEvent$Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>#isWasDeath</code> method can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
 [[Category:Data Storage]]

← Older revision		Revision as of 00:59, 19 May 2021
Line 79:		Line 79:

	This can be done by handling the <code><nowiki>PlayerEvent.Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.		This can be done by handling the <code><nowiki>PlayerEvent.Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
		+
		+
		+	[[Category:Data Storage]]

@@ Line 13: / Line 13: @@
 == Creating Your Own Capability ==
-In general terms, a capability is declared and registered through a single method call to <code><nowiki>CapabilityManager#INSTANCE#register</nowiki></code>. One possibility is to define a static <code><nowiki>register</nowiki></code> method inside a dedicated class for the capability, but this is not required by the capability system.
+In general terms, a capability is registered through the event <code><nowiki>RegisterCapabilitiesEvent</nowiki></code> on the <code>MOD</code> event bus via the <code>#register</code> method.
 <syntaxhighlight lang="java">
-CapabilityManager.INSTANCE.register(IExampleCapability.class);
+@SubscribeEvent
 </syntaxhighlight>

@@ Line 1: / Line 1: @@
 As mentioned, attaching capabilities to objects that you have not created can be done using <code>AttachCapabilitiesEvent</code>. The same event is used for all objects that can provide capabilities. <code>AttachCapabilitiesEvent</code> has five valid generic types providing the following events:
 * <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>: Fires only for entities.
-* <code><nowiki>AttachCapabilitiesEvent<TileEntity></nowiki></code>: Fires only for tile entities.
+* <code><nowiki>AttachCapabilitiesEvent<BlockEntity></nowiki></code>: Fires only for block entities.
 * <code><nowiki>AttachCapabilitiesEvent<ItemStack></nowiki></code>: Fires only for item stacks.
-* <code><nowiki>AttachCapabilitiesEvent<World></nowiki></code>: Fires only for worlds.
+* <code><nowiki>AttachCapabilitiesEvent<Level></nowiki></code>: Fires only for levels.
-* <code><nowiki>AttachCapabilitiesEvent<Chunk></nowiki></code>: Fires only for chunks.
+* <code><nowiki>AttachCapabilitiesEvent<LevelChunk></nowiki></code>: Fires only for level chunks.
-The generic type cannot be more specific than the above types. For example: If you want to attach capabilities to <code>PlayerEntity</code>, you have to subscribe to the <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>, and then determine that the provided object is an <code>PlayerEntity</code> before attaching the capability.
+The generic type cannot be more specific than the above types. For example: If you want to attach capabilities to <code>Player</code>, you have to subscribe to the <code><nowiki>AttachCapabilitiesEvent<Entity></nowiki></code>, and then determine that the provided object is an <code>Player</code> before attaching the capability.
-In all cases, the event has a method <code>addCapability</code>, which can be used to attach capabilities to the target object. Instead of adding capabilities themselves to the list, you add capability providers, which have the chance to return capabilities only from certain sides. While the provider only needs to implement <code>ICapabilityProvider</code>, if the capability needs to store data persistently it is possible to implement <code><nowiki>ICapabilitySerializable<T extends INBT></nowiki></code> which, on top of returning the capabilities, will allow providing NBT save/load functions.
+In all cases, the event has a method <code>addCapability</code>, which can be used to attach capabilities to the target object. Instead of adding capabilities themselves to the list, you add capability providers, which have the chance to return capabilities only from certain sides. While the provider only needs to implement <code>ICapabilityProvider</code>, if the capability needs to store data persistently it is possible to implement <code><nowiki>ICapabilitySerializable<T extends Tag></nowiki></code> which, on top of returning the capabilities, will allow providing NBT save/load functions.
 For information on how to implement <code>ICapabilityProvider</code>, refer to the [[Capabilities|a Capability]] section.
 == Creating Your Own Capability ==
-In general terms, a capability is declared and registered through a single method call to <code><nowiki>CapabilityManager#INSTANCE#register</nowiki></code>. One possibility is to define a static <code><nowiki>register</nowiki></code> method inside a dedicated class for the capability, but this is not required by the capability system. For the purpose of this documentation we will be describing each part as a separate named class, although anonymous classes are an option.
+In general terms, a capability is declared and registered through a single method call to <code><nowiki>CapabilityManager#INSTANCE#register</nowiki></code>. One possibility is to define a static <code><nowiki>register</nowiki></code> method inside a dedicated class for the capability, but this is not required by the capability system.
 <syntaxhighlight lang="java">
-private static class Factory implements Callable<IExampleCapability> {
+CapabilityManager.INSTANCE.register(IExampleCapability.class);
 </syntaxhighlight>
-== Persisting Chunk and TileEntity capabilities ==
+== Persisting LevelChunk and BlockEntity capabilities ==
-Unlike <code>Worlds</code>, <code>Entities</code> and <code>ItemStacks</code>, <code>Chunks</code> and <code>TileEntities</code> are only written to disk when they have been marked as dirty. A <code>capability</code> implementation with persistent state for a <code>Chunk</code> or a <code>TileEntity</code> should therefore ensure that whenever its state changes, its owner is marked as dirty.
+Unlike <code>Levels</code>, <code>Entities</code> and <code>ItemStacks</code>, <code>LevelChunks</code> and <code>BlockEntities</code> are only written to disk when they have been marked as dirty. A <code>capability</code> implementation with persistent state for a <code>LevelChunk</code> or a <code>BlockEntity</code> should therefore ensure that whenever its state changes, its owner is marked as dirty.
-<code>ItemStackHandler</code>, commonly used for inventories in <code>TileEntities</code>, has an overridable method <code><nowiki>void onContentsChanged(int slot)</nowiki></code> designed to be used to mark the <code>TileEntity</code> as dirty.
+<code>ItemStackHandler</code>, commonly used for inventories in <code>BlockEntities</code>, has an overridable method <code><nowiki>void onContentsChanged(int slot)</nowiki></code> designed to be used to mark the <code>BlockEntity</code> as dirty.
 <syntaxhighlight lang="java">
-public class MyTileEntity extends TileEntity {
+public class MyBlockEntity extends BlockEntity {
    private final IItemHandler inventory = new ItemStackHandler(...) {
@@ Line 58: / Line 30: @@
      protected void onContentsChanged(int slot) {
        super.onContentsChanged(slot);
-       markDirty();
+       setChanged();
+     }
+   }
@@ Line 69: / Line 41: @@
 There are three different situation in which you may want to send synchronization packets, all of them optional:
-# When the entity spawns in the world, or the block is placed, you may want to share the initialization-assigned values with the clients.
+# When the entity spawns in the level, or the block is placed, you may want to share the initialization-assigned values with the clients.
 # When the stored data changes, you may want to notify some or all of the watching clients.
 # When a new client starts viewing the entity or block, you may want to notify it of the existing data.
@@ Line 78: / Line 50: @@
 By default, the capability data does not persist on death. In order to change this, the data has to be manually copied when the player entity is cloned during the respawn process.
-This can be done by handling the <code><nowiki>PlayerEvent.Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
+This can be done by handling the <code><nowiki>PlayerEvent$Clone</nowiki></code> event, reading the data from the original entity, and assigning it to the new entity. In this event, the <code>wasDead</code> field can be used to distinguish between respawning after death, and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
 [[Category:Data Storage]]