Skip to content

Technical Documentation

Jump to bottom
Romain Odeval edited this page Oct 23, 2025 · 1 revision

Technical Documentation

Table of Contents

Architecture Overview

RPVoiceChat follows a modular architecture designed for Vintage Story modding, with clear separation between client and server components. The mod implements proximity-based voice chat with advanced audio processing and multiple networking transports.

High-Level Architecture

┌────────────────────┐    ┌─────────────────┐
│    Client Side     │    │   Server Side   │
├────────────────────┤    ├─────────────────┤
│ RPVoiceChatClient  │    │RPVoiceChatServer│
│ MicrophoneManager  │    │   GameServer    │
│ AudioOutputManager │    │                 │
│ PlayerNetworkClient│    │                 │
│     GuiManager     │    │                 │
└────────────────────┘    └─────────────────┘
         │                       │
         └───────────┬───────────┘
                     │
            ┌─────────────────┐
            │  Network Layer  │
            │ UDP/TCP/Native  │
            └─────────────────┘

Key Design Principles

  • Modularity: Each component has a single responsibility
  • Extensibility: Easy to add new audio effects, codecs, or network transports
  • Performance: Optimized for real-time audio processing
  • Cross-platform: Works on Windows, Linux, and macOS (with some issues for last one)

Core Components

RPVoiceChatMod (Base Class)

The abstract base class that provides common functionality for both client and server implementations.

Key Responsibilities:

  • Configuration initialization (ModConfig, WorldConfig)
  • Logger setup
  • Network channel registration
  • Game content registration (blocks, items, entities)
  • Patch management

Key Methods:

public override void StartPre(ICoreAPI api)     // Early initialization
public override void Start(ICoreAPI api)          // Main initialization
public override void AssetsFinalize(ICoreAPI api) // Asset finalization

RPVoiceChatClient

Handles all client-side functionality including audio capture, processing, and transmission.

Key Components:

  • MicrophoneManager: Audio input and processing
  • AudioOutputManager: Audio output and spatial audio
  • PlayerNetworkClient: Network communication
  • GuiManager: User interface management
  • ClientSettingsRepository: Local settings persistence

Initialization Flow:

  1. Extract and load native DLLs (RNNoise)
  2. Initialize audio managers
  3. Setup network transports (UDP, TCP, Native)
  4. Register GUI components and keybinds
  5. Launch audio processing threads

RPVoiceChatServer

Manages server-side voice chat coordination and game content integration.

Key Components:

  • GameServer: Core server logic
  • Network transport management
  • Command system (/rpvc commands)
  • World configuration management

Server Commands:

  • /rpvc whisper <distance> - Set whisper range
  • /rpvc talk <distance> - Set talk range
  • /rpvc shout <distance> - Set shout range
  • /rpvc info - Display current settings
  • /rpvc reset - Reset to defaults

Audio System

MicrophoneManager

Handles audio input capture, processing, and transmission.

Key Features:

  • Real-time audio capture (48kHz)
  • Multiple voice levels (Whisper, Talk, Shout)
  • Audio effects pipeline (denoising, gain, compression)
  • Push-to-talk and voice activation
  • Audio wizard for setup

Audio Processing Pipeline:

Raw Audio → Channel Detection → Mono Conversion → 
Denoising → Gain Control → Compression → Encoding → Transmission

Key Classes:

  • IAudioCapture: Audio input interface
  • IAudioCodec: Audio encoding/decoding
  • IDenoiser: Noise reduction
  • SoundEffect: Audio effects processing

AudioOutputManager

Manages audio output, spatial positioning, and player audio sources.

Key Features:

  • 3D spatial audio positioning
  • Distance-based volume attenuation
  • Wall muffling effects
  • Player audio source management
  • Loopback support for local monitoring

Spatial Audio Calculation:

// Distance-based volume calculation
float distance = MathTools.Distance(playerPos, listenerPos);
float volume = CalculateVolume(distance, voiceLevel);

// Wall muffling
float mufflingFactor = CalculateWallMuffling(playerPos, listenerPos);
volume *= mufflingFactor;

Audio Codecs

OpusCodec: High-quality, low-latency audio compression

  • Frame size: 960 samples (20ms at 48kHz)
  • Bitrate: Configurable
  • Low latency: ~20ms

DummyCodec: Uncompressed audio for testing

  • No compression overhead
  • Higher bandwidth usage
  • Useful for debugging

Networking Layer

Transport Architecture

RPVoiceChat supports multiple network transports with automatic fallback:

  1. Native Transport: Uses Vintage Story's built-in networking
  2. UDP Transport: Custom UDP implementation with UPnP support
  3. TCP Transport: Reliable TCP connection for poor network conditions

Network Client (PlayerNetworkClient)

