v0.6.0 UE 5.5 / 5.6 / 5.7 Protocol v6 Win64 · Mac · Linux Full C++ Source Blueprint Surface Pro · Fab

Rollback Core Pro

Welcome to Rollback Core, a GGPO-style rollback netcode plugin for Unreal Engine 5. It features a deterministic fixed-step simulation loop, automatic state capture via SaveGame property reflection, a peer-to-peer UDP transport with input redundancy and reliable ACKs, OnlineSubsystem matchmaking, and an in-editor frame-scrubber debugger. Ships with three demo maps and a complete automation-test suite.

Fab Marketplace ⚡ Quick Start 📖 API Reference

60 Hz Default fixed tick

8 Max peers per match

~12 Typical rollback depth

3 Included demos

01 Overview

Rollback netcode is the prediction strategy invented for fighting games (GGPO, 2006) and now standard across the competitive genre — Street Fighter 6, Guilty Gear Strive, Skullgirls, Mortal Kombat 1. Instead of waiting for the remote player's input (delay-based netcode), each peer predicts that the opponent will repeat their last input and simulates immediately. When the real input arrives later, the simulation rolls back to the predicted frame, replays with the corrected input, and fast-forwards to the present. The local player feels zero latency.

The cost is CPU (resimulating up to a dozen frames per tick) and a hard requirement: the simulation must be deterministic. Same inputs in, same state out, every time.

Rollback Core Pro provides:

• A deterministic fixed-step simulation loop (URollbackManager) that decouples gameplay from render rate.
• Automatic per-frame state capture (URollbackStateComponent) driven by UPROPERTY(SaveGame) reflection — no manual serialization code per actor.
• A UDP peer-to-peer transport (URollbackNetSubsystem) with input redundancy, reliable ACK/resend, heartbeats, and peer-timeout detection.
• OnlineSubsystem-backed matchmaking with provider abstraction (LAN NULL, EOS, Steam, or any configured OSS).
• A frame-by-frame visual debugger with scrubbing, entity-state inspection, and desync checksum diff.
• A complete Blueprint surface via URollbackNetworkBlueprintLibrary.
• Performance instrumentation (FRollbackPerformanceStats) covering sim time, rollback time, snapshot size, bandwidth, and rollback frequency.
• Three demos: a basic top-down two-pawn rollback, a network packet-loss simulator, and a sprite-based 2D viking duel.
• Editor automation tests covering the full pipeline.

How to read this manual

If you're new, follow sections 1–3 in order to install and run the demos, then read section 4 (Architecture) before writing any code. If you're integrating into an existing project, jump straight to Installation and API Reference. If you're debugging desyncs, head to Determinism and Visual Debugger.

02 Quick Start

Before writing any code, run the included demo environments. Each demonstrates a different facet of the plugin and serves as a working reference you can read alongside this manual.

Demo 1 — Basic prediction & correction

Open any empty level and type into the Unreal console (default ~):

Rollback.SpawnDemo

The demo spawns two pawns. You control the Blue pawn with WASD. The Red pawn moves automatically — but its inputs reach your simulation delayed by 15 frames. When Red changes direction, your prediction fails, and you see Red snap to its true state while a cyan ghost trail shows the corrected timeline.

The local pawn keeps running; when remote input lands, frames are silently resimulated and the ghost trail visualizes the correction.

Demo 2 — Network packet-loss simulator

To exercise the UDP transport, packet-loss simulation, input redundancy, and rollback correction path in a single PIE session:

Rollback.SpawnNetworkDemo

The Blue pawn is local WASD. The Red pawn is driven through the rollback network buffer with simulated packet loss and latency. The on-screen HUD reports:

• Local + remote UDP endpoints
• Packets sent, packets received, simulated drops
• Resend count and pending reliable packets
• Rollback count and correction distance

Demo 3 — 2D Viking duel

The sprite-based fighting demo shows Rollback Core Pro in a genre-relevant setup with extracted transparent frames, metadata-driven animation, hitboxes, hurtboxes, blocking, hitstun, KO states, and rollback correction:

Rollback.SpawnVikingDemo

Use Rollback.SpawnDebugger alongside any demo to open the runtime frame-scrubber panel.

03 Installation

Requirements

Install from Fab marketplace

1. Open Epic Games Launcher → Library → Fab → search for Rollback Core Pro.
2. Click Install to Engine and select your engine version (5.5, 5.6, or 5.7).
3. In your project, open Edit → Plugins, search for Rollback Core Pro, and check Enabled.
4. Restart the editor when prompted. Done.

Install into project Plugins folder (source build)

1. Copy or clone the RollbackCorePro/ folder into YourProject/Plugins/.
2. Right-click your .uproject file and choose Generate Visual Studio project files.
3. Open the resulting .sln in Visual Studio and build the editor target.
4. Launch the editor — the plugin auto-enables on first load.

Verify the installation

After enabling the plugin and restarting the editor, open the console (~) and run:

Rollback.SpawnDemo

