Netcode in Hanamori, part 1: the tick, the wire and the area of interest
The 20 Hz server tick, the fixed-layout binary wire, the area of interest, and why every update about another player now carries the tick it describes. With the real code.
Hanamori is a game in which many people stand in the same field and each believes they are standing in it right now. They are not. Every one of them is looking at a picture that is already a little old, sent by a server that is a little far away, over a network whose main hobby is being late. Netcode is the craft of keeping that illusion alive without anyone noticing. This is the first of four posts about how Hanamori does it. They are long on purpose: the previous version of this post fit the whole subject into nine minutes, which is about as accurate as describing the ocean as “damp”.
The meadow server is Hanamori's open-world server; realm servers run the dungeons. The servers are built as described in Shared-nothing, and the way they talk to each other is in Hanamori on Rune. None of that is on this path. Here we only care about the single WebSocket between one browser and one server, and the few thousand bytes per second that decide whether your character looks smooth or looks like it is being operated by a nervous puppeteer.
The series:
- Part 1 (this one): the tick, the wire, who gets told what, and the tick number that every entity update now carries.
- Part 2: your own character. Prediction, the input ring buffer, the server's input queue, reconciliation, snap versus ease.
- Part 3: everyone else. Tick stamps, the clock estimator, the adaptive interpolation delay, with a jitter worked example.
- Part 4: fairness in dungeons. Hit grace, the trace ring, what is deliberately not rewound, and a catalogue of the things that go wrong.
Each idea is explained, then shown in code and in a diagram. Code is copied from the source where it is short. A block marked trimmed has had lines removed; a block marked shape is illustrative and not a quote. Numbers come from the code; worked examples are marked as such.
What changed today
Short version for people who read the old post. Until today the browser stamped every remote player update with the time it received it, and drew remote players a fixed 100 ms in the past. Now:
ENTITY_FULLandENTITY_DELTAcarry the server's simulationtick(protocol and schema version 4). Remotes are stamped by server tick, not by receive time.- A shared estimator,
TickClock, maps server ticks to the local clock.SelfStateticks feed it too. - An adaptive
InterpDelayreplaces the fixed 100 ms. It works out toclamp(interval + 2 × jitter, 100, 250)ms. Both the open-world meadow and the dungeons (“realm”) use it. - Realm one-off events (attacks, damage, spawns) now fire when
at <= now - delay.ms.
Why: a fixed 100 ms delay at a 10 Hz update rate means the picture is drawn exactly one update behind the newest data. Zero spare. The first late packet leaves nothing to draw. Part 3 does the arithmetic. First we need the vocabulary, which is this post.
| Fact | Value | Where it lives |
|---|---|---|
| Simulation tick | 20 Hz, 50 ms. The meadow server and the realm server | SimProcessor.h, RealmWorker.h |
| SelfState to you | every tick, 20 Hz | SimWorld::sendSelfState |
| Input from you | a message every 2nd step, 10 Hz, up to 4 inputs each | netSendInputs |
| Other players, meadow | 10 Hz per viewer, two staggered phases, 30 m radius | AoiSystem.h |
| Everyone, realm | 20 Hz, one shared frame, no area of interest | RealmWorker::publish |
| Wire | SBE binary, schema 140, protocol 4, one message per WebSocket frame | Codec.h |
| Interpolation delay | adaptive, 100 to 250 ms | net/interpdelay.mjs |
1. The problem: everybody is late
The server owns the truth. Clients send intent (keys, never positions), so there is no position to forge. That solves cheating and creates a new problem: your key press travels to the server, the server decides, and the answer travels back. A perfect straight fibre from New York to London costs roughly 28 ms each way before a single router has had a thought, and real routes are neither straight nor thoughtless. At 100 ms of round trip, a game that waits for the answer before moving your character feels like walking through yoghurt.
So Hanamori uses three tricks, one per post:
- Predict yourself. Run the same movement code locally, show the result at once, and quietly fix it when the server disagrees. (Part 2.)
- Show others in the past. You cannot know where another player is now. You can know where they were 100 ms ago, and you can draw that smoothly. (Part 3.)
- Be kind in fights. In dungeons, a monster's hit waits long enough for your screen to have shown it coming. (Part 4.)
All three depend on the same two things: a clock everyone agrees to count in, and a wire that carries it. That is why this post is about ticks and bytes.
2. The tick: 20 Hz fixed steps
The simulation runs at 20 Hz, 50 ms per tick. That is slow next to a 60 Hz monitor on purpose: each tick costs CPU for every player, and
a human cannot tell 50 ms steps from smaller ones once you interpolate between them (part 3). The same number appears three times, which is the point: the server loop,
the client's fixed step, and the shared movement step all use a DT of 0.05 s. If those disagreed, prediction would be a rumour.
// movement.mjs: the step both sides run. DT is rounded to float32 once, on purpose.
export const DT = f(0.05);
One tick on the meadow server does these things, in this order. The order matters: the same-tick SelfState must describe the state after the input was applied,
and the AOI pass must read positions after movement.
// SimWorld.h, tick() (trimmed) void tick(int64_t nowMs, Outbox& out) { ++tick_; // 1. one input per player, through the shared float32 step forEachPlayer([&](Player p) { auto [in, seq] = p.in.queue.next(); p.in.lastSeq = seq; p.in.lastStep = hsim::step(st, in, goal, p.ps.speedMul, map_); // ... store position, re-bucket in the spatial grid }); // 2-3. auto-arrival, pickups, gold auto-pick // 4. SELF_STATE to every player forEachPlayer([&](Player p) { sendSelfState(p, out); }); // 5. AOI: every tick, for the half of the viewers whose phase matches (each viewer still runs at 10 Hz) aoi_.run(reg_, grid_, out, static_cast<uint8_t>(tick_ & 1), static_cast<uint32_t>(tick_)); // 6. portal and item timers 7. persist positions }
Different messages leave at different rates, because they have different jobs. Your own state needs every tick, because you are comparing it with your prediction. Other people can afford half that, because you are going to interpolate them anyway. The result is the schedule below.
Two things in that picture are worth saying out loud.
- Each viewer is updated at 10 Hz, not the whole server. The viewers are split into two phases by parity. Phase 0 viewers get their AOI pass on even ticks, phase 1 on odd ticks.
The server keeps the two phases balanced (
phaseCount_), so no tick pays for the whole population. Cost smoothing, not a rule of physics. - The tick number is the shared clock. Tick 1200 means the same thing to the server, to you and to the player behind you in the queue for the portal. The question “what time is it?” has a very good answer on the server (“tick 1200”) and a hard one on the client (“tick 1200 was some time ago; how long?”). Part 3 is the answer to that.
Realm is faster and simpler
Dungeons run the same 20 Hz loop (RealmWorker.h: “One tick (20 Hz, FrameSyncIdleStrategy) per doWork”). Each tick, every active hero gets a private RealmSelf
(the realm cousin of SelfState), and everybody gets one shared RealmTick frame. There is no staggering and no 10 Hz. A dungeon holds a handful of heroes, so the server
can afford to tell everyone everything, every tick.
3. The wire: fixed-layout binary messages
Hanamori speaks SBE, Simple Binary Encoding. A message is a fixed header, a fixed block of fields, and optional repeating groups. There are no field names on the wire,
no quotes, no braces. The schema (hanamori-wire.xml, schema id 140) is turned into a C++ codec for the server and a JavaScript codec for the browser, so both sides agree on every byte.
One message is one WebSocket binary frame; WebSocket gives order and delivery, SBE gives the shape.
The 8-byte header is four u16s: block length, template id, schema id, version. The client reads the template id straight out of the header when a frame will not decode,
so it can count failures per message type:
// net/conn.mjs, Conn._rx _rx(data) { if (!(data instanceof ArrayBuffer)) return; // text frames are not part of the protocol const u8 = new Uint8Array(data); this.stats.rx++; const m = decode(u8); if (!m) { const tid = u8.length >= 4 ? u8[2] | (u8[3] << 8) : -1; // template id sits at byte 2 this.stats.decodeFail[tid] = (this.stats.decodeFail[tid] || 0) + 1; return; } this._onMsg(m); }
Text frames are ignored; a frame that does not decode is counted and dropped. The decoder never throws on garbage, because the garbage comes from the internet.
The messages that matter for netcode
Here are the schema entries (from hanamori-wire.xml, field lists shortened) for the three messages that carry almost all the weight:
// shape, from the schema (fields abbreviated) Input (id 2) group inputs[<=4]: seq u32, keys, edges, autoTarget u32, viewYaw f32 SelfState (id 66) lastSeq u32, tick u32, x y z yaw vy speed f32, dash*, flags, autoTarget EntityFull (id 67) tick u32, group entities: id u64, name[16], x y z yaw f32, anim u8 // 42 bytes each EntityDelta (id 68) tick u32, group entities: id u64, mask u8, data (1-byte length + payload)
Inputcarries up to four inputs (MAX_INPUTS = 4). Each has a sequence numberseq, six held-key bits (forward, back, left, right, run, block), edge bits (jump, dash), an auto-move target, and the camera yaw. The server never sees a position from you. Part 2.SelfStateis your own character as the server computed it, pluslastSeq(the last input of yours that was applied) andtick. The first is the acknowledgement. The second is the tick stamp. Part 2 useslastSeq; part 3 usestick.EntityFull/EntityDelta/EntityGoneare other players. Next section.
Guard rails on the wire
- Version gate. The client sends
protocolVersioninJoin. A mismatch getsJoinFailwith code 7 (BAD_VERSION) and the client halts with an “Update needed” badge instead of retrying forever. Today's bump from 3 to 4 means an old browser tab is told to reload, which is a more polite failure than silently reading the new tick field as part of the first entity. - Rate limit. On the meadow, per connection, a token bucket of 120 messages per second sustained with a burst of 40;
Pongis exempt. Honest clients send about 10Inputs a second and never notice it. - Malformed frames.
decode()never throws and rejects anything that is not exactly one well-formed message: wrong length, reserved mask bits, out-of-range counts. A non-finiteviewYawin anInputrejects the message in the codec, and the sim substitutes the current yaw as a second line of defence. - Reconnect. Backoff doubles from 1 s and caps at 8 s (
backoffMs: 1000, 2000, 4000, 8000). A version mismatch halts instead of looping.
4. Who gets told what: the area of interest
The meadow is large and may be crowded, and sending every player to every other player is quadratic. AoiSystem (area of interest) limits each viewer to
players within 30 m. A spatial grid of 32 m cells does the cheap first cut; an exact horizontal distance test (dist² ≤ 900) does the rest. There is no cap on how many players a viewer can see.
A pass for one viewer works like this. It is the most intricate piece of the server side, so here are the steps in the order the code does them:
- Snapshot once. At the start of a pass, every player's state is copied once into a dense array. All viewers read the snapshot, never the live components, so everyone in the pass sees the same instant. That instant is the tick.
- Query. Ask the grid for the boxes around the viewer, then keep the ones within 30 m.
- Merge against the viewer's subscriptions. The viewer has a sorted list of ids it has been told about, each with a baseline: the last state sent. For each nearby id:
- new → a FULL entry; baseline := exactly what the FULL carried.
- known → compare each field bitwise with the baseline (no epsilon). A mask of the fields that differ. Mask 0 sends nothing; otherwise a DELTA entry, and the baseline takes the new values.
- out of range → start a countdown of 3 passes (about 300 ms); at 0, send GONE. Coming back in range cancels it. No GONE, no FULL; the baseline still matches what the client holds, so the next DELTA catches it up.
- Chunk and send. Entries go out in messages of at most 32 (
AOI_CHUNK). GONE is one message per id.
Two notes on cost, because the server does this for every viewer, ten times a second.
- Encode once. A target's 42-byte FULL entry is encoded once per tick and copied into every viewer's message. A DELTA entry depends on the viewer's baseline, but in the steady state that baseline is the target's snapshot from the viewer's previous pass, so the mask and the bytes are the same for every such viewer and are computed once and copied. The last two snapshots are kept for that.
- Silence is free. A player standing still produces no delta at all. This matters for part 3: for a standing player, the interpolation ring simply holds its last sample.
Full versus delta, byte by byte
A FULL entry is 42 bytes: id (8), name length (1), name (16), x, y, z, yaw (4 each), animation (1). A DELTA entry is an id, a mask, a length, and only the fields whose mask bit is set, little-endian, in bit order: bit 0 x, 1 y, 2 z, 3 yaw, 4 animation. The three high bits are reserved and must be zero. The codec is short enough to read:
// DeltaCodec.h (trimmed) struct DeltaFields { static constexpr uint8_t X = 1u << 0, Y = 1u << 1, Z = 1u << 2, YAW = 1u << 3, ANIM = 1u << 4; static constexpr uint8_t ALL = X | Y | Z | YAW | ANIM; // 0x1F static constexpr size_t packedSize(uint8_t mask) { return 4u * std::popcount(unsigned(mask & 0x0F)) + ((mask & ANIM) ? 1u : 0u); } // ... static bool unpack(uint8_t mask, const uint8_t* data, size_t len, DeltaFields& out) { if ((mask & ~ALL) != 0 || len != packedSize(mask)) return false; // reserved bit, or wrong length // ... read the set fields in bit order } };
And the browser's side of the same contract, reading the mask the same way:
// parts/19e-netmeadow.js, EntityDelta handler (trimmed) netOn('EntityDelta', (m) => { const tMs = mStamp(m.tick); // one stamp for the whole message for (const e of m.entities) { const r = remotes.get(e.id); if (!r || !(e.data instanceof Uint8Array)) continue; // a delta for an unknown id is ignored const s = Object.assign({}, r.last), mask = e.mask; let p = 0; if (mask & 1) { s.x = dv.getFloat32(p, true); p += 4; } if (mask & 2) { s.y = dv.getFloat32(p, true); p += 4; } if (mask & 4) { s.z = dv.getFloat32(p, true); p += 4; } if (mask & 8) { s.yaw = dv.getFloat32(p, true); p += 4; } if (mask & 16) { s.anim = dv.getUint8(p); p += 1; } r.last = s; r.interp.push(tMs, s); } });
Worked example. Player 77 at tick 1200 moved sideways: x and z changed, nothing else. The mask is 0b00000101 = 0x05, the payload is 8 bytes, the entry is
8 + 1 + 1 + 8 = 18 bytes. In a message that carries only that entry, the total is 8 (header) + 4 (tick) + 4 (group dimension) + 18 = 34 bytes. The FULL for the same player is 42 bytes
per entry, plus the same 16 bytes of message overhead. Deltas are small; they are also the reason a client needs a FULL first, and why a delta for an unknown id is ignored on the meadow.
5. The new field: a tick stamp on every update
Before version 4, an ENTITY_* message said where things were but not when. The browser used the moment the frame arrived. That folds every
bit of network jitter into the motion: a late frame looked like a slow player, and a burst looked like a teleport. In version 4, EntityFull and EntityDelta have a root field,
tick (u32), the simulation tick the batch describes, on the same clock as SelfState.tick. It is one per message, not per entity: 4 bytes whatever the count.
// AoiSystem.h: every FULL / DELTA message of a pass is stamped with the pass's tick void run(entt::registry& reg, const SpatialGrid& grid, Outbox& out, uint8_t phase = ALL_PHASES, uint32_t tick = 0) { tick_ = tick; takeSnapshot(); for (const ecs::Entity ve : group_) if (phase == ALL_PHASES || subStore_->get(ve).phase == phase) viewer(ve, grid, out); } // sendFulls (trimmed): the generated codec writes the root field const size_t sz = hproto::encode<hproto::EntityFull>(span, [&](hproto::EntityFull& m) { m.tick(tick_); auto& g = m.entitiesCount(static_cast<uint16_t>(n)); // ... }); // sendDeltas (trimmed): DELTAs are hand-assembled from a prefix captured at construction; patch the tick in std::memcpy(buf, deltaPrefix_.data(), DELTA_PREFIX); std::memcpy(buf + TICK_OFFSET, &tick_, sizeof tick_); // tick u32 LE
The hand-assembled delta path is the interesting part. For speed, DELTA messages are built from a prefix, not through the generated encoder. To make sure this shortcut cannot silently drift from the schema, the constructor encodes a probe message with the real codec and compares the bytes; if they differ it throws. The tick change touched exactly that: the prefix grew by the 4-byte root block, the group dimension moved, and the check was updated to look for the group dimension at the new offset. A schema bump that breaks the shortcut now fails at startup rather than in front of a player.
Both sides get the version bump: SCHEMA_VERSION = 4, PROTOCOL_VERSION = 4 on the server (Codec.h) and PROTOCOL_VERSION = 4 in the browser's sim/protocol.mjs.
A tick is a u32 at 20 Hz, so it wraps after about 6.8 years of uptime. The server, one hopes, will have been restarted for other reasons by then.
One ordering detail that makes the tick honest
The tick on an entity message means “the state at the end of this tick”. That is true because the AOI pass runs after movement in the same tick (step 5 after step 1 above), and because it reads the snapshot taken at the start of the pass, not live data. A message cannot describe half of one tick and half of the next. Part 3 relies on that: it assumes that every entity in the message has the same timestamp.
6. Four things that do not exist
Netcode posts have a habit of describing the textbook version of the thing and letting you believe the product has it. Here is what is not in Hanamori, so you do not go looking.
- No ping or round-trip based clock sync in the meadow. The meadow server will answer a
Pingwith aPongif a client sends one, but the game client does not send it, and nothing uses a round trip to set a clock. The clock is estimated from tick stamps on arriving updates (part 3). Realm does measure round trip, once a second, but for one purpose: hit grace (part 4). - No extrapolation. If the interpolation ring runs dry, the entity holds its last sample. It does not guess where the player went. A late update shows as a pause, not as a prediction that has to be undone.
- No rewinding of monsters for player hits. When you swing at a monster, the server judges the swing against the monster's position now. Lag compensation exists only in the other direction, and it is not a rewind: it is a delay on monster hits (part 4).
- No area of interest in realm. A dungeon sends every hero to every other hero. The area of interest of section 4 is meadow only.
That is the vocabulary: a 20 Hz tick, a fixed-layout binary wire, a 30 m area of interest, and a tick stamp on every update. Part 2 takes the first of the three tricks: how your own character moves instantly on a connection that is not.