Kzeroko KTM2

Shared wand and staff models

Resource profiles, optional animations and safe fallbacks.

Updated Oct 25, 2026 4 min read

Wands and staves share one GeckoLib renderer. Assets named after the equipment ID load automatically; an optional resource profile selects custom paths or clip names. The equipment catalog continues to own item identity and statistics.

What you are making

Place these resources under assets/isekaiexpansion/, replacing <catalog_id> with the equipment ID:

ResourcePathRequired
Geometrygeo/item/weapons/<catalog_id>.geo.jsonYes
Texturetextures/item/weapons/<catalog_id>.pngYes
Animationanimations/item/weapons/<catalog_id>.animation.jsonNo; uses idle and cast when present

Resolution tries a valid focus_models/<catalog_id>.json profile first, then the matching assets above, then default_wand.json or default_staff.json. The wand default uses calibration_standard_wand; the staff default uses clocktower_staff. The catalog automatically supplies primary shared-parent and low-resolution item models unless a resource pack overrides them. Authored models/item/<catalog_id>.json files control display transforms; GeckoLib geometry belongs in geo/.

Requirements

Model IDs reference baked GeckoLib geometry; texture IDs reference existing PNG resources. Animations are optional. Invalid profiles or incomplete asset pairs log a warning and try the next resolution step. If no valid visuals remain, all perspectives use the low-resolution icon; a missing icon model resolves to the ordinary missing-model placeholder.

Missing-profile substitution happens in ItemRenderer.getModel, so external previews receive the same visible fallback. Valid profiles keep their primary model there; configured low-resolution icons are selected later by render perspective. Iceberg’s detail renderer also requires IsekaiTweaks’ registered client.geckolib.IcebergCustomItemRendererMixin to dispatch valid primary models through GeckoLib.

Steps

  1. Export geometry and texture to the matching paths above.
  2. Add an animation file at the matching path if needed; use idle and cast clip names. Static models need no animation file.
  3. Add the optional profile below only to choose different paths, reuse another model or map different clip names. An explicit profile uses only its declared animation resource.
  4. Reload client resources, then inspect inventory, held, ground and NPC-held rendering while idle and casting.

Declaring it

An optional assets/isekaiexpansion/focus_models/<catalog_id>.json overrides automatic discovery:

{
  "model": "isekaiexpansion:geo/item/weapons/clocktower_staff.geo.json",
  "texture": "isekaiexpansion:textures/item/weapons/clocktower_staff.png",
  "animation": "isekaiexpansion:animations/item/weapons/clocktower_staff.animation.json",
  "idle": "idle",
  "cast": "cast"
}
FieldTypeDefaultContract
modelresource identifierRequiredBaked GeckoLib geometry path including .geo.json.
textureresource identifierRequiredExisting texture path including .png.
animationresource identifierAbsentGeckoLib animation resource; missing resource or clip disables that animation.
idlestringidleOptional looping idle clip name.
caststringcastOptional cast clip name; plays once and holds its last frame until casting ends.

Unknown fields reject the profile and trigger fallback. Idle/cast names alone do not load animations without an animation resource. Cast speed is clip duration divided by the current cast duration, clamped to 0.05–8; idle speed is 1. Players and other Spell Engine cast-process providers use their process duration; base NPCs use their synchronised casting phase and duration.

Profile successes and failures are cached until client resource reload. Each item retains at most 128 animation managers keyed by holder and render perspective; least recently used entries are evicted. World changes and animation-cache replacement clear retained managers. Rendering does not allocate persistent stack animation IDs.

Iceberg detail rendering

IsekaiTweaks owns the Iceberg/GeckoLib bridge. Its IcebergCustomItemRendererMixin scopes the supplied vertex provider across Gecko item rendering; GeoItemRendererMixin keeps GUI geometry, glint and emissive layers on that provider. Iceberg retains control of lighting and flushing. This applies to automatic fallback staves and wands too; changing a fallback texture is not the repair for a black detail preview.

The bridge was compiled against GeckoLib 4.8.3 and IsekaiTweaks 1.20.1-0.4.0. Check a normal item, a fallback focus and an emissive focus in the Iceberg detail view with the target renderer. Compilation does not establish visual acceptance.

Checklist

Check a static wand, an animated staff, a model with only idle, one with only cast, and missing model/texture/animation resources. Confirm matching assets work without a profile, an explicit profile takes priority and an invalid profile still tries the item’s own assets. Confirm fallback remains visible, repeated casts restart correctly, different holders do not share cast state, and changing resource packs refreshes cached results.

src/main/resources/equipment is required startup catalog data. Clocktower Staff now uses the common catalog focus item and reloadable balance pipeline; its old dedicated item and renderer are removed. Do not delete the catalog folder when editing data-pack balance overrides.