If a two-pawn demo appears with rollback correction visualization, you're ready. If the command isn't recognized, the plugin failed to load — check Edit → Plugins → Networking → Rollback Core Pro and verify there are no compile errors in the Output Log.

Project layout reference

YourProject/
├── Plugins/
│   └── RollbackCorePro/
│       ├── RollbackCorePro.uplugin     # Plugin descriptor
│       ├── Config/
│       │   └── FilterPlugin.ini        # Files staged in packaged builds
│       ├── Content/
│       │   ├── Demo/                   # Generated viking sprites + JSON
│       │   └── Maps/                   # RC_BasicDemo, RC_NetworkDemo, RC_VikingDemo
│       ├── Docs/
│       │   ├── index.html              # This manual
│       │   ├── editor-ui.md
│       │   ├── viking-demo.md
│       │   └── network-prediction-mover.md
│       ├── Resources/                  # Plugin icon
│       └── Source/
│           ├── RollbackCorePro/        # Runtime module
│           │   ├── Public/             # Headers
│           │   └── Private/            # Implementations + Tests
│           └── RollbackCoreProEditor/  # Editor-only module (debugger, wizard)

04 Architecture

Rollback Core Pro is a runtime plugin built around three world subsystems, one actor component, and one Blueprint function library. Each piece has a single, well-bounded responsibility.

High-level architecture. The runtime module is the entire C++ surface; the editor module adds the debugger panel and setup wizard.

The simulation lifecycle

Standard Unreal games tick on render-frame cadence. Rollback netcode must tick at a fixed rate, identical across peers — otherwise the same input sequence won't produce identical results. URollbackManager takes over the gameplay loop using an accumulator:

// Conceptual per-engine-tick loop inside URollbackManager
Accumulator += DeltaTime;
while (Accumulator >= FixedTimeStep) {       // FixedTimeStep = 1/60 by default
    AdvanceFrame();                             // — one deterministic step
    Accumulator -= FixedTimeStep;
}

Each AdvanceFrame() does the following, in order:

1. Increment CurrentFrame.
2. For each registered entity (anything implementing IRollbackEntity): call RollbackTick(dt, frame). This is where gameplay logic runs.
3. For each registered entity: call SaveRollbackState(frame). The state component writes the actor's SaveGame properties + transform + velocity into the ring buffer.

The rollback path

When a late authoritative input arrives over UDP and changes a frame from the past:

1. The network subsystem buffers the input under (PlayerId, Frame).
2. Your gameplay code (or ApplyBufferedInputsAndRollback from the Blueprint library) calls URollbackManager::RollbackToFrame(EarliestMismatchFrame).
3. For each entity, LoadRollbackState(Frame) restores the snapshot.
4. The manager replays frames Frame+1..Current with the corrected input history.
5. Latest state is now authoritative; the visual shell (mesh, animation, camera) follows on the next render frame.

05 Auto-State Saving

The most error-prone part of any rollback system is state capture — getting every byte of gameplay state into a snapshot, and back out, without missing a field or accidentally including non-deterministic data. Rollback Core Pro solves this by repurposing Unreal's existing SaveGame property flag.

The SaveGame flag

UE's reflection system already supports marking properties as part of a save file:

UPROPERTY(SaveGame, BlueprintReadWrite) int32   Health = 100;
UPROPERTY(SaveGame, BlueprintReadWrite) FVector SimulatedVelocity = FVector::ZeroVector;
UPROPERTY(SaveGame, BlueprintReadWrite) uint8   HitstunFramesRemaining = 0;
UPROPERTY(SaveGame, BlueprintReadWrite) uint8   FacingDirection = 0;

In Blueprints, you mark a variable as SaveGame by selecting it and toggling the SaveGame checkbox in the Advanced section of the Details panel.

Rollback Core Pro repurposes this same flag for per-frame snapshot/restore. One annotation, two uses — your rollback state list and your save-file state list are identical, which is almost always what you want anyway.

The component scans the owning actor once at BeginPlay, caches the SaveGame-flagged FProperty pointers, and writes them into the ring buffer each tick.

How the component works internally

On BeginPlay, URollbackStateComponent walks the owning actor's class properties via UE's reflection system. Every FProperty whose PropertyFlags contains CPF_SaveGame is cached into TrackedProperties. Iteration happens once; per-frame serialization just walks the cached array.

Each tick the component writes the tracked properties into an FArchive wrapping a TArray<uint8>, plus the actor's Transform and Velocity directly (cheap path, no Serialize overhead). The byte array is stored in StateBuffer[Frame]. On restore, the inverse happens.

What gets captured

Multi-actor and projectiles

Every actor that should be rolled back needs its own URollbackStateComponent. Projectiles, particle-driven hitboxes, status-effect carriers — give each a state component and they'll automatically participate in the rollback. The component registers itself with the world's URollbackManager on BeginPlay; you don't need to call anything manually.

Inspecting captured state

The component exposes diagnostics that are useful for inline UI or debug overlays:

06 Deterministic Movement

