Recursive AI

Encode a 3D physics snapshot delta in C#

onegame is a free, open-source game engine for .NET from Recursive AI. MIT or Apache-2.0, no editor required.

NuGet GitHub Docs Download example (.zip)

A snapshot delta records a physics state relative to an earlier full snapshot. Keep that baseline to decode it later.

Terminal
dotnet add package RecursiveAI.OneGame.Physics

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

Fixed.One is one in the engine’s deterministic fixed-point number type; FVec3 is its three-dimensional vector type.

C#
using OneGame.Core;
using OneGame.Physics;
 
var space = new PhysicsSpace3D();
space.AddSphere(Fixed.One,
    new FVec3(0, 4, 0));
var baseline = space.Snapshot();
space.Step();
var delta = space.SnapshotDelta(baseline);
var copy = new PhysicsSpace3D();
copy.RestoreDelta(baseline, delta);
Console.WriteLine(
    $"Same state: {space.Hash == copy.Hash}");
Text
Same state: True

The example creates a sphere, saves its baseline, advances one tick, and restores the delta into another space.

Unzip the example, then dotnet run.

Variations

Append this to compare the complete snapshot bytes after the delta restore.

C#
Console.WriteLine(space.Snapshot().AsSpan()
    .SequenceEqual(copy.Snapshot()));
Text
True

The short answer

Use PhysicsSpace3D.SnapshotDelta(baseline) to encode the current physics state against a full snapshot from Snapshot(). Decode it with RestoreDelta(baseline, delta). Both calls take the baseline bytes explicitly: the receiver’s current state is not a substitute for that argument. The example changes the state by stepping a falling sphere and prints a hash comparison after decoding.

How do I encode a 3D physics snapshot delta in C#?

Capture the full baseline before advancing the simulation. Retain that byte array, step the space to the state you want to save, and produce a delta against the retained baseline. The snippet at the top runs this sequence without creating an engine world or opening a window. PhysicsSpace3D can be used as a standalone space; Step() advances one fixed tick.

Treat the baseline and delta as a pair in your storage or transport design. A delta is not a standalone full snapshot. If you keep several baselines, associate each delta with the baseline you actually passed when encoding it. The API does not choose a baseline for your application. A saved checkpoint can instead use Snapshot() when independent decoding is more useful than baseline management.

How do snapshot deltas work in networked physics?

A sender and receiver need access to the same baseline. Glenn Fiedler’s explanation of delta compression describes the networking consequence: the sender must use a baseline the receiver has received. Acknowledgments and baseline retention belong to the transport design, not to this encoding call.

OneGame exposes these methods for tooling. Its physics integration contract says the sync stack has no per-table delta hook. Calling SnapshotDelta does not turn on automatic wire compression. Ordinary table serialization still writes a bounded full snapshot and tick rate. This example therefore demonstrates the codec, not a complete network replication protocol.

How do I check a restored physics snapshot in C#?

Compare Hash after restoring, as the program does. The space’s hash covers saved physics sections, including events and origin, rather than only the sphere’s visible position. The variation also compares the full snapshot bytes, so its result is not merely a visual check.

Keep the two spaces at the same intended checkpoint when making that comparison. Stepping only one of them changes what is being compared. Snapshot deltas preserve the accumulated origin as part of physics state; they are not just differences between local body positions.

RestoreDelta bounds decoded data to 64 MiB. The wrapper also checks the lengths of the supplied baseline and delta. The API describes delta creation as an allocating tooling operation, so use it deliberately for checkpoints or diagnostics rather than assuming it is an allocation-free part of every simulation tick.

All onegame recipes