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

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

Performance Issues

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

Client Disconnections

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

Maps & World

Components

Gameplay

GUI

Advanced

Latency Simulation

Latency Simulation

Overview

Configuration

Environment Variables

Programmatic Configuration

Usage Examples

Basic Latency Simulation

Selective Latency

Combined with Packet Loss

Monitoring

Best Practices

1. Realistic Latency Values

2. Selective Application

3. Testing Different Scenarios

4. Client-Side Considerations

API Reference

PartyConnection.configureLatency()

PartyConnection.getLatencyStatus()

Troubleshooting

Messages Not Being Delayed

Performance Issues

Client Disconnections

​Latency Simulation

​Overview

​Configuration

​Environment Variables

​Programmatic Configuration

​Usage Examples

​Basic Latency Simulation

​Selective Latency

​Combined with Packet Loss

​Monitoring

​Best Practices

​1. Realistic Latency Values

​2. Selective Application

​3. Testing Different Scenarios

​4. Client-Side Considerations

​API Reference

​PartyConnection.configureLatency()

​PartyConnection.getLatencyStatus()

​Troubleshooting

​Messages Not Being Delayed

​Performance Issues

​Client Disconnections

Latency Simulation

Overview

Configuration

Environment Variables

Programmatic Configuration

Usage Examples

Basic Latency Simulation

Selective Latency

Combined with Packet Loss

Monitoring

Best Practices

1. Realistic Latency Values

2. Selective Application

3. Testing Different Scenarios

4. Client-Side Considerations

API Reference

PartyConnection.configureLatency()

PartyConnection.getLatencyStatus()

Troubleshooting

Messages Not Being Delayed

Performance Issues

Client Disconnections