ARCANUM
← Blog
architecture

Netcode in Hanamori, part 3: living in the past, on purpose

Other players are drawn in the past. This post is about how far in the past, how the browser works out what time the server thinks it is, and how the delay now adapts to the link.

2 Nov 2026 · 20 min read · part 3 of 4

You can predict yourself because you know your own inputs and you have the rulebook. You cannot do that for anyone else. For the other people in the field you get a stream of positions, sent 10 times a second by a server that is a little far away, over a connection that delivers them at intervals that are on average right. This post is about how those positions are turned into smooth motion without inventing any. It is also the post about the change made today, so there is a lot of arithmetic. I have tried to make the arithmetic funny. The arithmetic has declined.

The series: part 1 (tick, wire, area of interest), part 2 (yourself), part 3 (this one: everyone else), part 4 (dungeon fairness, edge cases). In these posts the meadow server is Hanamori's open-world server, and realm servers run the dungeons.

The approach is interpolation: draw each other player at now − delay, not at the newest sample. At that moment the client holds one sample just before and one just after, and can blend between them. The price is that you see the past. The reward is smooth motion. Two questions remain, and they are the whole post. (1) “now − delay” by whose clock? Samples are labelled by the server's clock, and the browser has a different one. (2) How big should the delay be? Too short and the ring runs out of samples when an update is late; too long and what you see is so old that you walk into things that are no longer there.

1. The sample ring and the render cursor

For each other player the client keeps a small ring of the last 16 samples. Each sample is a position and heading plus a time stamp. To draw the player the client asks: what was this entity doing at now − delay? The answer is found by locating the two samples that bracket that time and blending between them.

// net/interp.mjs (trimmed)
const RING = 16;
push(tMs, sample) {
  const n = this.buf.length;
  if (n && tMs < this.buf[n - 1].t) tMs = this.buf[n - 1].t;   // a stale stamp is clamped forward
  this.buf.push({ t: tMs, s: sample });
  if (this.buf.length > RING) this.buf.shift();
}
sample(nowMs, delayMs = 100, lerpFn = lerpSample) {
  const b = this.buf, n = b.length;
  if (!n) return null;
  const target = nowMs - delayMs;
  if (target <= b[0].t) return b[0].s;            // before the first: hold the first
  if (target >= b[n - 1].t) return b[n - 1].s;    // after the last: hold the last. No extrapolation.
  let i = n - 2;
  while (i > 0 && b[i].t > target) i--;
  const a = b[i], c = b[i + 1], span = c.t - a.t;
  return lerpFn(a.s, c.s, span > 0 ? (target - a.t) / span : 1);
}

Two honest notes. First, the last-but-one line: when the cursor is past the newest sample, the entity holds its last position. There is no extrapolation: the client does not guess that a running player goes on running. A late update shows as a pause rather than as a ghost that must be pulled back. Second, headings use lerpYawDeg, which takes the shortest arc: turning from 350° to 10° goes through 0°, not backwards through 180°.

healthy: the cursor has data on both sides 1000 1100 1200 1300 1400 1500 samples (server-tick stamps) now 1560 cursor 1460 delay starved: the next sample has not arrived 1000 1100 1200 1300 1400 1500 samples (server-tick stamps) now 1660 cursor 1560 delay blend 1400 and 1500: 60 % cursor 1560 is after the newest sample (1500): hold it Ring of 16 samples per entity. Stamps in the ring only ever move forward: a stale stamp is pushed up to the newest one.
The render cursor is now minus the delay. Between two samples it blends them. Past the newest sample it holds, and does not guess.

Look at the second timeline. The newest sample is stamped 1500, and now is 1660, so with a 100 ms delay the cursor is at 1560. The cursor ran off the end of the data. The entity is frozen there until the next sample arrives, at which point it moves on (and, because the new sample is old by the time it is shown, it will hop). This is starving, and avoiding it is what the delay is for.

The requirement is plain. A sample stamped t that reaches the browser late ms after its due time is only usable from t + late on. For the cursor to find it in time:

delay ≥ interval between samples + lateness of the latest arrival

