VoiceChatAddon

VoiceChatAddon connects players using Simple Voice Chat and Plasmo Voice through a bidirectional proximity voice bridge.

Players can use either supported client mod and still hear nearby players using the other one. The plugin also provides voice-client detection, one-time rewards, PlaceholderAPI statuses and counters, SQLite/MySQL storage, LiteBans mute synchronization and configurable MiniMessage actions.

The bridge connects proximity voice only. It does not merge private groups or channels between Simple Voice Chat and Plasmo Voice.

---

Features

• Bidirectional Simple Voice Chat ↔ Plasmo Voice proximity bridge
• No additional VoiceChatAddon client mod required
• Players only need one supported voice mod
• Preserved speaking distance in both directions
• Simple Voice Chat whisper-distance support
• Bridged distance clamped to 1–128 blocks
• Duplicate audio protection for dual-mod clients
• Independent Simple and Plasmo client detection
• Configurable ANY, BOTH, SIMPLE and PLASMO reward modes
• Separate reward actions for Simple, Plasmo and dual-mod players
• One-time reward claims
• Optional IP-based alt-account protection
• SQLite and MySQL storage
• Standard and relational PlaceholderAPI placeholders
• Online voice-user counters
• Configurable MiniMessage status icons
• Optional LiteBans mute synchronization
• Configurable actions and muted notification cooldown
• Optional Vault economy actions
• Configuration reload command
• Detailed per-player debug report

---

How It Works

Install the Paper versions of Simple Voice Chat and Plasmo Voice on the same backend server and enable both systems in config.yml.

• A Simple Voice Chat player can be heard by nearby Plasmo Voice players.
• A Plasmo Voice player can be heard by nearby Simple Voice Chat players.
• Players using the same voice mod continue to communicate through their original voice system.

Players do not need both client mods. Each player can use their preferred supported voice mod.

---

Voice Bridge

The bridge relays encoded voice frames in both directions:

Simple Voice Chat -> Plasmo Voice
Plasmo Voice -> Simple Voice Chat

The voice frames are forwarded without an additional decode-and-reencode step.

The bridge is enabled when:

• Simple Voice Chat is installed and initialized
• Plasmo Voice is installed and initialized
• SIMPLE and PLASMO are both listed in settings.voiceChats
• settings.bridgeVoiceChats is true
• the Plasmo Voice proximity line and activation are available

settings:
  voiceChats:
    - PLASMO
    - SIMPLE
  bridgeVoiceChats: true

Distance

For Simple Voice Chat speakers, the bridge uses the server's configured voice distance. Whispering uses approximately 33% of that distance.

For Plasmo Voice speakers, the distance from the active proximity packet is preserved.

The final bridged distance is clamped between 1 and 128 blocks.

Duplicate Protection

If a speaker has both supported voice mods, VoiceChatAddon does not relay that speaker through the bridge.

Bridged audio is also filtered for listeners who already receive the original stream through the source voice mod. This prevents duplicate playback and echo.

---

Voice Detection and Rewards

Players can claim a configured reward with:

/voice

The plugin checks the player's available voice clients and executes the matching action list.

Available reward sections:

actions.reward
actions.reward_simple
actions.reward_plasmo
actions.install
actions.noPermsReward

• reward is used when both voice mods are detected.
• reward_simple is used for Simple Voice Chat.
• reward_plasmo is used for Plasmo Voice.
• install is used when the configured reward condition is not met.

Reward Modes

Mode	Required client voice chat
ANY	Simple Voice Chat or Plasmo Voice
BOTH	Both voice mods
SIMPLE	Simple Voice Chat
PLASMO	Plasmo Voice

settings:
  mode: ANY

---

One-Time Claims and Anti-Abuse

Every successful claim is stored with the player's UUID, name, IP address and claim time.

• Each UUID can claim once.
• With antiIPAbuse: true, a different UUID using an already claimed IP address is also blocked.

settings:
  antiIPAbuse: true

Disable IP protection if several legitimate players share one network or if your proxy does not forward real player addresses correctly.

---

Storage

Supported storage types:

SQLITE
MYSQL

SQLite is enabled by default and stores claims in:

plugins/voicechat-addon/storage.db

MySQL example:

settings:
  database:
    type: MYSQL
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "voicechat_addon"
      username: "root"
      password: ""

Database connections are managed through HikariCP.

Changing the storage type or database credentials requires a full server restart.

---

LiteBans Integration

When LiteBans is installed, VoiceChatAddon checks the player's active mute before accepting outgoing voice packets.

Muted players cannot speak through:

• Simple Voice Chat
• Plasmo Voice
• the cross-mod bridge

Incoming voice is not blocked; the integration only prevents the muted player from transmitting.

When a muted player attempts to speak, actions.muted is executed. The action cooldown is configured in milliseconds:

settings:
  mutedActionCooldown: 30000

Mute results are cached briefly to avoid querying the LiteBans database for every audio packet.

---

PlaceholderAPI

PlaceholderAPI is a required dependency.

