Clock synchronization estimator for networked games. More...

#include "n_common.h"

Include dependency graph for n_clock_sync.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	N_CLOCK_SYNC
	clock synchronization estimator More...

Macros
#define	N_CLOCK_SYNC_BURST_INTERVAL 0.5
	accelerated interval used until N_CLOCK_SYNC_BURST_SAMPLES real responses have been collected — a fresh estimator converges in a couple of seconds instead of minutes

#define	N_CLOCK_SYNC_BURST_SAMPLES 5
	number of REAL samples below which the burst interval applies

#define	N_CLOCK_SYNC_INTERVAL 3.0
	default interval between sync requests in seconds

#define	N_CLOCK_SYNC_MAX_RTT 10.0
	responses with an RTT above this are rejected outright (retransmit storms / suspend-resume artefacts — not usable timing data)

#define	N_CLOCK_SYNC_SAMPLE_COUNT 11
	number of samples for the median filter

#define	N_CLOCK_SYNC_SLEW_SECONDS 1.0
	seconds over which n_clock_sync_server_time slews from the previous offset estimate to a new one (smoothstep).

Functions
void	n_clock_sync_delete (N_CLOCK_SYNC **cs)
	free a clock sync estimator

void	n_clock_sync_mark_sent (N_CLOCK_SYNC *cs, double local_now)
	mark that a sync request was just sent

N_CLOCK_SYNC *	n_clock_sync_new (void)
	allocate and initialize a new clock sync estimator

int	n_clock_sync_process_response (N_CLOCK_SYNC *cs, double client_send_time, double server_time, double local_now)
	record a sync response: client_send_time is the local time the request was sent, server_time is the server's timestamp from the response, local_now is the current local time when the response was received.

void	n_clock_sync_seed (N_CLOCK_SYNC *cs, double offset, double rtt)
	Inject a synthetic (offset, rtt) sample, e.g.

double	n_clock_sync_server_time (const N_CLOCK_SYNC *cs, double local_now)
	get estimated server time given a local time value.

int	n_clock_sync_should_send (const N_CLOCK_SYNC *cs, double local_now)
	check if it's time to send a new sync request (returns TRUE/FALSE).

Detailed Description

Clock synchronization estimator for networked games.

Estimates the time offset between a local clock and a remote clock using periodic sync request/response pairs. The offset adopted is the sample with the lowest RTT (NTP-style — smallest one-way uncertainty); absurd-RTT responses are rejected; consumers read the offset through n_clock_sync_server_time, which slews across estimate changes instead of stepping. Request cadence bursts until the estimator is warm.

Usage:

N_CLOCK_SYNC *cs = n_clock_sync_new();
 
// Periodically:
if (n_clock_sync_should_send(cs, local_now)) {
    n_clock_sync_mark_sent(cs, local_now);
    send_sync_request(local_now);  // include local_now in request
}
 
// On response:
n_clock_sync_process_response(cs, client_send_time, server_time, local_now);
 
// Convert local time to estimated server time:
double srv_time = n_clock_sync_server_time(cs, local_now);
 
n_clock_sync_delete(&cs);

Author: Castagnier Mickael

Version: 1.1

Date: 19/07/2026

Definition in file n_clock_sync.h.

Data Structures

Macros

Functions

Detailed Description