Protocol Puzzle is a visual, block-based parser generator. It bridges the gap between abstract binary/text protocol definitions and concrete implementation code. Define your protocol using a drag-and-drop puzzle interface and instantly generate high-performance parsing code for C++, C#, and Python.
It includes a Virtual Test Lab powered by GenAI (Google Gemini or OpenAI) to simulate parsing logic against raw Hex data before you even compile your code.
- Visual Editor: Drag-and-drop interface to define Structs, Lists, Primitives, and Bitfields.
- Multi-Language Support: Generate idiomatic code for C#, C++, and Python.
- AI-Powered Simulation: Test your protocol logic immediately with a "Virtual Runtime" that parses Hex strings on the fly.
- Dual AI Provider: Support for Google Gemini (Flash 2.5) and OpenAI (GPT-4).
- Drag & Drop Reordering: Easily restructure your protocol definitions.
- A modern web browser (Chrome, Edge, Firefox).
- An API Key for Google Gemini or OpenAI.
This project uses modern ES Modules via esm.sh. You can serve it using any static file server.
-
Clone the repository:
git clone https://github.com/yourusername/protocol-puzzle.git cd protocol-puzzle -
Start a static server (e.g., using Python):
# Python 3 python -m http.server 8080 -
Open
http://localhost:8080in your browser. -
Click the Settings (Gear Icon) in the top right to configure your API Key.
We provide a Docker configuration for easy deployment.
Option 1: Using Docker Compose (Recommended)
# Build and start the container
docker-compose up -d --buildAccess the app at http://localhost:8080.
Option 2: Building Manually
docker build -t protocol-puzzle .
docker run -p 8080:80 protocol-puzzleWe aim to make Protocol Puzzle the standard tool for rapid protocol prototyping.
- Basic Block Structure (Int, String, Float)
- Complex Types (Nested Structs, Repeated Lists, Bitfields)
- Recursive Visual Rendering
- Code Generation (C#, C++, Python)
- Virtual Test Lab (GenAI Simulation)
- Drag & Drop Reordering
- Multi-Provider Support (Google & OpenAI)
- Endianness Control: Toggle Big/Little Endian per field or globally.
- Conditional Fields: Support "If-Else" blocks (e.g., if field_A == 1, then parse field_B).
- Enums: First-class support for Enum definitions and mapping.
- Computed Fields: Fields that derive values from others (Length, Checksums).
- Protobuf Import/Export: Convert
.protofiles to Puzzle blocks and vice versa. - Pcap Integration: Upload a
.pcapfile and attempt to auto-generate a schema. - Project Persistence: Save/Load projects to LocalStorage or a JSON file.
- Syntax Highlighting: PrismJS integration for the code viewer.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
See CONTRIBUTING.md for detailed guidelines.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.