Why Fomoxa
Most formats let the encoder choose: field order, integer width, whether to write a default. Fomoxa takes every one of those choices away, so the same value gives the same bytes in every language. This page covers when that is worth it, and what it costs.
Problem
With JSON or Protobuf, the same data can come out as different bytes depending on the language, the library or the version. Usually nobody notices, but it causes failures in three places.
A signature covers bytes. If another implementation re-encodes the value differently, verification fails although the data did not change.
Two machines must reach the same state from the same inputs. A checksum over that state only works if both sides serialize it identically.
The only way to prove two SDKs agree is to compare their bytes. That needs exactly one right answer to compare against.
Idea
Wherever an encoder is allowed to choose, two encoders will eventually choose differently. Four rules leave the encoder nothing to choose.
u32 is four bytes, even for zero, and there are no varints.u32 length or count. String length counts UTF-8 bytes.Each rule has a price, listed under trade-offs: fields evolve only at the end, nothing is optional, and decoding against the wrong schema usually gives wrong values rather than an error. What you get in return is a single test for correctness: pass 100% of the RFC-0003 vectors.
Workflow
Protobuf keeps the schema in one .proto file and generates a type per language.
The Fomoxa reference tools keep it on the types you already have. Each approach has costs, listed below.
.proto file.protoc or buf for each target language.buf breaking.fomoxac generate in each of those projects.fomoxac ci fails a pull request on a breaking change.fomoxac ci and by the runtime handshake at connect time, not by the compiler..fomoxa/schema.json is generated output.Seen in practice: fomoxa-example-game declares its protocol in Rust, C# and C++, and a script checks that each schema fingerprint matches the server's.
Annotations are a choice of the reference tools, not of the specification. A separate schema file, macros or a hand-written codec are equally valid, as long as the bytes pass RFC-0003.
Fit