openbpx

README

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
• AI 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

CLI (bpx)

From package managers

# 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

Build locally

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

Official release artifacts are published on GitHub Releases.

AI Agent Skills

Generate SKILL.md files from installed bpx (recommended)

# Generate all command Codex skills to .codex/skills
bpx generate-skills --output-dir .codex/skills

# Generate all command Claude skills to .claude/skills
bpx generate-skills --output-dir .claude/skills

Generated layout:

• skills/bpx-shared/SKILL.md
• skills/bpx-<command>/SKILL.md

bpx generate-skills uses built-in command help metadata and built-in command-profile supplements baked into the binary, so generation works from a single binary without reading repository files.

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

Item	Current Support
UE version window	FileVersionUE5=1000..1018 (UE 5.0 to 5.7)
Asset files	.uasset, .umap
Read/inspect commands	Implemented (see docs/commands.md)
Scoped update commands	Implemented (safety-constrained)
High-risk structural rewrites	Partially blocked by design

How It Works

1. Parse package data into a binary-safe model.
2. Decode known structures while retaining unknown/raw regions.
3. Apply deterministic, scoped edits only to the intended region.
4. Re-serialize with offset/size updates and validation checks.

Documentation

• Command Specification
• Test Plan and Fixture Specification
• Distribution Build Guide
• Disassembly Script Extraction Notes
• Package Manager Publish Guide

Contributing

Contributions are welcome.

• Read CONTRIBUTING.md before opening a PR.
• Use ISSUE.md when filing bug reports or feature requests.
• For large features, open an Issue first to align design and scope.
• For CLI contract changes, update docs/commands.md in the same PR.

Changelog

Release history is tracked in CHANGELOG.md.

License

Apache License 2.0. See LICENSE.

About Wild Dog

BPX is created and maintained by Wild Dog, Inc. (株式会社ワイルドドッグ), an indie game development studio based in Japan, operated by a team of 20 members. Our mission is to deliver player-first games where fun always comes first.