Configuration Guide

Configuration Guide

Starting with DreamVoice 2.0.0, the configuration architecture transitioned from a monolithic layout to an isolated, modular per-module directory structure.

Depending on your server platform:

• Paper / Purpur: Located at plugins/DreamVoice/
• Fabric: Located at config/dreamvoice/

Both platforms share identical JSON structures and file schemas.

---

Directory Architecture Overview

<config_root>/
├── config.json                     # Root master module switches & visualizer
├── lang/
│   └── lang-dreamvoice.json        # Localization strings (DreamAPI LangService)
├── sounds/                         # Shared audio library (.wav, .mp3) for speakers & radios
└── modules/
    ├── wall/
    │   └── config.json             # Acoustic occlusion, air damping & visualizer physics
    ├── room/
    │   ├── config.json             # Acoustic room presets & persistence settings
    │   └── data.json               # Active Cuboid zones & bounds
    ├── speaker/
    │   ├── config.json             # Persistence & auto-save settings
    │   └── data.json               # 3D spatial speakers data
    ├── radio/
    │   ├── config.json             # Persistence & auto-save settings
    │   └── data.json               # Radio frequency channels
    ├── wiretap/
    │   ├── config.json             # Persistence & auto-save settings
    │   └── data.json               # Covert listening bugs
    ├── projection/
    │   ├── config.json             # Persistence & auto-save settings
    │   └── data.json               # Voice projection anchors
    ├── transmitter/
    │   ├── config.json             # Persistence & auto-save settings
    │   └── data.json               # Voice transmitters
    ├── record/
    │   ├── config.json             # Persistence settings
    │   ├── recordings/             # Captured raw audio (.dv)
    │   └── exports/                # Exported audio files (.mp3, .ogg, .wav)
    ├── filter/
    │   └── filters/                # Dynamic filter files (.yml, .json, .java)
    └── speech/
        ├── config.json             # Speech-to-text, stations & sidecar settings
        ├── keywords.json           # Realtime keyword spotting definitions
        └── models/                 # Offline Vosk models (downloaded or custom)

---

1. Root config.json

The root configuration file is dedicated exclusively to enabling or disabling modules on startup:

{
  "modules": {
    "wall": true,
    "speaker": true,
    "record": true,
    "radio": true,
    "wiretap": true,
    "projection": true,
    "transmitter": true,
    "room": true,
    "filter": true,
    "speech": true
  }
}

---

2. Common Persistence Block

Every persistent module (speaker, radio, wiretap, projection, transmitter, room, record) contains an asynchronous persistence section in its respective modules/<module>/config.json:

{
  "persistence": {
    "saveOnStop": true,
    "autoSave": true,
    "autoSaveIntervalSeconds": 300
  }
}

• saveOnStop (boolean): When true, automatically flushes runtime data to disk during server shutdown. Default: true.
• autoSave (boolean): Enables periodic background saving. Default: true.
• autoSaveIntervalSeconds (long): Interval in seconds between asynchronous disk flushes. Default: 300 (5 minutes).

---

3. VoiceWall Configuration (modules/wall/config.json)

Controls real-time sound occlusion, aperture diffraction, and material dampening:

{
  "enabled": true,
  "distance": 16.0,
  "mode": "REALISTIC",
  "airDamping": true,
  "airDampingFactor": 0.05,
  "apertureDiffraction": true,
  "diffractionSampleStep": 1.0,
  "materials": {
    "AIR": 0.0,
    "OAK_DOOR": 3.0,
    "GLASS": 4.5,
    "STONE": 18.0,
    "OBSIDIAN": 35.0
  }
}

• enabled (boolean): Enables the acoustic occlusion engine.
• mode (string): STRICT (full cutoff through walls) or REALISTIC (progressive decibel dampening).
• airDamping (boolean): Simulates high-frequency sound absorption through open air.
• apertureDiffraction (boolean): Allows sound to bend around doorframes and windows.
• materials (map): Custom sound transmission loss (in dB) per block type.

---

4. Acoustic Visualizer Mode

DreamVoice provides an acoustic visualizer (/voice visualizer):

• Renders real-time particle rays displaying line-of-sight sound paths, wall collisions, diffraction bypasses, and 3D speaker audible spheres.
• Hand-Held Requirement: In order to save client rendering performance and prevent visual clutter, particle streams are rendered only when the inspecting player has the visualizer tool (default: compass) equipped in their main hand.

---

5. Network Sync on Fabric

On Fabric servers, all module states and visualizer configurations are kept in sync with connected clients and third-party companion mods via the packet channels described in Network Packets & Protocols. Client mods can request a full configuration snapshot at any time by sending ServerBoundRequestConfigSyncPacket.