openbpx

README

OpenBPX: Blueprint Toolkit for Unreal Engine (bpx)

BPX is a Go CLI for reading and safely editing Unreal Engine package assets (.uasset, .umap) without launching Unreal Editor.

It is designed for automation and scripting use-cases 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.

Project Status

• Phase: Alpha
• Current CLI version: 0.1.2
• Supported UE window: UE 5.0 to UE 5.6 (FileVersionUE5=1000..1017)
• 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 source with go install

go install github.com/wilddogjp/openbpx/cmd/bpx@latest

Build locally

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

Official release artifacts are published on GitHub Releases.

Install BPX skill for Codex

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo wilddogjp/openbpx \
  --path .agents/skills/bpx \
  --method git

After installation, restart Codex.

If you install with --method auto or --method download, ensure executable bits are set on Unix-like systems:

chmod +x ~/.codex/skills/bpx/bpx_*

Install BPX plugin for Claude Code

git clone https://github.com/wilddogjp/openbpx.git
cd openbpx
claude --plugin-dir .

This repository ships fallback BPX binaries for supported platforms in .agents/skills/bpx/. Use the skill in Claude prompts as /openbpx:bpx.

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

Safety and Security Model

• Preserve bytes that BPX does not interpret.
• Keep read -> no edit -> write byte-identical.
• Reject unsupported UE versions outside 1000..1017.
• 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..1017 (UE 5.0 to 5.6)
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

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.