If two recordings number the same simulation step differently, shift one on the shared timeline with offset.
dotnet tool install --global RecursiveAI.OneScope.ToolRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
Sources are numbered from 0 in the order they’re opened, so b.txt is source 1.
dotnet build -o bin/demo onescope open a.txt --headless \ --module bin/demo/Example.dll \ --run 'open {"path":"b.txt"}' \ --run 'offset {"source":1,"offset":5}' \ --run 'seek {"step":2}'
Unzip the example, then dotnet run.
Run the commands from the unzipped example. a.txt contains 0, and b.txt contains 5: the starting ticks. The build restores OneScope.Sdk for the included C# module. OneScope needs a working graphics renderer even without a window.
The last JSON result, reformatted, shows shared tick 2 with source 0 at tick 2 and source 1 at tick 7:
{ "step": 2, "start": 0, "steps": 10, "sources": [ { "source": 0, "step": 2, "hash": "0000000000000002" }, { "source": 1, "step": 7, "offset": 5, "hash": "0000000000000007" } ] }
The full program
The program installs OneScope.Tool 1.0.0 and loads the example module, which uses OneScope.Sdk 1.0.0. Each sample contains one digit and a newline; the module gives each ten steps after its starting tick. The demo seeks to the same shared tick before setting, after setting, and after clearing the offset.
using System.Buffers; using System.Buffers.Binary; using System.Diagnostics; using System.Text.Json; using OneScope.Sdk; // Install the published command-line tool into the build folder. string toolDir = Path.GetFullPath("obj/onescope-tool"); string tool = Path.Combine(toolDir, OperatingSystem.IsWindows() ? "onescope.exe" : "onescope"); if (!File.Exists(tool)) Run("dotnet", "tool", "install", "RecursiveAI.OneScope.Tool", "--version", "1.0.0", "--tool-path", toolDir); var results = Open( "open {\"path\":\"b.txt\"}", "seek {\"step\":2}", "offset {\"source\":1,\"offset\":5}", "seek {\"step\":2}", "offset {\"source\":1,\"offset\":0}", "seek {\"step\":2}"); PrintSteps("Before offset", results[2]); PrintSteps("After offset", results[4]); PrintSteps("After reset", results[6]); static void PrintSteps(string label, JsonElement result) { var sources = result.GetProperty("sources"); Console.WriteLine($"{label}: shared {result.GetProperty("step")}, " + $"A {sources[0].GetProperty("step")}, B {sources[1].GetProperty("step")}"); } JsonElement[] Open(params string[] operations) { var arguments = new List<string> { "open", "a.txt", "--module", typeof(TickModule).Assembly.Location, "--headless", "--size", "640x480" }; foreach (string operation in operations) arguments.AddRange(["--run", operation]); string output = Run(tool, arguments.ToArray()); return output.Split('\n', StringSplitOptions.RemoveEmptyEntries) .Select(line => JsonDocument.Parse(line).RootElement.Clone()) .ToArray(); } string Run(string command, params string[] arguments) { var start = new ProcessStartInfo(command) { RedirectStandardOutput = true, RedirectStandardError = true }; foreach (string argument in arguments) start.ArgumentList.Add(argument); using var process = Process.Start(start)!; var output = process.StandardOutput.ReadToEndAsync(); var errors = process.StandardError.ReadToEndAsync(); process.WaitForExit(); if (process.ExitCode != 0) throw new InvalidOperationException(output.Result + errors.Result); return output.Result; } // Demo format: one digit (the start tick), followed by a newline. public sealed class TickModule : IScopeModule { public string Id => "tick-demo"; public string Name => "Tick demo"; public IScopeSource Open(ReadOnlyMemory<byte> data, string name) { if (data.Length != 2 || data.Span[0] is < (byte)'0' or > (byte)'9' || data.Span[1] != 10) throw new ScopeFormatException(name, "Expected one digit and a newline."); var recording = Recording.Create(data, new ReadOnlyMemory<byte>[10], startStep: data.Span[0] - '0'); return new TickSource(name, recording); } } public sealed class TickSource(string name, Recording recording) : IScopeSource { public SourceInfo Info { get; } = new() { ModuleId = "tick-demo", Name = name, Dimensions = 2, Unit = LengthUnit.Metre, Axes = [new AxisInfo(AxisIds.Time, "Time", 0)] }; public Recording Recording => recording; public IScopeWorld CreateWorld() => new TickWorld(recording.StartStep); public IScopeSource WithRecording(Recording other) => new TickSource(name, other); public void WriteReplay(IBufferWriter<byte> writer) => throw new NotSupportedException("This demo only reads the two sample recordings."); } public sealed class TickWorld(long start) : IScopeWorld { public long Step { get; private set; } = start; public ulong Hash() => (ulong)Step; public void Advance(ReadOnlySpan<byte> input, TimelineSink sink) => Step++; public void AdvanceAxis(string axis, int position, ReadOnlySpan<byte> input) => throw new NotSupportedException(); public void WriteSnapshot(IBufferWriter<byte> writer) { BinaryPrimitives.WriteInt64LittleEndian(writer.GetSpan(8), Step); writer.Advance(8); } public void Restore(ReadOnlySpan<byte> snapshot) => Step = BinaryPrimitives.ReadInt64LittleEndian(snapshot); public void CollectEntities(List<EntityInfo> into) => into.Clear(); public bool Inspect(EntityId entity, PropertyList into) { into.Clear(); return false; } public void EncodePoke(in PokeCall call, IBufferWriter<byte> into) => throw new NotSupportedException(); public Difference? FirstDifference(IScopeWorld other) => Step == other.Step ? null : new Difference(default, "Step", Step.ToString(), other.Step.ToString()); public void Draw(DrawList into, in DrawRequest request) { } }
Before offset: shared 2, A 2, B 5 After offset: shared 2, A 2, B 7 After reset: shared 2, A 2, B 5
If the requested source number does not exist, OneScope returns not_found; check the current source numbers before applying the offset.
Variations
Clear the offset
Append these two operations to the onescope open command to reset source 1 and check it at shared tick 2 again:
--run 'offset {"source":1,"offset":0}' \ --run 'seek {"step":2}'
The last result shows source 1 at tick 5 again: tick 2 falls before its first recorded tick.
Related recipes
The short answer
Use offset on the replay whose tick labels differ. Leave the reference replay at offset zero. At shared tick s, the other replay shows its own tick s + offset, clamped to the ticks it recorded. In this example, the starts, A’s tick 0 and B’s tick 5, represent the same moment, so B’s offset is +5. Two ticks later the two views show ticks 2 and 7.
How do I calculate the tick offset between two replays?
Pick a moment you can identify in both recordings, then subtract the reference replay’s tick from the other replay’s tick at that moment. For example, if a collision occurs at tick 40 in the reference and tick 45 in the second run, use +5. If the second run records it at tick 37 instead, use -3. The sign tells OneScope which tick number to look up in that recording, not which way to drag its timeline.
Use the difference between the two start ticks only if the start states already represent the same moment. If one recorder started after the motion began, use a later event that both files captured. Check another event farther along if you need the runs to stay aligned across a range.
Can I synchronize replays recorded at different tick rates?
An offset adds the same number at every seek. It can line up one event but cannot make recordings with different tick rates stay synchronized. If the runs use different steps per second, a fixed difference in tick numbers won’t describe the same elapsed time throughout both recordings. Changing OneScope’s presentation speed does not change the recorded steps or resample them.
Check the shared step against the per-source step fields in seek. Near the ends of a recording, OneScope holds the first or last available state, which can look like a pause while the other source continues. The shared timeline covers the union of the shifted ranges, not just their overlap. For a side-by-side comparison, inspect steps where both recordings have data. See the shell’s offset and time behavior.