A packet capture that runs inside the Minecraft: Bedrock client
Every packet the client sends and receives, and the reason it rejected the ones it could not read
If you write server software, a proxy or a protocol translator, a packet the client cannot read usually shows up as a dropped connection or a world that looks wrong. Spyglass runs inside the client and shows you the packet, how far the client read into it, and the error it raised.
The overlay is laid out like Wireshark, with three panes:
- Packet list. Every packet of the session with its direction, id, length and name. Failed decodes are coloured, and the list follows the newest packet until you scroll up.
- Details. The packet's decoded fields, with the names and enum values the client itself uses. NBT opens as a tag tree. For a failed decode you also get the client's error, the fields it read before it stopped, and the call stack down to file and line. Click a field to highlight its bytes, or click a byte to select the field it belongs to.
- Bytes. The packet body in hex, with the part the client never read tinted. Search it with
Ctrl+FandF3, and copy a selection as a hex dump, a hex stream, text, a C array or base64.
Filtering works the way it does in Wireshark. Type a display filter in the bar under the toolbar, or press Ctrl+/ to
jump there, and press Enter. The bar turns green when the filter is valid and red when it is not, and suggests packet
and field names as you type. Press Tab to take a suggestion.
| Filter | Shows |
|---|---|
MovePlayer or MovePlayerPacket |
that packet |
!(MovePlayer || LevelChunk) |
everything except those two packets |
name contains "Item" |
every packet with Item in its name |
failed |
packets the client failed to decode |
unread > 0 |
packets the client left bytes of unread |
sent, received |
packets in one direction |
id == 0x09, frame.len > 1000, frame.number >= 500 |
packets by id, length or number |
Join terms with &&, ||, ! and parentheses, or with and, or and not. Comparisons also take eq, ne, gt,
lt, ge and le.
To build a filter from something on screen, right-click it and choose Apply as Filter or Prepare as Filter. This
works on a packet, a row of the details tree, a row of Statistics ▸ Packet Types and a group in the expert
information window. In the packet list, the column you right-click decides the field. The arrow at the end of the bar
lists recent filters, and Expression... opens a builder that lists every field and every packet seen so far.
Start, Stop and Restart control the capture. A capture has no length limit, and Spyglass deletes it when the
client closes. Capture ▸ Options sets how much memory it uses and can turn off capturing sent packets. The status
bar shows the packet count, the share that failed, the size of the capture and any dropped packets.
The menus hold everything else:
Gojumps to a packet by number, to the next failed decode or to the next packet of the same kind, and back and forward through the packets you viewed.Editfinds packets by name, id, or hex or text in the body. It also marks packets, sets the zero of theTimecolumn, and copies rows or the details tree as text or CSV.Viewhides panes, zooms, opens a packet in its own window, and sets what theTimecolumn shows.Analyzeopens the filter builder, groups failed decodes by error and packet, and reads the selected bytes as an integer, a float, a varint and text.Statisticsshows a breakdown per packet id, the distribution of packet lengths and a graph of packets or bytes per second.Fileexports packets as text, CSV or JSON, the selected bytes as a raw file, or a session summary. The save dialog starts in%LOCALAPPDATA%\spyglass, or~/.local/share/spyglasson Linux.
- Download
spyglass-vX.Y.Z-windows-x64.zipfrom the releases and unpack it. - Start Minecraft.
- Run
spyglass.exefrom the unpacked folder. It asks for administrator rights and continues in a new window. - Press F12 in game to open the overlay.
The zip holds one DLL per client version, and spyglass.exe loads the one that matches the running client.
| Option | Description |
|---|---|
--dll <path> |
Load this DLL instead of the one that matches the client. |
--process <name> |
Inject into a process other than Minecraft.Windows.exe. |
The overlay takes the mouse only while the cursor is visible and over the overlay, so you can leave it open while you play.
On Linux, Spyglass is a mod for the Minecraft Bedrock Launcher.
-
Download
spyglass-vX.Y.Z-linux-x64.zipfrom the releases and unpack it. It holds one mod folder per client version. -
Copy the folder for the client your launcher runs into the launcher's mods directory:
mkdir -p ~/.local/share/mcpelauncher/mods/spyglass/0.3.4 cp -r spyglass-0.3.4-1.26.40 ~/.local/share/mcpelauncher/mods/spyglass/0.3.4/x86_64
-
Add that directory under
Modsin the profile you play, and start the game. -
Press F12 in game to open the overlay.
| File | Client |
|---|---|
spyglass-0.3.4-1.26.50.dll |
Windows release 1.26.50.5, 1.26.51.1 |
spyglass-0.3.4-1.26.60.dll |
Windows release 1.26.60.5 |
spyglass-0.3.4-1.26.70.preview.dll |
Windows preview 1.26.70.21 |
libspyglass-0.3.4-1.26.40.so |
Android x86_64 1.26.4x, for the Linux launcher |
A payload loaded into a client it was not built for installs nothing. If the packet count stays at zero while you are
connected, open the errors window under Help to see why. A client update can break a payload until a new release
supports it.
Both platforms build with CMake presets, and the configure step fetches every dependency.
You need clang-cl and lld-link from LLVM 18 or newer (the "C++ Clang tools for Windows" component of Visual Studio), the MSVC build tools for the Windows SDK and STL, CMake 3.28 or newer, and Ninja. Run these from a Developer prompt:
cmake --preset relwithdebinfo-windows
cmake --build --preset relwithdebinfo-windowsspyglass.exe and the DLLs land in build/relwithdebinfo-windows. spyglass.exe also picks up a DLL you build for
another client if you put it in the same folder.
The mod is an Android x86_64 shared object. You need the Android NDK with ANDROID_NDK_ROOT set, CMake 3.28 or newer,
and Ninja:
cmake --preset relwithdebinfo-android
cmake --build --preset relwithdebinfo-androidThe mod folders land in build/relwithdebinfo-android. The release-windows, release-android and debug-android
presets work the same way.
A build produces the payloads a release ships. To build for other clients, set MINECRAFT_CLIENTS. Write a release
client as three version parts and a preview client as four:
cmake --preset relwithdebinfo-windows -D MINECRAFT_CLIENTS="1.26.60;1.26.70.21"The build fails for a client version Spyglass has no patterns for.
- On Windows the overlay draws over Direct3D 11 and 12 only.
- On Linux the overlay uses the launcher's own ImGui. It does not appear on a stripped launcher, or on one built against a different ImGui revision.
- The error for a failed decode is whatever the client reports, and some packets report little.
- Call stack frames from a source file added in a client update show as
<hash>:lineuntil Spyglass adds the file. - A capture holds everything you and the server sent, including your login. An export writes it to disk unchanged, so check a file before you share it.
MIT, see LICENSE.