Unreal's built-in CharacterMovementComponent and Chaos Physics are fundamentally non-deterministic across peers. Sub-tick interpolation, root-motion blending, physics sub-stepping, and floating-point error accumulation all cause two clients to diverge given identical inputs over enough frames.

Rollback Core Pro ships URollbackMovementComponent, a minimal deterministic alternative. It's intentionally tiny — it's a starting point you customize, not a full character controller.

What it does

URollbackMovementComponent::DeterministicMove(FVector InputVector, float DeltaTime) integrates input into actor location using:

• An explicit fixed-delta multiplication — never the variable engine DeltaSeconds.
• Input scaling clamped to the component's configured MaxSpeed.
• Truncation of intermediate floating-point results to a fixed precision, reducing per-platform float-rounding divergence.

Typical usage

void AMyFighter::HandleRollbackTick(float Dt, int32 Frame, FRollbackInput Input)
{
    const FVector InputVec(Input.Axes.X, Input.Axes.Y, 0.f);
    MoveComp->DeterministicMove(InputVec, Dt);

    // Then deterministic combat logic here, reading from Input.Buttons
    if (Input.Buttons & ButtonAttack) {
        StartAttackFrame(Frame);
    }
}

OnRollbackTick event:
  → URollbackMovementComponent → DeterministicMove(InputVector, DeltaTime)
  → Branch on Input.Buttons bits → custom attack/block logic

07 Network Transport

URollbackNetSubsystem is a thin, purpose-built UDP transport for rollback inputs. It is symmetric — any peer can be a host. It supports up to 8 peers per match. It is intentionally not wrapped through Unreal's replication system, because rollback transport has different priorities (latency > ordering > reliability) than gameplay replication.

Wire packet layout

Every packet is a single UDP datagram, capped by MaxPacketBytes (default 1200, safe under typical MTU):

Compact, hand-rolled wire format. Overhead per packet: 25 bytes of header (21 before v6 added the 4-byte sender advantage) + 5 bytes per repeated input frame.

Reliability model

Input packets are sent unreliably by default — the redundancy window almost always covers transient packet loss without round-trips. For data that must arrive (initial Hello, configuration changes), the transport supports a reliable mode:

• Reliable packets receive a unique sequence number and are queued in PendingReliable.
• Each incoming packet carries a cumulative ACK of the highest contiguous sequence the sender has received.
• If a reliable packet hasn't been ACKed after ResendAfterSeconds (default 80 ms), it is resent.
• After MaxReliableRetryCount resends (default 20), the peer is considered failed and OnPeerMaxRetriesExceeded fires.

Peer lifecycle

1. Connection starts when either side calls ConnectToPeer(PlayerId, Host, Port) or accepts an incoming Hello.
2. Heartbeats are sent at HeartbeatIntervalSeconds (default 2 s) if no other packet has been sent recently.
3. If no packet is received for PeerTimeoutSeconds (default 10 s), the peer is dropped and OnPeerDisconnected fires.

Usage from C++

URollbackNetSubsystem* Net = GetWorld()->GetSubsystem<URollbackNetSubsystem>();

// 1. Open the UDP socket.
FRollbackTransportConfig Config;
Config.LocalPort = 7777;
Config.InputRedundancyFrames = 8;
FString Error;
if (!Net->StartUdpPeer(Config, Error)) {
    UE_LOG(LogTemp, Error, TEXT("Transport failed: %s"), *Error);
    return;
}

// 2. Connect to a remote peer.
Net->ConnectToPeer(/*PlayerId*/ 2, TEXT("203.0.113.42"), 7777, Error);

// 3. Each deterministic frame, send local input.
Net->SendInputFrame(LocalPlayerId, CurrentFrame, MyInput, /*bReliable*/ false);

// 4. Apply received remote input and trigger rollback if predictions diverged.
bool bChanged = false;
int32 EarliestChangedFrame = -1;
Net->ApplyBufferedInputsToState(RemoteStateComp, RemotePlayerId,
                                CurrentFrame - 15, CurrentFrame,
                                bChanged, EarliestChangedFrame);
if (bChanged) {
    Manager->RollbackToFrame(EarliestChangedFrame);
}

Usage from Blueprint

URollbackNetworkBlueprintLibrary wraps the common cases:

MakeLoopbackTransportConfig(LocalPort, PacketLossPercent, MinLatencyMs, MaxLatencyMs)
StartLoopbackPacketLossTransport(WorldContext, LocalPort, ...)
SendRollbackInputForCurrentFrame(WorldContext, PlayerId, Input, bReliable)
SendRollbackInputToAllPeers(WorldContext, PlayerId, Input, bReliable)
ApplyBufferedInputsAndRollback(WorldContext, RemoteStateComp, RemotePlayerId,
                               FromFrame, ToFrame, bOutRolledBack, OutRollbackFrame)
ConnectToRemotePeer(WorldContext, PlayerId, RemoteHost, RemotePort)
GetConnectedPeerIds(WorldContext) / GetAllPeerInfo(WorldContext)

Local two-instance smoke test

