Fix sound player interface mismatch (minekube#601)

* feat: Add player server entity ID and match check

Co-authored-by: robin.braemer <robin.braemer@web.de>

* Add sound package tests and update player interface

Co-authored-by: robin.braemer <robin.braemer@web.de>

* Refactor sound package to use type assertions for player methods

Co-authored-by: robin.braemer <robin.braemer@web.de>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: robinbraemer

pkg/edition/java/sound/sound.go

@@ -37,14 +37,14 @@ const (
 
 // Player represents a player that can play and stop sounds.
 // This is typically a *connectedPlayer from the proxy package.
+//
+// The Play function uses type assertions to access additional methods
+// (CurrentServerEntityID, CheckServerMatch) that are not part of this
+// interface, allowing API users to pass proxy.Player without requiring
+// those methods in the proxy.Player interface.
 type Player interface {
 	proto.PacketWriter
 	Protocol() proto.Protocol
-	// CurrentServerEntityID returns the entity ID of the player on their current server.
-	// Returns false if the player is not connected to a server.
-	CurrentServerEntityID() (int, bool)
-	// CheckServerMatch checks if the other player is on the same server.
-	CheckServerMatch(other interface{ CurrentServerEntityID() (int, bool) }) bool
 }
 
 // ParseSource parses a sound source from a string.
@@ -110,8 +110,22 @@ func Play(player Player, sound Sound, emitter Player) error {
 		return fmt.Errorf("%w: player is on %s", ErrUISourceUnsupported, player.Protocol())
 	}
 
+	// Type assert to access server entity methods that are not part of the Player interface.
+	// This allows API users to pass proxy.Player without requiring those methods in the interface.
+	type entityIDProvider interface {
+		CurrentServerEntityID() (int, bool)
+	}
+	type serverMatcher interface {
+		CheckServerMatch(other interface{ CurrentServerEntityID() (int, bool) }) bool
+	}
+
+	entityProvider, ok := player.(entityIDProvider)
+	if !ok {
+		return fmt.Errorf("player does not implement required methods for sound playback")
+	}
+
 	// Get target player's entity ID
-	targetEntityID, ok := player.CurrentServerEntityID()
+	targetEntityID, ok := entityProvider.CurrentServerEntityID()
 	if !ok {
 		return ErrNotConnected
 	}
@@ -122,11 +136,20 @@ func Play(player Player, sound Sound, emitter Player) error {
 		// Self emitter
 		emitterEntityID = targetEntityID
 	} else if emitter != nil {
+		// Type assert emitter to entityIDProvider
+		emitterProvider, ok := emitter.(entityIDProvider)
+		if !ok {
+			return ErrInvalidEmitter
+		}
 		// Check if emitter is on the same server
-		if !player.CheckServerMatch(emitter) {
+		matcher, ok := player.(serverMatcher)
+		if !ok {
+			return fmt.Errorf("player does not implement CheckServerMatch")
+		}
+		if !matcher.CheckServerMatch(emitterProvider) {
 			return ErrDifferentServers
 		}
-		emitterEntityID, ok = emitter.CurrentServerEntityID()
+		emitterEntityID, ok = emitterProvider.CurrentServerEntityID()
 		if !ok {
 			return ErrEmitterNotConnected
 		}

pkg/edition/java/sound/sound_test.go

@@ -0,0 +1,39 @@
+package sound
+
+import (
+	"testing"
+
+	"go.minekube.com/gate/pkg/edition/java/proxy"
+)
+
+// TestProxyPlayerImplementsSoundPlayer validates that proxy.Player can be used
+// as sound.Player, which is required for the sound package examples in the docs.
+//
+// This test ensures that the usage pattern shown in the documentation examples
+// (e.g., .web/docs/developers/examples/sound-example-play.go) will compile.
+//
+// The sound.Player interface only requires proto.PacketWriter and Protocol(),
+// which proxy.Player provides through its embedded interfaces. The additional
+// methods (CurrentServerEntityID, CheckServerMatch) are accessed via type
+// assertion to internalPlayer in the implementation.
+func TestProxyPlayerImplementsSoundPlayer(t *testing.T) {
+	// This is a compile-time check: if proxy.Player doesn't implement sound.Player,
+	// this will fail to compile.
+	var _ Player = (proxy.Player)(nil)
+}
+
+// TestSoundPlayWithProxyPlayer validates that sound.Play can accept proxy.Player.
+// This mirrors the usage in the documentation examples where:
+//   player := e.Player()  // returns proxy.Player
+//   sound.Play(player, sound, player)  // should work
+//
+// The function should compile even though proxy.Player doesn't explicitly
+// implement CurrentServerEntityID and CheckServerMatch in its interface.
+// The implementation uses type assertion to internalPlayer to access these methods.
+func TestSoundPlayWithProxyPlayer(t *testing.T) {
+	// This function signature matches what's used in the docs examples.
+	// If this compiles, then the docs examples should also compile.
+	_ = func(player proxy.Player, snd Sound, emitter Player) error {
+		return Play(player, snd, emitter)
+	}
+}