Usage

Delta-Pack supports TypeScript, C#, and Rust. All three share the same schema format and binary encoding, so a TypeScript server can communicate with a Rust or C# client.

Code generation (recommended)

Generate typed code from a YAML schema using the CLI:

delta-pack generate schema.yml -l typescript -o generated.ts
delta-pack generate schema.yml -l csharp -o Generated.cs
delta-pack generate schema.yml -l rust -o generated.rs

TypeScript

Install:

npm install @hpx7/delta-pack

TypeScript supports codegen mode as well as a dynamic runtime mode.

Codegen:

import { Position } from "./generated";

const prev: Position = Position.default();
const current: Position = { ...prev, x: 1.5 };

// Snapshot
const snapshotBytes = Position.encode(current);
const decoded = Position.decode(snapshotBytes);
Position.equals(decoded, current); // true

// Delta
const diffBytes = Position.encodeDiff(prev, current);
const patched = Position.decodeDiff(prev, diffBytes);
Position.equals(patched, current); // true

Runtime -- define schemas programmatically, no build step needed:

Schema definition:

import { ObjectType, FloatType, load, Infer } from "@hpx7/delta-pack";

const Position = ObjectType("Position", {
  x: FloatType({ precision: 0.1 }),
  y: FloatType({ precision: 0.1 }),
});
type Position = Infer<typeof Position>;

const api = load(Position);
const bytes = api.encode({ x: 1.5, y: 2.0 });

Class definition:

import { FloatType, loadClass } from "@hpx7/delta-pack";

class Position {
  @FloatType({ precision: 0.1 })
  x: number = 0;

  @FloatType({ precision: 0.1 })
  y: number = 0;
}

const api = loadClass(Position);
const bytes = api.encode(new Position());

C#

Install:

dotnet add package DeltaPack

The C# runtime is Unity-compatible, and supports both codegen and runtime modes.

Codegen:

var prev = Position.Default();
var current = Position.Clone(prev);
current.X = 1.5f;

// Snapshot
byte[] snapshotBytes = Position.Encode(current);
Position decoded = Position.Decode(snapshotBytes);
Position.Equals(decoded, current); // true

// Delta
byte[] diffBytes = Position.EncodeDiff(prev, current);
Position patched = Position.DecodeDiff(prev, diffBytes);
Position.Equals(patched, current); // true

Runtime -- build schemas from C# classes:

class Position {
    [DeltaPackPrecision(0.1)]
    public float X { get; set; }
    [DeltaPackPrecision(0.1)]
    public float Y { get; set; }
}

var api = new DeltaPackCodec<Position>();
byte[] bytes = api.Encode(new Position { X = 1.5f, Y = 2.0f });

Rust

Install:

cargo add delta-pack

Rust uses codegen exclusively:

use generated::Position;

let prev = Position::default();
let current = Position { x: 1.5, ..prev.clone() };

// Snapshot
let snapshot_bytes = current.encode();
let decoded = Position::decode(&snapshot_bytes);
current.equals(&decoded); // true

// Delta
let diff_bytes = Position::encode_diff(&prev, &current);
let patched = Position::decode_diff(&prev, &diff_bytes);
current.equals(&patched); // true

CLI

The delta-pack CLI handles code generation and data conversion:

# Encode JSON to binary
delta-pack encode schema.yml -t Player -i state.json -o state.bin

# Decode binary to JSON
delta-pack decode schema.yml -t Player -i state.bin -o state.json

# Create a binary diff
delta-pack encode-diff schema.yml -t Player --old prev.json --new next.json -o diff.bin

# Apply a binary diff
delta-pack decode-diff schema.yml -t Player --old prev.json --diff diff.bin -o next.json