Run two editor instances or two machines on the same LAN. On the host:

Rollback.NetHost 7777 RollbackCoreProSmoke 0

On the client, replace the address with the host's IP:

Rollback.NetClient 192.168.0.10 7777 7778 0

The final numeric argument is simulated packet loss percent. Use 10 for a stress test:

Rollback.NetClient 192.168.0.10 7777 7778 10

Configuration reference

08 Pacing & the Latency Envelope

Two peers simulating the same match will never run at exactly the same speed. One machine hitches, one has a slower GPU, one's crystal drifts. Left alone the clocks separate, and once they separate by more than the rollback window, corrections arrive too old to apply and the match desyncs permanently with no way back.

Pacing is the mechanism that stops that: the peer that is ahead holds its clock for a frame and lets the other catch up.

Why "how late is my confirmation?" is the wrong question

The obvious metric is how old your newest confirmed frame is — if you're at frame 400 and only confirmed through 380, you're 20 frames "ahead". Before 0.5.0 that is what drove the stall.

It is wrong, and the reason matters: latency alone drives that number up even when both clocks are in perfect step. On a 100 ms link your confirmation is always ~6 frames old, in both directions, forever. The old rule read that as drift and stalled continuously — so a high-latency match ran in slow motion for both players, which is the opposite of what pacing is for.

The halving is not cosmetic: the difference counts each peer's contribution twice, so a delta of N means N×2 frames of real divergence. That is why MaxFrameAdvantageFrames defaults to 4 and tolerates 8 frames of separation.

What it measures now

