Runic Instruments

[0.9.0] — 2026-04-17

First release under the Runic Instruments name. The mod is a top-to-bottom refactor of Effective Instruments into a Runecraft-native musical magic system.

Rebrand

• Mod ID: effectiveinstruments → runicinstruments
• Package: com.crims.effectiveinstruments → com.crims.runicinstruments
• Vocabulary: "Aura" → "Resonance" throughout classes, commands, and UI
• Command: /effectiveinstruments → /runicinstruments
• Config directory: config/effective_instruments/ → config/runic_instruments/
• Network protocol version bumped to 5 (incompatible with any Effective Instruments build)
• A boot-time hint points users at legacy EI configs so they can migrate

Core systems

• Polymorphic effect system. Resonances accept three effect types:
  • potion — vanilla MobEffect with per-effect amplifier (clamped 0–4)
  • attribute — AttributeModifier with deterministic UUIDs keyed by source + resonance + attribute, so two musicians do not double-apply
  • custom — dispatch to integration-registered action handlers
• Per-effect targeting. Each effect can independently target ALLIES, HOSTILE, SELF, WORLD, or ALL. The resonance-level targetMode is inherited only when an effect omits its own target.
• Strongest-wins potion hand-off. When a musician stops or switches, any potion effect they were applying is re-applied by the next strongest active musician in range before being removed, so party buffs do not flicker when players shuffle.
• Server-authoritative selector sync. SyncInstrumentScreenS2CPacket drives the client UI from server data on every screen open and selection change, including name, description, color, tier, and effect summary.
• Per-instrument mapping. instrument_auras.json restricts which resonances are offered for a given instrument, with a default auto-selected on open.

Progression

• Tier system (1 Apprentice → 4 Legendary), displayed in tooltips and on buttons.
• Advancement-gated unlocks. 75 per-resonance advancement files under data/runicinstruments/advancements/resonances/. Tier-1 resonances are available immediately; tiers 2–4 are gated.
  • Known limitation: every shipped advancement currently uses minecraft:impossible as its criterion. Out of the box, gated resonances are obtainable via Song Scroll loot or /runicinstruments grant. Real trigger criteria and an advancement tree are a 1.0 target.
• Ensemble bonuses. 2+ musicians within 32 blocks scale resonance radius: Duo +25%, Trio +50%, Quartet+ +75%.
• Environmental modifiers. Dawn/dusk adds +2 radius, mountain biomes add +4, thunderstorms multiply by 1.5.

Content

• 90 resonance patterns across 15 instrument families (6 per family, 15 T1 + 30 T2 + 30 T3 + 15 T4).
• Instruments covered: Windsong Lyre, Vintage Lyre, Floral Zither, Glorious Drum, Nightwind Horn, Ukulele, Djem Djem Drum, Guitar, Keyboard, Koto, Pipa, Saxophone, Shamisen, Trombone, Violin. Note Block variants are mapped to their closest thematic family.
• Default resonance JSONs are generated into the config directory on first load and merged on subsequent versions so user overrides survive.

Items

• 4 Rune items (Amplification, Extension, Reach, Persistence) — passive while carried; only one of each type counts.
• Song Scroll — loot-dropped item; right-click to grant the encoded resonance's unlock advancement. Blank scrolls exist for creative/admin use; filled scrolls are what survival players encounter.
• Creative tab — all runes, a blank scroll, and one pre-filled scroll per gated resonance.

Loot

• Song Scroll loot modifiers for: Simple Dungeon, Abandoned Mineshaft, Desert Pyramid, Jungle Temple, Stronghold Library, End City treasure. Chance ranges from 0.15 (mineshaft) to 0.2 (dungeon / end city).

Recipes

• Four rune recipes using vanilla ingredients (paper, amethyst shard, glowstone dust, lapis, etc.). Blank Song Scroll is currently creative/loot-only.

Commands

All require operator permission level 2:

• /runicinstruments reload — reload resonance definitions and mappings
• /runicinstruments status [player] — inspect active resonance state
• /runicinstruments grant <player> <resonance> — force-unlock
• /runicinstruments revoke <player> <resonance> — force-lock

Integrations (optional, reflection-based)

• Ars Nouveau — source_regen replenishes Source mana
• Blood Magic — lp_regen adds to the musician's Soul Network
• Nature's Aura — aura_boost deposits positive aura in the chunk
• MineColonies — colony_morale placeholder (currently applies Regeneration to nearby citizens; full happiness API integration is a 1.0 target)
• Attribute hooks for AttributesLib and Iron's Spells 'n Spellbooks attributes. Missing mods produce a warning log and the effect is skipped.

Client

• Overlay selector widget anchored top-right of the instrument screen, with mouse click, hover tooltips (display name, description, per-effect summary, tier), and locked-state visuals.
• Client config overlayScale, compactMode, showOverlay, particlesMode, and screenClassAllowlist for third-party instrument screen adapters.

Placeholder art

• Item textures. Five 16×16 placeholder PNGs (rune_of_*.png, song_scroll.png) generated by tools/gen_placeholder_textures.py. Replace with commissioned art before 1.0.
• Resonance icons. 90 base + 90 _selected 32×32 placeholder icons and a missing_icon.png fallback. Not yet wired into the selector widget — the client still renders the letter-in-color-box fallback until SyncedResonanceData carries the icon fields and the widget blits them.

Known limitations shipping in 0.9.0

• Advancement criteria are minecraft:impossible (see Progression).
• Resonance icons exist on disk but are not yet blitted by the widget.
• Item textures are simple placeholders.
• Config directory is still named runic_instruments/auras/ and the instrument mapping is instrument_auras.json — rename scheduled for 0.9.1.
• MineColonies colony_morale is a Regeneration placeholder.
• Attribute display text uses raw attribute.getDescriptionId() (shows the translation key rather than a friendly name).
• serendipity_song is spelled serendipty_song in defaults and the corresponding advancement file — fix and migration planned for 0.9.1.

0.9.x → 1.0 punch list

• Wire icon textures through SyncedResonanceData and the selector widget.
• Replace placeholder item textures with commissioned art.
• Rename auras/ → resonances/ and instrument_auras.json → instrument_resonances.json with on-load migration.
• Replace minecraft:impossible advancement criteria with real gameplay triggers; build an advancement tree with displays and parents.
• Fix the serendipty_song typo with a file-rename migration.
• Replace the MineColonies Regeneration placeholder with the real happiness/morale API.
• Expand Song Scroll loot coverage to Trial Chambers, Ancient Cities, Woodland Mansions, and bastion / fortress / village chests.
• Keyboard navigation, scroll, and collision-avoidance on the selector widget.
• Full localization for all 90 resonance names and effect descriptions.

Test & build

• ./gradlew build and ./gradlew test both pass on Java 17 with the Genshin Instruments 5.0 / Even More Instruments 6.1.4 dev dependencies.

Versions 1.0.0–1.2.0 were released as "Effective Instruments" — see git history for the prior changelog.