openbpx

OpenBPX: Blueprint Toolkit for Unreal Engine (bpx)

A safety-first CLI for reading and editing Unreal package assets (.uasset, .umap) without launching Unreal Editor.

BPX is designed for automation and scripting workflows where binary safety matters: unknown bytes are preserved, no-op round-trip stays byte-identical, and unsupported/high-risk operations fail explicitly.

BPX runs on Windows, macOS, and Linux.

# Windows
winget install --id WilddogJP.OpenBPX --exact

# Debian / Ubuntu (WSL)
curl -fsSL https://raw.githubusercontent.com/wilddogjp/openbpx/main/scripts/install-bpx-from-release.sh | bash

# macOS
HOMEBREW_DEVELOPER=1 brew install --formula https://raw.githubusercontent.com/wilddogjp/openbpx/main/packaging/homebrew/openbpx.rb

[!IMPORTANT] This project is under active development. Expect breaking changes as we march toward v1.0.

Contents

• Quick Start
• Why OpenBPX?
• Install
• Legacy Agent Skills
• Safety and Security Model
• Supported Scope
• How It Works
• Documentation
• Contributing
• Changelog
• License
• About Wild Dog

Quick Start

# Show help and version
bpx --help
bpx version

# Inspect an asset
bpx info ./Sample.uasset
bpx validate ./Sample.uasset --binary-equality

# Read properties
bpx prop list ./Sample.uasset --export 1 --format json

# Safe write flow example
bpx prop set ./Sample.uasset --export 1 --path "MyValue" --value '123' --dry-run
bpx prop set ./Sample.uasset --export 1 --path "MyValue" --value '123' --backup

Why OpenBPX?

For humans: inspect package metadata, exports/imports, properties, DataTables, and Blueprint data from a single CLI.

For automation and AI agents: use structured output (json/toml) and deterministic safety-first write flows (--dry-run, --backup, validate).

Project Status

• Phase: Alpha
• Supported UE window: UE 5.0 to UE 5.7 (FileVersionUE5=1000..1018)
• Supported platforms: Windows / macOS / Linux (amd64, arm64)
• Core principles: unknown-byte preservation, round-trip fidelity, safety-first editing, UE behavior-grounded implementation

Install

Agent Plugins

BPX plugins include bundled bpx binaries for Linux, macOS, and Windows (amd64/arm64), so a separate CLI install is optional for agent use.

• Codex app: add a marketplace with Source wilddogjp/openbpx, Git ref main, and an empty Sparse path, then install openbpx.
• Claude Code local use: claude --plugin-dir .

claude plugin marketplace add .
claude plugin install openbpx@openbpx

If Codex says no plugin was found, leave Sparse path empty. This repository is not laid out under plugins/codex.

CLI

# Windows
winget install --id WilddogJP.OpenBPX --exact

# Debian / Ubuntu (one-command installer with checksum verification) / WSL
curl -fsSL https://raw.githubusercontent.com/wilddogjp/openbpx/main/scripts/install-bpx-from-release.sh | bash

# macOS (Homebrew formula hosted in this repository)
# Homebrew blocks URL/path formula install by default, so enable developer mode for this command.
HOMEBREW_DEVELOPER=1 brew install --formula https://raw.githubusercontent.com/wilddogjp/openbpx/main/packaging/homebrew/openbpx.rb

Official release artifacts are published on GitHub Releases.

Build Locally

git clone https://github.com/wilddogjp/openbpx.git
cd openbpx
go build ./cmd/bpx

Legacy Agent Skills

bpx generate-skills --output-dir .codex/skills
bpx generate-skills --output-dir .claude/skills

Use this older direct SKILL.md workflow only when plugin installation is unavailable.

Safety and Security Model

• Preserve bytes that BPX does not interpret.
• Keep read -> no edit -> write byte-identical.
• Reject unsupported UE versions outside 1000..1018.
• Fail explicitly for unsupported/high-risk structural rewrites.
• Treat all input assets as untrusted binary input.

See SECURITY.md for vulnerability reporting and response policy.

Supported Scope