• Every outgoing packet carries SenderFrameAdvantage — this peer's own advantage (protocol v6).
• Each frame, the manager computes (local advantage − peer's reported advantage) / 2.
• That sample feeds a 40-frame rolling window (two-thirds of a second at 60 Hz — long enough to average out jitter, short enough to still react inside a stall's useful lifetime). The same window GGPO uses.
• ShouldStallForFrameAdvantage() returns true when the smoothed delta reaches MaxFrameAdvantageFrames.

Why pacing cannot deadlock

A stall suppresses local input. No input means the peer's confirmation freezes, which makes the peer stall too — a loop with no exit if pacing is ever allowed to hold the clock indefinitely.

Pacing therefore corrects at a duty cycle rather than by withholding every frame: at most one frame in four is held (StallDutyCycleFrames), so the clock still yields ground — at 75% rate — while the input stream never stops and the peer is never starved into stalling. Withholding every frame was measured on the 180 ms profile halving the effective rate, with one peer's confirmation frozen for 15.58 s of a 20 s run.

The clock holds outright in exactly one case: the advantage is already past the rollback window and the peer has genuinely gone silent (no confirmation progress for SilentPeerFrames, 30 timesteps). Past the window advancing buys nothing — RollbackToFrame rejects corrections deeper than the window, so those frames could never be reconciled — and the 10-second peer timeout resolves a genuinely dead peer by disconnecting it, which drops the advantage to 0 and lets the clock resume on its own.

Both conditions are required. A merely slow peer must not be held against: on a high-latency link a healthy session sits close enough to the window that ordinary jitter crosses it, and holding there would starve the peer into stalling — the very loop the duty cycle exists to break.

Choosing a rollback depth for your latency

Rollback depth is a budget, not a safety net. A correction older than MaxRollbackDepthFrames is discarded, and a discarded correction is a permanent desync. So the window has to be wider than the confirmation lag your players will actually see.

Confirmation lag in frames is roughly one-way ms ÷ 16.67, plus your input delay, plus a margin for jitter. Measured against the shipped soak profiles:

Widen the window (or lower input delay) until RejectedRollbackCount stays flat under your worst realistic connection.

Peak-advantage figures come from the plugin's own RCPSoak suite — five real-time latency profiles run for 20 s each — so you can re-derive them rather than take them on trust.

Input-stream integrity

Confirmation never advances across a missing frame, and redundancy cannot heal a hole — SendInputFrame only re-sends frames already in local history, and a frame that was never submitted was never there. So one missing input frame freezes that peer's confirmation for the rest of the session.

This is easy to cause by accident. Callers poll input once per engine tick while URollbackManager can advance up to MaxCatchUpFramesPerTick (4) fixed frames in that same tick — so any engine frame slower than 60 fps drops a frame from the wire.

The gap is filled once, from a per-player watermark, and capped at MaxInputGapFillFrames (120) so a session that has already fallen minutes behind cannot flood the link.

Use SendInputFramesThrough, which sends every frame from a per-player watermark through the current frame:

// Sends every frame from the last one sent through CurrentFrame, filling any gap.
// Repeating the polled value across skipped frames is exact, not an approximation:
// the local simulation used that same value for every fixed frame it stepped.
int32 Sent = Net->SendInputFramesThrough(PlayerId, Manager->CurrentFrame, Input, false);
// Returns frames sent, 0 if none were due, -1 on transport failure. 0 is success.

The Blueprint node ApplyBufferedInputsAndRollback and all three shipped demo environments already route through it. If you wrote your own send path against SendInputFrame, switch it.

09 Platform Matchmaking

For LAN testing or shipping platform integration, URollbackNetSubsystem can advertise and discover matches through Unreal's configured OnlineSubsystem. The session itself carries the rollback transport's UDP endpoint as session settings, so a client that joins a session immediately knows where to point its UDP socket.

Provider matrix

Host flow

FRollbackTransportConfig Config;
Config.LocalPort = 7777;
FString Error;
RollbackNetSubsystem->StartUdpPeer(Config, Error);

// Advertise the rollback endpoint via OnlineSubsystem.
RollbackNetSubsystem->CreatePlatformSession(
    /*SessionName*/ FName("RollbackCorePro"),
    /*MatchId    */ "Ranked-1v1",
    /*PublicConn */ 2,
    /*bLan       */ false,
    Error);

Client flow

// 0. (Optional) Tune the search timeout, then size your own "Searching..."
//    watchdog/UI to it instead of hard-coding a matching number.
RollbackNetSubsystem->SetSessionSearchTimeoutSeconds(15.f);
const float SearchTimeout = RollbackNetSubsystem->GetSessionSearchTimeoutSeconds();

// 1. Search.
RollbackNetSubsystem->FindPlatformSessions("Ranked-1v1", /*MaxResults*/ 20, /*bLan*/ false, Error);

// 2. Pick a result (delivered via OnMatchmakingResult delegate).
RollbackNetSubsystem->OnMatchmakingResult.AddDynamic(this, &UMyMenu::HandleResult);

// 3. Join.
RollbackNetSubsystem->JoinPlatformSessionByIndex(ResultIndex, Error);

On successful join, the transport auto-connects its UDP socket to the host's advertised endpoint and OnMatchmakingComplete fires with bWasSuccessful = true.

Blueprint: async matchmaking nodes (Find / Host / Join)

For Blueprint graphs, three Advanced-Sessions-style latent nodes wrap the whole flow so it's one node each — no manual delegate wiring:

Helper pure nodes: Find Best Rollback Session (lowest ping with an open slot) and Format Rollback Session (one-line summary for menus).

// C++ equivalent of the Find node's payload (Host/Join mirror this shape).
URollbackFindSessionsAsync* Search =
    URollbackFindSessionsAsync::FindRollbackSessions(this, "Ranked-1v1", /*MaxResults*/ 20, /*bLan*/ false, /*Timeout*/ 15.f);
Search->OnFound.AddDynamic(this, &UMyMenu::HandleSessionsFound);   // TArray<FRollbackMatchmakingResult>
Search->OnFailed.AddDynamic(this, &UMyMenu::HandleSearchFailed);
Search->Activate();

Example assets & one-click generation

The C++ actor ARollbackMatchmakingExampleActor wires all three nodes into one Blueprintable actor with editable defaults (Match Id, LAN, port, timeout) and OnSessionsFound / OnHosted / OnJoined / OnError events to bind to UI. A bundled generator authors ready-to-open example assets under /RollbackCorePro/Examples/:

Generate them from the editor in one click — Rollback toolbar → Examples → Generate Example Content, or the Setup Wizard → Integration → Generate Example Blueprints button. Both call FRollbackCoreProEditorModule::GenerateExampleContent(), which runs the generator through the Python Editor Script Plugin and reports whether it ran (a clear on-screen note appears if Python is disabled). You can also run Content/Python/generate_matchmaking_examples.py manually via Tools > Execute Python Script…. Re-running is idempotent — existing assets are left untouched.

Ready-made menu widget

URollbackMatchmakingMenuWidget is a fully native UMG menu — no .uasset required, it builds its own widget tree in RebuildWidget. It drives the Find / Host / Join async nodes for you and shows discovered sessions as a scrollable list, each row with its own Join button. Pop it on screen instantly with Rollback.ShowMatchmakingMenu, or add it from your HUD with CreateWidget + AddToViewport.

The native menu as rendered by Rollback.ShowMatchmakingMenu: Host / Find in the header, a live status line, and one row per discovered session. Row text comes from Format Rollback Session; each Join routes through the Join Rollback Session (Async) node.

Config & events

Console & headless parity

The whole async flow is reachable from the console, so you can test or script matchmaking with no Blueprint at all: Rollback.Host, Rollback.Find, and Rollback.Join spin up the same URollbackCreateSessionAsync / URollbackFindSessionsAsync / URollbackJoinSessionAsync nodes and report through URollbackNetConsoleSink. Because OnlineSubsystemNull discovery only works across separate processes, a genuine find/join is a two-process exercise:

Two-process Null-LAN parity flow. Use Tools/Verify-Matchmaking.ps1 to launch a host + joiner side by side; it auto-runs Host/Find and reports discovery, leaving Rollback.Join 0 + Rollback.NetPeers as the one interactive step.

# Process A — host
Rollback.Host Ranked-1v1 7777 2 1

# Process B — joiner (once the host is advertising)
Rollback.Find Ranked-1v1 20 1 8     # logs: Find complete: 1 session(s)
Rollback.Join 0                       # joins the cached result; transport auto-connects
Rollback.NetPeers                     # confirm the link on both sides

Delegates

Provider validation

Before shipping a new provider, validate the OSS is loaded:

Rollback.NetProvider default 1
Rollback.NetProvider NULL    1
Rollback.NetProvider EOS     1
Rollback.NetProvider STEAM   1
Rollback.NetFindNull RollbackCoreProSmoke 20

The first three forms check that the named provider is loaded and exposes a session interface. The last one performs an actual LAN session search using OnlineSubsystemNull, which is the fastest in-editor sanity check.

10 Visual Debugger

Rollback bugs are invisible by default — the player just sees a snap or a desync. The debugger surfaces what was actually happening on each historical frame.

Inline ghost trails

When bEnableVisualDebugging is true on URollbackManager, the manager continuously renders a cyan ghost (drawn via DrawDebugBox) at the actor's true position from DebugLiveFrameLag frames ago (default 5). If your local prediction is drifting, the ghost separates from the live actor.

Frame-scrubber panel

For frame-by-frame inspection, spawn the runtime debugger panel:

Rollback.SpawnDebugger

The panel reads from URollbackManager's saved frames and surfaces:

• The currently-selected frame number (scrub via slider or commands)
• All registered rollback entities at that frame
• Per-entity saved byte count, checksum, location, velocity, and the input that was used
• Yellow ghost renders for the selected frame's state
• Cyan trail renders for the frames between the selected frame and live

Scrubber console interface

Programmatic access

C++ and Blueprint projects can use the same data without the panel:

const TArray<int32> AvailableFrames = Manager->GetAvailableDebugFrames();
const TArray<FRollbackDebugFrameRecord> Records = Manager->GetDebugFrameRecords(Frame);
Manager->SetDebugScrubFrame(Frame);
Manager->StepDebugScrubFrame(+1);
Manager->SetDebugScrubFollowLive(true);

Desync detection

The state component stores an FNV-style checksum of every snapshot. The manager compares pre-rollback vs post-rollback checksums for the same frame; any mismatch indicates a non-deterministic actor and fires the OnDesyncDetected delegate with:

• The frame where the divergence was detected
• The entity name that desynced
• The XOR of the two checksums (useful for rough bucketing of error types)

11 Performance & Tuning

Rollback's CPU cost is proportional to (rollback depth) × (per-frame sim cost) × (number of entities). The plugin instruments all three so you can tune confidently.

Performance stats

URollbackNetSubsystem::GetPerformanceStats() returns an FRollbackPerformanceStats struct sampled over a rolling 60-frame window plus 1-second bandwidth window:

Quick dump

Rollback.Perf

Prints a multi-line summary to the on-screen log and the output log.

Tuning levers

Memory footprint estimate

Default MaxBufferSize on the state component is 60 frames. With 4 entities averaging 64 bytes of SaveGame state each, that's 60 × 4 × 64 = 15 KB of rolling snapshot memory. Comfortable for any platform.

12 Determinism Rules

If "same inputs in, same state out" breaks for one entity on one frame, every peer's prediction silently diverges. This section is the canonical reference for what you may and may not do inside rollback-authoritative code.

The do / don't matrix

The two-layer pattern

The pattern every shipping rollback game uses is what GGPO calls the deterministic core plus visual shell:

The visual shell is allowed to be non-deterministic — it can use timelines, latent actions, async loads, anything you want. It just reads from the core's state and reacts. If a rollback happens, the visual shell will see the corrected state and naturally update; it never participates in the rollback itself.

Verifying determinism

Rollback Core Pro provides five complementary mechanisms to detect, audit, and pinpoint non-determinism:

1. Single-process local validation (ValidateDeterminism). Call URollbackManager::ValidateDeterminism(FramesBack) during unit tests or soak runs to resimulate historical frames locally from saved inputs. It catches unseeded RNG, TMap/TSet iteration order issues, and uninitialized variables in a single process without needing a network connection.
2. Field-level & property-level desync diagnostics. When a desync occurs, CompareRollbackStates and DescribeRollbackStateDifference compare snapshots and report exact field differences (e.g. Velocity: (12, 0, 0) -> (12.5, 0, 0)). Call SetDetailedDesyncDiagnosticsEnabled(true) to add per-property checksums to ActorData, allowing desyncs inside reflection properties (e.g., Health, ComboCounter) to be identified by name rather than as an opaque byte offset. Read the report via GetLastDesyncDetail().
3. Cross-build float semantics (FPSemanticsMode.Precise). Both RollbackCorePro and RollbackVikingGame build with FPSemantics = FPSemanticsMode.Precise in their .Build.cs. This prevents compiler fast-math reassociation and FMA contraction that otherwise cause DebugGame, Development, and Shipping builds (or MSVC vs Clang) to desync over identical input streams.
4. Differential build testing (Diff-BuildDeterminism.ps1). Run Tools\Diff-BuildDeterminism.ps1 to generate per-frame state checksum traces (via RunDeterminismTrace) across different build configurations and verify bit-level reproducibility.
5. Cross-peer checksum monitoring & loss testing. Bind OnDesyncDetected to catch real-time state divergence during multi-peer matches, or run Rollback.SpawnNetworkDemo with high simulated loss (30%+) to test resimulation under latency.

13 Network Prediction & Mover Integration

Rollback Core Pro is intentionally a standalone deterministic layer. It does not wrap Unreal's Network Prediction plugin or Mover because the two systems solve different problems with different assumptions.

When to use which

• Rollback Core Pro only — fighting games, platform fighters, deterministic projectile combat, small symmetric multiplayer prototypes
• Network Prediction / Mover only — shooters, racing games, anything where the server is authoritative and the client is predicting locomotion
• Both, layered — Mover handles locomotion (movement, jumping, traversal), Rollback Core Pro handles combat state on top (hit windows, blocking, freeze frames, projectile interactions). The combat layer rolls back; the movement layer does not.

Recommended integration patterns

1. Deterministic core + visual shell. Rollback Core Pro simulates compact gameplay state. Meshes, animation, VFX, audio, and cameras follow the corrected state after rollback.
2. Separated systems. Mover or Network Prediction owns locomotion. Rollback Core Pro owns deterministic combat, projectile, hit-validation, or frame-data logic. The two systems exchange information only through clean read interfaces — no shared mutable state.
3. Prototype migration. Use Rollback Core Pro to validate rollback game feel during prototyping. Migrate production movement to Network Prediction or Mover when the project needs Epic's server-authoritative pipeline, but keep the combat layer on Rollback Core Pro.

14 API Reference

URollbackManager — world subsystem

URollbackStateComponent — per-actor component

URollbackNetSubsystem — world subsystem

URollbackNetworkBlueprintLibrary — Blueprint helpers

Static helpers that wrap the most common URollbackNetSubsystem calls in WorldContext-aware Blueprint nodes. See section 7 for the full list.

Core data types

Interfaces

15 Console Commands

All commands are registered globally and operate on the active UWorld's subsystems. Open the console with ~.

+ConsoleKeys=Tilde
+ActionMappings=(ActionName="ToggleDebugger",Key=F2,bShift=False,bCtrl=False,bAlt=False,bCmd=False)

16 Project Settings

Surfaced under Edit → Project Settings → Plugins → Rollback Core Pro. Backed by URollbackCoreProSettings (UDeveloperSettings) and persisted to DefaultEngine.ini.

Settings are read by URollbackManager::Initialize and by any code that constructs an FRollbackTransportConfig from defaults. Changing them while the editor is running takes effect on the next PIE session or world load.

17 What's New

v0.6.0 — Precise float semantics, field-level desync diagnostics & protocol mismatch handling

• Narrowed Platform Declaration. The runtime module's PlatformAllowList explicitly declares Win64, Mac, and Linux to match what is exercised and verified. (Sockets and OnlineSubsystem integrations remain platform-agnostic).
• Cross-Build Float Semantics (Precise). Both RollbackCorePro and RollbackVikingGame build with FPSemantics = FPSemanticsMode.Precise in their .Build.cs. This prevents compiler fast-math reassociation and FMA contraction that otherwise cause DebugGame, Development, and Shipping builds (or MSVC vs Clang) to desync over identical input streams. Tested and verified bit-identical across Win64 (MSVC) and Linux (Clang 20).
• Single-Process Determinism Validation. URollbackManager::ValidateDeterminism(FramesBack) resimulates historical frames locally from saved inputs to catch non-deterministic code (unseeded RNG, TMap/TSet iteration order, uninitialized variables) in a single process without network setup. Automated differential trace tool available at Tools\Diff-BuildDeterminism.ps1.
• Field-Level & Property-Level Desync Attribution. CompareRollbackStates and DescribeRollbackStateDifference report exact per-field differences (e.g. Velocity: (12, 0, 0) -> (12.5, 0, 0)). GetLastDesyncDetail() returns a single-line loggable summary. SetDetailedDesyncDiagnosticsEnabled(true) adds per-property checksums to ActorData blobs to attribute desyncs inside SaveGame properties by name.
• Explicit Protocol Version Mismatch Reporting. Incoming datagrams carrying an incompatible wire protocol version trigger OnProtocolVersionMismatch, increment FRollbackTransportStats::ProtocolMismatches, record GetLastProtocolMismatchVersion(), and emit warning logs naming both versions.
• Diagnosable Socket Subsystem Selection. FRollbackTransportConfig::SocketSubsystemName and project setting DefaultSocketSubsystemName allow routing transport over EOS P2P. An unavailable subsystem fails hard with an explicit error listing registered subsystems rather than silently falling back to platform UDP.
• Adaptive Input Redundancy. Outgoing input packets dynamically widen their redundancy window under burst loss based on peer frame-advantage feedback, preventing temporary packet drops from freezing confirmation progress.

v0.5.0 — Difference-based pacing on protocol v6

The defect. Frame-advantage pacing stalled on how old the newest confirmation was. Latency alone pushes that past the bound even when both clocks are in perfect step, so peers on a slow link stalled continuously and the match ran in slow motion for both players. Worse, a stall suppresses local input, which freezes the peer's confirmation, which stalls the peer — a loop with no exit.

Measured across five real-time latency profiles, 20 s each, on the plugin's own soak suite:

After the fix: 0 stalls, 0 rejected rollbacks, 0 desyncs on every profile. The "before" column is one run of three — no profile's pre-fix result was stable across runs, which is why the fix was validated over repeated clean runs rather than one.

• Pacing now measures the difference between peers. Every packet carries the sender's own advantage; each peer stalls only on the smoothed delta. Symmetric latency cancels to zero. See section 8.
• Input-stream gaps are filled. A single missing input frame used to freeze a peer's confirmation for the rest of the session. SendInputFramesThrough sends every frame from a per-player watermark, so an engine frame slower than 60 fps no longer drops input off the wire.
• Pacing can no longer withhold the clock indefinitely. It corrects at a duty cycle — at most one frame in four is held — so the input stream never stops. The clock holds outright only against a peer that has both passed the rollback window and gone silent.
• The latency envelope is documented rather than implied — including the honest limit that the default 12-frame window is not enough at 140–180 ms one-way. See section 8.
• Demo pawns render correctly again. SetColor was writing a Color parameter to a material that does not declare one, so every demo drew two identical grey spheres; the engine-default pawn was also left orphaned in frame.

v0.2.3 — Multi-engine support & desync detection

This release focused on multi-engine support, cross-peer desync detection, complete physics state rollback, and Fab marketplace readiness.

Each engine version is packaged separately with RunUAT BuildPlugin -StrictIncludes against an installed engine build, from a clean source copy with no stale Binaries or Intermediate. -StrictIncludes disables precompiled headers and unity builds, so every header must be self-contained — the same condition marketplace validation compiles under, and the one that unity builds hide.

🌐 Cross-Peer Desync Detection

Peers exchange per-frame state checksums on confirmed frames. A mismatch fires OnDesyncDetected — no false positives from in-flight prediction.

• Wire protocol v3 — new StateChecksum packet type; incompatible with ≤ 0.2.1 peers.
• Auto-wired: URollbackManager records and sends confirmed-frame checksums automatically while transport is connected.
• Confirmed-frame policy: only frames whose inputs are all in from every peer are checksummed, eliminating false positives.

🧊 Complete Physics & CMC State Rollback

🎯 Rollback Correctness

• Off-by-one double-application fixed. SimulateFrame now snapshots start-of-frame state before ticking, so RollbackToFrame(F) restores and replays applying the target frame's input exactly once.
• New test: Rollback.NoOpReplayIsIdentity — a no-op rollback must reproduce the exact pre-rollback state.

📦 Fab Marketplace Packaging

• Plugin descriptor updated with CreatedBy, DocsURL, SupportURL, CanContainContent: true
• Copyright headers verified on all 61 source files (.cs, .cpp, .h)
• Content included: Demo sprites, example Blueprints, maps, Python scripts, full documentation

🔧 UE 5.7 Compatibility

UE 5.7 tightened NewObject constraints for UActorComponent subclasses — they now require an AActor* outer instead of UPackage*. The Movement.RollbackStepSafe test was updated to create a proper test world/actor while still validating that RollbackStep is safe to call without registered or initialized movement data.

18 Automation Tests

The plugin ships with automation coverage under WITH_DEV_AUTOMATION_TESTS in Source/RollbackCorePro/Private/Tests/RollbackCoreProAutomationTests.cpp. Run them from the Session Frontend (Tools → Test Automation → Automation) or via the command line:

"<UE_path>\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" YourProject.uproject ^
  -ExecCmds="Automation RunTests RollbackCorePro; Quit" ^
  -unattended -nop4 -nosplash -nullrhi

What's covered

19 Troubleshooting & FAQ

20 Glossary

21 Rollback Core (OSS) vs Rollback Core Pro

A stripped-down open-source distribution — Rollback Core — is available on GitHub at gregorik/Rollback-Core under the MIT license. It contains the same deterministic simulation, transport, and basic demo. Rollback Core Pro (this product) adds matchmaking, the visual debugger, multi-engine-version packages, additional demos, and direct support.

When to use which

FREE / MIT

Rollback Core (OSS)

• Prototyping rollback into an existing project
• You already have matchmaking (Steamworks, EOS, custom backend)
• Comfortable building your own debug UI
• Open project or commercial title that can't accept a marketplace EULA
• Only targeting one engine version

COMMERCIAL · FAB

Rollback Core Pro

• OnlineSubsystem-backed matchmaking out of the box
• Visual frame-scrubber debugger for desync hunting
• 5.5–5.7 verified packages without maintaining backports
• Worked 2D fighter demo as a starting point
• Time-to-first-rollback-match matters more than license cost