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.
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.
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.
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.
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 inSelfState.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.
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.
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.
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
| Situation | What the code does |
|---|---|
| Tab hidden for a minute, then shown | Frame 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 clump | The 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 order | The 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 second | Held keys repeat for 10 ticks, then neutral. Jump, dash and auto-target are never repeated. |
Client sends a non-finite viewYaw | Codec 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 m | Snap. This is the whole “teleport” mechanism: there is no teleport message. |
| Pickup request while inputs are still queued | The 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 dead | The 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 →