Effective Instruments v1.2.1: Hardening, performance, and UX improvements

Address 24 findings from full code review: fix logout effect cleanup,
add packet rate limiting, clamp JSON amplifiers, cache pet allowlist and
enabled presets, optimize tick handler to iterate only active musicians,
add effect listing to tooltips, add button row wrapping, validate aura
IDs, add file size limits, fix compact icon overflow, update tests and
docs. Also includes v1.2.0 textures and icon generation tool.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: otectus

CHANGELOG.md

@@ -2,24 +2,58 @@
 
 All notable changes to Effective Instruments will be documented in this file.
 
+## [1.2.1] - 2026-03-26
+
+### Bug Fixes
+- Fixed player logout not cleaning up aura effects on buffed targets in abrupt disconnection scenarios
+- Fixed effect cleanup incorrectly stripping long-duration effects from other sources (e.g. beacons) that matched the aura's amplifier — now also checks remaining duration
+- Fixed `onInstrumentClose` bypassing debug logging when clearing aura selection
+- Fixed compact mode icon (16px) overflowing the 14px button — icon now scales to fit
+
+### Security & Hardening
+- Added 5-tick (~250ms) rate limiting on `SelectAuraC2SPacket` and `InstrumentOpenC2SPacket` to prevent packet spam
+- Effect amplifiers in aura JSON files are now clamped to 0–4 (Level I–V) with a warning if exceeded
+- Aura JSON files over 64KB are skipped with a warning to guard against maliciously large files
+- Aura IDs derived from filenames are validated against `[a-z0-9_]+` — non-conforming files are skipped
+- Suspicious instrument IDs from unknown namespaces are logged at WARN level
+
+### Performance
+- Pet entity allowlist is now cached statically instead of being re-parsed every tick interval per musician
+- Tick handler now iterates only active musicians instead of all players in the level
+- Enabled presets list is pre-computed on load instead of being rebuilt on every call
+
+### Improvements
+- Aura button tooltips now show actual effects with levels (e.g. "Speed I, Regeneration I")
+- Aura selector buttons now wrap into multiple rows when total width exceeds 60% of screen width
+- Replaced misleading `ConcurrentHashMap` with `HashMap` (all access is on the main server thread)
+- Documented dimension-change cleanup limitation (effects expire naturally within 13 seconds)
+- Updated test data from obsolete aura names to current v1.2.0 names
+- Added link to INSTRUMENT_AURAS.md design reference in README
+- Added server admin note in README about disabling Smoky Allure's Hero of the Village effect
+
 ## [1.2.0] - 2026-03-23
 
 ### Features
