SocketSVC DocsArchitecture and modules
SocketSVC's overall architecture, loader interfaces, client audio pipeline and the responsibility of each directory
SocketSVC consists of a client mod (Fabric/Quilt, NeoForge, Forge) and a server side (a Paper plugin, or a Fabric/Quilt, NeoForge or Forge server mod), plus an optional Velocity/BungeeCord relay proxy plugin. Opus audio is carried over WebSocket/WSS.
The development section is the entry point for development, testing, version maintenance and releases. The development rules are the process to follow when making changes; validation and releases describes the checks that actually exist today. The two are not the same: not every step is automated.
Baseline
The development docs describe the state as of 2026-09-17. Version numbers, dependencies and CI behaviour can change; when they do, update the docs following future changes and long-term maintenance. The date is not a guarantee that the docs stay current afterwards.
Architecture overview
Minecraft plugin messaging / custom payload: login handshake / one-time token / reconnect token request
↓
Client mod ←──── WebSocket voice and state ────→ Paper plugin or server mod
(Fabric/Quilt/NeoForge/Forge) (shared common/core relay)
↑ ↑
settings, UI, audio devices auth, player positions, distance routing, speaker API- Handshake: client and server exchange a one-time token and the voice address over plugin messaging/custom payloads (
socketsvc:handshake,socketsvc:handshake_request) on the Minecraft game connection; reconnects request a fresh token over the same channel. See network compatibility between loaders. - Voice: with the token, the client opens a separate WebSocket connection for audio and state. See the voice protocol.
- Proxy relay (optional): a Velocity/BungeeCord network can relay every backend's voice connection through one public port; the relay only forwards bytes and does not understand the voice protocol. See Proxy.
Loader interfaces
Loader differences on both sides are confined to one small interface: ClientPlatform on the client and ServerModPlatform on the server mod. Each loader project only adapts its own events, network registration, keybinds and permissions to the shared code.
Client audio pipeline
| Direction | Processing order |
|---|---|
| Capture and send | 48 kHz mono input → echo processing → RNNoise → gain/limiter → speech detection → mic volume/limiter → Opus encoding → send |
| Receive and play | per-player bounded queue → decode → mix → distance/per-player volume → output; the mix also serves as the echo reference |
Directory responsibilities
| Path | Responsibility and when to change it |
|---|---|
| common/core | Plain Java: voice protocol, WebSocket relay (AbstractVoiceServer/SpatialVoiceServer), config validation, speaker API types; compiled directly into the client, server mod and Paper JARs, not a separately deployed module |
| common/minecraft | Code that depends on Minecraft but not on a loader, shared by the client and server mod (handshake payloads) |
| client/common/src | Loader-independent client: connection, audio, settings, commands, UI, Mixin, resources (main), 26.x-specific implementations (modern), JUnit (test), native audio regression (audioRegression) |
| client/fabric | Fabric/Quilt entry point, fabric.mod.json, Mod Menu and Flashback integration; also runs the client/common tests |
| client/neoforge, client/forge | NeoForge/Forge entry points, platform implementations and mods.toml |
| server/common/src | Loader-independent server mod: config file, listener lifecycle and hot reload, commands, permission cache, SocketSvcModApi |
| server/fabric, server/neoforge, server/forge | Dedicated server entry point and permission/network implementation for each loader |
| server/paper | Paper plugin, SocketSvcApi, API JAR, example speaker plugin and server regression tests |
| proxy/common | Single-public-port relay engine shared by Velocity/BungeeCord; does not understand the voice protocol, only forwards bytes |
| proxy/plugin | One jar containing both the Velocity and BungeeCord/Waterfall plugins: loads config, resolves the player's current backend, starts/stops the relay |
| gradle/socketsvc.properties | Version catalog: feature versions of the three sides, supported Minecraft list, per-version Java/loaders/dependencies |
*.gradle under gradle/ | Shared build logic: minecraft.gradle (source assembly and version adaptation), client/server scripts per loader, modular-jar.gradle (NeoForge/Forge packaging) |
| gradle/compat | Build-time transformation rules for upstream API renames/access-path changes |
| images | Icon source art; must be synced into the client resources to reach the artifacts |
| scripts/build_matrix.py | Reads the version catalog and builds all, or selected, Minecraft versions/loaders/sides in sequence |
| scripts/modrinth_release.py | Builds and publishes every artifact to Modrinth (see publishing) |
Documentation index
Development setup
Versions and loaders
Workflow and rules
Validation and releases
Audio validation
Soundboard design
Voice protocol
Spatial audio API
Proxy relay
/ssvc-proxy commands- Audio validation contains historical build instructions; for JDKs and client artifact paths, development setup and versions and loaders are authoritative.
- the roadmap: early planning and phase records, not a complete list of current features or supported versions.
Maintenance principle: actual versions/dependencies are whatever the build configuration says, and the protocol is checked against the common/core implementation and the protocol docs. When adding behaviour or changing development commands, update the related docs in the same change instead of leaving it only in commit messages or conversations.