-
Notifications
You must be signed in to change notification settings - Fork 40
Cardinal Components Item
This module allows mods to attach components to ItemStack instances. 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.
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'.
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).
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.
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.
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.
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.
+ 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