-- **Instrument-specific auras:** Each instrument can have its own aura (or set of allowed auras) configured via `config/effective_instruments/instrument_auras.json`. The selector only shows auras allowed for the current instrument.
+- **15 unique instrument auras** replacing the original 4 generic presets — each instrument now has its own thematic aura (Zephyr's Blessing, Warcry Cadence, Moonlit Passage, Smoky Allure, Ghost Flame, and more)
+- **Instrument-specific aura filtering:** Each instrument can have its own set of allowed auras configured via `config/effective_instruments/instrument_auras.json`. The selector only shows auras allowed for the current instrument.
+- **All EMI Note Block Instrument variants mapped** — all 16 variants (basedrum, bass, bell, bit, chime, etc.) now have assigned auras instead of showing all auras
 - **Per-instrument aura memory:** Manual aura overrides are remembered per-instrument within the session (forgotten on logout)
 - **`/effectiveinstruments status [player]`** command to view aura state (selected aura, instrument, active status, buffed target count)
 - CI workflow for automated builds via GitHub Actions
 - Unit test scaffolding with JUnit 5
 
 ### Changes
 - **Aura selection now clears when closing an instrument** (previously persisted across close/reopen). The instrument-specific default will auto-select on next open.
+- **Old aura presets replaced:** Soothing Hymn, Invigorating March, Guardian Chorus, and Luminous Nocturne have been replaced by 15 instrument-specific auras. Existing installs keep their old files (marker-based generation).
 - Network protocol bumped to version 3 (clients and servers must use matching mod versions)
 - `/effectiveinstruments reload` now also reloads instrument-aura mappings and reports mapping count
+- Server-side validation: players can only select auras allowed for their current instrument
 
 ### Technical
 - New `InstrumentOpenC2SPacket`: client sends instrument ID to server when opening an instrument screen
 - New `SyncAuraSelectionS2CPacket`: server syncs auto-selected aura back to client
 - `NoteActivityHandler` now captures instrument ID from note metadata as a fallback
+- `InstrumentAuraMapping` supports both string shorthand and object form (with `default` + `allowed` list)
 
 ## [1.1.0] - 2026-03-23
 

CURSEFORGE_DESCRIPTION.md

@@ -1,32 +1,53 @@
 # Effective Instruments
 
-**Play music. Empower allies.** Effective Instruments adds a magical aura system to [Genshin Instruments](https://www.curseforge.com/minecraft/mc-mods/genshin-instruments), letting musicians grant potion effects to nearby players and tamed pets while they perform. Pick an aura, play your instrument, and watch enchanted music notes drift outward as your allies receive buffs.
+**Play music. Empower allies.** Effective Instruments adds a magical aura system to [Genshin Instruments](https://www.curseforge.com/minecraft/mc-mods/genshin-instruments), letting musicians grant potion effects to nearby players and tamed pets while they perform. Every instrument has its own unique aura — pick up a Windsong Lyre and feel the breeze quicken your step, or pound the Glorious Drum to steel your allies for battle.
 
 ---
 
 ## How It Works
 
 1. **Open any instrument** from Genshin Instruments (or Even More Instruments).
-2. **Select an aura** from the icon buttons that appear in the top-right corner of the instrument screen.
+2. **Your instrument's aura auto-selects.** Each instrument has a default aura mapped to it — no manual selection needed.
 3. **Start playing.** As long as you're actively playing notes, your aura applies its potion effects to all valid targets within range. Colored music note particles float outward to show the aura's reach.
-4. **Stop playing** and the aura deactivates after a short grace window (configurable, default 5 seconds). Effects are applied with a set duration and will naturally expire on their own.
+4. **Stop playing** and the aura deactivates after a short grace window (configurable, default 5 seconds). Effects will naturally expire on their own.
+5. **Close the instrument** and the aura clears. Open the same instrument again and it remembers your last selection for that session.
 
-Switching to a different aura **immediately clears** the previous aura's effects from all targets before the new one kicks in — no stacking exploits, clean transitions.
+If an instrument has multiple allowed auras, use the selector buttons in the top-right corner of the instrument screen to switch between them.
 
 ---
 
-## Built-In Auras
+## Instrument Auras
 
-Effective Instruments ships with four aura presets out of the box:
+Every instrument ships with its own unique, thematic aura:
 
-| Aura | Effects | Color |
+### Genshin Instruments
+
+| Instrument | Aura | Effects |
+|---|---|---|
+| **Windsong Lyre** | Zephyr's Blessing | Speed I |
+| **Vintage Lyre** | Echoes of Antiquity | Regeneration I |
+| **Floral Zither** | Bloom Veil | Absorption I + Saturation I |
+| **Glorious Drum** | Warcry Cadence | Strength I + Resistance I |
+| **Nightwind Horn** | Moonlit Passage | Night Vision + Slow Falling |
+| **Ukulele** | Sunkissed Serenade | Luck I |
+| **Djem Djem Drum** | Rhythm of the Earth | Haste I + Jump Boost I |
+
+### Even More Instruments
+
+| Instrument | Aura | Effects |
 |---|---|---|
-| **Soothing Hymn** | Regeneration I | Green |
-| **Invigorating March** | Speed I + Haste I | Orange |
-| **Guardian Chorus** | Resistance I + Absorption I | Blue |
-| **Luminous Nocturne** | Night Vision | Lavender |
+| **Guitar** | Wanderer's Anthem | Speed I + Jump Boost I |
+| **Keyboard** | Harmonic Resonance | Regeneration I + Haste I |
+| **Koto** | Tranquil Current | Water Breathing + Dolphin's Grace |
+| **Pipa** | Silk Road Vigor | Speed I + Strength I |
+| **Saxophone** | Smoky Allure | Hero of the Village I |
+| **Shamisen** | Ghost Flame | Fire Resistance + Strength I |
+| **Trombone** | Bulwark Fanfare | Resistance I + Absorption II |
+| **Violin** | Heartstring Aria | Regeneration I + Absorption I |
+
+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.
 
-Each has its own unique icon in the instrument UI, with a highlighted variant when selected. All four can be freely customized, disabled, or deleted entirely.
+All auras can be freely customized, disabled, or deleted. Add your own by creating new JSON files.
 
 ---
 
@@ -38,7 +59,7 @@ Every aura is defined by a simple JSON file in your config folder:
 config/effective_instruments/auras/
 ```
 
-On first launch, the mod generates the four default aura JSON files and a `_README.txt` reference guide. From there, you have full control:
+On first launch, the mod generates 15 default aura JSON files 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
@@ -83,9 +104,39 @@ Each entry in the `effects` array takes:
 
 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.
 
-### Hot Reload
+---
+
+## Instrument-Aura 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:**
 
-Use the command `/effectiveinstruments reload` (requires operator permission level 2) to reload all aura JSON files without restarting the game. If a player has an aura selected that no longer exists or was disabled after reload, their selection is automatically cleared.
+**String shorthand** — single aura, default and only option:
+```json
+"genshinstrument:windsong_lyre": "zephyrs_blessing"
+```
+
+**Object form** — default aura + additional allowed auras in the selector:
+```json
+"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
+- Use `/effectiveinstruments reload` to apply changes without restarting
+
+---
+
+## Commands
+
+| Command | Permission | Description |
+|---|---|---|
+| `/effectiveinstruments reload` | OP (level 2) | Reload all aura presets and instrument mappings |
+| `/effectiveinstruments status [player]` | OP (level 2) | Show a player's current aura state |
 
 ---
 
@@ -112,7 +163,6 @@ All config files live under a single folder: `config/effective_instruments/`.
 | `includeOtherPlayers` | `true` | Whether other players in range receive effects |
 | `includeTamedPets` | `true` | Whether tamed animals in range receive effects |
 | `petEntityTypeAllowlist` | `[]` | Extra entity type IDs to treat as pets (e.g. `["alexsmobs:crow"]`) |
-| `screenClassAllowlist` | `[]` | Fully-qualified class names for instrument screens from other mods that don't extend Genshin Instruments' `InstrumentScreen` |
 
 ### Client Config (`client.toml`)
 
@@ -122,31 +172,33 @@ All config files live under a single folder: `config/effective_instruments/`.
 | `overlayScale` | `1.0` | Scale factor for overlay buttons (0.5 - 2.0) |
 | `compactMode` | `false` | Use a compact button layout |
 | `particlesMode` | `ALL` | Floating music note particles: `ALL`, `MINIMAL`, or `NONE` |
+| `screenClassAllowlist` | `[]` | Fully-qualified class names for instrument screens from other mods that don't extend Genshin Instruments' `InstrumentScreen` |
 
 ---
 
 ## 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 — green drifting notes for Soothing Hymn, orange for Invigorating March, and so on. They gently rise, drift, pulse in size, and fade out.
+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. The server always sends particle data; the client decides whether to render it.
+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.
 - **Ambient effects:** Aura-applied effects use the ambient flag (subtle swirling particles) to distinguish them from potions and to keep the visual clutter low.
-- **Deselecting:** Clicking the active aura button to deselect lets existing effects expire naturally rather than stripping them immediately.
+- **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
-- **Other instrument mods** — use the `screenClassAllowlist` server config to add support for screens from mods that don't extend `InstrumentScreen`
+- **Even More Instruments** (optional) — all EMI screens extend Genshin Instruments' `InstrumentScreen` and are automatically supported, including all 16 Note Block Instrument variants
+- **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.
 
@@ -163,7 +215,8 @@ Effects from other mods (potion effects, beacons, etc.) are never stripped or ov
 ## Quick Start
 
 1. Install the mod alongside Genshin Instruments.
-2. Open any instrument in-game. You'll see four aura icons in the top-right corner.
-3. Click one to select it, then start playing. Nearby allies will receive the buff.
-4. To customize or add auras, edit the JSON files in `config/effective_instruments/auras/`.
-5. Use `/effectiveinstruments reload` to apply changes without restarting.
+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. To customize auras, edit the JSON files in `config/effective_instruments/auras/`.
+5. To change instrument mappings, edit `config/effective_instruments/instrument_auras.json`.
+6. Use `/effectiveinstruments reload` to apply changes without restarting.