A deterministic binary wire format: one value has exactly one valid encoding, so a Rust server,
a C# client and a C device agree byte for byte. The reference generator reads annotations on the
types you already have.
The specification is the single source of truth. The spec is never changed to accommodate an
implementation; everything else is derived from it.
The order Fomoxa follows
RFC
Compiler
SDK
Application
Not this
SDK
Protocol
A protocol shaped by the first library that wrote it.
The test applied to every sentence of the specification:
could somebody writing an encoder in assembly on an 8-bit microcontroller follow it?
If not, that sentence describes an implementation and is removed from the spec.
Definition
What is Fomoxa?
Fomoxa is a protocol.
Fomoxa is not
× RPC
× Networking
× Runtime
× Serialization library
Fomoxa only specifies
Model
Bytes
Model
Transport, retransmission, ordering, matchmaking, encryption, compression, checksums:
all of these are built on top of Fomoxa. The specification stops where
the bytes are formed.
Philosophy
Ten principles, two layers.
Seven are conformance conditions. Three are choices the Reference Implementation made.
Mixing the two gradually turns a protocol into a framework.
Principles of the specification
A format that violates any of these is not Fomoxa.
01Specification first
The spec is the single source of truth. Never change it to accommodate an implementation.
02Protocol over framework
Fomoxa defines how data appears on the wire, and defines no API or runtime.
03Minimal wire format
Send the data, never a description of it: no field names, type info, tags or padding.
04Deterministic by design
One value, exactly one byte sequence. Two valid encodings of the same data must not exist.
05Language neutral
No language is the reference language. Nothing in the format favours one type system.
06Implementation independent
No mandated parser, macro, or generator. The spec describes bytes and stops.
07Implementation replaceable
The Reference Implementation is not the standard. Replace it entirely and the wire format holds.
Principles of the Reference Implementation
Design choices, not conformance conditions. Another implementation may choose differently,
provided the bytes stay the same.
08User owns the Model
No mandatory DTO layer, no base class. The RI reads the fields you mark and ignores the rest.
09Compile-time over runtime
Anything decidable at build time is decided at build time.
10Zero runtime reflection
The wire format permits a reflection-free implementation and the spec does not require one, so AOT and bare-metal targets stay viable.
The decision rule, in two questions. One: is this statement observable from the
byte stream? If not, it belongs to the Reference Implementation and must not enter the spec.
Two: does it violate one of the seven above? If yes, it is not part of Fomoxa.
Trade-offs
What Fomoxa deliberately does not do
Each of these is the direct cost of a guarantee above. None of them is on a roadmap.
✕
Schema evolution only at the end
Position is the only field identifier. Append or remove a field at the
end of a Model and the wire holds (Version skew, RFC-0002 §9.1).
Inserting a field in the middle, reordering fields, changing a field's type: breaking change.
✕
Compatibility only at the trailing edge
An old client reads a new server's message only when the sole change is a
field appended at the end. The extra bytes are discarded (Version skew, RFC-0002 §9.1).
A field inserted or changed in the middle is a hard break, and both ends
must deploy together.
✕
No metadata, not self-describing
The stream carries no field names, types or tags. The receiver must already know the
field order and types. As a consequence, decoding against the wrong definition
usually raises no error and silently produces wrong values.
✕
No mandated IDL
The source of truth is the Schema. The spec does not dictate how you
write the Schema down. No mandatory IDL, no mandatory .fomoxa file. The
Reference Implementation expresses the Schema as annotations on your existing type. It
extracts exactly three things: the type, its fields, and each field's Fomoxa type. The
cost: no standalone Schema document to hand a third party. Each end must
derive the same Schema independently.
✕
No Optional, no nullable, no explicit default
There is no wire-level marker for absence, neither a tag nor a null byte. A trailing field can
end up with no data through Version skew (§9.1). How an implementation represents that
(a default value, Option<T>, an exception) is left to the
implementation, not to the wire format.
✕
No transport, no framing, no crypto
Fomoxa produces a byte sequence and stops. Message boundaries, retransmission, ordering,
encryption and compression belong to layers built on top.
If any of these is unacceptable for your problem, a format with tag IDs and optional fields will
serve it better.
Count for [1,2,3] is 3, not 12. An empty inner array is a count of 0 and no further bytes.
Enum
Always UInt32. Four bytes, regardless of how few members it declares.
enum PlayerState { Idle=0, Walk=1, Run=2, Jump=3 }
Idle → [00 00 00 00]
Walk → [01 00 00 00]
Jump → [03 00 00 00]
99 → invalid - outside the defined set
A protocol decision, not a storage optimization. There is nothing for two peers to negotiate.
Version skew
The writer and the reader may run two different versions of the same Model. One condition:
the only difference is a field appended or removed at the end.
model ItemV1 { id: u32 }
model ItemV2 { id: u32; name: String }
written ItemV1, read ItemV2
[2A 00 00 00] → id=42, bytes end exactly on the boundary before name
→ valid - name has no data
written ItemV2, read ItemV1
[2A 00 00 00 05 00 00 00 53 77 6F 72 64] → id=42, 9 bytes remain
→ valid - the leftover is discarded
written ItemV2, read ItemV2, truncated mid-field
[2A 00 00 00 05 00 00 00 53 77] → length=5, only 2 bytes of data remain
→ invalid - Unexpected EOF, NOT version skew
The stopping rule is “does the shortfall or surplus fall exactly on a field boundary?”, not “is data missing?”. Inserting a field mid-Model, reordering fields, changing a
field's type: still a breaking change. See RFC-0002 §9.1.
A complete message, byte by byte
The example from RFC-0002 §15. Nested model, string, integers, bool. It encodes to 31 bytes.
Hover a field to light up the bytes it owns. Hover a byte to find its owner.
Want to change the values? Open it in the inspector →
Hex dump · 31 bytesPosition is the only identifier
000000002A000000060000004B6E696768740000
0000001028416666A2413333A3C06400000001
Total31 bytes · 0 bytes of metadata
Nothing separates the fields: the nested model has no length prefix, there is no delimiter between
position and health, and there is no terminator at the end. The decoder knows
which field it is reading from how far the cursor has advanced. That is why
reordering a field is a breaking change, and why renaming one is free.
A test vector is a pair of (logical value, byte sequence), never a pair of
(function call, return value). A vector names no method, no language, no API.
Input→Expected bytes
Primitive
ID
Input
Expected bytes
P-002
bool true
01
P-011
u8 255
FF
P-021
u16 300
2C 01
P-032
u32 0x12345678
78 56 34 12
P-035
i32 −2147483648
00 00 00 80
P-042
u64 2⁶⁴−1
FF FF FF FF FF FF FF FF
F-005
f32 0x4048F5C3 · 3.14
C3 F5 48 40
F-002
f32 0x80000000 · −0.0
00 00 00 80
F-031
f32 0x7FC00001 · NaN
01 00 C0 7F
S-004
String “中”
03 00 00 00 E4 B8 AD
S-005
String “Xin chào”
09 00 00 00 58 69 6E 20 63 68 C3 A0 6F
P-032 catches endianness. A big-endian implementation writes 12 34 56 78 and fails here.
F-031 catches NaN canonicalization. Producing 00 00 C0 7F means user data was modified.
Model
ID
Input
Expected bytes
T-001
Item{ id=42, name="Sword" }
2A 00 00 00 05 00 00 00 53 77 6F 72 64
T-002
Empty{}
- 0 bytes
T-003
Vector3{1.5, 2.5, 3.5}
00 00 C0 3F 00 00 20 40 00 00 60 40
T-004
Body{ pos=Vector3{1.5,2.5,3.5}, hp=100 }
00 00 C0 3F 00 00 20 40 00 00 60 40 64 00 00 00
T-010
Mixed{ a=1, b=2, c=3 }
01 02 00 00 00 03
T-011
Order{ z=1, a=2 }
01 02
T-010 catches memory-layout copying (12 bytes) and compiler field reordering.
T-011 catches implementations that sort fields alphabetically “for stability”. 02 01 is a bug.
Array
ID
Input
Expected bytes
A-001
Array<u32> []
00 00 00 00
A-002
Array<u32> [1,2,3]
03 00 00 00 01 00 00 00 02 00 00 00 03 00 00 00
A-003
Array<String> ["a","bc"]
02 00 00 00 01 00 00 00 61 02 00 00 00 62 63
A-004
Array<Array<u8>> [[1,2],[]]
02 00 00 00 02 00 00 00 01 02 00 00 00 00
A-005
Array<bool> [true,false,true]
03 00 00 00 01 00 01
A-002 catches the count-versus-byte-length bug. The correct count is 3, not 12.
Enum
ID
Input
Expected bytes
E-001
PlayerState::Idle
00 00 00 00
E-002
PlayerState::Walk
01 00 00 00
E-003
PlayerState::Jump
03 00 00 00
E-010
Encoded size of any enum
always 4 bytes
E-010 catches implementations that “optimize” a four-member enum down to one byte.
Version skew
ID
Written
Read
Bytes
Expectation
V-001
ItemV1{ id: u32 }
ItemV2{ id: u32; name: String }
2A 00 00 00
✓ not rejected · name has no data
V-002
ItemV2{ id: u32; name: String }
ItemV1{ id: u32 }
2A 00 00 00 05 00 00 00 53 77 6F 72 64
✓ not rejected · 9 leftover bytes discarded
Valid only when the shortfall or surplus lands exactly on a field boundary.
Compare with N-022 below: bytes go missing mid-field, and it MUST still be rejected. Treating
every missing or extra byte as version skew, even mid-field, is the most common conformance
bug when adding this support (RFC-0002 §9.1).
Invalid stream
ID
Input bytes
Expected result
N-001
bool · 02
reject · not 00/01
N-010
u32 · 00 00 00
reject · unexpected EOF
N-020
String · 02 00 00 00 FF FE
reject · invalid UTF-8
N-021
String · 03 00 00 00 ED A0 80
reject · encoded surrogate
N-022
String · 05 00 00 00 41 6C 69
reject · length 5, 3 bytes remain
N-023
String · 64 00 00 00 41 6C 69 63 65
reject · length 100, 5 bytes remain
N-030
Array<u32> · 03 00 00 00 01 00 00 00
reject · count 3, one element
N-031
Array<u32> · FF FF FF FF
reject · before allocating
N-040
enum{0,1} · 63 00 00 00
reject · value 99 undefined
Rejection is MUST; the error name is only SHOULD. N-023 and N-031 check whether the length
is validated before allocating. Crashing and catching the exception
does not count as a pass.
The full set is in
RFC-0003.
It covers 8-byte integers, f64, round-trip checks, and cross-implementation checks.
Conformance
Fomoxa Compatible
An implementation is Fomoxa Compatible if and only if it passes
100% of the test vectors.
✓ RFC-0002
✓ Test vectors
✓ Deterministic output
There is no “partially compatible” level such as 98%. One failing vector means data exists on
which two implementations disagree, silently, in production.
An implementation 10× slower that passes 100% of the vectors is Fomoxa Compatible.
A faster implementation that fails one vector is not.
These tools are reference implementations of the Fomoxa Protocol.
They are not part of the protocol itself.
Replace all of them and the wire format holds. Nothing in Fomoxa requires you to use them.
They are published so others can read them and write better ones. See the whole ecosystem →