The old code used delay = 100. The meadow server sends each viewer an update every 100 ms (part 1, section 4). So the old formula was 100 ≥ 100 + lateness, which is true only when the lateness is exactly zero. Which it never is. That is the problem this change fixes, and the next sections are how.

2. What time is it? Tick stamps versus receive time

Until today, the browser stamped each remote update with the time it arrived. That has a flaw you can see in a small example. Suppose the server sends three updates for ticks 16, 18, 20, evenly spaced 100 ms apart, and the player is walking at 5 m/s, so x goes 10.0, 10.5, 11.0. The network delivers the first on time, the second 65 ms late, and the third on its heels:

old: stamp = time received 1000 1050 1100 1150 1200 1250 x=10.0 x=10.5 x=11.0 new: stamp = clock.toLocal(tick) 1000 1050 1100 1150 1200 1250 x=10.0 x=10.5 x=11.0 receive-stamped: 10.0 to 10.5 over 163 ms (3.1 m/s), then 10.5 to 11.0 over 47 ms (10.6 m/s) tick-stamped: 5 m/s, as the server saw it, whatever the network did to the arrivals
Same three packets, two stamping rules. The second packet was late; the third turned up right behind it.

Stamped by arrival, the player appears to walk 0.5 m in 163 ms (3.1 m/s) and then 0.5 m in 47 ms (10.6 m/s): a slow shuffle and a sprint, because the network's hiccup has been written into the data as if it were the player's behaviour. Stamped by the server's own tick, the samples are exactly where the server had them: evenly spaced, 5 m/s. The network can still delay when the sample arrives, but it can no longer rewrite when it happened.

That is what the tick field of part 1 (section 5) is for. With it, every entity update says which server tick it describes. The client then needs one function: server tick → local time. That is the next section.

