Effect Replication: Address an Effect by Where It Lands

🗺 Overview

Retiring the TickManager moved every visual effect off a global reliable multicast and onto state replicated per entity. That was the right move and it is not being reversed. It did, however, invert one thing without anyone deciding to: relevance became keyed on what caused an effect, rather than on where the effect happened. An arrival — an impact, a blast, a death — is a fact about a place, and a place has no proxy.

The first draft misdiagnosed the reported bug

The first version of this document asserted that NetCullDistance defaults to 150 m, so a shot fired from 400 m away produces nothing on a client. That is wrong, and the error is worth recording because it is easy to repeat: 15 000 cm is the field initialiser on UHorizonEntityProxy, and the planet-unit path overwrites it. UPlanetUnitRepSyncProcessor writes UPlanetUnitSettings::NetCullDistance, which is 150 000 cm — 1.5 km. Reading a declaration is not the same as finding out who assigns it.

So the sniper case as originally framed sits comfortably inside relevance today and cannot be what players are reporting. Two defects that can explain it were found instead, both verified in the code, and both far cheaper to fix than this port.

🩹 Phase 0: Fix First, Then Judge

Both of these are verified present, both are cheaper than the port, and either could be the reported regression. Neither is fixed by building the bulletin, and the bulletin would be built on top of both.

UMachineEntityProxy::CopyFrom documents this trap in a comment and is the only site in the codebase handling it correctly, looping MARK_PROPERTY_DIRTY_FROM_NAME_STATIC_ARRAY_INDEX per element. UPlanetUnitEntityProxy carries six C-array properties — Shots, AliveMask, MoveSamples, PartHeat, PartDamageType, WindupProgress — and every one is marked the whole-property way. An AliveMask that only ever ships word 0 means part destruction beyond part index 32 never reaches a client, which is a complete explanation of missing destruction effects on its own.

🔍 What Is on the Wire Today

🎯 The Model

A region is a Mass entity

One long-lived replicated object per occupied world cell, carrying a bounded ring of effect packets. Registering it as an ordinary Horizon entity type — rather than a bespoke replicated object — is what makes it cheap: the spatial grid filter, the cull distance, the dirty-tag sync, the client mirror creation and the archetype pre-registration all already exist and need no plugin changes.

A cell entity models nothing in the game, and that is the honest objection. The defence is that it is not game state: it is a spatial index over the world, the same category of object as the factory nav grid's tiles, the planet spatial hash, and Iris's own filter grid.

📡 The Region Bulletin

The packet

USTRUCT()
struct FFXEventPacket
{
    // Effect position relative to the owning cell's centre. Relative, not absolute, so the
    // value stays small and quantises well; the drain adds the cell centre back.
    FVector3f LocalPosition = FVector3f::ZeroVector;

    // For a point effect, the surface normal. For an arrival, the direction the thing that
    // caused it came FROM, which is what lets a viewer draw an incoming tracer without
    // knowing where the shooter is.
    FVector3f Direction = FVector3f::ZeroVector;

    // Authority world time the effect happened. Held until the render clock reaches it.
    float ServerTime = 0.f;

    // Monotonic per-cell counter starting at 1. The de-dup key: a drain tracks the highest
    // it has drawn and compares wrap-safely, so a ring re-sent unchanged replays nothing.
    uint16 Seq = 0;

    // Impact, Explosion, Debris, DropPod — and the channel's visual variant id.
    uint8 Channel = 0;
    uint8 Visual  = 0;

    // Per-channel scalars, quantised against a per-channel range. Explosion uses both
    // (blast radius, blast force); most channels use neither.
    uint8 Value0 = 0;
    uint8 Value1 = 0;

    // The unit this landed on, or invalid when it landed on terrain. Used ONLY to pick the
    // render clock and re-anchor onto the pose this viewer is drawing. Never dereferenced
    // for anything the effect needs in order to exist.
    FMassNetworkID TargetNetID;
};

SurfaceID is carried on the proxy, not in the packet, and is mandatory in three places for three different reasons. It belongs in the cell key, because surfaces are separated by a Z offset of 10 000 cm — far inside every tier's cull — so the spatial filter alone cannot tell a factory from a planet. It is stamped as a surface-membership fragment, because that is what the surface-clear path queries on. And it is replicated, because the client sync processor caches one shared-fragment value per entity type, so a per-surface const-shared value structurally cannot reach a client.

Tiers — two, not three, and both forced

Cells are flat in XY, and that is forced rather than preferred. Cull distance is view radius plus half the cell diagonal. A 60 000 cm cubic cell gives 100000 + 51962 = 151962 — over the cap on day one. Flat gives 142 426. Surfaces are separated in Z alone, and the SurfaceID key already provides that separation.

Global is not a convenience. No spatially filtered tier can ever match 150 000 cm of relevance, because its guaranteed reach is its view radius — an effect may sit a half-diagonal from the cell centre — and view + half-diagonal is hard-capped. Anything that must be as visible as the unit it belongs to has to be always-relevant.

The ring

Iris delivers only a property's newest value and coalesces updates, so a single slot would lose every event but the last between two sends. Depth must cover the peak events in one cell per replication interval, plus events that have arrived but are not yet due. Overflow overwrites oldest-first, costing a missing burst and nothing else.

Cell lifecycle

Created lazily on the first effect published into them, retired after an idle timeout comfortably longer than the drain's lateness window. Pooled and long-lived by design: the per-cell cost that matters is the Iris creation header, sent once per cell per client, so a cell must never be spun up per explosion. The find-or-create path must validate its cached handle and treat a retiring record as absent, or a publish landing between the destroy and the observer writes through a dying handle — the stale-handle class this project has hit twice.

