VoiceWall Acoustic Engine

VoiceWall Acoustic Engine

The VoiceWall Acoustic Engine calculates realistic sound occlusion, material attenuation, aperture diffraction, and distance air damping in real time between speaking and listening players across both Paper / Purpur and Fabric.

---

Acoustic Physics & Raycasting

When a player speaks, DreamVoice evaluates the acoustic path between the speaker's vocal tract and the listener's ears:

Speaker (Mouth) ───[ Raycast Line-of-Sight ]───> Listener (Ears)
                          │
                   (Solid Wall Encountered)
                          │
                          ├──> Tier 1: Material Attenuation (dB accumulation)
                          └──> Tier 2: Aperture Diffraction (bypassing doors/windows)

1. Direct Line-of-Sight (LOS)

The engine casts spatial rays between head positions. If blocks intersect the path:

• In REALISTIC mode: The attenuation of each block is accumulated based on material categories and thickness.
• In STRICT_BLOCK mode: Any solid block instantly marks the direct path as soundproof, handing over to aperture diffraction.

2. Aperture Diffraction

If direct line of sight is obstructed, the diffraction system casts secondary lateral rays to find adjacent openings (such as open or closed doors, windows, and corridors).

• Sound bends around the obstacle with an attenuation penalty (doorLoss or openAirLoss).
• If a valid diffraction path is found within maxPathDistance, the listener hears the audio realistically emanating from the aperture direction.

3. Atmospheric Air Damping

Over longer distances, air absorbs high-frequency sound energy faster than low-frequency rumble. When airDamping is active, distant audio sounds naturally warmer and muffled rather than simply quieter.

---

Acoustic Visualizer & Debugger

DreamVoice provides two distinct visual diagnostic tools:

1. Acoustic Visualizer Mode (/voice visualizer)

• Renders real-time 3D particle rays illustrating active audio transmission paths, wall collisions, diffraction bypasses, and 3D speaker audible spheres.
• Hand-Held Requirement: To maintain optimal rendering performance and prevent visual clutter, particles are rendered only when the inspecting player has the visualizer tool (compass) equipped in their main hand.

2. VoiceWall Raycast Debugger (/voicewall debug)

Administrators can inspect acoustic calculations for specific players.

• Green Particles: Clear line of sight; sound passes unobstructed through air.
• Yellow Particles: Diffracted acoustic path bending through a door, window, or corridor.
• Red Particles: Obstructed ray hitting an impassable solid block or soundproof threshold.
• Action Bar HUD: Displays decibel attenuation (-6.0dB), linear volume multiplier (50%), and status ([HEARD] or [SILENT]).

---

In-Game Commands

Command	Permission	Description
/voice visualizer [toggle|on|off]	dreamvoice.visualizer	Toggles the 3D acoustic visualizer mode (hand-held tool required).
/voicewall toggle	dreamvoice.voicewall.admin	Globally toggles the VoiceWall occlusion engine.
/voicewall mode <strict|realistic|off>	dreamvoice.voicewall.admin	Switches acoustic calculation mode.
/voicewall airdamping <true|false>	dreamvoice.voicewall.admin	Toggles high-frequency distance air absorption.
/voicewall debug [player]	dreamvoice.voicewall.debug	Toggles visual particle raycasting and Action Bar diagnostics.

---

Java API & Integration (Paper & Fabric)

Service Retrieval

import fr.dreamin.dreamvoice.api.DreamVoiceAPI;
import fr.dreamin.dreamvoice.api.wall.service.VoiceWallService;
import fr.dreamin.dreamvoice.api.wall.model.VoiceWallMode;
import java.util.UUID;

VoiceWallService voiceWall = DreamVoiceAPI.get().wallService();

Dynamic Mode Switching

// Switch to strict soundproof mode:
voiceWall.setMode(VoiceWallMode.STRICT_BLOCK);

// Enable high-frequency air damping:
voiceWall.setAirDampingEnabled(true);

Enabling Debug HUD Programmatically

voiceWall.setDebugPlayer(playerUuid, true);