Placeholder	Result
%voicechataddon_voice%	Configured voice status icon for the player
%voicechataddon_voice_total%	Online players with at least one configured voice mod
%voicechataddon_voice_simple%	Online Simple Voice Chat users
%voicechataddon_voice_plasmo%	Online Plasmo Voice users
%rel_voicechataddon_voice%	Whether the viewer can hear the target player

The relational placeholder returns one of three configurable values:

• available — viewer and target share a voice mod, or the active bridge connects them
• incompatible — target has voice chat, but the viewer cannot hear that voice system
• unavailable — target has none of the configured voice mods

settings:
  voicePlaceholder:
    available: "<#10FA20>●"
    incompatible: "<#FA8B10>●"
    unavailable: "<#EA0909>●"

The values use MiniMessage formatting. Voice status counters are refreshed on voice-state changes and periodically reconciled.

---

Actions

Rewards, install prompts, mute feedback, errors and reload messages are configured as action lists.

Supported action types:

[MESSAGE]
[BROADCAST]
[CONSOLE]
[PLAYER]
[SOUND]
[TITLE]
[ACTIONBAR]
[BOSSBAR]
[PARTICLE]
[FIREWORK]
[EFFECT]
[VAULT]
[CLOSE]

Built-in placeholders:

{prefix}
{player}

PlaceholderAPI values can also be used in action text and commands.

actions:
  reward_simple:
    - "[MESSAGE] {prefix} Reward claimed for Simple Voice Chat"
    - "[SOUND] sound:ENTITY_EXPERIENCE_ORB_PICKUP && volume:1.0 && pitch:1.2"
    - "[CONSOLE] give {player} diamond 3"
  install:
    - "[MESSAGE] {prefix} Install one of the supported voice mods"
  muted:
    - "[ACTIONBAR] <red>You are muted and cannot speak && ticks:100 && updating:false"

[VAULT] actions require Vault and a registered economy provider.

---

Configuration

Main configuration file:

plugins/voicechat-addon/config.yml

Core settings:

settings:
  prefix: "<#FDBE00><bold>SERVER</bold><gray>:<white>"
  antiIPAbuse: true
  voiceChats:
    - PLASMO
    - SIMPLE
  bridgeVoiceChats: true
  mode: ANY
  mutedActionCooldown: 30000
  database:
    type: SQLITE

Use /voice reload after changing normal settings or actions. Restart the server after changing database settings.

---

Commands

Command	Description
/voice	Checks the player's voice mod and processes the one-time reward
/voice reload	Reloads configuration, bridge state and cached voice statuses
/voicechataddon <player>	Displays a detailed debug report for an exact online player

/voice is player-only. The debug command reports detected clients, API state, bridge readiness, connection details and viewer compatibility.

---

Permissions

Permission	Description	Default
voicechat.addon.reload	Allows /voice reload	OP
voicechat.addon.debug	Allows /voicechataddon <player>	OP

The normal /voice reward command does not require a permission.

---

Requirements

• Java 21 or newer
• Minecraft 1.21.x
• Paper 1.21.x or a compatible Paper-based fork
• PlaceholderAPI
• Simple Voice Chat and/or Plasmo Voice

For cross-mod bridging, both voice plugins must be installed on the same backend server.

Optional:

• LiteBans — blocks outgoing voice while a player is muted
• Vault and an economy plugin — enables [VAULT] actions

VoiceChatAddon is built against Simple Voice Chat 2.6.21, Plasmo Voice Paper 2.1.14, PlaceholderAPI 2.12.3 and LiteBans 2.19.0. These are build-time API versions, not a promise that only those exact versions can be used.

---

Installation

1. Install PlaceholderAPI on the backend server.
2. Install the Paper version of Simple Voice Chat, Plasmo Voice, or both.
3. Configure each voice plugin's UDP port and networking according to its documentation.
4. Place VoiceChatAddon.jar into the backend server's plugins folder.
5. Install LiteBans and/or Vault if their integrations are needed.
6. Start or restart the server.
7. Open plugins/voicechat-addon/config.yml.
8. Configure voice systems, reward mode, storage and actions.
9. Restart the server, or use /voice reload for supported configuration changes.

In a Velocity network, VoiceChatAddon still belongs on every Paper backend where its features are needed. It is not a Velocity plugin.

---

Notes

• The bridge connects players on the current backend only; it does not relay audio between backend servers.
• Both server-side voice plugins are required for the bridge, but each player only needs one client mod.
• Only cross-mod proximity voice is provided. Private groups and channels are not merged between the two mods.
• VoiceChatAddon does not open ports, merge UDP transports or configure the firewall.
• Reward claims are permanent and limited to one claim per UUID.
• IP addresses are stored with reward claims. Disable antiIPAbuse if IP-based blocking is not wanted.
• Correct real-IP forwarding is required when IP protection is used behind a proxy.
• Review the bundled reward actions before players can use /voice; the included console commands are server-specific examples.
• A claim is stored before reward actions run, so failed reward commands do not automatically allow another claim.
• Database type and credential changes require a full restart.
• Folia support is not declared.

---

Credits

Voice bridge logic is adapted from PfauMC/voice-bridge under the MIT License.