@breezil/packet-defs

v1.0.1

Published

22 days ago

Typed Minecraft protocol packet definitions and shared interfaces. Minecraft 1.8.9 is available now, with every version planned.

0High
0Medium
0Low

grillekkj

breezil minecraft packets protocol 1.8.9 typescript

Breezil-Packets

Fully typed Minecraft protocol packet definitions for the Breezil ecosystem. Minecraft 1.8.9 is ready today, with every version on the way.

Documentation | Report a bug | Request a feature | Join the Discord

About

Breezil-Packets describes Minecraft protocol packets as typed TypeScript interfaces, organized by protocol state and direction. It gives the rest of the Breezil ecosystem one shared, honest source of truth for what is on the wire.

Today it ships complete coverage of Minecraft 1.8.9 (protocol version 47). The goal is to bring every Minecraft version under the same roof, each one fully typed and documented the same way 1.8.9 is. The package is pure type definitions plus a handful of helper enums and constants, with no runtime protocol logic of its own, so tools like the Breezil proxy can decode raw network frames by numeric packet id straight into typed, well documented shapes.

Part of Breezil, an open-source org building clean, well-documented projects, tools, and bots. No closed blobs, no sketchy builds. Every line is here to read.

Using a third-party API or platform? Breezil-Packets follows the terms of service of anything it integrates with. We do not ship anything designed to abuse a platform or get accounts banned.

Versions

| Minecraft version | Protocol | Status | | ----------------- | -------- | --------- | | 1.8.9 | 47 | Available | | Other versions | various | Planned |

Every new version targets the same bar: complete coverage of all states and directions, every packet a documented interface, every field annotated with the values you can expect.

Features

🧩 Complete packet coverage for every 1.8.9 protocol state: handshake, status, login, and play (clientbound and serverbound)
🏷️ Every packet is a documented TypeScript interface, with per-field notes on the values you can expect
🔢 Built for id-based decoding, so consumers like the proxy map a numeric packet id to a typed shape
🛰️ Bonus coverage for custom Hypixel ModAPI packets and channels
🧭 Designed to grow across Minecraft versions, each one held to the same complete, documented standard
📦 Ships as a typed library, with .d.ts declarations published alongside the build

Tech Stack

| Layer | Choice | | ----------- | --------------------------------------------- | | Language | TypeScript | | Build | tsc -b (TypeScript project references) | | Types | @types/node (some fields use Node Buffer) | | Package mgr | npm |

Getting Started

Prerequisites

Make sure you have these installed before you start.

| Requirement | Version | Notes | | ----------- | ------- | -------------------------------- | | Node.js | >=20 | nodejs.org | | npm | >=10 | Ships with Node.js |

Installation

# Clone the repo
git clone https://github.com/Breezil/Breezil-Packets.git
cd Breezil-Packets

# Install dependencies and build
npm install
npm run build

Prefer it as a dependency in your own project?

npm install @breezil/packet-defs

Quick Start

import type {
  SetProtocolServerbound,
  ChatClientbound,
} from "@breezil/packet-defs";

// Read a decoded chat packet with a known, typed shape.
function describeChat(packet: ChatClientbound): string {
  return `[pos ${packet.position}] ${packet.message}`;
}

// Build a handshake to send to the server.
const handshake: SetProtocolServerbound = {
  protocolVersion: 47, // Minecraft 1.8.9
  serverHost: "mc.hypixel.net",
  serverPort: 25565,
  nextState: 2, // Login
};

Because this package is type definitions, the imports above add no runtime weight. You pair them with whatever encoder or decoder you already use, and the shapes keep both sides honest.

Documentation

The full reference and guides live at breezil.github.io/Breezil-Packets.

This README covers the essentials. The docs site is the complete reference: every packet across every state and direction, with its numeric id and every field documented. Start there when you need the exact shape of something on the wire.

| Page | What is inside | | ---------------------------------------------------------------------------------- | --------------------------------------------- | | Getting Started | Install, import, and use the type definitions | | API Reference | The complete, per-packet, per-field reference |

API Reference

Everything is exported from the single entry point @breezil/packet-defs. There are no functions or classes to call, only interfaces, enums, and a few constants, grouped by protocol state and direction so they line up with how packets flow on the wire.

