Use cases
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
A Rust or C# server, Unity clients in C#, Unreal clients in C++. One schema, and every engine reads and writes the same bytes.
com.fomoxa.networking package takes Vector3, Quaternion, Color and other Unity types as field types and generates their codecs.// 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
Services in Go, Rust, C# and Node.js exchanging messages where the bytes themselves carry meaning: signed, hashed, cached or compared.
fomoxac ci compares the schema against the target branch and fails the build on a breaking change..fomoxa/schema.json around and use fomoxa-inspect.// 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
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.
static inline functions, with no dependency.-fno-exceptions.string, bytes and arrays in the generated C allocates with malloc. On targets without a heap, keep those fields out of the model./* 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
Replay recorders, binary logs, level and asset pipelines, editor plugins: tools written in one language that read data produced by another.
.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.# 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.