Manages multiple transport connections and handles automatic failover.

Connection Strategy:

var networkTransports = new List<INetworkClient>()
{
    new UDPNetworkClient(forwardPorts),   // Primary: Low latency
    new TCPNetworkClient(),               // Fallback: Reliable
    new NativeNetworkClient(capi)         // Last resort: Game networking
};

Network Server (GameServer)

Coordinates voice chat between players and manages transport selection.

Key Responsibilities:

  • Player connection management
  • Audio packet routing
  • Distance-based filtering
  • Transport health monitoring

Packet Types

AudioPacket: Main voice data transmission

public class AudioPacket : NetworkPacket
{
    public string Sender { get; set; }
    public AudioData AudioData { get; set; }
    public long SequenceNumber { get; set; }
}

ConnectionInfo: Player connection details

public class ConnectionInfo
{
    public string Address { get; set; }
    public int Port { get; set; }
}

Configuration System

ModConfig

Centralized configuration management with automatic serialization.

Client Configuration (rpvoicechat-client.json):

  • Audio device settings
  • Input/output preferences
  • UI preferences
  • Keybind settings

Server Configuration (rpvoicechat-server.json):

  • Network settings
  • Server port/IP configuration
  • Performance settings
  • Content settings

WorldConfig

Runtime configuration stored in the world save file.

Key Settings:

  • Voice level distances
  • Audio encoding preferences
  • Name tag rendering
  • Wall thickness weighting

Configuration Hierarchy:

  1. World-specific settings (highest priority)
  2. Server configuration
  3. Default values (lowest priority)

Game Content Integration

Block System

Communication Blocks:

  • TelegraphBlock: Long-distance communication
  • ChurchBellLayerBlock: Area-wide announcements
  • ConnectorBlock: Network connections
  • SoundEmittingBlock: Audio emitters

Block Entities:

  • BETelegraph: Telegraph functionality
  • BEChurchBellLayer: Church Bell multi-block system
  • BEConnector: Network connections
  • BEWeldable: Welding mechanics

Item System

Communication Items:

  • TelegraphWireItem: Telegraph wiring
  • VoiceAmplifierItem: Voice amplification (e.g., megaphones)
  • SoundEmittingItem: Audio emitters (e.g., bells)

Wire Network System

Advanced communication network allowing players to connect devices across distances.

Key Components:

  • WireNetwork: Network topology management
  • WireConnection: Individual connections
  • WireMesh: 3D network visualization
  • IWireConnectable: Interface for connectable devices

Development Guidelines

Code Organization

Namespace Structure:

RPVoiceChat/
├── Audio/           # Audio processing
├── Client/          # Client-specific logic
├── Config/          # Configuration management
├── DB/              # Data persistence
├── Gui/             # User interface
├── Networking/      # Network layer
├── Patches/         # Harmony patches
├── Server/          # Server-specific logic
├── Systems/         # Game systems
└── Utils/           # Utilities

Adding New Features

Audio Effects:

  1. Implement ISoundEffect interface
  2. Register in MicrophoneManager
  3. Add configuration options
  4. Update GUI controls

Network Transports:

  1. Implement INetworkClient/INetworkServer
  2. Add to transport list
  3. Handle connection management
  4. Implement packet serialization

Game Content:

  1. Create block/item classes
  2. Register in appropriate registry
  3. Add block entity if needed
  4. Create assets and textures

Performance Considerations

Audio Processing:

  • Use fixed frame sizes (960 samples)
  • Minimize allocations in hot paths
  • Use object pooling for audio buffers
  • Profile audio thread performance

Networking:

  • Implement proper connection pooling
  • Use async/await for I/O operations
  • Implement backpressure handling
  • Monitor network health

Memory Management:

  • Dispose resources properly
  • Use using statements
  • Implement IDisposable pattern
  • Monitor memory usage

Testing Guidelines

Unit Testing:

  • Test audio processing algorithms
  • Verify configuration serialization
  • Test network packet handling
  • Validate distance calculations

Integration Testing:

  • Test client-server communication
  • Verify audio quality
  • Test network failover
  • Validate GUI interactions

Performance Testing:

  • Measure audio latency
  • Test with multiple players
  • Monitor memory usage
  • Profile CPU usage

Debugging

Logging:

  • Use appropriate log levels
  • Include context information
  • Log performance metrics
  • Use structured logging

Audio Debugging:

  • Enable audio wizard
  • Use loopback for testing
  • Monitor audio levels
  • Test with different devices

Network Debugging:

  • Enable verbose logging
  • Monitor packet loss
  • Test transport failover
  • Verify UPnP functionality

This documentation provides a comprehensive overview of RPVoiceChat's technical architecture. For specific implementation details, refer to the source code and inline documentation.

Clone this wiki locally