Kzeroko KTM2

Equipment catalog runtime

Define equipment once and derive registration, default resources and reloadable balance from the catalog.

Updated Oct 23, 2026 7 min read

The equipment catalog owns item identity, kind, rarity, icon and default balance. It registers items at startup and supplies default resources in memory. Server datapacks can then override bonuses and storage limits.

What it does

EquipmentAPI in net.kzeroko.isekaiexpansion.api delegates to the implementation under internal.equipment. The implementation types are internal contracts, not extension APIs for other mods.

Collections feed registration, slot tags, default item models, focus low-resolution models and combat-parent resources. No equipment datagen step is required. Recipes remain separately authored. Wands and staves use shared primary models and optional animation profiles.

Runtime model

OwnerResponsibility
EquipmentCatalogLoads equipment/catalog.json, reads its ordered collections and validates definitions before registration.
EquipmentRegistryRegisters immutable item identities and selects the common implementation from kind and concealment data.
EquipmentResources / EquipmentResourcePackBuild cached default resource bytes and prepend them below ordinary packs. Explicit pack resources take precedence; tags merge unless replaced.
EquipmentRuntimeResolves immutable balance snapshots, caches attribute lookups and focus modifiers, and replaces equipped modifiers on successful reload.
EquipmentStorage / SpellStoragePolicyNormalise container limits without rewriting inscriptions, and check binding, formula replacement and casting.
EquipmentNetworking / ClientEquipmentAPISynchronise server balance on join and reload; restore local defaults after leaving a remote server.
EquipmentLightCompatRegisters catalog light declarations through LambDynamicLights’ item-source event on the client. The optional dependency owns light updates.

There is no per-item file read during equipment ticks. Reload preparation resolves the entire snapshot before publication. Publication runs through server lifecycle events; the old bonuses are removed before the new snapshot is installed and reapplied.

Contracts

  • New item IDs, item kinds, rarity, texture paths, base weapon values, light declarations and concealment traits require a restart. Matching catalog content must ship on both sides.
  • Only bonuses and vessel limits use the reloadable format. Missing overrides start from bundled defaults each time. Failed datapack reloads do not publish staged balance.
  • Every focus receives a models/lowres/ icon model. Wands and staves also receive a shared models/item/ parent; explicit resources override these defaults. Focus model profiles select geometry, textures and optional clips, with safe missing-resource fallback.
  • RelicItem.canEquip prevents another copy of the same item from being equipped. Subclasses use canEquipRelic for extra restrictions.
  • hand/relic supplies 2 custom relic slots. Different relics can occupy both slots; the duplicate-item rule still applies.
  • Catalog bonuses use the UUID of the complete Trinkets slot. Gem, curse and item-mastery modifiers use the same slot identity as their seed, including the slot group and index, so repeated slot names do not overwrite enhancements.
  • Storage checks use the full evaluated formula tier. Lower limits leave inscriptions intact; stored order determines which entries remain active. Binding and casting consult the same live profile.
  • ICLootRarity belongs to IsekaiCore. The catalog does not add recommended-level or profession tooltip lines.

Extending it

Add a JSON array to src/main/resources/equipment/collections/<name>.json, then append its name to src/main/resources/equipment/catalog.json. No Java registration list or datagen provider needs a corresponding row.

The index fields are:

FieldTypeDefaultEffect
schema_versionintegerrequiredMust be 2. Other versions fail startup.
collectionsarray<string>requiredOrdered, unique names matching [a-z0-9_]+; each resolves to a collection file.

A complete ring entry looks like this:

