HorribleAssault's two clients
HorribleAssault has two clients, and they are not two views of one renderer:
| Browser | packages/core/src/modules/hassault/** — TypeScript + three.js, served as a page by apps/assault-web (the dashboard pane is a launcher for the native client and plays nothing) |
| Native | apps/native-fps/** — Rust + wgpu, a standalone OS window |
Both talk to the same backend over the same hassault /ws channel, read the
same served numbers, and render the same maps and the same character asset.
Neither is a port of the other in the sense of being generated from it: they
are two independent implementations that must agree.
This page exists because that agreement does not maintain itself. A feature added to one and not the other does not fail — it just makes the game different depending on which client you launched, and the person who notices is a player, not a test.
Every divergence on this page was found by looking at a screenshot, not by a failing build. The native client kept a rig of hand-posed boxes for a long time after the browser had a skinned character; its world was lit by a single hardcoded direction long after the browser had a light rig, a tone curve and surface grain. Both compiled. Both passed their tests.
The two reference directions
Confusion about which client is "right" is the root of most drift, so it is worth stating plainly, because the answer is different for different questions:
- The server is the reference for rules. Anything that decides an outcome —
the hitbox, weapon numbers,
plane_order, spawn placement, what is spotted, how much a fall hurts — is served, and a client that hardcodes a copy has created a divergence that produces no error. Neither client gets a vote. - The browser is the reference for look and feel. It is where the rendering work has historically landed first, so when the two disagree about how something looks, the browser is the target and the native client is behind until shown otherwise.
The second rule has one important exception, and it is worth internalising
because it burned an afternoon: the browser being the reference does not mean
copying three.js's numbers without its conventions. three treats a raw vertex
colour attribute as already-linear, applies 1/π inside its Lambert BRDF, and
converts a Color from sRGB on the way in. Port the light intensities without
the 1/π and every surface comes out π times too bright; add an sRGB decode
three does not do and every map comes out darker and more saturated. Both look
like the palette is wrong rather than the exposure.
What is duplicated, and how it is pinned
Some duplication is unavoidable — a Rust client cannot import a TypeScript module. What matters is whether the duplication is pinned by a shared fixture that both sides replay, or merely asserted in a comment.
Pinned
| Logic | Implementations | Fixture |
|---|---|---|
| Movement, collision, spawn placement | world.ts + player.ts, physics.py, physics.rs | __tests__/physics-vectors.json (cases, spawns) |
| Shot geometry | trace.ts, weapons.py, trace.rs | same fixture (traces, bodies) |
| Operator clip selection | models/clips.ts, clips.rs | __tests__/clip-vectors.json |
| Operator gait: stride, foot plants, pelvis turn and lean | models/locomotion.ts, locomotion.rs (in f64, to land touchdowns on the browser's frame) | __tests__/locomotion-vectors.json (UPDATE_LOCOMOTION_VECTORS=1) |
Demo format (.hademo): parse, id normalisation, interpolated sampling | demo.ts, demo.rs | __tests__/demo-vectors.json (UPDATE_DEMO_VECTORS=1) |
| Surface tint, face shades, detail tile | geometry.ts + surfaces.ts, geometry.rs + detail.rs | __tests__/surface-vectors.json |
| Radar frame (span, centre, rotation), blip sizes, floor bands, wall outline, palette, settings reader | radar-view.ts, radar.rs | __tests__/radar-vectors.json (UPDATE_RADAR_VECTORS=1); its noise radii are also read back by test_hassault_radar_heard.py |
| Light rig, sky, fog and point lights | atmosphere.py (served), atmosphere.ts, atmosphere.rs + lighting.wgsl.inc | tests/browser_parity.rs, which reads the TS and Python sources: fallback rigs, candela rule, attenuation |
| Image-based light, GGX | environment.ts (environmentRadiance, PMREM) + three's MeshStandardMaterial; environment.rs (CPU GGX prefilter) + dfg_lut.rs + shader.wgsl (shade_physical) | tests/browser_parity.rs: three's DFG table value for value, the Fresnel/multiscatter/roughness constants against three's chunks, the sky-and-ground function at its ends and midpoint; environment.test.ts |
| Sun shadow fit, High's shadow map, map normals | shadow-fit.ts (drawnBounds, shadowSphere) + aimSun, TIERS.high.shadowSize, world3d.ts (exported normals kept); shadow.rs fit, Quality::High preset, world3d.rs read_normals | tests/browser_parity.rs: the sphere in both, 4096 at High in both, no normal recompute; shadow-fit.test.ts |
| Surface breakup (anti-tiling, macro tint, grime), water surface | surface-breakup.ts (installSurfaceBreakup via applyGlbSurface; setBreakupDetail per tier (TierSpec.breakup, High only), installLowTierBreakup on Low's Lambert twins), water.ts (WATER_COMMON); shader.wgsl (surface_breakup, anti_tile, sample_tiled, both at detail 2 only; water_surface) + renderer.rs (WATER_CLOCK_WRAP) | tests/browser_parity.rs: every constant, the hash, the band offsets and blend, grime only below High in both, the waves term for term, fresnel and the environment; surface-breakup.test.ts (the patch finds its anchors in three's shaders) |
| Baked bounce light (COLOR_1) | bounce-light.ts (readBounce, installBounceAttribute → hdBounce, kept through the batch merge in world3d.ts), added to irradiance after lights_fragment_maps in surface-breakup.ts; world3d.rs (read_bounce, BounceEncoding) → Vertex::bounce (Float16x4), bounce_irradiance in lighting.wgsl.inc / shade_physical | tests/browser_parity.rs: the encoding check, the scale · c² decode, the add before albedo / π, world-only, no setting; bounce-light.test.ts; test_world3d.rs (Dust II and Bank carry it to every render vertex) |
| Bloom, dither, emissive | post-chain.ts (PREFILTER, DISPLAY, COMPOSITE, MODERATE_BLOOM, TierSpec.bloom) + three's emissive; post.wgsl (fs_prefilter, frame_from_scene, dither_noise) + post.rs + world3d.rs/shader.wgsl (glow in the AO attribute) | tests/browser_parity.rs: threshold, knee, dither constants, bloom before the curve in both, the 0.25 default in four sources and off at Low in both, emissive on native; post-chain.test.ts (bloomShare) |
| Tone curve, fog order, clear colour | three's ACESFilmicToneMapping + post-chain.ts (DISPLAY, inverseAces, sceneColoursForChain), post.wgsl (display) + atmosphere.rs (aces, display_hex_to_scene) | tests/browser_parity.rs: the fit and both matrices in all three sources, half-float scene targets in both, fog and clear colours pre-inverted in both; post-chain.test.ts round-trips the inverse |
| Signed envelope + node id | Python, Kotlin (the Android companion) | backend/tests/test_network_mobile_conformance.py |
The contract in every case is the same: the fixture pins agreement, each side's own unit tests pin correctness. A fixture is not a substitute for testing that the rules are right; it is insurance that three implementations of a right rule stay the same rule.
Physics is duplicated three times rather than two, because the authoritative match server has to simulate as well.
Not pinned — maintain by hand
These are duplicated with nothing checking that they agree. Each is a live maintenance hazard, listed so that changing one sends you to the other:
| Logic | Implementations | What drift looks like |
|---|---|---|
| Tone curve, sky shader | HorribleAssaultPanel.tsx + atmosphere.ts createSky, lighting.wgsl.inc | The two clients stop looking like the same game |
| Faction colours | skins.ts, bodies.rs + animator.rs | Teams read differently depending on the client |
| Grip transform for held weapons | CharacterModel.ts, held.rs | A rifle in the wrist rather than the hand |
| Demo recording cadence (the tick grid) and kill bookmark labels | demo.ts DemoRecorder, demo.rs DemoRecorder | A demo from one client keeps a different number of frames, or labels a frag differently |
| A skin's tint on the GLB weapon (palette body, decoded from sRGB; archetype knives left white) | viewmodel.ts requestProp, viewmodel.rs prop_tint → props_gpu Props::tint. The palette under it is pinned (tests/cosmetics.rs); the decode and the knife rule are not | The same skin a different shade in each client, or a karambit painted over its baked finish |
| Leg and aim solves over the gait (pelvis squaring, two-bone legs, spine thirds, head levelling) | CharacterAnimator.ts, animator.rs | Not fixture-pinned, but each side carries the same two measurements on the shipped rigs — a grounded foot slides under 2% of the ground covered, barrel and face within 3° of the look (locomotion.test.ts, animator.rs) — so drift shows as one of them failing rather than as a look |
| Effect lifetimes, tints, blast curves | effects.ts, effects.rs | A tracer that lingers in one client and blinks in the other |
| Build-in timing, band, rise, glow | reveal.ts, reveal.rs + shader.wgsl | The map assembles at a different speed or from a different direction |
| Grenade and cloud tints, fuse blink rate | nades.ts, nades.rs | Smoke reads as a different colour depending on which client you launched |
The two rows that used to head this table — the surface tint and the detail tile — are the ones that moved to the table above. What happened when they were pinned is the argument for pinning the rest of it, and it has its own section below.
It was two sets of literals, one in the panel and one in the shader, and every map
was lit the same way. It is now data: the backend resolves a map's
atmosphere and lights and serves them on MapInfo, and both clients draw from
those numbers (Light, sky and fog are served).
What each client still holds is a fallback for an older node, and
browser_parity.rs pins both fallbacks against the Python.
The sun's direction used to be a constant in both shadow.rs and the shader,
pinned by a test that read one from the other. The shadow map is now fitted to the
map's served sun, the same vector the shader's uniform carries, so there is
nothing left to disagree.
What the native client still lacks
Accurate as of the invite and roster work. Everything here exists in the browser and does not exist natively — not as a stub, not as a partial: the code is absent.
| Feature | Browser | Notes |
|---|---|---|
| Boot/backdrop scenery | backdrop.ts | Not ported as such: it is boot-sequence scenery, faded to zero once you deploy. The native menu has its own instead — the selected map, live, flying its benchmark framings (backdrop.rs) |
| Joining an invite mid-session | session.ts | The invite is now shown natively; acting on it means leaving this match and reconnecting to another room, which the client cannot yet do |
And in the other direction, so the list is honest: the native client has a
NetGraph (F3), a trace/conformance harness, a HUD the browser pane has
not caught up with — chamfered panels, a damage-lag trail on the health bar, a
per-round magazine strip, a reload dial and an armour bar — and a layer of game
feel the browser has been catching up on (G5 ported the damage arrows and the kill
chord, and found the impact and crosshair rows already done).
Both are deliberate, recorded divergences rather than drift, and every row is the browser's to pick up when somebody wants it:
| Native has | Browser | Notes |
|---|---|---|
| Damage-direction arrows | damage-arrows.ts | Off you.hurt, which both clients receive. Same life (1.2 s), cap (6), square fade, radius and spread in HUD units; damage-arrows.test.ts pins the screen-space sign in all four quarters |
| Damage-lag trail, magazine strip, reload dial | — | Pure presentation, no wire involved |
| A 3D stage in the loadout, inventory and store: the weapon, operator or skin to turn, zoom and inspect | A static loadout page | showcase.rs + showcase_gpu.rs, on the match's own prop and character pipelines. No wire involved; the models are the ones both clients already ship |
| A list of saved replays, auto-recording, and an export stepped at a fixed 60 fps | A file picker, a record button, and a real-time MediaRecorder export | front/replays.rs, replay.rs, export.rs (ffmpeg from the PATH). The files are the same format both ways — see the demo row above |
| Armour bar | armour in the HUD | The browser has read armour all along; the native client silently dropped the field, because an undeclared field in serde is not an error. Declared now |
| Screen shake | — | camera::Shake, fed by firing (from the served kickback), by damage taken, and by nearby detonations. Applied to a copy of the camera at draw time — see below |
| Weapon draw/holster | — | A swap reads as an action. The holster fires on the key, before the server has confirmed the slot, and recovers on its own if it is refused |
Reload dip on the served reloadTime | — | Both clients have reloadTime and reloadIn; the browser's dip is not driven by either |
| Impact sparks and dust | effects.impactSpatter | Per pellet, off the served faces: a pellet that stopped on a surface (face >= 0) throws that surface's material (dust, sparks, splinters, shards) along its normal. The one difference left: native also throws sparks where a pellet found a body, and the browser throws nothing there |
| Per-weapon-class muzzle flash, with a bloom | one cone | The bloom is a second, wider, dimmer cone rather than a post-process. Both clients now have a bright-pass (the HDR bloom), but the flash is unlit at 1, under its threshold |
| Kill confirmation | CrossfireKillBadges + the kill chord | A centre notice and a distinct chord, once per snapshot however many markers carry the kill. Both clients drive it off you.hits, so Train confirms a downed dummy too. The chord is the same Timbre in both |
| Sub-bass transient on shots | — | Timbre::thump. The one field where the native Timbre is no longer the browser's field for field — see the note under it in audio.rs |
| Floating damage numbers | — | Off you.hits, which both clients receive and only this one draws. Anchored to the victim's body and projected every frame; a victim absent from the roster falls back to the crosshair rather than being dropped |
| Killstreak notices | — | Counted from our own hitmarkers, so Train has them too. Ends at the death, not at the respawn |
| Post-match summary card | panels/PostMatchDebrief.tsx | The browser's is a dashboard panel after the process exits; this one is in the game window, at the moment the server settles up. An addition, not a port — see the damage-dealt note below |
| Tactical type system | the system sans | Display (Bahnschrift, tracked) for labels, Mono (Cascadia Mono) for every figure, Body (Segoe UI) for names and chat — OS fonts only, through one glyph atlas in the overlay's vertex stream. Rolling HP/armour/money, staggered entrances, grid-backed panels. The browser HUD keeps its own CSS stacks; bringing it to the same three faces is a follow-up, not drift |
The shake row carries the rule that governs the whole of this layer: a client-side
camera effect must never reach the camera the game runs on. self.camera is what
view_angles puts on the wire and what a shot's ray is built from; Camera::shaken
returns a copy, and only the renderer is handed it. Written the other way, the shake
would stop being cosmetic and become recoil the server faithfully honours — which
fails silently, as a game that feels like it has recoil nobody can find the tuning
for. There is a unit test asserting the real camera is untouched.
The dust row carries the other one. Fx::Shot's hit says whether the shot found a
body, per shot rather than per pellet, so gating dust on it cost a shotgun with one
pellet in a player and seven in a wall all seven of its wall marks. Both clients now
read the per-pellet faces instead, and hit is only native's fallback for a server
that predates them. Inventing a per-pellet answer the wire did not carry would have
been exactly the mistake effects.rs's header is about; asking the server for one
was the fix.
The crosshair is no longer on this list either way: both clients draw spec v1 from
the same hassault.crosshair.* bag through ports of crosshair.py
(crosshair-view.tsx, crosshair.rs), pinned by crosshair-vectors.json.
Your own gun is felt on the click, in both clients. The browser's
ShotController always played its own kick and gunshot off the local trigger.
Native had no trigger controller, so it waited for the server's Fx::Shot naming
us: a round trip plus a tick. Since G5 it predicts the shot when the command carrying
fire goes on the wire (own_shots.rs), gated the way the server gates it: alive,
not reloading, a round left once the shots in flight have spent theirs, the trigger
released between semi-automatic shots, and no weapon switch in flight. Each snapshot
reconciles by ack. A server shot we did not predict still gets its feedback, late,
and a refused one is dropped. The recoil index the camera follows is the server's plus
the predicted shots in flight, so no shot is kicked twice. Hits are never predicted in
either client.
The summary row carries a third, and it is the sharpest example on this page of
why two clients drift. The dashboard's debrief shows damage dealt; the native
card deliberately does not, because the client cannot reproduce that number.
_apply_damage accumulates damage_dealt from landed, capped at the victim's
remaining health, while the HitMarker on the wire carries the uncapped
post-armour amount — so summing hitmarkers overstates it systematically. The
native card shows hits landed and headshot kills instead: different names,
exactly countable, and therefore incapable of contradicting the other card. Adding
a stat to one client is easy; adding one that cannot disagree with the other
client's is the actual work.
The armour row is the one worth remembering, because it is this page's warning happening again in the other direction: the symptom was not a missing number, it was a native player taking half damage for a reason nothing on screen explained.
It claimed the native client had a developer console. There was no console.rs
and no match arm for console_res — grep for "console" under
apps/native-fps/src/ returned nothing at all. That is the failure this page
warns about, committed on the page itself: a table maintained by hand, describing
two clients neither of which fails a build when it drifts. The console is real
now; the lesson is that step 5 of the checklist below is the load-bearing one.
Divergence is now reported, not silent
Everything above describes drift that was found by looking at a screenshot. Three
mechanisms in the native client made that the only way it could be found, and
all three are now instrumented in apps/native-fps/src/divergence.rs:
| Mechanism | What it swallowed | What happens now |
|---|---|---|
Event::Other | roster, invite, invites, invite_sent, console_res — every event with no Rust variant, dropped by a => {} in app.rs | classify names it once per event name |
| serde ignoring undeclared keys | spotted, nades, zones, flash arrived and evaporated for as long as they existed | every wire struct carries #[serde(flatten)] extra, walked per message |
#[serde(other)] on Fx | a new effect kind became Fx::Other, and the tag — the one useful fact — was destroyed as it was learned | fx is read as JSON first so the kind can be named |
Two properties are load-bearing and easy to lose:
- Reported once per distinct thing, not per occurrence. A snapshot arrives 20 times a second; an unfiltered warning is a way of being silent that also costs frames.
- Reporting is never refusing.
#[serde(deny_unknown_fields)]would have been the one-line version of this and it is the wrong tool: a client that failed to parse a snapshot because the server grew a key would stop rendering the moment the backend gained a feature. Rendering a little less of a newer server is the correct behaviour; doing it in silence was not.
The extra capture is deliberately a flattened catch-all rather than a list of
expected keys. A list would need updating in step with the struct — the same
discipline that failed in the first place — whereas declaring a real field
removes the key from the report on its own.
The console, and the client-CVar contract
The native client now has a developer console (`), and it is worth being
precise about what is shared and what is not, because "both clients have a
console" is exactly the kind of statement that hides a divergence.
The registry is served. GET /api/hassault/console/definitions is the one
definition of every CVar, ConCommand and macro; console.py owns it,
registry.ts reads it, and console.rs reads it. There is no Rust table. A
node that cannot answer the route costs completion and validation and changes
no rendering at all — which is why ClientCvars holds overrides rather than
a mirror seeded from the served defaults.
Execution splits on the flags, not on a namespace. A client-flagged CVar is
applied locally and never reaches the wire (the server does not apply them —
draw.hitboxes means nothing on a machine with no screen). Everything else is
sent as console_exec on the match socket, not through the REST route the
browser pane uses: channel.py resolves the room and the player from the
connection itself, so a command sent that way lands in the match the client is
actually in, with no room id to get wrong.
affectedCvars has two spellingsThe websocket handler writes affectedCvars; the REST route's Pydantic model
writes affected_cvars. The browser pane only ever sees the second, so nothing
has forced them to agree. ConsoleResponse accepts both — not out of tolerance,
but because reading one would silently drop half the CVar updates depending on
which pipe the answer came down.
The honesty rule
The node serves 22 client-flagged CVars and the native client reads seven of
them (console::HONORED). The tempting behaviour — accept every assignment
silently — is the same failure this page exists to end: a console that answers
net.prediction = false while prediction carries on running has now told the
player something untrue.
So setting a CVar with no reader here stores the value and says so, and
DIVERGENCE typed into the console prints two lists: the client CVars this build
has no reader for, derived from the served registry rather than written down, and
everything the running server has actually sent that this build dropped. The
console is the place divergence is visible rather than another place it hides.
One consequence worth keeping: F3 and net.graph are now the same number.
The NetGraph step used to be a private field in app.rs while net.graph sat
unread beside it, so typing net.graph 2 changed the browser pane and not this
client — the shape of divergence in miniature. Both now go through
App::net_graph().
The radar
Now drawn natively. What is on it is not this client's decision: you.spotted is
resolved by MatchRoom.spotted_by, because the answer depends on two things only
the server holds — the level's geometry and the smoke standing in it. radar.rs
filters by team and nothing else.
The asymmetry between the two rules is the whole mechanic and is easy to get
wrong in the tidy direction: teammates are unconditional (that is a radio,
and they are deliberately absent from spotted — a per-player id list that never
changes would be bytes a tick to say something already known), while an enemy
needs to have been seen by somebody on our side, never by you specifically.
Why it is not a port of Radar.tsx
The browser rasterises the map into an offscreen canvas once and blits it with a transform. There is no image and no transform here — the overlay is triangles, rebuilt from nothing each frame — so three things had to be solved differently rather than copied:
| The browser | Natively |
|---|---|
| An offscreen canvas of open cells, blitted | Open cells merged into runs once per map, each drawn as an oriented thick line |
ctx.clip() to a circle | Segments cut against the circle analytically (radar::clip_to_circle) |
ctx.rotate | The same rotation applied per point, y-down, to match canvas exactly |
Runs rather than cells because the browser's 110-cube span is ~12,000 open cells, and a quad each is more geometry than the map itself. A floor plan is mostly long corridors, so merging collapses it — measured at startup, which is why the run count is printed beside the triangle count:
| Map | Grid | Cells | Runs |
|---|---|---|---|
hd_atrium | 128² | 16,384 | 312 |
ac_africa | 256² | 65,536 | 237 |
ac_aqueous | 256² | 65,536 | 554 |
A run is also a segment, which rotates correctly — whereas a rotated
axis-aligned rectangle is not axis-aligned any more, and Painter has no
primitive for one. Rows are culled against the span before any of them is
transformed, so a frame touches a band of that few hundred rather than all of it.
A radar with the rotation sign flipped still turns when you turn, still puts contacts at the right distance, and is mirrored — worse than no radar, because it is trusted. Two tests read the emitted geometry back and assert that what is ahead is up and what is on your right is on the right; both were checked by deliberately breaking the projection, because a test that cannot fail is the same as no test. A third pins the scale against the browser's 110-cube span: right direction and wrong distance is the same lie in a quieter voice.
Drawn only once joined, matching the browser's online && gate. Train has no
server and therefore no spotted — and the centre of the instrument is the one
thing on it that must not be a guess.
Pinned, not copied
The radar used to sit in the not pinned table, and its two copies agreed by a
comment ("76 HUD units is the browser's 168 px"). Everything that decides the
picture is now one TypeScript module, radar-view.ts, whose own output is the
fixture radar.rs replays: radarFrame (span from cl_radar_scale, the zoom
key, the clamped un-centred view, north-up), project, blipRadius as a
fraction of the radius (the one unit both clients mean the same thing by),
floorBand, wallEdges in the same order, the palette, and the settings reader
including its garbage handling. A divergence is now a failing cargo test, not a
screenshot.
What is still drawn differently, on purpose: the browser blits a canvas and
clips; natively, runs and wall edges are cut by clip_to_circle, and a site disc
or noise ring that would cross the rim is skipped rather than cut, because a disc
has no cheap clip. Footstep blobs are a radial gradient in the browser and two
stacked discs here.
radar::Memory holds the two things the radar remembers between frames — the
last-known position of a contact that stopped being spotted, and recent foe
footsteps — and is fed from the same snapshot as everything else. It only ever
holds positions this client was already sent.
Utility and effects
Grenades, clouds, tracers, impacts and detonations are now drawn natively. Every
one of them renders something the server already resolved: the arc, the bounce,
the fuse, the cloud's radius and every shot's endpoints all arrive in the
snapshot. Nothing in nades.rs or effects.rs simulates.
Three things are worth carrying forward.
flatten does not reach inside an enum
Fx::Shot has carried origin and ends since shots existed, and the native
client declared neither — it matched the effect, flashed the muzzle from the
id, and threw the geometry away. Fx::Detonate had no variant at all.
The wire's own divergence check did not catch either, and the reason is a real
limit worth knowing: #[serde(flatten)] cannot be applied inside an enum
variant, so a thin variant is indistinguishable from a complete one. The
catch-all reports unknown fx kinds — which is how detonate was found —
but a missing field on a kind that is already handled is still only findable by
reading match.py.
One translucent pass, two things in it
Clouds and effects share a pipeline because they share the three properties that
make a pass necessary: they blend, they must not write depth, and they must not
cull back faces (walking into smoke has to fill the screen). They do not
share shading, so VolumeVertex carries an explicit mode.
That is deliberately a field and not a convention. The tempting trick is a zero normal — no sphere produces one — but a rule encoded in the absence of data is one nobody finds when it breaks, and four bytes on a buffer of a few thousand vertices is not worth being clever about.
Buffer budgets are a real failure mode here
MAX_BODY_VERTS was 4096, justified in its own comment by "16 players × 6 box
faces × 6 vertices = 576, generous room". That arithmetic was true when a body
was a box. bodies.rs later became an articulated operator of some nineteen
boxes — 684 vertices a body — and the cap silently stopped fitting six
players. set_bodies truncates, so a full match simply stopped drawing its last
players, and a body cut off mid-torso is not a symptom anyone traces to a
constant.
There are now two defences, and both earned their place immediately:
- The budgets are asserted from the real builders (
renderer::budget), not estimated. That test movedMAX_VOLUME_VERTStwice while this landed — once when a full team's smokes came to 18,432, again when tracers and impacts joined the same buffer and a shotgun volley from everyone put it past 48,000. - Overflow is reported through
divergence::note_overflow. Truncating is still the right behaviour — a buffer that grew mid-frame would stutter — but it is no longer silent.
The native clouds use a static world-space value noise; the browser animates its shader on a time uniform, and this pass has no clock. Smoke here has structure but does not roil. Recorded rather than quietly accepted, because a difference nobody wrote down is the next entry in the drift table.
The shaders are checked now
cargo check never looks at a .wgsl file — it is a string literal to the
compiler. A typo failed at create_render_pipeline, on a machine with a GPU, at
the instant somebody launched the game. tests/shaders.rs parses and validates
the same concatenated source the renderer builds, and asserts that every entry
point a pipeline names exists. It does not replace running the thing (vertex
layouts and bind group types are still only proven on a driver), but it catches
the whole class of "the shader does not compile".
The build-in
The map assembles itself when you arrive: cubes rise into place along a front
that sweeps out from the middle, lit at the frontier and settling into their
normal shading behind it. reveal.rs plus four additions to shader.wgsl,
ported from the browser's reveal.ts.
It is not. reveal.ts is the map build-in, and the row in the table above
described it as a wallhack for however long it sat there. Nobody would have
found that by reading the code, because nobody reads a row describing a feature
they are not building — which is the same way the "native has a developer
console" row survived.
It is not driven by load progress, in either client
reveal.ts's own header says it is "driven by the real load progress". The call
site does the opposite and explains why: "Runs on its own clock rather than on
load progress: the map is already here by now, and the point of the animation is
to show the world arriving, not to stall until it has." The call site is the one
that is true.
That contradiction is the only reason this was portable. Driven by real progress it would need the native client's startup restructured — the window does not exist until the map is fetched and meshed. On its own clock it is a float and a shader.
Where the progress lives, and why that is the design
In the camera's uniform (CameraUniform::reveal), not a uniform of its own.
The world, the bodies and the view model all share one pipeline and one shader
and differ only in which camera bind group is bound, so what is and is not
revealed becomes a matter of which uniform you hand a draw call rather than a
branch somebody has to remember:
| Draw | Bind group | Revealed |
|---|---|---|
| World mesh | camera_bind_group | yes |
| Bodies, grenades, hitbox wireframes | settled_bind_group | no |
| Skinned operators | settled_bind_group | no |
| View model | viewmodel_bind_group | no |
settled_bind_group was added because of a divergence this created:
skin.wgsl declares a Camera without the reveal field at all, so the skinned
operators were exempt automatically while the box-body fallback would have risen
out of the floor with the map. Two body paths behaving differently, decided by
which shader happened to declare which struct. They are now exempt explicitly.
The two silent failure modes
Both are the kind that produce a plausible picture rather than an error:
- A zero radius or height divides by zero in the ordering function and
resolves every vertex to build order 1 — a world that appears all at once at
the very end, looking exactly like an effect that simply did not run.
Reveal::fitclamps, and a test pins it. - Stopping progress at exactly 1.0 leaves the far corner mid-rise forever,
which is how a build-in finishes with a seam across the map. Progress is
driven to
1 + BAND.
And one performance note: once the build is over the shader takes a uniform-coherent branch and skips the ordering function entirely, rather than evaluating a hash, a length and a floor per vertex per frame for the rest of the match to compute a number that is always 1.
The browser skips the animation for prefers-reduced-motion. This client has no
way to read that preference — winit does not expose it and the Windows API for it
would mean a dependency for one boolean — so Reveal::disable exists and nothing
calls it. Recorded rather than quietly dropped.
Rows that were never native gaps
Three entries sat in the table above for a long time. None of them described something the native client was behind on, and each was wrong in a different way. They are recorded here rather than deleted, because the reason each was wrong is the reusable part.
Voice comms — neither client has it
voice.ts opens your microphone, builds a spatial audio graph, and exposes
attachPeerStream. Nothing calls attachPeerStream. There is no
RTCPeerConnection anywhere in the module, no signalling, and no voice channel
in the backend — grep -rn voice backend/modules/hassault returns a comment
about a weapon's sound and nothing else.
So voice comms is a microphone, an audio graph and a panel of toggles with no transport between players. Porting the native half would have been building the client end of a feature that has no middle. What is missing is the transport, for both clients at once.
Match companion and post-match debrief — the browser's UI for the native client
MatchCompanion renders under {nativeRunning && ...}. It is the dashboard
panel shown while the native game runs in its own window. Porting it into
the native client is a category error.
PostMatchDebrief is populated from GET /hassault/match/latest_summary, and
the summary is written by channel.py's _record_result when a socket leaves a
room — which happens for a native client exactly as it does for a browser one.
A native match is already recorded and already produces a debrief; it appears in
the dashboard, where the XP and the skin drop it reports also live.
Armoury — a store, not a game surface
899 lines of inventory and marketplace. The native client already reads the
equipped skins it needs (GET /hassault/skins/inventory). Buying cosmetics
belongs in the dashboard, and a native client that also had to be a shop would
be duplicating a surface for no gameplay reason.
Every one of these rows was written by someone listing what the browser has and
the native client does not, without asking what the thing is. That is the same
inventory that described reveal.ts as a through-wall wallhack and claimed the
native client had a developer console. A gap table is only worth having if each
row has been read against the code it names.
The events that were still being dropped
invite, invites, joined, left and roster reached the native client and
vanished into Event::Other. The divergence report named them; this closes them.
The one that cost something is invite. fabric.py broadcasts it the moment
it arrives, so a client that is already in a game is precisely who it is aimed
at — and a friend inviting a native player got silence with no way to know why.
It now prints and lands on the kill feed, which is already the place this client
says what just happened.
It is shown, not acted on: joining would mean leaving this match and
reconnecting to another room mid-session, which the client cannot do. The room id
is on screen so --room can be used deliberately. That is now the honest row in
the "still lacks" table, replacing three that were not.
Two shapes worth pinning, both of which a tidier model would have got wrong:
joinedcarries a wholeplayerrow;leftcarries only aplayerId. Modelling them as one event reads an empty row on every departure and announces that somebody called""has left.roster'saddedis a list of names and itsremovedis a count. Not symmetric. Declaringremovedas a list parses nothing, silently, and reports no bots leaving.
left is also the one thing a snapshot cannot express: a body that disconnected
and a body behind a wall both simply stop appearing.
Pinning the look: what the surface fixture found
The two rows above sat under a note saying they were the ones most worth pinning next. They were, and the reason generalises: a pure function of small integer inputs is the cheapest thing on this page to pin and among the most expensive to leave unpinned. The tint decides the colour of every surface in every map and the tile decides the grain on all of them, and neither has any failure signal at all — no throw, no warning, no broken frame.
packages/core/src/modules/hassault/__tests__/surface-vectors.json now holds the
browser's own output for both, replayed by surface-conformance.test.ts here and
by #[cfg(test)] mod conformance in geometry.rs and detail.rs there. The
expectations are generated from the browser because the browser is where both
originated — detail.rs's header calls itself a port of surfaces.ts.
Generation lives inside the vitest file, behind UPDATE_SURFACE_VECTORS=1,
rather than in scripts/ beside gen_hassault_vectors.py:
UPDATE_SURFACE_VECTORS=1 pnpm --filter @horrible/core test surface-conformance
The physics fixture is written by Python, which has no trouble importing the server. These two functions are TypeScript with extensionless imports, which bare Node cannot resolve — and a generator carrying its own copy of the maths would pin the copy rather than the client, which is worse than having no fixture at all.
It failed on the first run
Which is the point of this section. tex_color computed the hue in f32 with
the golden ratio conjugate truncated to 0.618_034, under a comment asserting
that this and the browser's f64 digits "both round to the same f32". They do
not. The error is proportional to the texture id: invisible at id 4, about
1.4e-5 by id 255.
That is far too small to see, and that is exactly what makes it the right kind of
catch. It is not a bug anybody would have found by looking; it is a class of
bug that had no detector, sitting in the one function whose output covers every
pixel of the world. The fix is to do the arithmetic in f64 and cast the three
channels at the end, which costs nothing — tex_color runs once per quad at mesh
build, not per pixel and not per frame.
Two details of the fixture's design are doing real work:
- The tint tolerance is
1e-5; the tile's comparison is exact. The tint crosses a precision boundary (f64one side,f32the other) so it needs a budget, and a hue step is ~0.6 apart, so1e-5is four orders of magnitude tighter than anything an eye could resolve and still catches drift. The tile does not cross one —detail.rsis deliberatelyf64throughout, because the hash multiplies by 43758.5453123 and atf32the fraction that comes back is a different number entirely — and both sides round to a byte at the end. A tolerance there would quietly admit the drift the file exists to catch. - The tile is pinned by samples and by whole-tile statistics. Nineteen
sampled pixels can agree by luck while the rest of the 16384 have moved, so
min, max and mean over all of them are pinned too. And the tile is drawn a
second time at 16 wide:
sizeis a parameter and the noise's wrap period is derived from it, so a port that hardcoded 128 anywhere inside the lattice would match every sample of the full-size tile and fail only there.
The four shade constants are in the fixture as well, and not as padding. A shade
is one of the two inputs to the tint, so pinning the colours while letting
SHADE_CEIL drift would pin agreement on colours neither client ever draws.
Adding a feature: the checklist
When you add something to either client, walk this list. It is short on purpose.
- Does it decide an outcome? Then it belongs on the server and is served to both clients. Do not implement it twice — implement the fetch twice.
- Does it have to be computed identically in both? Then it needs a shared
fixture in
packages/core/src/modules/hassault/__tests__/, replayed by both suites. Add the vectors before the second implementation, not after. - Does it need a wire field? Check
protocol.rsactually declares it. The native client silently ignorednades,zones,spottedandflashfor as long as they existed, because an undeclared field in serde is not an error. It is no longer silent — see "Divergence is now reported" above — but a line on stderr is a prompt to declare the field, not a substitute for doing it. - Is it visual? Then it will not be caught by any test. Render it and look:
cargo run --example operator_previewfor the character offscreen, or launch the client against a local node. Put the picture next to the browser's. - Update this page, specifically the "still lacks" table. A feature that lands in one client and is not recorded here is one nobody will remember is missing from the other.
Verifying by eye, repeatably
Two things exist to make "look at it" less ad hoc than it sounds:
apps/web/operator-check.html— loads the operator GLB in the browser and reports clip count, height, and how many bones move per mesh. Reachable at/operator-check.htmlunderpnpm dev.apps/native-fps/examples/operator_preview.rs— renders the same character offscreen to a PNG, in the same five clips, with no window and no match.
They pose the same five clips so the two pictures can be put side by side. That is the only comparison that catches a character facing backwards, inside out, or in the wrong colour — all of which stay true while every unit test passes.
For the world, launch the native client against a running node and compare against the browser pane's Train on the same map. There is no automated version of this yet, and it is where every divergence on this page was actually found.