#14228·Paper

Add API method to retrieve a Block's associated Instrument

Author: Paulem79Created Sep 1, 2026Updated Sep 9, 2026
Labelsstatus: accepted

Is your feature request related to a problem?

Well, a problem when creating my plugin but there is some workarounds.

Describe the solution you'd like.

Expose a method on BlockData, BlockState, or Block:

java
public interface BlockData {
    /**
     * Gets the {@link Instrument} associated with this block data,
     * as used by note blocks placed above or below it.
     */
    @NotNull
    Instrument getInstrument();
}
java
public interface BlockState {
    /**
     * Gets the {@link Instrument} associated with this block state,
     * as used by note blocks placed above or below it.
     */
    @NotNull
    Instrument getInstrument();
}
java
public interface Block {
    /**
     * Gets the {@link Instrument} associated with this block,
     * as used by note blocks placed above or below it.
     */
    @NotNull
    Instrument getInstrument();
}

Describe alternatives you've considered.

Currently, there is no API to retrieve the Instrument associated with a block or block state (e.g., sand producing SNARE, wood producing BASS, or mob heads producing their respective sound).

When implementing custom block logic, note block emulators, or custom music systems, you'd either:

  1. Maintain an extensive, manual mapping of Material / Tags that breaks or requires updates across Minecraft releases.
  2. Cast to internal implementation classes (CraftBlock) and call NMS methods (getNMS().instrument()).

Since Minecraft's BlockState natively holds an instrument() property, exposing this through the Paper API would be a clean and non-breaking solution ig.

Other

No response