| Category | What is inside | | ------------------------------ | ------------------------------------------------------------------------------------------ | | Handshake | SetProtocolServerbound, LegacyServerListPingServerbound, and helpers | | Login | LoginStartServerbound, LoginSuccessClientbound, EncryptionBegin*, and more | | Status | ServerInfoClientbound, PingClientbound, ServerStatusResponse, and more | | Hypixel (ModAPI) | HypixelLocationPacket, HypixelPartyInfoPacket, HYPIXEL_CHANNELS, and more | | Play, clientbound, connection | KeepAliveClientbound, LoginClientbound, RespawnClientbound, and more | | Play, clientbound, player | PositionClientbound, UpdateHealthClientbound, AbilitiesClientbound, and more | | Play, clientbound, chat and UI | ChatClientbound, TitleClientbound, PlayerInfoClientbound, and more | | Play, clientbound, scoreboard | ScoreboardObjectiveClientbound, ScoreboardTeamClientbound, and more | | Play, clientbound, entity | SpawnEntityClientbound, EntityTeleportClientbound, EntityMetadata, and more | | Play, clientbound, inventory | OpenWindowClientbound, SetSlotClientbound, WindowItemsClientbound, and more | | Play, clientbound, world | MapChunkClientbound, BlockChangeClientbound, ExplosionClientbound, and more | | Play, serverbound, connection | KeepAliveServerbound, SettingsServerbound, CustomPayloadServerbound, and more | | Play, serverbound, movement | PositionServerbound, LookServerbound, PositionLookServerbound, and more | | Play, serverbound, interaction | UseEntityServerbound, BlockDigServerbound, BlockPlaceServerbound, and more | | Play, serverbound, inventory | WindowClickServerbound, SetCreativeSlotServerbound, EnchantItemServerbound, and more | | Play, serverbound, chat | ChatServerbound, TabCompleteServerbound, UpdateSignServerbound |

Many categories also export supporting enums and value unions (for example NextProtocolState, ChatMessagePosition, DiggingStatus, ScoreboardScoreAction) and shared structures reused across packets, like Slot, Position, and PlayerProperty.

For the complete list, with every interface, its numeric id, and every field documented, see the full API Reference.

Project Structure

Breezil-Packets/
├─ src/
│  ├─ index.ts                  # Public entry point, re-exports everything
│  ├─ handshake/                # Handshake state (index.ts + types.ts)
│  ├─ login/                    # Login state packets
│  ├─ status/                   # Server list ping / status
│  ├─ hypixel/                  # Custom Hypixel ModAPI packets and channels
│  └─ play/
│     ├─ clientbound/           # Server to client packets
│     │  ├─ connection/
│     │  ├─ player/
│     │  ├─ chat/
│     │  ├─ scoreboard/
│     │  ├─ entity/
│     │  ├─ inventory/
│     │  └─ world/
│     └─ serverbound/           # Client to server packets
│        ├─ connection/
│        ├─ movement/
│        ├─ interaction/
│        ├─ inventory/
│        └─ chat/
├─ docs/                        # VitePress docs site, logo, assets
└─ package.json

Each leaf folder typically holds an index.ts with the packet interfaces and, where needed, a types.ts with the enums and value unions those packets reference.

Releases and Deployment

Two things ship automatically from this repo, so there is no manual deploy step.

Documentation. The docs site rebuilds and deploys to GitHub Pages on every push to main, via .github/workflows/docs.yml. Merge to main and the site updates on its own.

npm package. Publishing to npm is automated by .github/workflows/publish.yml, which runs when a GitHub Release is published. Releases follow Semantic Versioning. To cut one:

Bump version in package.json (for example 1.0.1).
Commit that change to main.
On GitHub, go to Releases, choose Draft a new release, create a tag like v1.0.1, write the notes, and click Publish release.

Publishing the release triggers the workflow, which builds the package and runs npm publish with provenance. The first publish is done once by a maintainer (npm publish locally) so the package exists, after which the Trusted Publisher setup lets the Action handle every release with no token to manage.

Roadmap

Minecraft 1.8.9 (protocol version 47) is complete today: every state and direction, fully typed and documented. From there:

[ ] Add more Minecraft versions, each held to the same complete, per-field standard
[ ] Per-version exports, so you can pin the exact protocol version you target

Want a particular version prioritized? Open a feature request.

Contributing

Contributions are welcome and genuinely appreciated, first timers included. 💙

Fork the repo and create your branch: git checkout -b feat/my-feature
Make your changes, keeping field docs accurate and ids correct
Run npm run build to make sure the types still compile cleanly
Commit using Conventional Commits: feat: add combat event packet
Open a Pull Request and describe what changed and why

New to the project? Look for issues labeled good first issue. See the Breezil contributing guide for the full guide.

Code of Conduct

This project follows the Breezil Code of Conduct. By taking part you agree to uphold it. Be kind, be welcoming.

License

Distributed under the MIT License. See LICENSE for the full text.

Support and Community

💬 Discord: Join the Breezil community
🐛 Issues: github.com/Breezil/Breezil-Packets/issues
💡 Discussions: github.com/Breezil/Breezil-Packets/discussions

Acknowledgements

The Minecraft 1.8.9 protocol (version 47) as documented by the wiki.vg community
minecraft-protocol for protocol reference
Everyone in the Breezil Discord