VocalText

A realistic proximity-based chat plugin for Minecraft (Bukkit / Paper). Players can only hear each other if they are close enough — and distant voices become garbled and harder to read.

Features

• Distance-muffled local chat — text degrades as distance increases; beyond the radius, nothing is heard
• Directed whisper (/vt w <player> <message>) — sends a private message to a nearby player; bystanders see only that someone whispered
• Area whisper (/vt w <message>) — like local chat but at a tighter radius
• Shout (/vt shout <message>) — server-wide broadcast for important announcements
• Dead-player ghost channel — dead players can only talk to each other until they respawn
• Spy mode (/vt spy) — admins can listen to all local chat regardless of distance
• Multi-language support — built-in EN / 繁體中文 / 简体中文; switch per-player with /vt lang
• PlaceholderAPI support — placeholders in format strings are expanded if PAPI is installed
• bStats telemetry — anonymous usage statistics

Requirements

Dependency	Version	Type
Paper / Spigot	1.21	Required
PlaceholderAPI	2.11+	Optional

Installation

1. Download the latest VocalText-x.x.x-all.jar from the releases page.
2. Drop the JAR into your plugins/ folder.
3. Restart or reload the server.
4. Edit plugins/VocalText/config.yml to adjust radii, formats, and toggles.

Commands

Command	Description	Permission
/vt w <message>	Whisper to nearby players	—
/vt w <player> <message>	Direct whisper to a specific nearby player	—
/vt shout <message>	Shout server-wide	—
/vt spy [player]	Toggle spy mode for yourself or another player	vocaltext.admin
/vt lang [code|reset]	View or change your display language	—
/vt reload	Reload config and translations	vocaltext.admin
/vt debugchat <distance> <message>	Preview how a message looks at a given distance	vocaltext.admin

Aliases: /vocaltext → /vt

Permissions

Node	Default	Description
vocaltext.admin	op	Access to /vt spy, /vt reload, /vt debugchat

Configuration (config.yml)

# Maximum radius (blocks) for local chat
chatRadius: 50.0

# Gradually replace characters with _ and ? based on distance
enableDistanceMuffleText: true

# Local chat format — supports color codes (&) and PlaceholderAPI
localFormat: "&b[Vocal] &f%player%: &7%message%"

# ── Shout ──────────────────────────────────────────────
enableShoutCommand: true
shoutFormat: "&c[Shout] &f%player%: &c%message%"

# ── Whisper ────────────────────────────────────────────
enableWhisperCommand: true
# Whisper radius = chatRadius × constrictionRatio
constrictionRatio: 0.25
whisperFormat:       "&7[Whisper] &f%player%: &7%message%"
whisperDirectFormat: "&7[→ %target%] &f%player%: &d%message%"
whisperReceiveFormat:"&7[← %player%] &d%message%"
whisperActionFormat: "&8* %player% whispers something to someone nearby..."

# ── Spy ────────────────────────────────────────────────
enableSpy: true
spyFormat: "&8[Spy] %message%"

# ── Dead Chat ──────────────────────────────────────────
enableDeadChat: true
deadChatFormat: "&8[✦ Ghost] &7%player%: &8%message%"

# ── Miscellaneous ──────────────────────────────────────
enableNotifyWhenNoOneHeard: true
noOneHeard: "&cThere's no one heard you..."

Format placeholders

Placeholder	Meaning
%player%	Sender's name
%target%	Recipient's name (whisper only)
%message%	The chat message

PlaceholderAPI placeholders (e.g. %vault_rank%) work in any format string when PAPI is installed.

Language (/vt lang)

Code	Language
en	English
zh_tw	繁體中文
zh_cn	简体中文

Run /vt lang reset to revert to your client's locale.

Custom translations can be added by placing a file named <code>.yml in plugins/VocalText/lang/.

Dead Chat

When a player dies, they are moved to a ghost channel automatically. In this state:

• Their chat is only visible to other dead players.
• Spy-mode admins still see ghost messages.
• On respawn the player is returned to the normal local channel.

Building from Source

git clone <repo>
cd VocalText
./gradlew shadowJar
# JAR is in build/libs/

To deploy directly to a local test server, add deploy.path=C:/path/to/server/plugins to gradle.properties, then run:

./gradlew deployJar

License

MIT — free to use on public or private servers.