Effective Instruments

Minecraft 版本： 1.20.1

平台： forge

标签： equipment game-mechanics magic

Effective Instruments

Play music. Empower allies. Or curse your enemies. Effective Instruments adds a magical aura system to Genshin Instruments, letting musicians grant potion effects to nearby players and tamed pets while they perform — or, if they pick the negative-polarity variant, inflict debuffs on nearby mobs. Every instrument has its own unique positive and offensive aura — pick up a Windsong Lyre and feel the breeze quicken your step (positive) or call down a howling gale that slows and weakens every foe in range (offensive).

New in 1.4.x:

• Offensive (negative) auras — every instrument gets a mirrored debuff variant (Wither, Poison, Slowness, Blindness, etc.). Pick the red-bordered icon to swap polarities on the fly.
• Instrument durability — instruments now wear out with use (per-instrument NBT durability) and can be repaired on an anvil. Vanilla-style durability bar under every instrument slot. Offensive auras wear instruments out faster.
• 1-to-1 unique auras across 42 instruments. Every GI, EMI (including all 16 note-block variants), and Immersive Melodies instrument has its own distinct positive + offensive pair — 84 unique auras shipped.
• Broad offensive targeting by default — negative auras hit every mob in range except the musician, their own pets, and other players' pets. Admins can flip to fine-grained per-category control if preferred.
• Diagnostics command — /effectiveinstruments diagnose surfaces every gate in the aura pipeline so "why isn't my aura firing?" has a one-command answer.

From 1.3.0: Optional Immersive Melodies support! Walk around playing an IM instrument and receive lighter, passive buffs — no screen needed.

How It Works

Stationary Tier (Genshin Instruments / Even More Instruments)

1. Open any instrument from Genshin Instruments (or Even More Instruments).
2. Your instrument's default positive aura auto-selects. Each instrument has a default aura mapped to it — no manual selection needed.
3. Play a single note and the aura applies immediately to all valid targets in range. Effects refresh as you keep playing; colored music note particles float outward to show the aura's reach.
4. Pick the red-bordered icon in the top-right to switch to the instrument's offensive variant. Non-ambient particles on affected mobs show the debuff landed.
5. Stop playing and the aura deactivates after a short grace window (configurable, default 5 seconds). Effects naturally expire.
6. Close the instrument and the aura clears. Open the same instrument again and it remembers your last selection for that session.

Mobile Tier (Immersive Melodies — optional)

When Immersive Melodies is installed alongside Effective Instruments:

1. Hold an IM instrument and start a melody (autoplay) or use free-play mode.
2. Walk around freely — a passive aura buff applies to you and nearby allies every pulse (default: once per second). Colored music notes float around the musician while the aura is active.
3. Pause or switch instruments — effects linger briefly then clear.
4. Pick the red-bordered icon to swap to the mobile-tier offensive aura for the held instrument.

Mobile auras are deliberately lighter than stationary ones (single effect, shorter range and duration) for balance. If both tiers would apply to the same player, the stationary tier takes precedence by default.

Free-play support shipped in 1.4.3. Opening the IM screen is enough to activate the aura — no autoplay required. (Durability is only charged during autoplay / actual note playback, not while browsing the melody list.)

Instrument Auras

Every instrument ships with its own unique, thematic aura:

Genshin Instruments

Even More Instruments

Note Block Instrument variants (basedrum, bass, bell, etc.) are also mapped to thematically matching auras — see _README_INSTRUMENTS.txt in your config folder for the full list.

Immersive Melodies (mobile passive tier)

All auras can be freely customized, disabled, or deleted. Add your own by creating new JSON files.

Fully Data-Driven Aura System

Every aura is defined by a simple JSON file in your config folder:

config/effective_instruments/auras/

On first launch, the mod generates 84 default aura JSON files (31 stationary positive + 31 stationary offensive + 11 mobile positive + 11 mobile offensive) and a _README.txt reference guide. From there, you have full control:

• Edit any default aura — change its effects, duration, radius, color, name, or description
• Disable an aura by setting "enabled": false — it stays on disk but won't appear in-game
• Delete a default aura file — it won't be regenerated
• Create new auras by adding your own .json files to the folder

Aura JSON Format

{
  "displayName": "Fire Ward",
  "description": "Fire Resistance to nearby allies",
  "color": "FF4400",
  "enabled": true,
  "durationTicks": 200,
  "radius": 12,
  "sortOrder": 10,
  "effects": [
    { "effect": "minecraft:fire_resistance", "amplifier": 0 }
  ]
}

