From f71efd747e982d18e4af9d5def0a58c982e8bb73 Mon Sep 17 00:00:00 2001
From: Apehum <36326454+Apehum@users.noreply.github.com>
Date: Thu, 21 Nov 2024 12:24:45 +0800
Subject: [PATCH] add info about default player source filters

---
 docs/api/sources.md                            | 10 +++++++++-
 snippets/api/sources/player-remove-filter.java |  6 ++++++
 snippets/api/sources/player-remove-filter.kt   |  3 +++
 3 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 snippets/api/sources/player-remove-filter.java
 create mode 100644 snippets/api/sources/player-remove-filter.kt

diff --git a/docs/api/sources.md b/docs/api/sources.md
index 5ad7953..9e508c8 100644
--- a/docs/api/sources.md
+++ b/docs/api/sources.md
@@ -30,13 +30,21 @@ Entity sources are attached to the entities.
 :::
 
 ### Player source
-Player sources are attached to the players.
+Player source is attached to the player, audio will be played at a certain distance around the player.
 
 ::: code-group
 <<< @/snippets/api/sources/player.java [java]
 <<< @/snippets/api/sources/player.kt{kotlin} [kotlin]
 :::
 
+By default, the player attached to the source can't hear the audio.
+If you want to override this behaviour, you need to remove the first source filter:
+::: code-group
+<<< @/snippets/api/sources/player-remove-filter.java [java]
+<<< @/snippets/api/sources/player-remove-filter.kt{kotlin} [kotlin]
+:::
+You can also remove all filters, but beware that vanish support won't work for this source.
+
 ### Direct source
 Direct sources are attached to a specific player and can only be heard by that player.
 
diff --git a/snippets/api/sources/player-remove-filter.java b/snippets/api/sources/player-remove-filter.java
new file mode 100644
index 0000000..43a7396
--- /dev/null
+++ b/snippets/api/sources/player-remove-filter.java
@@ -0,0 +1,6 @@
+ServerPlayerSource source = /* */;
+
+source.getFilters()
+        .stream()
+        .findFirst()
+        .ifPresent(source::removeFilter);
diff --git a/snippets/api/sources/player-remove-filter.kt b/snippets/api/sources/player-remove-filter.kt
new file mode 100644
index 0000000..29fac72
--- /dev/null
+++ b/snippets/api/sources/player-remove-filter.kt
@@ -0,0 +1,3 @@
+val source: ServerPlayerSource = /* */
+
+source.removeFilter(source.filters.first())
\ No newline at end of file