Limitations

What is missing or fragile today, so you can plan around it.

mc-protocol works end to end against a real 26.2 client, but it is young. These are the known gaps, in roughly the order they are likely to bite you. The repository’s todo.md tracks the plan for each.

Protocol

• One version. Only Minecraft 26.2 / protocol 776 is built in. The negotiation and the per-version tables exist (see Versions), but a second version needs its packet definitions generated first.
• No encryption. The clientbound login Hello (encryption request) and serverbound Key packets are defined, but nothing implements the RSA/AES exchange. Servers run offline-mode only; clients and proxies cannot join online-mode servers.
• Offline identity is trusted. autoInit uses whatever username and UUID the client sends in Hello. Two clients claiming the same name are not rejected.

Connection handling

• Outgoing packets are not serialized per client. Two concurrent sendPacket calls on the same client can interleave if packet lookup or the socket write yields. Sequential await (as in every example in these docs) is safe; fire-and-forget bursts are not.
• autoInit is not awaited. The server starts the initialization sequence without waiting for it, so a client that spams LoginAcknowledged could trigger overlapping runs.
• No handshake timeouts. A client that connects and never sends anything stays connected. Only the play-state keep-alive (30 s) drops idle clients.
• close() is not awaitable. It destroys clients and closes the listener, but there is no graceful drain.

Validation

• Strings, UUIDs, and fixed-size byte fields are read without checking negative or oversized lengths first.
• NBT decoding has no nesting limit.
• Outgoing frames are not checked against the peer’s size limits before writing.

A malformed packet from a hostile peer is more likely to throw (surfacing on Packet:Error or Client:Error) than to be handled gracefully.

Typing

sendPacket(name, data) takes data: any, and packet event payloads are unknown. There are no generated TypeScript types for packet fields yet; use the Packets reference for field names.

Tooling

tools/generate-packet-index.ts, tools/generate-blocks.ts, and tools/generate-items.ts are in the repository. They rebuild lookup tables from files that are already checked in. The generator that produces packet definition files from Minecraft protocol data is not; adding a new protocol version is not a one-command job.

What is planned next

In order: per-client send ordering, awaited and guarded autoInit, connection deadlines, field validation, typed packet payloads, and then opt-in client-side login automation. Contributions are welcome at GDLev/mc-protocol.