New in 1.3.0: Two optional fields control tier support:

• "tiers" — array of "stationary", "mobile", or both. Defaults to ["stationary"] if omitted, so existing files need no edits.
• "showInSelector" — true/false. Defaults to true for stationary presets, false for mobile-only.

Fields:

Each entry in the effects array takes:

• "effect" — the registry name of the potion effect (e.g. "minecraft:regeneration", "minecraft:speed")
• "amplifier" — effect level minus 1 (0 = Level I, 1 = Level II, etc.)

If icon/iconSelected are omitted, the button displays the first letter of the display name as a fallback — so custom auras don't require any texture work.

Instrument-Aura Mapping

Stationary Mapping

The file config/effective_instruments/instrument_auras.json controls which auras are available for each instrument and which one auto-selects when opened.

Two formats are supported per entry:

String shorthand — single aura, default and only option:

"genshinstrument:windsong_lyre": "zephyrs_blessing"

Object form — default aura + additional allowed auras in the selector:

"genshinstrument:windsong_lyre": {
  "default": "zephyrs_blessing",
  "allowed": ["zephyrs_blessing", "echoes_of_antiquity", "bloom_veil"]
}

• If an instrument is not listed, all enabled auras are shown (backwards-compatible)
• The default aura is always included in the allowed list automatically

Mobile Mapping (new in 1.3.0)

The file config/effective_instruments/mobile_instrument_auras.json maps Immersive Melodies instrument IDs to mobile-tier aura presets. Each entry is a simple string (one aura per instrument, no selector):

"immersive_melodies:flute": "windstep_mobile"

Use /effectiveinstruments reload to apply changes to either mapping without restarting.

Commands

Configuration

All config files live under a single folder: config/effective_instruments/.

Server Config (server.toml)

General settings:

Targeting settings:

Mobile tier settings (new in 1.3.0):

These no-op when Immersive Melodies is not installed.

Client Config (client.toml)

Visual Effects

When an aura is active, colored floating music note particles spawn across the full radius of the aura's effect range. The particles are tinted to match the aura's configured color — teal drifting notes for Zephyr's Blessing, crimson for Warcry Cadence, violet for Moonlit Passage, and so on. They gently rise, drift, pulse in size, and fade out.

Particle rendering is entirely client-side. If particles cause performance issues, use the particlesMode client config option to reduce or disable them.

Smart Buff Handling

• Strongest wins: If a target already has a stronger version of the same effect from another source (e.g. a beacon or potion), the aura won't overwrite it.
• Clean switching: Changing auras instantly strips the old aura's effects from all targets. The mod tracks exactly which effects it applied to which entities and only removes its own.
• Clean close: Closing an instrument clears the aura and strips tracked effects. The instrument's default aura will auto-select next time it's opened.
• Tier precedence: When both stationary and mobile tiers could apply to the same player, stationary wins and suppresses the mobile tier (configurable).
• Ambient effects: Aura-applied effects use the ambient flag (subtle swirling particles) to distinguish them from potions and to keep the visual clutter low.
• Per-instrument memory: If you override the default aura for an instrument, your choice is remembered for that instrument within the session (forgotten on logout).

Compatibility

• Genshin Instruments (required) — all instrument screens are automatically detected
• Even More Instruments (optional) — all EMI screens extend Genshin Instruments' InstrumentScreen and are automatically supported, including all 16 Note Block Instrument variants
• Immersive Melodies (optional, new in 1.3.0) — enables mobile passive tier. No IM classes imported, no reflection, no mixins. When IM is absent the compat layer is a zero-cost no-op
• Other instrument mods — use the screenClassAllowlist client config to add support for screens from mods that don't extend InstrumentScreen

Effects from other mods (potion effects, beacons, etc.) are never stripped or overwritten unless the aura provides a stronger or equal version.

Requirements

• Minecraft 1.20.1
• Forge 47+
• Genshin Instruments 5.0+
• Optional: Even More Instruments 6.0+
• Optional: Immersive Melodies 0.6.0+ (enables mobile tier)

Quick Start

1. Install the mod alongside Genshin Instruments.
2. Open any instrument in-game. Its unique aura auto-selects and the corresponding button appears in the top-right corner.
3. Start playing. Nearby allies will receive the buff.
4. (Optional) Install Immersive Melodies. Hold an IM instrument and start a melody — passive buffs activate automatically.
5. To customize auras, edit the JSON files in config/effective_instruments/auras/.
6. To change instrument mappings, edit the mapping files in config/effective_instruments/.
7. Use /effectiveinstruments reload to apply changes without restarting.