[
  {
    "id": "duelist_kestrel_signet",
    "rarity": "RARE",
    "role": "VANGUARD",
    "kind": "RING",
    "icon": {
      "texture": "isekaiexpansion:item/relic/playstyles/duelist_kestrel_signet",
      "size": 50
    },
    "stats": [
      {
        "attribute": "isekaiexpansion:technique",
        "amount": 9,
        "operation": "ADDITION"
      },
      {
        "attribute": "isekaiexpansion:melee_crit_chance",
        "amount": 0.035,
        "operation": "ADDITION"
      },
      {
        "attribute": "isekaiexpansion:shield_break",
        "amount": 8,
        "operation": "ADDITION"
      }
    ]
  }
]
FieldTypeDefaultEffect
idstringrequiredUnique catalog path matching [a-z0-9_]+; registered in isekaiexpansion.
rarityenumrequiredIsekaiCore values: COMMON, UNCOMMON, RARE, EPIC, LEGENDARY, UNIQUE. The last two make the item fireproof.
roleenumrequiredDesign metadata: VANGUARD, BULWARK, MARKSMAN, HUNTER, ARCANIST, CLERIC, PRIEST, UTILITY. Does not impose a profession requirement.
kindenumrequiredRING, PENDANT, BELT, RELIC, SPELLBOOK, WAND, STAFF, MACE, HAMMER. The last four are focuses.
iconobjectrequiredTexture declaration used by the default model and asset checks.
icon.textureidentifierrequiredNamespaced texture without .png, resolved under assets/<namespace>/textures/. Parent traversal is rejected.
icon.sizeintegerrequiredDeclared square texture size, 16–256 pixels. Current batches use 50; resource tests check the actual image.
weaponobjectAbsentRequired only for focuses, prohibited for other kinds.
weapon.damageintegerrequiredNon-negative attack-damage constructor input for the common focus item.
weapon.speednumberrequiredFinite attack-speed modifier above -4.
vesselobjectAbsentRequired for focuses and SPELLBOOK, prohibited for other kinds. Its complete field contract is in the balance-data page.
lightobjectAbsentOptional client light declaration. Absence registers no item light; requires LambDynamicLights. This is startup catalog data, not a balance override.
light.luminanceintegerrequiredLight level 0–15; 0 registers no source. Values outside the range or fractional values fail startup.
light.water_sensitivebooleanfalseMarks the source as extinguished underwater when LambDynamicLights’ water-sensitivity check is enabled. Non-boolean values fail startup.
concealsenumAbsentOnly rings: EAR, HORN, TAIL, WING, OTHER, ALL. Selects the vanity implementation.
statsarray<object>requiredAttribute bonuses; empty is allowed. Duplicate attribute IDs fail validation.
stats[].attributeidentifierrequiredRegistered attribute ID, resolved once per accepted balance snapshot.
stats[].amountnumberrequiredFinite, nonzero signed amount in the attribute’s units or fractional multiplier.
stats[].operationenumrequiredADDITION, MULTIPLY_BASE or MULTIPLY_TOTAL.

Unknown keys, wrong types, duplicate IDs, missing required fields and invalid kind combinations fail startup. An invalid collection prevents partial item registration.

For a luminous staff, add "light": { "luminance": 12, "water_sensitive": false } to its catalog entry. The optional client entrypoint registers these sources again whenever LambDynamicLights rebuilds them. It does not place light blocks or add common-side dependency imports. Test held equipment in both hands; LambDynamicLights controls which item-bearing entities emit light and whether dynamic lighting is enabled.

LambDynamicLights uses the brightest matching item source. A resource pack may add another source, but a dimmer source does not reduce the catalog light. Change the startup catalog declaration to lower or remove that registered source.

Install the transparent PNG at the declared texture path. Add item names through language_assemble/categories/item_trinkets/ and lore through language_assemble/categories/weapon_tooltips/, then run ./gradlew.bat assembleLanguageFiles. Existing catalog implementations supply storage information and the shared lore flow.

The expedition_relics and expedition_grimoires collections use the same registration, slot-tag, model and lore flow. Their art handoff is tools/art/equipment_expansion_20261023/design_cards.json; it records construction, palette, intended playstyle and the difference from an existing neighbour. The runtime reads only the equipment collections.

Verifying

Run ./gradlew.bat compileJava assembleLanguageFiles. Check every new catalog texture exists at its declared size, each item has a name and lore in both languages, and the complete catalog has unique IDs. Equip two different relics with the same gem attribute and confirm both enhancements apply; remove either and confirm the other remains. Check mastery bonuses and matching curse downsides the same way. Confirm a second copy of either relic is rejected. With LambDynamicLights enabled, hold a luminous staff in either hand, switch to a non-luminous item and check that the light follows the held item. Repeat in water for a water-sensitive declaration and with the optional mod absent.

In a development client, equip a relic and a vessel, apply a valid balance override, then reload. Confirm attributes and storage tooltips change on server and client without re-equipping. Reject a malformed override and confirm the previous values remain. Lower the vessel limits, confirm excess inscriptions remain present but cannot cast, then raise the limits and confirm they work again. Check the same cases after reconnecting to a dedicated server.