Installation & Setup

Requirements

Unreal Engine 5.8. Server-authoritative networking - dedicated or listen. Compatible with Iris replication on or off; the batched mode registers its container as an Iris-aware fast array where Iris is enabled.

Install the plugin

1. Install from Fab

   Add the plugin to your library and install it to your engine version from the Epic Games Launcher.

2. Enable the plugin

   Edit → Plugins → Networking → ButterNet Movement Sync, then restart the editor.

3. Add the component

   On the pawn Blueprint you want replicated: Add Component → ButterNet Movement Sync. No graph wiring is required - the component drives itself from BeginPlay.

4. Disable Replicate Movement

   On the same actor, clear Replication → Replicate Movement. Two systems writing proxy transforms will fight every frame.

Optional: enabling Iris

Iris is Unreal's newer replication backend. The plugin works with it on or off, and nothing needs changing on the component either way. Enabling it changes how the engine handles the state this plugin sends, and two of those changes matter enough to be worth understanding before you decide.

1. Enable Iris and push model

   Add these to [SystemSettings] in Config/DefaultEngine.ini:

   net.Iris.UseIrisReplication=1
   net.Iris.PushModelMode=1
   net.IsPushModelEnabled=1
   net.SubObjects.DefaultUseSubObjectReplicationList=1

2. Leave relevancy alone

   Pawns pick up Iris spatial filtering automatically, provided bAlwaysRelevant, bOnlyRelevantToOwner and bNetUseOwnerRelevancy are all false. You only need an explicit entry under [/Script/IrisCore.ObjectReplicationBridgeConfig] for a class that sets one of those and still wants spatial filtering.

3. Rebuild

   These are engine-init settings, not runtime toggles. A running server will not pick them up.

What it changes for this plugin

Push model is the one that matters. Without it, a replicated property is polled and compared against a shadow copy on every update cycle, whether or not it changed. The component's dead-bands stop it sending when a pawn is still, but the engine still pays to check. With push model on, an unchanged pose is never marked dirty, so it is not compared, not serialised and not considered at all. That is what turns "this pawn did not move" into genuinely zero work rather than merely zero bytes.

Batched mode gets delta serialisation. The shared per-region container is a fast array, so a single pawn moving sends one item rather than the whole region's contents. This is the difference between batched mode scaling with the number of pawns that moved and scaling with the number of pawns present.

Iris on against Iris off has not been benchmarked for this plugin, so there is no speed figure to quote here. Both effects above are structural rather than incidental, but if the number matters to your decision, measure it on your own content.

Replication model

The component behaves differently per network role, and registers no work where it has none to do.

The wire format is a single replicated struct carrying position, quantised yaw/pitch/roll, velocity, a server timestamp and a teleport counter. Disabled channels are written as zero, which compresses to almost nothing rather than carrying stale data.

Replication is push-model: the property is only considered after an explicit dirty mark, which happens only when the sampled transform clears the dead-bands. A pawn standing still is not compared, not serialised and not sent. Because the payload is state rather than an event, a dropped update is self-correcting - the next one carries current truth - and a late-joining client receives the current pose as part of normal initial replication.

SampleAndSend()          // authority, timer-driven at SendRate
  └─ ShouldSend()        // dead-band test; early-out costs nothing
     └─ mark dirty       // push model: no mark, no consideration
        └─ per-actor  → replicated property, owner-skipped
           batched    → one item in the region's fast array

In batched mode a pawn registers with the container for its region and with neighbouring regions while inside the overlap band, so crossing a boundary never interrupts its update stream. Clients route arriving items by pawn reference into that pawn's own interpolation buffer, so a pose arriving from a different region continues the same playback without a reset. Duplicate poses produced by the overlap are rejected by timestamp.

Parameters

All values are per-component, editable in the Details panel. Distances are Unreal units, times are seconds.

Blueprint API

Tuning

Start from InterpolationDelay ≈ 2 / SendRate. At the default 10 Hz that is the shipped 0.25 s, which tolerates one dropped packet without the buffer running dry.

Graph GetBufferedStateCount during play. A healthy client holds two or more states; sitting at 0 or 1 means playback has caught up with arrivals and is extrapolating, which is the usual root cause of reported jitter. Either raise InterpolationDelay or raise SendRate.

Dead-bands are the cheapest bandwidth lever and cost nothing at rest, but they quantise motion - a pawn moving slower than PositionDeadband × SendRate per second will visibly step. Lower the dead-band rather than raising the send rate for slow-moving pawns.

In batched mode, region size is a trade rather than an optimisation: smaller regions send each client less but increase the number of replicated containers the server tracks. If your container count approaches your pawn count, the region size is too small for how your population is distributed.

Troubleshooting

Out of scope

The component replicates a pose and nothing else. Everything below is deliberately left to the engine or to your own systems, and knowing which is which will save time later.

The short version: it makes pawns the player does not control move smoothly, cheaply and correctly. It does not decide what those pawns are doing, and it does not attempt to replace character movement.