ARCANUM
← Blog
architecture

Netcode in Hanamori, part 2: predicting yourself

Your character moves the instant you press a key, on a connection that is not instant. How: the same float32 step on both sides, an input ring buffer, and a correction that eases in over 100 ms.

2 Nov 2026 · 19 min read · part 2 of 4

Part 1 ended with a promise: your own character moves the instant you press a key, on a connection that is not instant. This post is the trick. It is called client-side prediction, and it is the single most important thing in the whole stack. Without it every key press would wait for a round trip, and a round trip over the open internet is long enough to make walking feel like steering a barge.

The series: part 1 (tick, wire, area of interest), part 2 (this one: yourself), part 3 (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.

Prediction has three parts: apply each input locally at once, keep a list of the inputs the server has not yet confirmed, and when the server's state arrives, replay that list on top of it.

1. The client runs a fixed-step loop

The server ticks every 50 ms (part 1). For prediction to work, the browser has to take its steps at the same size: one step is 50 ms of movement. It cannot step once per rendered frame, because frames come at 60, 144 or “whatever this laptop felt like” per second. So the client keeps an accumulator, which is a running total to which each frame adds the time that passed. Whenever the total reaches 50 ms, one fixed step is taken and 50 ms is subtracted. Left-over time stays in the total.

This is the real loop (trimmed). Note the clamp: if the tab was hidden for a minute, the frame after it returns would try to take 1200 steps. The clamp makes it at most 0.25 s, so five steps at most.

// 19e-netmeadow.js, netMeadowStep (trimmed)
const now = performance.now();
const dt = NETM.lastT ? Math.min(0.25, (now - NETM.lastT) / 1000) : 0;   // wall clock, not frame time
NETM.lastT = now;
NETM.acc += dt;
while (NETM.acc >= NET_DT) {           // NET_DT = 0.05
  NETM.acc -= NET_DT;
  netFixedStep();                      // one 50 ms step: read keys, predict, maybe send
}
const a = NETM.acc / NET_DT;           // how far we are into the next step, 0..1
// draw at lerp(previous step, current step, a) + error ease offset

Why wall-clock time and not the frame time? Because the frame delta is itself clamped, and a slow client would fall behind the server. The server does not wait for slow clients. It also does not apologise.

frames ~60 Hz steps every 50 ms 0 50 100 150 200 250 300 ms acc / 50 ms the fraction a 1 0 this frame: 17 ms past a step a = 17/50 = 0.34 Rendered position = lerp(previous step, current step, a) + ease offset. The picture slides between steps.
The screen refreshes whenever it likes. The simulation steps every 50 ms on wall-clock time. The sawtooth is how far into the next step we are.

Two details in the figure matter. First, each step records prev (where we were) before taking the new step, so that drawing can slide from one to the other. Second, a rendered frame almost never lands exactly on a step, so the picture is a blend, a of the way from the old step to the new one. At 144 fps you draw roughly seven frames per step, each slightly further along. Smooth. Not magic, only arithmetic.

2. One step, written once, run twice

Prediction works only if the client and the server compute the same step from the same input. The movement rules (walk 5.6 m/s, run 14 m/s which is 0.7 m per step, dash 34 m/s for about 0.31 s, jumps, turning, the blocking slowdown) live in one file, sim/movement.mjs, and the server has a C++ port in hanamori/sim/Movement.h. Both must agree not “roughly” but to the last bit.

This sounds easy and is not. JavaScript does all arithmetic in 64-bit doubles. C++ uses 32-bit floats for the position. Two machines that disagree in the seventh decimal place will agree for a while, and then, 400 steps later, be two metres apart and each certain the other is cheating. So the JavaScript rounds every operation to float32 with Math.fround, and it does not call the platform's sin, cos or atan2 at all, because those are allowed to differ by browser and CPU. fmath.mjs has its own fsinDeg, fcosDeg and fatan2Deg. The C++ port is bit-for-bit, and the tests compare both against shared golden vectors.

// movement.mjs: the step both sides run. DT is rounded to float32 once, on purpose.
export const DT = f(0.05);

The input to a step is a tiny struct, the same on both sides:

// shape: what netFixedStep builds each step (field names are the real ones)
const inp = {
  fwd: +1 | 0 | -1,        // W / S
  turn: +1 | 0 | -1,       // A / D
  run, block,              // held keys
  jump, dash,              // edges: true for exactly one step
  autoTarget,              // item id the player clicked, 0 if none
  viewYaw,                 // where the camera looks (float32), steers the character
};

Held keys and edges differ. “Run” is true for as long as you hold Shift. “Jump” must be true for exactly one step, even if you press it between steps, so key presses are latched into jumpQueued and NETM.dashQ and cleared once the next step has read them (see the two lines after inp in the source). Otherwise a quick tap that happens between two steps would be lost, and the game would feel as if it only works when you press with intent.

3. The input ring buffer: unconfirmed inputs

Each step the client does two things with the input: it applies it to the predicted state immediately, and it appends it to the list of unconfirmed inputs. The list is the Predictor. It is a bounded buffer: 256 entries at most, oldest dropped first, which at 20 steps per second is 12.8 s of unacknowledged input, about 11.8 s more than any healthy connection needs.

// net/predict.mjs (trimmed to the parts that matter)
const MAX_PENDING = 256;
const SNAP_M = 4;

input(seq, inp) {                       // called once per 50 ms step
  if (!this.st) return;
  this.stepFn(this.st, inp);            // predict: move now
  this._pend.push({ seq, inp });        // remember until the server acknowledges `seq`
  if (this._pend.length > MAX_PENDING) this._pend.shift();
}
pending()  { return this._pend.length; }
unacked(n) { return this._pend.slice(-n); }   // the newest n, oldest first

A word about the name. It is a ring buffer in behaviour (bounded, oldest overwritten, newest at one end), but it is implemented as a plain array with push and shift, which for 256 entries of 20-per-second input costs nothing measurable. The server side, by contrast, uses a true fixed ring (section 5). I mention it so that nobody goes looking for modular arithmetic here and feels cheated.

seq 1195 dropped seq 1196 dropped seq 1197 pending seq 1198 pending seq 1199 pending seq 1200 pending seq 1201 pending seq <= lastSeq 1196 shifted off the front replayed through the step, in order: 5 inputs unacked(4): the newest four ride in the next Input message client._pend (cap 256: push at the back, shift the oldest off the front) The oldest pending entry (1197) is not resent: it already left in the previous message.
The pending list after a SelfState with lastSeq 1196. It is the replay source and the send source at once.

Each step gets a sequence number, ++NETM.seq. It only ever grows. The server will echo back “the last sequence number I applied”, and everything up to that number is thrown off the list. What is left on the list is exactly the set of steps the server has not yet confirmed, which is the set we will need to redo.

4. Sending the inputs, over a network that loses things

The client sends input every second step, that is 10 messages per second, not 20. And each message carries not only the newest unacknowledged input but up to the newest four:

// 19e-netmeadow.js
const netSendInputs = () => {
  let list = pred.unacked(4);
  if (!list.length && NETM.last) list = [NETM.last];   // everything acked: repeat the newest (the server drops stale seqs)
  if (!list.length) return;
  netSend({ _t: 'Input', inputs: list.map(({ seq, inp }) => ({ seq, keys: { /* ... */ }, edges: { jump: inp.jump, dash: inp.dash }, autoTarget: inp.autoTarget, viewYaw: inp.viewYaw })) });
};
// and in netFixedStep:  if (++NETM.sinceSend >= 2) { NETM.sinceSend = 0; netSendInputs(); }

Why four every 100 ms? Each message covers the two steps taken since the last one, plus the two before them, as insurance. If one message is lost, the next one repeats its inputs and the server gets them anyway. (WebSocket is TCP, so a packet is not lost as such: it is delayed behind a retransmission. The redundancy is still useful, because a message that arrives 300 ms late arrives together with the next one and the server then has a backlog to chew through, section 5.) This is paid for with a few bytes. An input record is a handful of bytes and the message is sent 10 times a second. It is cheaper than a conversation about reliability.

When everything has been acknowledged and you are standing still, the list is empty. The client then re-sends the newest input anyway, as a heartbeat of sorts. The server will drop it as stale (same or older sequence), which is the point: that is cheaper than inventing a new message type.

5. The server's side: a queue that does not trust you

Inputs arrive on the server in batches, sometimes out of order, sometimes duplicated by the redundancy above, sometimes in a bunch because the network held three of them in a warm room and let them out together. The server cannot run them as they come. It runs one input per player per tick, so that you cannot move faster by sending more messages. That is what the per-player InputQueue is for.

InputQueue (std::array<InputCmd, 8>) seq 1198 seq 1199 seq 1200 seq 1201 seq 1202 empty empty empty head: next() takes this one tail: push() writes here push(c): if c.seq <= newestSeq: ignore (a repeat from a redundant batch). If full: drop the oldest. Else: append. next(), once per tick queue not empty apply it; it becomes held input empty, held < 10 repeat keys; no edges, no target empty, held >= 10 neutral input drained 10 ticks a new input arrives: back to the first state, held counter reset SelfState echoes lastApplied either way, so the client knows which of its inputs have been used.
Server side: one ring of 8 per player, and a rule for the tick when the ring is empty.

The rules, each with its reason:

  • Capacity 8, drop the oldest when full. A long stall followed by a flood must not make the server replay ten seconds of history. If the backlog exceeds eight, the oldest inputs are discarded. You will be corrected (section 7).
  • A sequence number that is not newer than the newest seen is ignored. This applies to applied or still queued inputs. The redundancy of section 4 sends every input up to four times; without this rule you would move four times as fast. That would be a free speed hack.
  • Empty queue: repeat the held keys for up to 10 ticks (0.5 s), with no edges and no auto-target. A hiccup of a tick or two should not make you stop and start. But after half a second the character goes neutral, so that a frozen tab does not walk into the sea.
  • The queue also tells you which input it just applied. next() returns the input and the sequence number. That number is echoed back in SelfState.lastSeq, and it is the acknowledgement the whole scheme rests on.
// include/meadow/sim/InputQueue.h (the heart of it)
void push(const hproto::InputCmd& c) {
    if (haveSeq_ && c.seq <= newestSeq_) return;          // stale or repeated
    haveSeq_ = true;
    newestSeq_ = c.seq;
    if (n_ == CAP) { head_ = (head_ + 1) % CAP; n_--; }   // full: drop the oldest
    q_[(head_ + n_) % CAP] = c;
    n_++;
}
std::pair<hsim::MoveInput, uint32_t> next() {
    if (n_ != 0) { /* pop the head, remember it as "held", lastApplied_ = c.seq */ }
    if (haveHeld_ && holdUsed_ < HOLD_TICKS) {            // HOLD_TICKS = 10
        holdUsed_++;
        hsim::MoveInput r = held_;
        r.jump = false; r.dash = false; r.autoTarget = 0; // edges are not repeated
        return {r, lastApplied_};
    }
    return {hsim::MoveInput{}, lastApplied_};             // neutral
}

Realm has a sibling, RealmInputQueue, with the same rules and one difference. If the queue is full and an old input is dropped, the dropped input's edges (attack, special, dodge, swap, jump, potions) are OR-ed into the new oldest entry. Nobody wants to lose a dodge to a queue overflow. A dodge is the one key you press at the exact moment you are about to be hit.

One more thing the server does on the way in. If viewYaw is not a finite number (a client bug, or a person with a hex editor and ambition), the codec rejects it, and the simulation substitutes the player's current yaw. It does not throw, it does not disconnect, it just does not take the suggestion. Messages in general are also rate-limited, 120 per second with a burst of 40, and the decoder never throws on malformed input (part 1).

6. The acknowledgement: SelfState

Every tick, after the movement is done, the server tells each player the truth about that player. This is step 4 of the tick in part 1, and it is not subject to the area of interest: you always hear about yourself, 20 times a second. The message is SelfState, and its relevant fields are: lastSeq (the last input applied), tick, position x y z, yaw, vertical speed, speed, the dash fields, flags, and autoTarget.

The ladder below follows one input through a connection with a one-way delay of 50 ms (a perfectly civilised 100 ms round trip, illustrative). Read it as a sequence: the client steps at 0, 50, 100 and so on. The input made at 50 ms leaves in a message and arrives at 100 ms. The server's next tick is at 120 ms; it applies input 1197 and sends back lastSeq = 1197. That reaches the client at 170 ms. By then the client has already taken steps 1198, 1199 and 1200.

CLIENT SERVER 0 ms step 1197 50 ms step 1198 100 ms step 1199 150 ms step 1200 200 ms step 1201 250 ms step 1202 applies 1197 applies 1198 applies 1199 applies 1200 Input [.., 1197, 1198] Input [.., 1199, 1200] SelfState, lastSeq 1197 lastSeq 1198 lastSeq 1199 ack 1197 lands: pending 1198, 1199, 1200 replay The client always lives a little in the future of the server: every ack describes a state that is already a round trip old.
Message ladder, one-way delay 50 ms (illustrative). The ack for 1197 arrives 120 ms after the client made that step.

That is the awkward and important fact. An acknowledgement is always about the past. When the client hears “after 1197 you were here”, it has already walked three more steps on its own authority. It cannot simply jump to the server's position, or it would be thrown three steps back every tick, which is exactly what unpredicted games feel like. It has to redo those three steps on top of the server's answer.

7. Reconciliation: rewind, replay, compare

Here is reconcile. It is short, and the whole idea lives in it. In words: remember where we think we are; drop every input the server has applied; take the server's state as truth; apply the remaining unacknowledged inputs to it with the same step function; the result is where we should be; the difference between where we thought we were and where we should be is the error.

// net/predict.mjs
reconcile(serverState, lastSeq, posOf) {
  const before = this.st ? posOf(this.st) : null;                    // where we thought we were
  while (this._pend.length && this._pend[0].seq <= lastSeq) this._pend.shift();   // server has these
  const st = this.cloneFn(serverState);                              // start from the truth
  for (const p of this._pend) this.stepFn(st, p.inp);                // redo the rest
  this.st = st;
  if (!before) return { errX: 0, errY: 0, errZ: 0, snap: false };
  const after = posOf(st);
  const errX = before.x - after.x, errY = before.y - after.y, errZ = before.z - after.z;
  return { errX, errY, errZ, snap: Math.hypot(errX, errY, errZ) > SNAP_M };
}

If the client and server agree about the rules and the inputs, the error is zero, exactly. Not “small”: zero, bit for bit, because of the float32 work in section 2. This is the normal case and it costs five or six float steps per tick, which a phone can do while thinking about something else.

Now a worked example, with numbers (illustrative, chosen to be easy to follow). You are running along one axis at 0.70 m per step. The server's state for input 1196 is at 104.34 m. Your pending list is 1197 to 1201, five inputs. Replaying them from the server's state gives 104.34 + 5 × 0.70 = 107.84 m. But your old prediction said 107.70 m. How can that be? Say a pair of boots that makes you faster was equipped. The server applied the bonus when it processed the input; your browser learned about it a round trip later. For those steps your guess was a bit slow. The error is old minus new, 107.70 − 107.84 = −0.14 m.

104 105 106 107 108 m server state at seq 1196 104.34 m replay 1197 to 1201: 5 x 0.70 m replayed head 107.84 m old predicted head 107.70 m error = old - new = 107.70 - 107.84 = -0.14 m 0.14 m < 4 m, so: ease it away over 100 ms. Above 4 m: snap. Example cause: boots that speed you up. The server applied the bonus a round trip before your browser learned about it.
Reconcile on a line (illustrative numbers). The replayed head is where you should be; the old head is where you were drawn.

So what do we do about 14 centimetres? We have two options, and the code uses both, depending on size.

8. Snap or ease

If the error is more than 4 m (SNAP_M), something is badly wrong: you were teleported, a dash was lost, the join or resume reset your state. No gentle fix would look right. The client snaps: the offset is cleared and the picture jumps. It is a hard cut, and it is honest. (There is no special “teleport” message in the protocol. A teleport is only a large error, and a large error is a snap.)

Otherwise the client eases. The predicted state is already corrected (the replay put it in the right place), but the picture is not allowed to jump. Instead the old error is added to the drawn position as an offset, and the offset fades linearly to zero over 100 ms (EASE_S = 0.1). In the first frame the picture is exactly where it was; 100 ms later it is exactly at the truth. In between you see a slight slide that nobody has ever described as a bug.

// net/predict.mjs
const EASE_S = 0.1;
set(err, snap) {
  if (snap) { this.x = this.y = this.z = 0; this.t = EASE_S; return; }   // hard cut
  const k = this._k();                                    // how much of the old offset is left: 1 - t/0.1
  this.x = this.x * k + err.errX; /* y, z the same */      // keep the residual, add the new error
  this.t = 0;
}
offset(dt) {
  this.t = Math.min(EASE_S, this.t + dt);
  const k = this._k();
  return { x: this.x * k, y: this.y * k, z: this.z * k };
}

Note the line that keeps the residual. SelfState arrives every 50 ms, but the ease lasts 100 ms. So there is almost always an ease in progress when the next error arrives. If the code reset the offset to the new error, the picture would jump by whatever was left of the old one. Instead it adds: the picture continues from exactly where it is. The figure shows this for two errors of 0.14 m, 50 ms apart: the second starts at 0.07 (what is left of the first) plus 0.14, which is 0.21, then fades.

0 ms 50 ms 100 ms 150 ms 0.07 0.14 0.21 offset (m) error 1: 0.14 m error 2 arrives: 0.07 left + 0.14 = 0.21 k = 1 - t/0.1 reconcile() returns err snap = hypot(err) > 4 m snap offset cleared, picture jumps else: ease x = x * k + err, t = 0 > 4 m else
ErrorEase: a residual that is still easing when the next error arrives is kept and added to, never reset.

One more piece of bookkeeping, in the SelfState handler. When an error is eased, NETM.prev (the previous step's position used for the in-between drawing) is shifted by the same error:

// 19e-netmeadow.js, netOn('SelfState') (trimmed)
mClock.observe(m.tick, performance.now()); mDelay.rebase(mClock.snapMs);   // feeds the clock of part 3
const r = pred.reconcile(selfToState(m), m.lastSeq, posOf);
if (r.snap) {
  ease.set(r, true);
  NETM.prev = { x: pred.st.x, y: pred.st.y, z: pred.st.z, yaw: pred.st.yaw };   // no blending across a cut
} else {
  ease.set(r, false);
  NETM.prev.x -= r.errX; /* y, z the same */      // shifting prev by the error keeps lerp(prev, cur) continuous
}

Without that shift the drawn position would be lerp(prev, cur, a) + offset where cur moved by the correction and prev did not, which adds a visible little twitch half a step long. With the shift, the correction goes entirely into the offset, and the offset fades. Fix in one line; finding it took, I assume, a long evening.

9. In a dungeon: predicting more than position

The dungeon (realm) uses the same Predictor, with a different step function, stepRealm, and a richer per-hero message, RealmSelf, sent every tick to the hero it describes. It carries the same lastSeq, and in addition knockback velocity (kx, kz), hit points, mana, and the state of the current action (act, actT).

The client predicts three things: position, knockback and the action state, which means the timing of attacks, specials, dodges, swaps and jumps. The timing half of the server's hero action logic is ported to net/realmacts.mjs. This is why pressing attack plays the swing at once and the dodge begins before the server has heard of it.

What is not predicted: damage, death, the start of knockback from a hit, the “hurt” and “block hit” reactions, potions and pickups. These depend on things the client cannot know (where the monster really is, whether a hit really landed), and predicting them would mean showing you a number and then retracting it. The server announces them in tick events, and part 3 shows how the client schedules them so that they appear in step with the world. The input edges in realm are: attack 1, special 2, dodge 4, swap 8, jump 16, HP potion 32, MP potion 64, packed into one byte-sized mask.

10. What goes wrong, and what happens

SituationWhat the code does
Tab hidden for a minute, then shownFrame dt clamped to 0.25 s: at most five catch-up steps. The server meanwhile held your keys for 10 ticks, then went neutral. By then the error is well over 4 m: snap.
Input messages arrive in a clumpThe queue holds up to 8 and applies one per tick. Over 8 and the oldest are dropped (edges merged in realm). The client is corrected, normally by an ease.
Same input arrives twice (redundancy)Dropped: sequence not newer than the newest seen.
Input arrives out of orderThe older one is dropped for the same reason. It was already covered by the redundant copy in a later message.
No input at all for half a secondHeld keys repeat for 10 ticks, then neutral. Jump, dash and auto-target are never repeated.
Client sends a non-finite viewYawCodec rejects it, server substitutes the current yaw.
Client sends too fast (over 120 per second, burst 40)Rate limiter drops the excess. Pong is exempt.
Server state jumps by more than 4 mSnap. This is the whole “teleport” mechanism: there is no teleport message.
Pickup request while inputs are still queuedThe server waits until the applied sequence catches up with the newest received, up to 10 ticks (PICK_WAIT_TICKS), so that you pick up an item from where you were, not where you were seven steps ago.
Hero is deadThe client sends zeroed inputs while H.dead.

11. Why it is built this way

  • Why not just wait for the server? At 100 ms round trip, every key press would feel 100 ms late, and 100 ms is where “responsive” stops.
  • Why not trust the client's position? Because then anyone can type a position. The server runs the same step on the same inputs and its answer is the one that counts. The client may be wrong; it may not be believed.
  • Why replay, rather than just adjust the position by the error? Because the correction changes what the next steps do (a wall, a speed change). Replaying with the real step function gives the exact result, at the cost of at most a few steps of arithmetic.
  • Why ease at all? Because a position that is right and a picture that is right are different things, and the person is looking at the picture.
  • What does it cost? The client needs the step function (shared, tested against golden vectors), a few hundred bytes of pending list, and the occasional 14 cm slide. The server needs one small queue per player.

That covers you. Everyone else is a different problem entirely: you have no inputs for them and no rulebook to run, only a stream of positions that arrive late and unevenly. Part 3 is about drawing them anyway.

← Part 1: the tick, the wire and the area of interest  |  Next: part 3, seeing everyone else →

← All posts