brarchive-extractor

KO | EN

gitlite — search

#framework #java #pdf #gpt #rag #data-science #self-hosted #gemini #nextjs #privacy

brarchive-extractor

(★ 9)

A TypeScript CLI for extracting Minecraft Bedrock .brarchive files and restoring MCB files to JSON with schemas.

File Explorer

ZIP Download

- - release.yml
- - brarchive-format.md
  - mcb-format.md
  - usage.md
- brarchive-format.md
- mcb-format.md
- usage.md
- extract-release-notes.ts
- binary-reader.ts
- brarchive.ts
- cli.ts
- errors.ts
- index.ts
- json-output.ts
- mcb-decoder.ts
- mcb-schema-rules.ts
- minecraft-documents.ts
- progress-speed.ts
- runner-types.ts
- runner.ts
- schema-registry.ts
- schema-types.ts
- brarchive.test.ts
- integration.test.ts
- mcb.test.ts
- progress-speed.test.ts
- - __init__.py
  - __main__.py
  - USAGE.md
- - __init__.py
  - __main__.py
  - USAGE.md
- - __init__.py
  - __main__.py
  - USAGE.md
.gitattributes
.gitignore
CHANGELOG.md
LICENSE
package-lock.json
package.json
README.md
README.zh.md
schema-config.json
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <h1>brarchive-extractor</h1>
  <p>
    <a href="https://github.com/LPaicen/brarchive-extractor"><img src="https://img.shields.io/badge/GitHub-LPaicen%2Fbrarchive--extractor-181717?logo=github" alt="GitHub repository"></a>
    <a href="https://github.com/LPaicen/brarchive-extractor/releases"><img src="https://img.shields.io/github/package-json/v/LPaicen/brarchive-extractor?label=version" alt="Version"></a>
    <a href="https://github.com/LPaicen/brarchive-extractor/blob/main/LICENSE"><img src="https://img.shields.io/github/license/LPaicen/brarchive-extractor" alt="License"></a>
  </p>
  <p>
    <a href="./README.md">English</a> | <a href="./README.zh.md">简体中文</a>
  </p>
</div>

`brarchive-extractor` is a TypeScript command-line tool for Minecraft Bedrock resources. It extracts individual or batched `.brarchive` files and can restore MCB binary documents to JSON using schemas. Schemas may come from Mojang's official repositories, be exported from BDS with [bedrock-apis/bds-docs](https://github.com/bedrock-apis/bds-docs), or be exported from the client with [LPaicen/ll-client-schema-exporter](https://github.com/LPaicen/ll-client-schema-exporter).

The installed command is the short alias `brax`.

The tool validates archive bounds, path traversal, output conflicts, and trailing MCB data. Failed MCB restorations preserve the original binary by default and processing continues.

## Installation

Node.js 20 or newer is required:

```powershell
npm install
npm run build
npm link
```

## Basic Usage

Extract one archive:

```powershell
brax ./entities.brarchive
```

Restore MCB files with a schema export:

```powershell
brax ./entities.brarchive --schema ./bds-schema
```

Process a directory recursively:

```powershell
brax ./input --schema ./bds-schema
```

Results normally go to `<input-name>_unpacked` beside the input. Use `--output` to select another output root, or `--in-place` to write directly into the source layout:

```powershell
brax ./input --in-place --schema ./bds-schema
```

`--in-place` directly modifies ordinary MCB/JSON source files and writes archive entries into their logical directories. A single `foo.brarchive` writes to the sibling `foo/` directory while preserving the archive. It cannot be combined with `--output`, `--split-archives`, or `--force`; back up the input before using it.

For a non-empty output directory, use `--overwrite` to preserve unrelated content and replace matching files. Use `-f` or `--force` to clear the entire output directory before processing. Clearing is irreversible, and `--force` cannot be combined with `--overwrite`.

Ordinary files in directory inputs are copied unchanged unless `--format-all-json` applies. `--mcb-only` keeps only MCB content; `--json-only` keeps MCB content and existing `.json` files while ignoring every other file type. `--no-empty-dirs` omits archive output directories that contain no extracted files; reports do not make an otherwise empty directory eligible. Use `--split-archives` to keep `foo.brarchive/` output separate from a sibling `foo/` tree.

## Schema

`--schema` may point to a standard [bds-docs](https://github.com/bedrock-apis/bds-docs) export, an [LL client schema exporter](https://github.com/LPaicen/ll-client-schema-exporter) export, or any directory containing JSON Schemas. The tool prefers `metadata/json_schemas/` when present; otherwise it scans the specified directory recursively. The only schema requirement is that at least one valid JSON file has `$id`.

The package-root `schema-config.json` configures payload-key aliases, versionless documents, tagged `oneOf` schemas whose exported branches omit ordinals, and normalized `oneOf` representations. `brax` reads it whenever it loads a schema registry, and the file is included in the npm package. See the [usage guide](docs/usage.md#schema-configuration) for its structure and fallback behavior.

## Conflicts

Normally, a same-named `foo.brarchive` and `foo/` under `__brarchive` are complementary: the archive stores direct files for the current level, while the directory stores child brarchives. They therefore do not conflict. If malformed input causes multiple contents to occupy one merged target, the tool pauses and displays the sources and total conflict count.

Enter `o`, `k`, or `c` to overwrite, keep the existing file, or coexist as `name (1).ext`. Uppercase `O`, `K`, and `C` apply that decision to every remaining conflict. An unresolved conflict in a non-interactive terminal is a fatal error.

## Command Options

```text
-d, --directory          Treat the input as a directory
-r, --recursive          Scan directories recursively (default)
    --no-recursive       Scan only the first input-directory level
-s, --schema <path>      Schema export or recursive schema directory
-o, --output <path>      Select the output root
-w, --overwrite          Overwrite matching existing output files
-f, --force              Clear the entire output directory first
-p, --report             Write .brarchive-report.json for each archive
    --verbose            Show status and progress (default)
    --no-verbose         Disable status and progress
-l, --list               List failure details only
-L, --list-all           List archive, failure, and conflict details
-j, --json-format <mode> Use pretty or compact restored MCB JSON
-J, --format-all-json    Format ordinary .json files; preserve comments
    --indent-size <0-10> Pretty JSON indentation width (default: 2)
    --indent-char <value> Indent with space or tab (default: space)
-F, --fail-fast          Stop after the first parsing failure
-D, --discard-failed     Do not write failed files; ignored with --fail-fast
    --mcb-only           Extract and restore MCB only
    --json-only          Extract MCB and existing JSON only
    --no-empty-dirs      Do not create directories without extracted files
    --split-archives     Keep same-named archives and directories separate
-i, --in-place           Write directly into the source layout
-h, --help               Show help
-v, --version            Show version
```

## Documentation

- [Complete usage guide](./docs/usage.md)
- [brarchive file format](./docs/brarchive-format.md)
- [MCB file format](./docs/mcb-format.md)

## Testing

```powershell
npm test
```

brarchive-extractor

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README