README
¶
df-noteblockplayer
A simple Dragonfly-MC plugin that lets players load and play Note Block Studio (.nbs) songs in-game.
What's New?
- The limitation for note keys below F#3 has been resolved. You can now play low-pitched notes without any problem.
- You can now control the note volume using the velocity property (see JSON examples).
- The
PlaySoundmethod has been updated to use direct packet session writing, allowing packets to be sent directly to the player.
Installation
- Import the package, and make sure there is a
noteblockfolder in your project directory:
package main
import (
_ "github.com/redstonecraftgg/df-noteblockplayer"
// other imports
)
- Put your
.nbsfiles or JSON files (you can create these with NoteblockParser) inside thenoteblockfolder.
Usage
You can play songs in two ways:
Using Commands
- To play a song, use
/playnoteblock <your file name>. You can also use/playnbor/pnbas shortcuts. - To stop the song, use
/stopnoteblock. Shortcuts are/stopnband/snb.
Using Functions
You can also play a song from your code with the PlayNoteblock() function:
err := PlayNoteblock(p.H(), "my_song.nbs")
if err != nil {
// handle error
}
To stop a song, you can use the StopNoteblock() function. You can also use the lower-level stopSong(eh *world.EntityHandle) function if needed.
success := StopNoteblock(p.H())
if success {
// The song was successfully stopped
} else {
// No song was playing
}
Known Issues and Limitations
- Playing custom noteblock instruments from resource packs is not yet supported (this feature may be added in a future version).
Documentation
¶
Index ¶
- func FloatVel(val int) float32
- func Floatkey(key int) float32
- func PacketPlaySound(p *player.Player, name string, pitch, volume float32, pos mgl64.Vec3)
- func PitchKey(key int) int
- func PlayNoteblock(eh *world.EntityHandle, filename string) error
- func Pow(base, exp float64) float64
- func StopNoteblock(eh *world.EntityHandle) bool
- type NBSData
- type Note
- type Notes
- type PlayNoteBlockCmd
- type Song
- type StopNoteBlockCmd
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FloatVel ¶ added in v1.1.0
FloatVel converts NBS/JSON note velocity (0-100) to Bedrock/Dragonfly volume [0.0, 1.0]. Values below or equal 0 are muted; above 100 are clamped to 1.0
func Floatkey ¶ added in v1.1.0
Bedrock "note" starts at key 33 (F#3). Each +12 is one octave (double freq/float).
F#3 = 0.5, F#4 = 1.0, F#5 = 2.0, etc.
So, the formulat is: 0.5 * 2^((key-33)/12)
func PacketPlaySound ¶ added in v1.1.0
PacketPlaySound sends a PlaySound packet directly to the player's session connection.
This function takes a player pointer (p), the sound name (name), float32 pitch and volume, and a 3D position (pos, mgl64.Vec3). It first converts the position to [3]float32 as required by the network packet.
Then, using Go reflection and pointer-unsafe tricks, it accesses the unexported player session field "s" and attempts to invoke the "WritePacket" method on it. If not directly available, it tries to extract the connection object (field "conn") and invoke "WritePacket" on that.
Ultimately, this method delivers the PlaySound packet to the player, which makes the sound play at the specified position with the given pitch and volume from the server side. This bypasses higher level APIs and directly calls the underlying session, which is useful for custom, low-level sound triggers in plugins or game logic.
func PitchKey ¶ added in v1.1.0
PitchKey calculates the Bedrock note pitch index based on the NBS note key. Bedrock's base is 33 (F#3).
func PlayNoteblock ¶
func PlayNoteblock(eh *world.EntityHandle, filename string) error
PlayNoteblock is a helper function to programmatically play a song file for a player.
Accepts player handle (EntityHandle) and file name (string, path relative to "noteblock" folder or base folder). Supported formats: ".nbs" (Noteblock Studio), ".json" (custom Song struct).
Returns error if loading or playback fails. Example usage (from any Go function with *player.Player object `p`):
err := PlayNoteblock(p.H(), "my_song.nbs")
if err != nil {
// handle error
}
Note: This helper does not send a chat message to the player! (Unlike the command.)
func StopNoteblock ¶
func StopNoteblock(eh *world.EntityHandle) bool
StopNoteblock is a helper function to stop the currently playing noteblock song for a player.
Accepts player handle (EntityHandle). Returns true if a song was stopped, false if no song was playing.
Example usage (from any Go function with *player.Player object `p`):
success := StopNoteblock(p.H())
if success {
// song stopped
} else {
// no song was playing
}
Types ¶
type NBSData ¶
type NBSData struct {
Version uint8 `json:"version"`
Length uint16 `json:"length"`
Layers uint16 `json:"layers"`
Tempo float32 `json:"tempo"`
Duration float32 `json:"duration"`
Notess []Notes `json:"Notess"`
}
NBSData holds global information as well as all Notes parsed from a NBS file.
type Note ¶
type Note struct {
Tick int `json:"tick"`
Layer int `json:"layer"`
Instrument int `json:"instrument"`
Key int `json:"key"`
Velocity int `json:"velocity,omitempty"`
Panning int `json:"panning,omitempty"`
Pitch int `json:"pitch,omitempty"`
}
Note represents a single note in a noteblock song. It includes properties like tick (time), layer, instrument, key (pitch), velocity, panning, and pitch bend.
type Notes ¶
type Notes struct {
Tick int `json:"tick"`
Layer int `json:"layer"`
Instrument uint8 `json:"instrument"`
Key uint8 `json:"key"`
Velocity uint8 `json:"velocity"`
Panning uint8 `json:"panning"`
Pitch int16 `json:"pitch"`
}
Notes represents a single note event read from the NBS file.
type PlayNoteBlockCmd ¶
type PlayNoteBlockCmd struct {
Filename string `cmd:"filename"`
}
PlayNoteBlockCmd is the command to play a noteblock song (NBS or JSON-based).
func (PlayNoteBlockCmd) AllowConsole ¶
func (PlayNoteBlockCmd) AllowConsole() bool
AllowConsole allows this command from the server console.
type Song ¶
type Song struct {
Tempo float64 `json:"tempo"` // Song tempo (ticks per second)
Length int `json:"length"` // Song length in ticks
Notes []Note `json:"notes"` // Notes
Title string `json:"title,omitempty"` // Optional song title
Author string `json:"author,omitempty"` // Optional song author
Duration float64 `json:"duration,omitempty"` // Calculated song duration (seconds)
}
Song represents the parsed noteblock song file, including meta info and all notes.
type StopNoteBlockCmd ¶
type StopNoteBlockCmd struct{}
StopNoteBlockCmd is the command to stop any currently playing noteblock song for the player.
func (StopNoteBlockCmd) AllowConsole ¶
func (StopNoteBlockCmd) AllowConsole() bool
AllowConsole allows this command from the server console.
Source Files