Cardinal Components Item

This module allows mods to attach components to ItemStack instances.

Features

Registration

Item components are registered by an ItemComponentInitializer, exposed as cardinal-components-item in the mod json (more information on the component registration page).

Component factories can be registered to all stacks of a given Item, using its identifier. You can also register a component factory with a Predicate<Item>, which lets you use your own criteria like "implements a specific interface" or "cannot be stacked" (or even to all items, although this is discouraged for performance reasons). Registering a factory using both a predicate and an item ID will cause the latter factory to override the former, letting you eg. use a different implementation for your tools than for others'.

Synchronization

Item components are automatically and systematically synchronized whenever their stack is. The AutoSyncedComponent interface has no effect when the component is attached to a stack.

Ticking

Item components do not support ticking. If you want the stack to change over time, you should store the time it was created/last updated and compute the age when needed.

Emptiness guarantee

Empty item stacks never expose any components, no matter what was originally attached to them. The components will become available again with no loss if the stack stops being empty at any point.

Transient Item Components

In most cases, Item components should store their data in their stack's NBT. Since version 2.7.10 of Cardinal Components API, this is facilitated with the ItemComponent interface.

The following example demonstrates re-implementing the IntComponent interface as defined in Implementing the Component interface as an ItemComponent.

public class ItemIntComponent extends ItemComponent implements IntComponent {
    @Override public int getValue() { return this.getInt("value"); }
    @Override public void increment() { this.putInt("value", this.getValue() + 1); }
}

Hard Item Components

"Hard" item components serialize their data separately. They are more prone to mod incompatibilities and suffer from various quirks that transient item components do not have.

Item components are automatically saved and synchronized with the stack they are attached to, and are copied whenever the stack's NBT is copied (notably in some recipes). They are also factored in the results of all ItemStack equality methods that consider NBT - for this reason, component implementations that get attached to item stacks must define a meaningful equals method!

In development environments, CCA checks that your itemstack components do redefine equals. If you want to disable this behaviour, add -Dcca.debug.noverifyequals=true to your VM options/run arguments.

A note on performance

If you attach a component to a significant amount of stacks, you really need to minimize your component's impact! This can be done by not writing default values in writeToNbt (speeds up serialization and avoids save file bloat), and by implementing CopyableComponent (speeds up stack copies).

A note on component initialization

For performance reasons, item stacks initialize their components lazily, only the first time they are queried. Because of this, components may get displayed clientside before they get initialized serverside. For this reason, ItemStack component initialization must be pure and constant, ie. the initial value of each field must not be random or based on volatile data like stack count or NBT. Failing that can lead to desynchronization, causing clientside item stacks to hold "ghost data" - data that does not match the server's expectations.

public MyItemStackComponent(ItemStack stack) {
    // Bad:
    this.bad0 = Math.random(); // DO NOT DO THIS, DESYNC WILL HAPPEN
    this.bad1 = stack.getCount(); // ALSO BAD, the stack's count may change before the component gets initialized on the server
    // Good:
    this.x = 3;  // Constant value
    this.y = Registry.ITEM.getId(stack.getItem); // cannot change
}

public void init() {
    this.r = Math.random(); // This is fine as long as init() is called outside of the constructor
}

Equality

Stack equality methods areTagsEqual and isEqualIgnoreDamage are modified to check component equality. If you have issues when attaching components to item stacks, it usually means you forgot to implement a meaningful equals check on your component.

Vanilla Alternative: Stack NBT

+ No dependency
+ No setup required, readily available on every stack
+ No overhead whatsoever until the data is actually added
= Automatically synchronized
- Requires a mixin to add data to every created stack
- Must be (de)serialized for every use (can be slow)
- Can only carry raw public data, no private fields, no methods, no interface implementing