Here are the numbers, computed with the real Interp class, for a 100 ms delay (wall time on the left; “truth” is the tick-stamped column, because that is the server's actual line):

wall time (ms)cursorshown x, tick-stampedshown x, receive-stamped
1150105010.00010.000
1180108010.15010.086
1215111510.32510.193
1240114010.45010.270
1262116210.56010.337
1350125011.00010.872

Two things in this table are honest rather than flattering. The tick-stamped column is ahead of the receive-stamped one, because it shows the truth and the other column shows a slowly catching-up distortion. And the tick-stamped player froze between 1150 and 1215, since in that window there was no sample past 1050 in the ring (the second packet was 65 ms late), and then it jumped from 10.0 to 10.325. Stamping by tick does not make late packets arrive. It makes sure that when they do, the picture is true. The delay (section 4) is what makes the freeze rarer.

3. The clock estimator: TickClock

We need toLocal(tick): when, on the browser's own clock (performance.now()), is the server's tick number N supposed to be happening? If the clocks ran at the same speed, that is a constant offset: t0 + N × 50 ms, where t0 is the local time of tick 0. (Tick 0 was when the server booted. t0 is a large negative number. Nobody minds.)

The browser cannot read the server's clock. It only knows: an update for tick N arrived at local time now. An arrival cannot happen before the update was sent, so t0 ≤ now − N × 50, with equality if the delivery took no time at all. Every arrival gives an upper bound on t0, and the tightest bound comes from the fastest delivery. So:

  • For each arrival, compute c = now − tick × tickMs, the offset that arrival implies.
  • If c < t0, we just saw a faster delivery than any before: snap down to it. snapMs = t0 − c, lateMs = 0.
  • Otherwise this arrival was late by lateMs = c − t0, and we drift up by 2 % of that: t0 += lateMs × 0.02.
// net/tickclock.mjs
export const DRIFT_UP = 0.02;

observe(tick, nowMs) {
  if (this.t0 === null) { this.start(tick, nowMs); return; }
  const c = nowMs - tick * this.tickMs;
  if (c < this.t0) { this.snapMs = this.t0 - c; this.lateMs = 0; this.t0 = c; }
  else { this.snapMs = 0; this.lateMs = c - this.t0; this.t0 += this.lateMs * DRIFT_UP; }
}
toLocal(tick) { return this.t0 + tick * this.tickMs; }

Why drift up at all? Because clocks run at slightly different speeds, and a pure minimum would never move up, so after an hour of the server's clock running a little slow the estimate would slowly become too early, and every packet would look late. The 2 % per sample drift is slow enough that one slow packet barely moves it, and fast enough to follow real drift. Its half-life is about 34 samples: 0.9834 ≈ 0.5. At 20 samples a second (SelfState feeds the clock at 20 Hz in the meadow, section 5) that is under two seconds.

Why not use ping and pong to measure round trips, like every other textbook? Because that is not needed. The estimator needs one-way lateness relative to the best case, not the absolute latency, and arrival tick stamps give it for free. (And, as part 1 said, the meadow does not do round-trip clock sync at all; the server's Pong is there, the client never asks.) What the clock calls “now” for the world is simply the fastest the network has ever done. Everything that arrives later than that is, by definition, late.

The table is from the real class, started with start(1000, 5000) so that t0 = −45000, fed these arrivals:

tickarrivedimplied offsetlatenesssnapt0 after
10025130−4497030.00−44999.40
10045260−4494059.40−44998.21
10065322−4497820.20−44997.81
10085440−4496037.80−44997.05
10105499−4500103.95−45001.00
10125640−4496041.00−45000.18
-45010 -45000 -44990 -44980 -44970 -44960 late 30 tick 1002 late 59.4 tick 1004 late 20.2 tick 1006 late 37.8 tick 1008 snap 3.95 tick 1010 late 41 tick 1012 estimate t0 ms (local clock, offset of tick 0) Red dots: implied offset (now minus tick x 50). Lateness = dot minus the estimate. A dot below the line pulls it down.
Each arrival implies an offset. The estimate follows the earliest ones: down at once, up at 2 % per sample. Numbers are from the real class.

The fifth packet turned out to be 4 ms faster than the one the clock had been using as its best, so the estimate was snapped down by 3.95 ms and everything stamped afterwards moves 3.95 ms earlier. That is acceptable: it is the estimate getting less wrong. What about the samples that are already in the ring at the old, later stamps? New samples may now be stamped slightly before the previous ones. This is the case push handles: a stale stamp is clamped forward to the newest, so the ring stays ordered. The cost is a few milliseconds of stretched time, once.

The clock has two other states. start(tick, now) anchors it directly, used when the realm sends a full snapshot (the client knows the world is at tick N now). And reset() forgets everything, used when a new snapshot, map, or reconnect makes the old estimate meaningless.

4. How big should the delay be: InterpDelay

With a clock that gives each arrival a lateness (lateMs), we can measure how jittery the link is, and size the delay to match. InterpDelay keeps two running averages:

  • interval: the average spacing of server ticks between updates (0.125 weight, so about eight samples). On meadow that settles at 100 ms; in realm at 50.
  • jitter: the average absolute deviation of lateness from its own running mean (0.0625 weight, so about sixteen samples). Not the lateness itself: a link that is always 80 ms late has no jitter, and needs no extra delay. A link that varies is the problem.

The target is then:

target = clamp(interval + 2 × jitter, 100, 250)

// net/interpdelay.mjs (trimmed)
export const DELAY_MIN_MS = 100,  DELAY_MAX_MS = 250;
export const JITTER_MULT = 2,  JITTER_ALPHA = 1 / 16,  INTERVAL_ALPHA = 1 / 8;
export const SLEW_UP = 0.1,  SLEW_DOWN = 0.02,  WARMUP_SAMPLES = 8;
export const MAX_SAMPLE_MS = 1000,  MAX_GAP_MS = 1000,  MAX_STEP_MS = 100;

get target() {
  if (this.samples < WARMUP_SAMPLES) return DELAY_MIN_MS;
  return Math.min(DELAY_MAX_MS, Math.max(DELAY_MIN_MS, this.interval + JITTER_MULT * this.jitter));
}
update(clock, tick) {                               // call right after clock.observe(tick, now)
  const prev = this.lastTick;  this.lastTick = tick;
  if (prev === null || tick === prev) return;       // first update, or a chunked batch sharing a tick
  const gap = (tick - prev) * clock.tickMs;
  if (!(gap > 0 && gap <= MAX_GAP_MS)) return;      // out of order, or a stall: not link behaviour
  this.interval = this.interval ? this.interval + (gap - this.interval) * INTERVAL_ALPHA : gap;
  if (clock.snapMs > 0) { this.mean += clock.snapMs; this.samples++; return; }
  const late = clock.lateMs;
  if (late > MAX_SAMPLE_MS) return;                 // a stall, ignored
  if (!this.samples) this.mean = late;
  const dev = Math.abs(late - this.mean);
  this.jitter += (dev - this.jitter) * JITTER_ALPHA;
  this.mean   += (late - this.mean)  * JITTER_ALPHA;
  this.samples++;
}

Read it as a list of decisions. Warm-up: until eight updates have been seen the target is the floor, because a jitter estimate from three samples is a rumour. Repeat ticks (a big update split across several messages shares one tick) are not counted twice. Gaps over a second and lateness over a second are stalls (a hidden tab, a garbage collection, a reconnect), not link behaviour, and are ignored rather than being allowed to drag the delay to the ceiling. Snaps shift the running mean by the same amount, because a clock snap changes every future lateness by the same amount and must not register as jitter.

10 Hz, quiet (jitter 0.5) interval 100 margin 1 = 101 ms 10 Hz, jittery (jitter 25) interval 100 margin 50 = 150 ms 20 Hz, jittery (jitter 25) interval 50 margin 50 = 100 ms 10 Hz, awful (jitter 75) interval 100 margin 150 = 250 ms (cap) floor 100 cap 250 Old design: always interval 100 at 10 Hz, margin 0. Computed from the formula, not measured.
delay target = clamp(interval + 2 x jitter, 100, 250). The violet part is the update interval, the cyan part is the safety margin for lateness.

Notice the first bar. On a quiet 10 Hz link the target is 101 ms: an interval of 100 plus twice a jitter of 0.5. The margin is 1 ms. I mention it because the previous design had a margin of exactly 0 and I would like to be fair about how much better 1 ms is. The point is not the quiet link. The point is that when the link stops being quiet, the margin grows with it, by a rule, while the old design stays at 0. The other bars show how: 25 ms of jitter at 10 Hz gives 150; at 20 Hz (realm) the interval is 50, so 25 ms of jitter gives exactly the floor, 100, and the floor itself carries a 50 ms margin.

A worked jitter example

This is a simulation with the real classes (illustrative arrivals, not live traffic). Updates every 100 ms at 10 Hz, usually 40 ms after they are due plus a few milliseconds of noise, then three late packets (70, 45 and 60 ms late). After the warm-up, the estimate is steady:

updatelatenessjitter (EWMA)target delay
11 (quiet)3.00.8101.7
12 (spike)69.94.9109.8
15 (spike)45.07.0114.0
18 (spike)60.09.9119.8
28 (quiet again)2.010.4120.9

A 70 ms late packet raised the jitter from 0.8 to 4.9, and the target from 101.7 to 109.8. That is the honest summary of the design: it does not absorb a single spike. The first late packet still arrives later than the margin allowed, and the entity still freezes and then hops. What it learns is that the link is not quiet, and the margin for the next one grows. After three spikes in thirty updates the target is 121, so a 20 ms spike no longer matters.

The slew limit: moving the delay without moving the picture

A target is not a delay. Changing the delay changes now − delay, the cursor, and a cursor that jumps backwards makes every entity rewind; one that jumps forward makes them leap. So the actual delay chases the target with a speed limit, applied per millisecond of wall time:

// net/interpdelay.mjs
step(nowMs) {                                      // once per frame
  const dt = this.lastStepAt === null ? 0 : Math.min(MAX_STEP_MS, Math.max(0, nowMs - this.lastStepAt));
  this.lastStepAt = nowMs;
  const t = this.target;
  if (t > this.ms) this.ms = Math.min(t, this.ms + SLEW_UP * dt);        // up: 100 ms per second
  else if (t < this.ms) this.ms = Math.max(t, this.ms - SLEW_DOWN * dt); // down: 20 ms per second
  return this.ms;
}

Up is five times faster than down, because running dry freezes the picture, while a delay that is a little too long costs only latency. And because the delay changes by at most 0.1 ms per millisecond, the render time now − delay still moves forwards, at 0.9 to 1.02 times real time: it never runs backwards. The frame time used for slewing is capped at 100 ms, so a tab that wakes after a minute does not teleport the delay.

A worked stall

The harder case, simulated with the real classes: a 300 ms stall, then three batches arriving together, 299.9, 193.9 and 90.1 ms later than the estimate expected. The jitter estimate goes 0.47 → 19.1 → 28.7 → 30.6 and the target 138 → 157 → 161. The delay follows at 100 ms per second, and about 0.9 s later it is at 166 ms. Then it relaxes at 20 ms per second:

100 120 140 160 0 s 2 s 4 s 6 s 8 s 10 s 12 s 166 ms at 0.9 s 124.5 at 5.9 s 107.3 at 9.9 s dashed: target the estimate asks for solid: delay actually used delay, ms Stall at t = 0: 3 batches arrive together, 299.9, 193.9 and 90.1 ms later than the estimate expected.
Simulated with the real TickClock and InterpDelay: a 300 ms stall, then three batches at once. Up fast (100 ms per second), down slowly (20 ms per second).
after the burstdelay (ms)target (ms)
0.0 s102.3161.2
0.9 s166.1166.1
2.9 s151.8150.3
5.9 s124.5123.5
9.9 s107.3107.3
11.9 s104.1104.0

The shape is the point: a quick lunge upward when the link misbehaves and a long lazy decline when it stops. For about twelve seconds after a stall the game is a little more laggy than strictly necessary, and nothing hops. This is the trade. Nobody has ever complained that a game was 10 ms too smooth.

5. Where it is wired in

In the meadow, stamping is one small function. It feeds the clock and the delay once per distinct tick (a 32-entry chunk sequence all shares one tick, so the second chunk must not count as another sample), and returns the local time for the tick:

// parts/19e-netmeadow.js
const mClock = new HSIM.net.tickclock.TickClock(NETM_TICK_MS), mDelay = new HSIM.net.interpdelay.InterpDelay();   // NETM_TICK_MS = 50
const mStamp = (tick) => {
  if (tick !== mDelay.lastTick || !mClock.started) { mClock.observe(tick, performance.now()); mDelay.update(mClock, tick); }
  return mClock.toLocal(tick);
};
// every EntityFull / EntityDelta:  r.interp.push(mStamp(m.tick), sample)
// every frame:                     const delay = mDelay.step(now);  r.interp.sample(now, delay)
// every SelfState (20 Hz):         mClock.observe(m.tick, now); mDelay.rebase(mClock.snapMs);

Two streams feed one clock. Entity updates arrive at 10 Hz per viewer. SelfState arrives at 20 Hz, and its tick is on the same clock, so each one is another observation. That makes the clock converge in half the time and notice a fast delivery twice as often. But a SelfState snap moves the clock without passing through InterpDelay.update, so the delay is told through rebase(snapMs): the mean of lateness shifts by the snap, and the jitter is untouched. Without it, a clock snap seen by one stream would look like a jitter burst to the other.

Realm has the same two classes with a 50 ms tick, as NR.clock and NR.delay. Positions are stamped the same way. RealmSelf does not feed the clock (the realm client predicts itself the way part 2 described, and the tick events do the clocking). A realm snapshot (FULL) anchors the clock directly with NR.clock.start(NR.tick, now).

The delay is reset, along with the clock, wherever the old estimate is meaningless: on a meadow join or resume snapshot (mClock.reset(); mDelay.reset()), and in realm on clear, rejoin and layout (nrClockReset).

6. Not just positions: events in a dungeon

A dungeon sends more than positions: attacks, damage numbers, spawns, projectile creation and removal, telegraphs, orbs, phase changes. If a position is drawn 100 ms in the past but a damage number appears now, you see a monster explode 100 ms before it was hit. That is not netcode, that is prophecy.

So every event in a realm tick is queued with its tick's local time, and fired only when the render time reaches it:

// parts/19f-netrealm.js (trimmed)
const nrAt = (tick, fn) => NR.evs.push({ at: nrTickMs(tick), fn });   // nrTickMs = NR.clock.toLocal(tick)
for (const a of m.acts)    nrAt(m.tick, () => nrAct(a));
for (const d of m.damage)  nrAt(m.tick, () => nrDamage(d));
for (const s of m.shots)   nrAt(m.tick, () => nrAddShot(s));
// netRealmStep, every frame:
const now = performance.now(), renderNow = now - NR.delay.step(now);
// ... every queued event with ev.at <= renderNow runs and is removed
1000 1050 1100 1150 1200 1250 event stamped at (tick -> local time), fires when now - delay reaches it at 1020: attack fires at now = 1120 at 1070: damage 12 fires at now = 1170 at 1120: spawn fires at now = 1220 With delay 100 the render clock is 100 ms behind the real one, so an event stamped 1020 fires at now = 1120. Mobs follow the same rule: shown once now - delay >= showAt (spawn: its tick time; FULL: always).
Realm events (attacks, damage, spawns) wait in a queue. Each fires when the render time, now minus delay, reaches its stamp.

Mobs have the same rule. A newly spawned mob is not drawn until now − NR.delay.ms ≥ showAt, where showAt is the spawn tick's local time (a FULL snapshot uses −Infinity: draw immediately). Otherwise the mob would appear at its spawn position and then slide in from nowhere. Shots are ballistic (the client flies them from their start and direction) and capped at 6 seconds of age, because the server always ends them and a lost “gone” message must not leave a fireball in the sky forever.

7. What goes wrong, and what happens

SituationWhat the code does
A packet is lateFreeze (cursor past the newest sample, hold), then a hop when it arrives. Honest. The jitter estimate grows, so the margin for the next one does.
Several packets arrive at once (burst)Each carries its own tick, so each is stamped at its true time, not all at “now”. The entity does not teleport to the newest position; it replays the burst in order, a little behind. The jitter estimate rises, see the worked stall.
Long stall (tab hidden, GC)Lateness or gap over 1 s: ignored by the delay estimate. The slew uses at most 100 ms of wall time per frame. The client side prediction clamps at 0.25 s (part 2).
A faster packet than ever beforeClock snaps down. Delay estimate re-bases its mean. Ring stamps are clamped forward if a new sample would land before the previous one.
Update arrives out of orderAn older tick is a gap ≤ 0 for the delay (ignored); in the ring the stale stamp is clamped forward. Nothing rewinds.
Two chunks of one message sequenceSame tick: one clock and delay observation only. All chunks share one stamp.
Ring runs dryHold the last sample. No extrapolation.
Player leaves the 30 m circleThe server waits 3 passes (about 300 ms) before telling you he is gone, and cancels if he returns (part 1). A brief wobble at the edge does not make people flicker.
New snapshot, map change, reconnectClock and delay reset; the next update anchors them again. The delay re-warms for 8 updates at the floor.
Old client talks to a version 4 serverThe server refuses the join with BAD_VERSION. The client halts with an “Update needed” badge instead of drawing garbage.

8. Why it is built this way

  • Why not one fixed bigger delay, 150 ms? Because on a good link it is 50 ms of unnecessary lag for everyone, all the time; a person fighting a boss notices. The adaptive delay pays extra only on bad links, and only while they are bad.
  • Why a floor of 100? At 20 Hz it is two intervals, so even a quiet realm link has one interval of margin. At 10 Hz it is one interval. The floor is the cheapest sane choice, not a proven optimum.
  • Why a ceiling of 250? A quarter second in the past is as far as a fight can be run. A link worse than that needs another solution, probably a different ISP.
  • Why not extrapolate? Because a wrong guess has to be un-done, and an un-done guess is visible as rubber-banding. A hold looks like a pause, which is what a laggy network looks like anyway, and is what players have been trained to forgive.
  • Why jitter as mean deviation, not as a maximum? A maximum means one 900 ms hiccup inflates the delay for ever. An average with a ceiling responds, and forgets.
  • What it cannot do. It cannot make a late packet early. It shows the truth about when things happened, it makes the next late packet less likely to hurt, and for a few seconds after a stall it trades latency for smoothness.

That is every other player. Part 4 is about what happens when one of them (a monster, usually) hits you, and what the server does so that the hit does not land before you could see it coming. Then it gathers every edge case in one place, because by then they will have earned it.

← Part 2: predicting yourself  |  Next: part 4, fairness and edge cases →

← All posts