Switching to BlinkBlox

A game that already has networking does not start from an empty schema. For five libraries the compiler reads the definitions the game has and writes a draft schema from them, and for every library there is a guide with the call sites side by side and a short wrapper that keeps the old call names working while they move.

The converters

blinkblox <definitions> --from <library>

From	Command	Reads	What the draft carries over
zap	--from zap	the .zap config	options, types, events, functions, namespaces, comments
ByteNet	--from bytenet	the Luau module that defines the packets	namespaces, packets, their types and reliability
Packet	--from packet	the Luau module that defines the packets	packets, their types, responses as functions, one-byte length bounds
QuickNet	--from quicknet	the Luau module that registers the events	events, their types, reliability, responses, and the rate limits
Warp	--from warp	the Luau module that calls useSchema	each schema as an event
Blink	none needed		a Blink schema is a BlinkBlox schema
Plain remotes	none		there are no definitions to read; the guide shows how to write them

A zap config is read as text. The other four define their events by running Luau, so the command runs the definitions file against a stand-in for the library that records what is defined and sends nothing. The file gets placeholders for game, script and the other Roblox globals, and no filesystem, network or process library. The details are under Command line.

What a draft is

The command writes a .blink file beside the definitions and prints what is left to decide. Three things hold for every draft:

• It compiles. The compiler compiles it before handing it over.
• It does not guess. What the other library has no way to say is a TODO(convert) comment where the answer goes, never a number picked for you.
• Nothing is dropped silently. A type with no equivalent becomes unknown, and each one is named in the printed list.

What a draft asks for depends on what the library’s definitions hold:

	zap	ByteNet	Packet	QuickNet	Warp
Which side sends an event	stated	asked	asked	asked	asked
Whether it is reliable	stated	stated	always reliable	stated	asked
How often a client may fire it	asked	asked	asked	carried over	asked
An upper bound on each length a client sends	asked where zap had none	asked	asked, except one-byte lengths	asked, except one-byte lengths	asked

Only what a client sends is marked for a rate and a bound. An unbounded array in an event the server fires is the server’s own business.

Moving a game

1. Convert the definitions, or write the schema by hand from plain remotes.
2. Settle the marks in the draft and compile it.
3. Wrap the generated modules in the guide’s wrapper, so the existing call sites keep working.
4. Move the call sites to the generated API, an event at a time. BlinkBlox uses remotes of its own, so it runs beside the library it is replacing.
5. Delete the wrapper and the old library, and install the server’s handlers. See Securing the server.

The guides

Plain remotesRemoteEvent and RemoteFunction: writing the schema, and what the checks in a listener become.

zapThe closest language. A config converts almost line for line.

ByteNetNamespaces and packets, and the player moving to the front of every call.

PacketPackets, responses as functions, and signals.

QuickNetEvents with their rate limits carried over.

WarpEvents by name, with direction and reliability stated once.

BlinkThe schema carries over; the wire and the server's behaviour change.