BBModel Unpack

Unbox everything inside a Blockbench model.

BBModel Unpack adds a right-click command to Visual Studio Code that extracts the contents of Blockbench .bbmodel project files into an organized folder: Minecraft Bedrock geo.json geometry, animation.json files, animation controllers, embedded textures and display settings.

A .bbmodel is a single JSON document that bundles geometry, textures (as base64), animations and metadata. This extension unpacks that bundle without ever needing to open Blockbench.

Features

• Extract BBModel Contents — right-click any .bbmodel in the Explorer and unpack everything.
• Extract All BBModels in Folder — right-click a folder to batch-extract every model inside it (recursive; confirms the file count first, then reports one summary).
• Extract Textures Only — pull just the embedded PNGs (plus .mcmeta for flipbook textures).
• Extract Geometry Only / Extract Animations Only — grab just the converted geometry, or just the animations together with their animation controllers.
• Preview BBModel Contents — inspect what a model contains before writing anything.
• .bbmodel files are marked with a small BB badge in the Explorer so they're easy to spot.
• Converted Bedrock geometry (.geo.json), animations (.animation.json) and animation controllers (.animation_controllers.json) that match Blockbench's own exporters.
• Handles old and new container formats (Blockbench 3.x inline outliner through the 5.0 flat groups layout), including legacy migrations like geometry_name and shade-based mirroring.
• Never overwrites silently: existing folders prompt for new folder / merge / overwrite, and merged files get safe (2)-style names.
• Full logging in the BBModel Unpack output channel, including every written file and every conversion warning.

Usage

1. Right-click a .bbmodel file in the Explorer.
2. Choose Extract BBModel Contents.
3. The extension writes a <model name>_extracted folder next to the file (or asks for a destination, if configured) and shows a completion message with Open Folder.

All commands are also available from the Command Palette (they use the active editor's file or ask you to pick one), and the file commands support multi-selecting several .bbmodel files at once.

Right-clicking a folder offers Extract All BBModels in Folder: it scans the folder recursively (skipping node_modules and .git), shows how many models it found and asks for confirmation, then extracts each one. Batch runs log per-file results to the output channel and finish with a single summary notification instead of one message per model; cancelling stops the rest of the batch.

Output layout

my_model_extracted/
├── bedrock/
│   ├── geometry.json                 Bedrock geometry (format_version 1.12.0+)
│   ├── animations.json               all animations (format_version 1.8.0)
│   └── animation_controllers.json
├── textures/
│   ├── skin.png                      decoded from embedded base64
│   ├── flip.png.mcmeta               only for flipbook/animated textures
│   └── layers/…                      Blockbench editing layers, if present
└── display/
    └── display.json                  Java item/block display transforms

File names are plain .json — no .geo.json / .animation.json compound suffixes (Minecraft reads the identifiers inside the files, not the file names). If your pack tooling expects the conventional name.geo.json style, rename on copy. The exception is <texture>.png.mcmeta, whose double extension Minecraft itself requires.

What gets converted, and how

Everything else in the file (editor state, history, project metadata) is deliberately left alone — the .bbmodel itself remains the source of truth for it.

Approximate or lossy conversions are flagged in the completion message and the log — for example: free-form meshes cannot be represented in Bedrock geometry (a warning lists them), bezier curves are baked, and Molang expressions on mirrored axes are negated by wrapping (-(expr)).

Commands

Settings

Security & privacy

• The extension treats model files as pure data: nothing inside a .bbmodel is ever executed or evaluated (Molang stays text).
• File names derived from model content are fully sanitized (no path traversal, no reserved Windows device names).
• The only file read outside the model itself is a texture's relative_path, resolved next to the .bbmodel, and only when the texture is not embedded.
• No telemetry, no network access.

Known limitations

• Free-form meshes, armatures and other non-cube geometry are not converted to geo.json (Bedrock's schema has no stable equivalent); a warning reports how many were skipped.
• Inverse-kinematics (null object) animation baking is not performed; null objects export as _null_* locators like Blockbench does.
• LZUTF8-compressed backup files (<lz>…) are detected and explained, not decoded — re-save them in Blockbench first.
• Java block/item model export (.json element models) is on the roadmap; today Java projects still get textures, animations and display settings.

Development

npm install        # dev dependencies only; the extension itself has zero runtime dependencies
npm run compile    # tsc -> out/
npm test           # unit tests (Node's built-in test runner)
npm run lint       # ESLint
npm run fixtures   # regenerate fixtures/ deterministically
npm run icon       # regenerate media/icon.png from scripts/generate-icon.js
npm run package    # build a .vsix with @vscode/vsce

Press F5 in VS Code to launch an Extension Development Host with the extension loaded. See docs/TESTING.md for a full manual test checklist, and docs/FORMAT-NOTES.md for the research notes behind the converters.

Credits & trademarks

• Conversion behavior follows the open-source Blockbench exporters (GPL-3.0) as a reference specification; this extension contains its own independent TypeScript implementation and no Blockbench code.
• Blockbench is a project by JannisX11 and contributors. Minecraft is a trademark of Mojang Synergies AB / Microsoft. This extension is not affiliated with, endorsed by, or sponsored by Blockbench, Mojang, or Microsoft.
• Icon and branding are original artwork for this project.

License

GPL-3.0 — © 2026 Kaioga5