VSS

VSS is a Fabric client/server mod that sends server-side LOD chunk data to Voxy-compatible clients. players on multiplayer servers can see distant terrain without first exploring the map locally, while the actual Voxy client mod stays a separate install.

players without VSS and Voxy are unaffected. VSS does not bundle or redistribute the Voxy client mod.

how it works

when a VSS client joins a VSS server, the client and server perform a handshake. the server sends session limits such as LOD distance, bandwidth limits, and generation settings. the client scans outward from the player in a spiral and batch-requests missing LOD columns.

the server then reads chunk data from disk or memory, can generate missing chunks on demand when enabled, serializes the section data, and streams voxel columns back to the client. as chunks change, the server broadcasts dirty-column updates so clients can refresh stale LOD data.

installation

fabric server

1. install Fabric Loader.
2. install Fabric API.
3. place the VSS jar in the server's mods/ folder.
4. start the server. config is generated at config/vss-server-config.json.

fabric client

1. install Fabric Loader.
2. install Fabric API.
3. install Voxy.
4. place the VSS jar in the client's mods/ folder.
5. join a server running VSS. config is generated at config/vss-client-config.json.

requirements

side	requirement
server	Fabric Loader, Fabric API, Java 21
client	Fabric Loader, Fabric API, Voxy, Java 21

use matching VSS and Minecraft versions on the client and server. VSS is currently Fabric-only and does not provide a Paper or Purpur plugin.

commands

server

the /vsslod commands require permission level 2.

command	description
/vsslod stats	show per-player transfer stats, handshake state, request counts, pending queues, and bytes sent
/vsslod diag	show server diagnostics, bandwidth, disk reader status, generation status, and queue depths

client

command	description
/vss clearcache	clear the local VSS column cache so LOD data is requested again
/vss diag	show client-side VSS connection, queue, throughput, request, and scan diagnostics

configuration

server

server config is generated at config/vss-server-config.json.

setting	default	description
enabled	true	enable VSS LOD distribution
lodDistanceChunks	256	maximum LOD request distance in chunks
bytesPerSecondLimitPerPlayer	20971520	per-player pre-compression bandwidth cap
bytesPerSecondLimitGlobal	104857600	global pre-compression bandwidth cap
diskReaderThreads	5	async disk reader thread count
sendQueueLimitPerPlayer	4000	max queued sections per player
enableChunkGeneration	true	allow missing chunks to generate for LOD data
generationConcurrencyLimitGlobal	32	max chunks generating server-wide at once
generationTimeoutSeconds	60	timeout for pending generation requests
dirtyBroadcastIntervalSeconds	10	interval for pushing dirty-column notifications
syncOnLoadRateLimitPerPlayer	800	sync request rate limit per player
syncOnLoadConcurrencyLimitPerPlayer	200	max in-flight sync requests per player
generationRateLimitPerPlayer	80	generation request rate limit per player
generationConcurrencyLimitPerPlayer	16	max in-flight generation requests per player
perDimensionTimestampCacheSizeMB	32	per-dimension timestamp cache budget

client

client config is generated at config/vss-client-config.json.

setting	default	description
receiveServerLods	true	receive LOD data from VSS servers
lodDistanceChunks	0	client LOD distance override, where 0 uses the server limit
offThreadSectionProcessing	true	process received sections off the render thread

troubleshooting

• make sure the server and client are using matching VSS and Minecraft versions.
• make sure the server has Fabric API and VSS installed.
• make sure clients that want server LODs have Fabric API, VSS, and Voxy installed.
• use /vsslod stats to confirm the server received a VSS handshake.
• use /vsslod diag and /vss diag to inspect queues, bandwidth, generation, and request activity.
• run /vss clearcache if client-side LOD data looks stale.

building

VSS is built from the tracked source in this repository:

./gradlew build

the output jar is written to build/libs/.

fabric metadata:

id: vss
name: VSS
package: dev.micr.vss

distribution policy

this repository may publish VSS artifacts. it must not publish or bundle the actual Voxy client mod from https://modrinth.com/mod/voxy.

license

MIT