Skip to main content

​
Latency Simulation

RPG-JS provides built-in latency simulation capabilities to test how your game behaves under various network conditions. This feature allows you to simulate realistic network delays between the server and clients.

​
Overview

Latency simulation adds configurable delays to outgoing messages from the server to clients, helping you:
  • Test game responsiveness under poor network conditions
  • Validate client-side prediction and reconciliation systems
  • Ensure smooth gameplay even with high latency
  • Debug synchronization issues

​
Configuration

​
Environment Variables

You can configure latency simulation using environment variables: 
# Enable latency simulation
RPGJS_ENABLE_LATENCY=true

# Set minimum and maximum latency in milliseconds
RPGJS_LATENCY_MIN_MS=50
RPGJS_LATENCY_MAX_MS=200

# Optional: Only apply latency to messages containing specific text
RPGJS_LATENCY_FILTER=sync

​
Programmatic Configuration

You can also configure latency simulation programmatically: 
import { PartyConnection } from '@rpgjs/vite';

// Enable latency simulation with 100-300ms range
PartyConnection.configureLatency(true, 100, 300);

// Enable latency only for synchronization messages
PartyConnection.configureLatency(true, 50, 150, 'sync');

// Disable latency simulation
PartyConnection.configureLatency(false, 0, 0);

​
Usage Examples

​
Basic Latency Simulation

// In your server configuration
PartyConnection.configureLatency(true, 100, 300);

// All outgoing messages will now have 100-300ms random delays
room.broadcast({ type: 'player_move', data: playerData });

​
Selective Latency

// Only apply latency to synchronization messages
PartyConnection.configureLatency(true, 50, 150, 'sync');

// This message will be delayed (contains 'sync')
room.broadcast({ type: 'sync', data: worldState });

// This message will be sent immediately (no 'sync' in content)
room.broadcast({ type: 'chat', message: 'Hello!' });

​
Combined with Packet Loss

You can use latency simulation together with packet loss simulation: 
// Configure both packet loss and latency
PartyConnection.configurePacketLoss(true, 0.1); // 10% packet loss
PartyConnection.configureLatency(true, 100, 300); // 100-300ms latency

// Messages will first be delayed, then potentially dropped
room.broadcast({ type: 'update', data: gameState });

​
Monitoring

The server logs will show latency simulation activity: 
[LATENCY SIMULATION] Connection conn_123: Delaying message by 156.7ms
[MESSAGE DATA] {"type":"sync","data":{"players":[...]}}

​
Best Practices

​
1. Realistic Latency Values

Use realistic latency ranges based on your target network conditions:
  • Local/LAN: 1-10ms
  • Good Internet: 20-100ms
  • Poor Internet: 100-500ms
  • Mobile/3G: 200-1000ms

​
2. Selective Application

Use filters to apply latency only to specific message types: 
// Apply high latency to world updates
PartyConnection.configureLatency(true, 200, 500, 'world_update');

// Apply low latency to critical messages
PartyConnection.configureLatency(true, 10, 50, 'critical');

​
3. Testing Different Scenarios

Test various latency scenarios: 
// Test with very high latency
PartyConnection.configureLatency(true, 500, 1000);

// Test with variable latency (simulates unstable connections)
PartyConnection.configureLatency(true, 50, 300);

// Test with consistent low latency
PartyConnection.configureLatency(true, 20, 30);

​
4. Client-Side Considerations

When latency simulation is enabled, ensure your client:
  • Implements proper client-side prediction
  • Uses interpolation for smooth movement
  • Handles message ordering correctly
  • Provides visual feedback for network conditions

​
API Reference

​
PartyConnection.configureLatency()

Configures latency simulation settings. Parameters:
  • enabled (boolean): Whether to enable latency simulation
  • minMs (number): Minimum latency in milliseconds
  • maxMs (number): Maximum latency in milliseconds
  • filter (string, optional): Only apply latency to messages containing this string

​
PartyConnection.getLatencyStatus()

Returns current latency simulation configuration. Returns: 
{
  enabled: boolean;
  minMs: number;
  maxMs: number;
  filter: string;
}

​
Troubleshooting

​
Messages Not Being Delayed

  1. Check if latency simulation is enabled: PartyConnection.getLatencyStatus()
  2. Verify the filter string matches your message content
  3. Ensure maxMs is greater than 0

​
Performance Issues

  1. High latency values may affect server performance
  2. Consider using filters to limit which messages are delayed
  3. Monitor server logs for excessive delay messages

​
Client Disconnections

  1. Very high latency may cause client timeouts
  2. Adjust client-side timeout settings accordingly
  3. Consider implementing heartbeat mechanisms