Fomoxa

EN/VI

Use cases

Where identical bytes matter

Fomoxa fits wherever two programs, often in two languages, must agree on data down to the byte. Here are four places that happens, with what works well and what to know before you start.

01 · Games

Multiplayer games across engines

A Rust or C# server, Unity clients in C#, Unreal clients in C++. One schema, and every engine reads and writes the same bytes.

Why it fits
  • Byte-identical snapshots make lockstep, replays and desync checksums comparable across platforms.
  • No tags or names on the wire: a player state costs only its fields. The example game spends 29 bytes per player.
  • Generated code uses no reflection, so it runs under Unity IL2CPP and other AOT targets.
  • The C# runtime targets netstandard2.1 and runs in Unity 2021+. In Unity 6, the com.fomoxa.networking package takes Vector3, Quaternion, Color and other Unity types as field types and generates their codecs.
Things to know
  • Client and server ship from the same schema. Only fields appended at the end survive a rolling update.
  • A client decoding with an outdated schema gets wrong values, not an error. The runtimes' schema handshake exists to stop that at connect time.
  • Fomoxa does not do prediction, interpolation or delta compression. Those stay in your netcode.
// Unity · a model with Unity types, for com.fomoxa.networking
[Network]
[Codec("game")]
public class PlayerState
{
    [Network("u32")]        [Codec("game")] public uint Id { get; set; }
    [Network("Vector3")]    [Codec("game")] public Vector3 Position { get; set; }
    [Network("Quaternion")] [Codec("game")] public Quaternion Rotation { get; set; }
    [Network("u8")]         [Codec("game")] public byte Health { get; set; }
}

Compared with other formats: Protobuf and FlatBuffers allow more than one valid encoding of the same snapshot, and Cap'n Proto's canonical form is opt-in. With them, two engines that compare snapshots must both run the same canonicalization step. With Fomoxa that step is the format itself.

Seen running: fomoxa-example-game puts Unity, Unreal and Go clients in one match against a Rust server. A single-threaded server held 30 Hz for 1000 bots, each receiving the state of 999 others, and encoding took 0.02 ms of the 33.3 ms tick.

02 · Services

Backend service communication

Services in Go, Rust, C# and Node.js exchanging messages where the bytes themselves carry meaning: signed, hashed, cached or compared.

Why it fits
  • A signature or hash made in one language verifies in another, because re-encoding the same value gives the same bytes.
  • Content-addressed caches and deduplication work without a separate canonicalization step.
  • fomoxac ci compares the schema against the target branch and fails the build on a breaking change.
  • Fomoxa is only a payload format, so it fits inside whatever you already run: HTTP bodies, message queues, files, or the sample runtimes over TCP/UDP.
Things to know
  • Teams that deploy independently for months are better served by field-numbered formats.
  • Payloads are not readable in logs. Keep .fomoxa/schema.json around and use fomoxa-inspect.
  • No RPC layer: service definitions, retries and routing are yours.
// Go signs, Rust verifies: both re-encode the same Order and get the same bytes
go    payload := encode(order)                 // 2A 00 00 00 ...
      sig     := ed25519.Sign(key, payload)

rust  let payload = encode(&order);              // 2A 00 00 00 ... identical
      verifying_key.verify(&payload, &sig)?;

Compared with other formats: Protobuf documents its serialization as not canonical, so a verifier checks the exact bytes it received rather than a re-encoding. With Fomoxa, either side can rebuild the payload from the value and get the bytes that were signed.

03 · Embedded

Embedded systems in C

Microcontrollers and gateways talking to servers and tools written in other languages. The specification is written so that an encoder in assembly on an 8-bit MCU can follow it.

Why it fits
  • Generated C is C99, header-only static inline functions, with no dependency.
  • Generated C++ is C++17 and works with -fno-exceptions.
  • A model made only of fixed-width fields always has the same size, so buffers can be sized at compile time.
  • Length and count prefixes are checked against the remaining bytes before any allocation, which matters on untrusted links.
  • The C runtime has no threads and no background work, and accepts a user-supplied transport.
Things to know
  • Decoding string, bytes and arrays in the generated C allocates with malloc. On targets without a heap, keep those fields out of the model.
  • The bundled runtime transports are TCP and UDP sockets. For UART, CAN or radio links, write a transport, or use only the codec with your own framing.
  • Fixed-width integers cost more bytes than varints on slow links.
/* A fixed-size telemetry frame: always 4 + 4 + 2 + 1 = 11 bytes */
FOMOXA_MODEL
FOMOXA_CODEC("uplink")
struct Telemetry
{
    FOMOXA_FIELD(u32) FOMOXA_CODEC("uplink") uint32_t sequence;
    FOMOXA_FIELD(f32) FOMOXA_CODEC("uplink") float    temperature;
    FOMOXA_FIELD(u16) FOMOXA_CODEC("uplink") uint16_t millivolts;
    FOMOXA_FIELD(u8)  FOMOXA_CODEC("uplink") uint8_t  status;
};

Compared with other formats: with varints, a message's size depends on its values, so embedded Protobuf libraries size buffers for the worst case. A Fomoxa model of fixed-width fields has exactly one size, whatever the values.

04 · Tooling

Cross-engine tooling

Replay recorders, binary logs, level and asset pipelines, editor plugins: tools written in one language that read data produced by another.

Why it fits
  • .fomoxa/schema.json is a language-neutral description of every model, ready for tools to read.
  • fomoxa-inspect and the byte inspector decode any payload against a schema.
  • Version skew rules say exactly which old recordings still decode: those that differ only by fields at the end.
  • A recording hashes the same no matter which engine wrote it, so files can be deduplicated and verified.
Things to know
  • Files carry no version marker. Store the schema fingerprint beside the data, or frame it yourself.
  • Reordering or retyping a field makes old files unreadable. Keep the old schema to migrate them.
# decode one frame of a replay file against the schema that recorded it
fomoxa-inspect --schema replays/v3/schema.json --message WorldSnapshot.game --file frame-0042.bin

# check a schema change against the one your recordings were made with
fomoxac compat --base replays/v3/schema.json

Compared with other formats: content-addressing recordings in another binary format works when every writer agrees to canonicalize first, as Cap'n Proto's canonical form allows. Fomoxa has no second form, so any conforming writer produces the same file.

Not sure Fomoxa fits? See how it compares with Protobuf, FlatBuffers, Cap'n Proto, Borsh, BCS, JSON and MessagePack.