EffectiveSpigot/ru.hukm.effectiveSpigot.minecraft.additional/AdditionalArgsSupport

AdditionalArgsSupport

Backend that turns the AdditionalArgs declaration into actual persistent-data reads and writes.

It is the glue behind EffectiveItem.getAdditionalArgs / EffectiveEntity.getAdditionalArgs: it parses raw string arguments (from createItemStack(args) / spawnEntity(loc, args) or the /egive and /emob commands) into typed values, stores them on the holder's PersistentDataHolder, and reads them back. You rarely call it directly — the base classes and commands do — but it is public so custom commands or tooling can reuse the same parsing.

Value formats. Each declared key has a PersistentDataType; a raw string is parsed accordingly: scalar types (STRING, BYTE, SHORT, INTEGER, LONG, FLOAT, DOUBLE, BOOLEAN) from a single token, and array types (BYTE_ARRAY, INTEGER_ARRAY, LONG_ARRAY) from a comma-separated list. Unsupported types fail to parse. When read back, values are stringified (arrays comma-joined) so they round-trip through commands and lore.

localeScope. Several methods take a localeScope ("items" or "entities") used only to pick the message key for errors — e.g. errors.items.cannot_parse_additional_arg — so item and entity failures read naturally.

Functions

additionalKey

fun additionalKey(args: AdditionalArgs?, name: String, localeScope: String): NamespacedKey

Resolves the NamespacedKey under which the declared arg name is stored — the key you then pass to EffectiveDataContainerUtils to read a single value from a stack/entity. Validates that name is actually declared in args.

applyToHolder

fun applyToHolder(holder: PersistentDataHolder, args: AdditionalArgs?, rawValues: List<String>, localeScope: String)

Parses rawValues (positional, one per declared key in args) into their PersistentDataTypes and writes each onto holder's persistent-data container under NamespacedKey(plugin, name).

namespacedKeys

fun namespacedKeys(args: AdditionalArgs?): List<Pair<NamespacedKey, PersistentDataType<*, *>>>?

All declared keys resolved to NamespacedKey -> PDC type pairs (in declaration order), or null if args is null. Handy for enumerating every stored parameter without knowing the names up front.

readFromHolder

fun readFromHolder(holder: PersistentDataHolder, args: AdditionalArgs?): List<String>

Reads the declared args values from holder's persistent data and returns them as strings, in declaration order (arrays comma-joined). Returns an empty list if args is null/empty or if any declared key is missing on the holder — i.e. it's all-or-nothing, matching how applyToHolder writes the full set. Useful for showing current values in lore or echoing them back to commands.