👁 Seeing What You Cannot See

A viewer does not get the shooter's position — neither available nor desirable to leak. It gets the impact, and the packet's direction gives the bearing the shot arrived from, so the drain can draw a bounded-length incoming tracer that reads as a shot arriving out of the dark.

The one place a packet looks at another entity

An impact on a moving unit must land on the unit where this viewer is drawing it, at that unit's own interpolation delay — not at the authority position it was recorded at.

⚙️ Publish and Drain

Publish (authority)

A server world subsystem owns the cell map and a plain queue of pending packets. Once per frame it drains the queue, buckets by tier and cell, creates any missing cell entity, appends into that cell's fragment and marks it dirty; a rep-sync processor copies fragment to proxy.

The queue is a plain array, not one entity per effect — these effects have no simulation to run, and the Niagara Data Channel batching already does the presentation batching.

Drain (every viewer, host included)

A Client | Standalone processor walks each cell's ring oldest-first, skips anything at or below its watermark, stops at the first packet not yet due, and submits the rest inside a client-presentation scope. The listen-server host drains the ring it just authored, through the same processor, at its own render clock. There is no host shortcut to diverge.

The drain reaches decals and smoulder through the explosion and destruction submits, never a lower-level spawn. That coupling is what makes "every explosion leaves a mark" true by construction, and it is why the channel enum has no Smoulder member: the explosion submit already presents the smoulder, the scorch and the wreckage impulse. A separate channel would double-draw the smoke, and one without an explosion has no producer anywhere.

📋 What Moves, and What Does Not

Projectile weapons never drew terminal effects from the shot ring

This is the subtlest thing in the port and it inverts the obvious change. The projectile update gates all four terminal submit sites on bPresents = (P.Role != EProjectileRole::Authoritative), so the authority's damage round presents nothing. There is therefore no existing code that could publish a projectile arrival.

Unit death narrows to a burst and a mark

The first draft promised full debris from a unit dying outside your view. It cannot deliver that: husks, the death scorch and the pooled physics debris all ride the destruction submit off the AliveMask diff and need the design layout, which a viewer without the unit does not have. What the bulletin carries is one packet meaning a unit died here — one burst, one ground mark. Wreckage stays derived for viewers who hold the unit.

De-dup the two paths at tear-off, not at presentation. A presentation-time record loses the race whenever the packet is due before the derived death, and a net-id presence probe cannot work at all, because both the server and client id maps are cleared in the same call as the publish. The tear-off hook runs on every rendering net mode, before any presentation, with the net-id fragment still attached.

✂️ Two Fixes That Are Not This Design

Both surfaced during planning, both are cheaper and more valuable per line than anything in the phases, and neither needs the bulletin.

🔁 Sustained Streams Stay Conditions

The bulletin must not quietly become the old bus with better filtering. A weapon hosing a wall at 10 Hz would otherwise publish ten arrivals a second into one cell for as long as it fires.

The same move already made for sustained fire applies to the far end of it: publish one packet describing the condition — impact point, rate, and a valid-until horizon — and let each viewer generate the impacts from it. Cost becomes proportional to state changes rather than to rounds, and a viewer that misses the end stops on its own.

Until measurement says this is needed, the interim protection is simpler: gate the projectile publish on the same sustained-fire test the generator already uses.

⚠️ Hazards

🚧 Phases

1. 0Fix the C-array dirty marking and the reader bounds; re-measure. Function bodies only, so no full rebuild. Knows it worked: a pure client sees more than one shot per unit per ring wrap, and part destruction fires for parts outside the first mask word. If it does, re-scope everything below.
2. 1The channel end to end, hitscan impacts only, publish behind a cvar. One tier, sized Area. Add a default fragment-registration override to the Horizon proxy base so that whole failure class dies. Knows it worked: with the cvar on, a listen host and a pure client each draw exactly one bulletin impact per shot in the same place; the client's newest sequence keeps advancing; cells are created and retired symmetrically; a planet unload leaves zero region entities.
3. 2Take the terminal half — hitscan and projectile in one change. Delete the shot-ring terminal block and its two flags; add the authority projectile publish; add the cosmetic gate. Flip the cvar on. Knows it worked: exactly one impact per shot by hand count, for both weapon kinds; the Client Parity table stays empty.
4. 3Unit death, narrowed to burst plus mark, including the tear-off claim. Knows it worked: one burst and one mark for a death you hold, one for a death you do not, never two. Test with the target held, torn off mid-linger, and never held.
5. 4Measure. No code.
6. 5The Global tier: drop pods and the orbital strike. One always-relevant cell per surface. Delete the pod multicast, its event struct and the now-callerless emit helper — and that path's presentation scope in the same edit. Coalesce pods to one packet per cell per frame with a count, since a batch shares a drop location. Knows it worked: a bulk deployment shows every pod; a client on another surface sees none; packet count scales with drop points, not units.
7. 6The orbital beam off its 20 Hz multicast, via the router. Three fixes ride along or the change ships an invisible weapon: the beam prewarm needs calling from BeginPlay, since its only caller today is the binding this deletes; the valid-until horizon must be extendable, because an authored-unbounded channel computes a horizon of zero; and the disconnect path must close the slot, since a dropped channeller's beam is currently stopped through the multicast this removes.
8. 7Condition packets, quantisation, tuning. Conditional on Phase 4.

📐 What to Measure

❓ Open Decisions

🔀 Alternatives Considered