Troubleshooting & FAQ

Troubleshooting & FAQ

This page addresses common operational questions, network setup issues, and diagnostic resolutions across both Paper / Purpur and Fabric.

---

Frequently Asked Questions

Visualizer particles are not showing in game

• Cause: To preserve client rendering performance and prevent visual clutter, the 3D acoustic visualizer (/voice visualizer) renders particles only when the inspecting player is holding the visualizer item (default: Compass) in their main hand.
• Fix: Run /voice visualizer on and make sure you hold a Compass in your main hand.

Sound is 100% blocked when standing next to a closed door

• Cause: In STRICT_BLOCK mode, if door materials are not defined in materials, the door block may be treated as a solid obstacle.
• Fix: Ensure your modules/wall/config.json includes appropriate door attenuation:

  "materials": {
    "OAK_DOOR": 4.0,
    "IRON_DOOR": 12.0
  }

  Also verify that apertureDiffraction is set to true.

Audio crackles or sounds distorted when speaking into a speaker

• Cause: Two conflicting DSP filters or saturated microphone input gain.
• Fix: DreamVoice 2.0.1 decodes raw Opus once per packet with built-in limiter normalization (AudioLimiter). Check /voice filter clear to reset active DSP chains.

Command permissions on Fabric servers

• Cause: Fabric does not use Bukkit's permission system natively.
• Fix: DreamVoice supports LuckPerms Fabric out of the box. Install LuckPerms on your Fabric server and grant nodes like dreamvoice.visualizer, dreamvoice.speaker.create, etc. Players with Vanilla OP level 2+ also have full access by default.

Netty EncoderException: String too big (was 17, max 16)

• Cause: Simple Voice Chat imposes a strict 16-character limit on volume category identifiers sent over the network protocol.
• Fix: DreamVoice automatically truncates and registers standard identifiers (dv_speaker, dv_radio, dv_wiretap).

Cassette playback is choppy or lags the server

• Cause: Traditional audio players transcode audio through pure-Java Opus encoders.
• Fix: DreamVoice 2.0.1 uses OpusAudioPlayer, which streams pre-encoded Opus frames directly without CPU transcoding overhead.

---

Diagnostic Checklist

1. Verify Simple Voice Chat is connected: Run /voicechat test <player> to ensure the UDP voice port is open and reachable.
2. Inspect VoiceWall raycast paths in game: Run /voicewall debug to visually see raycasts. Red lines indicate blocked paths; yellow lines indicate diffracted paths.
3. Inspect 3D Acoustic Visualizer: Hold a compass in hand and run /voice visualizer toggle.
4. Check console for startup errors: Verify that [DreamVoice] Simple Voice Chat compatibility layer initialized appears during startup on Paper, or [DreamVoice] Initializing DreamVoice Fabric v2.0.1 on Fabric.