VelocityVault

VelocityVault is a server-side Fabric mod designed to smooth out player movement in multiplayer environments, reducing visual jitter caused by network latency. It also exposes a clean API for other mods (like anti-cheats) to access high-precision velocity data.

Features

Server-Side Smoothing: Interpolates player positions before sending them to clients, making movement look fluid even for players with unstable connections.
Velocity Tracking: Maintains a rolling buffer of player positions to calculate precise velocity vectors.
Ping-Aware: Automatically adjusts smoothing intensity based on player latency.
Configurable: Fine-tune smoothing strength, buffer sizes, and debug logging.
Developer API: Provides easy access to movement history and velocity estimates for integration with other mods.

Installation

Download the latest release .jar file.
Place it in your server's mods folder.
Restart the server.

Requirements:

Minecraft 1.21.4
Fabric Loader 0.16.10+
Fabric API

Configuration

The configuration file is located at config/velocityvault.json.

Option	Default	Description
`enabled`	`true`	Master switch to enable/disable the mod.
`bufferSize`	`15`	Number of position samples to keep in history.
`smoothingTicks`	`3`	Number of ticks to spread corrections over.
`maxSmoothingDistance`	`2.0`	Max distance (blocks) to apply smoothing. Larger jumps snap instantly.
`minPingForSmoothingMs`	`50`	Minimum ping required to trigger smoothing.
`smoothSelf`	`false`	Whether to smooth the player's own position (usually not recommended).
`debugLogging`	`false`	Enable verbose logging for debugging.

Commands

/velocityvault stats - Show mod status and tracked player counts.
/velocityvault player <name> - Detailed movement and network stats for a specific player.
- Requires OP Level 2+.

Developer API

VelocityVault exports a simple API for other mods to query movement data.

1. Add Dependency

Add the mod jar to your development environment.

2. Access the API

The entry point is com.pepe.velocityvault.api.VelocityVaultAPI.

import com.pepe.velocityvault.api.VelocityVaultAPI;

public void checkPlayer(ServerPlayerEntity player) {
    VelocityVaultAPI api = VelocityVaultAPI.getInstance();
    
    // Check if API is available and enabled
    if (api == null || !api.isEnabled()) {
        return;
    }

    UUID playerId = player.getUuid();

    // 1. Get Estimated Velocity (average over last 1000ms)
    double[] velocity = api.getVelocityEstimate(playerId, 1000L);
    System.out.printf("Velocity: X=%.2f, Y=%.2f, Z=%.2f%n", velocity[0], velocity[1], velocity[2]);

    // 2. Get Average Ping
    double ping = api.getAveragePing(playerId);

    // 3. Get Movement History
    VelocityVaultAPI.MovementHistoryEntry[] history = api.getMovementHistory(playerId);
    for (var entry : history) {
        // Access entry.x, entry.y, entry.z, entry.timestampMillis
    }
}

API Methods

`getInstance()`

Returns the singleton API instance or null if the mod is disabled.

`getVelocityEstimate(UUID playerId, long windowMillis)`

Calculates the average velocity vector (blocks/sec) over the specified time window.

Returns: double[]{vx, vy, vz}

`getMovementHistory(UUID playerId)`

Returns the raw position samples stored in the buffer.

Returns: MovementHistoryEntry[] (ordered oldest to newest)

`getAveragePing(UUID playerId)`

Returns the player's smoothed average ping in milliseconds.

`getLastCorrectionDelta(UUID playerId)`

Returns the distance (in blocks) of the last server-side position correction applied to the player.