rewog 3.0.0

WOG Dump: extract and rebuild 3D weapon models from World of Guns: Gun Disassembly.

A command-line toolkit for 3D artists, modders and researchers who study game assets. WOG Dump logs in with your own game account, downloads encrypted Unity bundles from the game servers, decrypts them and rebuilds the weapon: one command turns the in-game AK-47 into a Blender-ready glTF scene with the exact part hierarchy, game materials and studio lighting. Scenes come out in disassembly states too, with an offline HTML viewer, STL/USD/FBX export, print preparation and turntable videos.

Overview · Features · Quick start · Usage · Configuration · Development · FAQ · Contributing · License

Overview

WOG Dump automates the full path from the game's servers to usable 3D data: weapon catalog, per-asset decryption keys, encrypted downloads, XOR decryption, Unity unpacking and scene export. It targets the current query2026 protocol (game 2.2.3t6, Unity 6) and was verified live against the production API in November 2026.

• For: 3D artists, modders, educators and researchers studying weapon assembly and Unity asset pipelines
• Input: your game-account credentials (or a captured client session) and the weapons you want
• Output: decrypted Unity bundles, extracted models and textures (OBJ, PNG, TGA), glTF scenes in assembled or disassembled poses, an offline HTML viewer, STL/USD/USDZ/FBX export, print-ready parts and turntable videos
• Scope: personal, educational and research use, extracted assets remain the property of Noble Empire Corp. (see License)

What's new: this release adds disassembly states and animated step-by-step builds, a self-contained HTML viewer with part annotations, STL/USD/USDZ/FBX export, print preparation, turntable and clip videos, the catalog command, a local web UI, CLI localization (Russian), a protocol compatibility probe, Docker images, a Blender addon and third-party extractor plugins. Full history: CHANGELOG.md.

Features

• Full pipeline: one command goes from weapon catalog to keys, download, decryption and unpacking. Downloads run in parallel, respect rate limits and resume after interruptions.
• Blender-ready scenes: build-scene rebuilds the assembled weapon exactly like in game: part hierarchy and positions, game materials with textures, camera and studio lighting, real-world scale. UI arrows, cutaway meshes and VFX are classified and skipped unless you ask for them with --extras.
• Disassembly states: --state field-strip puts parts where the game itself puts them after removal, --state exploded pushes them apart along removal directions, --state parts lays everything out in a grid. --assembly-steps writes a step-by-step build, and --animated adds one glTF animation placing part after part.
• Offline HTML viewer: --viewer embeds the scene and the three.js runtime into one viewer.html: open it in any browser, click parts to highlight them, read annotations with part sizes. No Blender, no internet, no install.
• Animations: --animations embeds the bundle's operate animation (fire, reload, safety) as real glTF animation tracks.
• Export formats: --format stl,usd,usdz,fbx converts a built scene: binary STL for slicers (units baked in), USD/USDZ for AR with preview materials, FBX through headless Blender.
• Print preparation: print-export repairs and checks every part with trimesh, reports watertight status per part and writes millimeter-true STLs.
• Previews and video: render turns a built scene into transparent turntable PNGs plus a GIF, --video encodes an orbit MP4 or one animation clip, all through headless Blender.
• Catalog: catalog lists every weapon with its pipeline status and sizes, filters by name and stage, and emits a stable JSON schema other tools build on.
• Web UI: serve opens a local page with the same catalog, a 3D viewer per weapon and stage buttons with live logs.
• Protocol probe: info --protocol-probe answers "did I break something or did the game update" in one run: endpoint reachability, anonymous query, authenticated key query, weapon list, client version. Any failure exits with code 2.
• Plugins: third-party packages register extra Unity-type extractors through entry points, no fork needed (see docs/plugins.md).
• Localization: --locale ru switches CLI messages to Russian, unknown locales fall back to English silently.
• Private by design: log in with your own game account (login / register) or a captured session. Credentials, sessions, keys and the weapon list live in a per-user SQLite database with owner-only permissions, no secrets ship with the repository.

Quick start

Requirements

• Python 3.12+
• uv (recommended) or pip
• A game account: create one with wog-dump register or use your existing email/password
• Internet connection and ~10–20 GB of free disk space for a full extraction
• Optional: AssetStudio for browsing raw Unity bundles manually
• Optional: Blender, for preview renders, videos and FBX export

Install

From PyPI:

pip install rewog

# USD/USDZ export support:
pip install "rewog[usd]"
# local web UI:
pip install "rewog[web]"
# print preparation:
pip install "rewog[print]"

From source (for development):

git clone https://github.com/InzGIBA/ReWOG
cd ReWOG

# with uv (install it via https://astral.sh/uv or `pip install uv`)
uv pip install -e .

# or with plain pip
pip install -e .

Run your first extraction

# 1. Create a game account and log in (once; or `wog-dump login` for an existing one)
wog-dump register

# 2. Everything: weapon list, keys, download, decrypt, unpack, normal maps
wog-dump full-pipeline --update-keys --convert-normals

# 3. Rebuild one weapon as a Blender-ready scene
wog-dump build-scene ak47

Data lands under runtime/:

runtime/
├── encrypted/       # raw encrypted Unity3D bundles
├── decrypted/       # decrypted bundles
├── unpacked/        # extracted models (OBJ) and textures (PNG, TGA)
└── scenes/ak47/     # ak47.glb + blender_setup.py + scene.json + textures/

Open runtime/scenes/ak47/ak47.glb in Blender (File > Import > glTF 2.0), or run the generated setup script for a configured scene with collections, hidden extras and a saved .blend:

blender --background --python runtime/scenes/ak47/blender_setup.py

Then try this

# Disassembly poses, straight from the game's own removal data
wog-dump build-scene ak47 --state field-strip
wog-dump build-scene ak47 --state exploded --explode-distance 0.5

# A step-by-step build plus one animated assembly GLB
wog-dump build-scene ak47 --assembly-steps 5 --animated

# Show it to someone without Blender
wog-dump build-scene ak47 --viewer --annotate

# Print a part
wog-dump print-export ak47 --part bolt

# Turntable previews and an orbit video
wog-dump render ak47
wog-dump render ak47 --video --duration 8

# What do I have, and how do I share this page?
wog-dump catalog
wog-dump serve

Usage

Step by step

Each pipeline stage is also available as its own command:

wog-dump info                          # configuration and status; add --protocol-probe
wog-dump download-weapons              # fetch the weapon catalog
wog-dump download-assets --update-keys # download bundles + fresh keys
wog-dump decrypt-assets                # XOR-decrypt the bundles
wog-dump unpack-assets                 # extract models and textures
wog-dump build-scene ak47              # Blender-ready glTF scene
wog-dump render ak47                   # turntable previews; --video for MP4
wog-dump print-export ak47             # print-ready STLs with diagnostics
wog-dump catalog                       # per-weapon status table
wog-dump convert-normals ./unpacked --recursive   # optional: fix normal maps

Every command documents itself: wog-dump --help and wog-dump <command> --help.

Common options

Scene output

build-scene writes everything you need into runtime/scenes/<weapon>/:

<weapon>.glb        # full scene: hierarchy, materials, camera, studio lights
blender_setup.py    # one-click Blender import + collections + .blend save
scene.json          # manifest: state, placements, counts, skipped objects, parts
viewer.html         # offline viewer (with --viewer, annotations with --annotate)
textures/           # source PNG textures (also embedded in the GLB)
previews/           # turntable PNGs + preview.gif (from wog-dump render)
renders/            # orbit / clip MP4s (from wog-dump render --video)
print/              # STLs + print_report.json (from wog-dump print-export)

Non-assembled states go to sibling folders: <weapon>-field-strip/, <weapon>-exploded/, <weapon>-parts/, and <weapon>-steps/ for step builds.

Cache management

wog-dump cache --migrate         # import legacy weapons.txt / keys.txt
wog-dump cache --show-cache      # detailed cache statistics
wog-dump cache --validate-assets # check downloads exist and are non-empty

Web UI

A local web UI over the same pipeline: catalog with statuses, a 3D viewer per weapon and stage buttons with live logs. Needs the web extra, binds 127.0.0.1 with a per-start token URL.

pip install "rewog[web]"
wog-dump serve

Docker

No local Python needed, all state lives in a named volume mounted at /data:

docker run --rm -it -v wog-data:/data ghcr.io/inzgiba/rewog:latest catalog
docker run --rm -it -v wog-data:/data ghcr.io/inzgiba/rewog:latest full-pipeline --update-keys
docker compose run --rm wog catalog   # from the repo, via docker-compose.yml

Images publish to GHCR on release tags (latest plus semantic versions), pull requests build the image without pushing.

Using as a Python library

from wog_dump.core.catalog import build_catalog
from wog_dump.core.config import get_config
from wog_dump.core.download import DownloadManager
from wog_dump.core.decrypt import KeyManager, AssetDecryptor

config = get_config()

with DownloadManager(config) as downloader:
    successful, failed = downloader.download_assets(["ak74", "m4a1"])

key_manager = KeyManager(config)
keys = key_manager.load_keys()

decryptor = AssetDecryptor(config)
decrypted_files, failed_assets = decryptor.decrypt_all_assets(keys)

# Catalog status without the CLI
for entry in build_catalog(config):
    if entry.scene:
        print(entry.name, entry.size_bytes)

More library entry points: core.export.convert_format (GLB to STL/USD/FBX), core.render.RenderManager (previews and video), core.viewer.render_viewer_html (offline viewer), core.probe.ProtocolProbe (compatibility check). The API reference pages live in the docs site.

Configuration

Settings come from a gitignored .env in the repository root (see .env.example) or from the environment. Credentials, sessions, keys and the weapon list are stored in a per-user SQLite database, never in the repository.

In-depth references:

• docs/configuration.md: every environment variable, .env setup, rate limiting, resumable downloads
• docs/architecture.md: how the modules fit together, the extraction pipeline
• docs/database.md: where keys and credentials live, schema, migration from pre-2.4 files
• docs/mitm-capture.md: capturing keys and identity from your own game traffic
• docs/plugins.md: writing third-party extractor plugins
• docs/research-disassembly-data.md: where the disassembly poses come from
• docs/benchmarks-download.md: download transport benchmark and decisions

Development

git clone https://github.com/InzGIBA/ReWOG
cd ReWOG
uv pip install -e ".[dev]"       # or: pip install -e ".[dev]"

Checks

pytest                          # all tests
pytest --cov=wog_dump           # with coverage (gate: 85 percent, see .coveragerc)
pytest -m live                  # against the real servers (needs auth in .env)

black src/ tests/               # formatting
isort src/ tests/
mypy src/                       # type checking
flake8 src/ tests/              # linting
mkdocs serve                    # docs site preview

Project structure

ReWOG/
├── src/wog_dump/          # Main package (source layout)
│   ├── core/              # config, http, api, auth, database, keys, paths,
│   │                      # download, decrypt, unpack, scene, scene_states,
│   │                      # scene_steps, anim, transforms, glb, export, viewer,
│   │                      # render, printprep, catalog, probe, key_import, webapp
│   ├── resources/         # Blender scripts, viewer runtime and templates
│   ├── utils/             # logging, normal maps, i18n, progress
│   └── cli/               # Click commands: download, decrypt, unpack, scene,
│                          # render, print-export, catalog, pipeline, auth,
│                          # cache, info, serve, convert
├── tests/                 # unit/ + integration/ (CLI end-to-end, real bundles)
├── docs/                  # guides, architecture, plugins, benchmarks, API reference
├── blender-addon/         # Blender 4.2+ extension over the CLI
├── examples/              # example extractor plugin
├── scripts/               # addon zip, locale compiler, benchmark and audit tools
└── pyproject.toml         # PEP 621 packaging

FAQ

General

Do I need to own the game? The tool downloads public asset files from the game's servers. Ownership is not required. We still recommend owning the game to support the developers.

What formats does WOG Dump export? Blender-ready glTF 2.0 scenes (build-scene), OBJ models, PNG/TGA textures, converted normal maps, binary STL (plain or print-prepared), USD and USDZ packages, FBX through Blender, and self-contained HTML viewers.

How do I get a disassembled weapon? Use a state: wog-dump build-scene ak47 --state field-strip places parts exactly where the game puts them after removal. --state exploded spreads parts along removal directions, --state parts lays everything out in a grid. --assembly-steps 5 --animated adds a step-by-step build and one placing animation.

Can I show a scene to someone without Blender? Yes: wog-dump build-scene ak47 --viewer produces one viewer.html file. Open it in any browser, click parts to highlight them, read sizes in the annotation cards. Share the file directly, it needs no internet.

Which operating systems are supported? Windows, macOS and Linux. The tool is pure Python (no C dependencies since v2).

How much disk space do I need? Encrypted ~2–5 GB, decrypted ~2–5 GB, extracted ~3–8 GB. Plan for 10–20 GB free.

Troubleshooting

Everything broke after a game update Run wog-dump info --protocol-probe first. It checks endpoint reachability, the anonymous query, the authenticated key query, the weapon list asset and your client version, and tells you whether the problem is local or the game protocol moved. Any FAIL exits with code 2, report drifts with the protocol drift template.

No game account configured when fetching keys The key API needs authentication. Run wog-dump register (new account), wog-dump login (existing one), or put WOG_ACCOUNT_EMAIL/WOG_ACCOUNT_PASSWORD, or a captured WOG_AUTH_ID/WOG_AUTH_SESSION, into .env (see docs/mitm-capture.md). Check what is configured with wog-dump cache.

Authentication failed (result=100) The API rejected the credentials. Verify the email/password pair in the game client itself, then wog-dump login again. A captured session expires sometimes. Capture a fresh one or switch to account login.

Session rejected (result=1000) The stored session expired. WOG Dump re-logins automatically, if the error persists, run wog-dump logout && wog-dump login.

429 / rate-limit errors Requests are too frequent. Raise the throttles in .env: WOG_API_REQUEST_DELAY=2.0 (key API) and WOG_REQUEST_DELAY=0.5 (downloads).

No weapon list found. Run 'download-weapons' first. Run wog-dump download-weapons. Coming from a pre-2.4 installation with runtime/weapons.txt? Import it once with wog-dump cache --migrate.

No decryption keys found. Use --update-keys to fetch them. Run wog-dump decrypt-assets --update-keys (auth must be configured).

Key API stopped working after a game update The client version strings are validated server-side. Update them in .env to match the current client (find the values in the game's installation or a fresh capture), e.g. WOG_GAME_VERSION=2.2.3u9 and WOG_UNITY_VERSION=6000.0.84f1.

Interrupted download: do I have to start over? No. Partial downloads are kept as runtime/assets/*.tmp and resumed via HTTP Range requests on the next run. If a .tmp file refuses to go away, delete the file to force a fresh download.

The tool seems stuck or slow Check your internet connection, reduce the thread count (wog-dump --max-threads 2 download-assets), enable --verbose (or --debug), and remember that downloads are throttled by design (see WOG_REQUEST_DELAY).

Previews or videos say "Blender not found" Install Blender, or point WOG_BLENDER_PATH in .env at the binary. Renders use CPU Cycles, so no GPU is required.

Blender addon

A native Blender extension (4.2+) over the same CLI: browse the catalog in a sidebar panel, build missing scenes and import the GLB without a terminal. Install the zip from a release, enable it in preferences, set the runtime directory. See blender-addon/README.md.

Contributing

Issues and pull requests are welcome: bug fixes, features, documentation, tests, plugins and localization all help. For larger changes, open an issue first to discuss the approach.

1. Fork and clone the repository, then uv pip install -e ".[dev]".
2. Create a feature branch and make a focused change.
3. Add or update relevant tests and docs, run pytest, black src/ tests/ and mkdocs build --strict.
4. Open a pull request.

• Contributing Guidelines: the detailed contribution process
• Issue Tracker: bug reports and feature requests
• Discussions: questions and general help
• Code of Conduct: community standards

Support

Where to get help, in the order we recommend:

1. The FAQ above
2. SUPPORT.md: diagnostics and common solutions
3. GitHub Issues: bug reports and feature requests (public, searchable)
4. GitHub Discussions: questions and general help

Please use the public channels so answers remain useful to others. For security-sensitive reports only, email the maintainer directly: inzgiba@gmail.com.

License

Released under the MIT License, see LICENSE.

Legal disclaimer. This tool is intended for educational and research purposes only. Extracted assets remain the intellectual property of Noble Empire Corp., ensure compliance with the game's Terms of Service, use extracted content only for personal, educational or research purposes, and do not redistribute game assets or use them commercially. The authors and contributors are not responsible for any misuse of this software or violation of terms of service. For questions about asset usage rights, contact Noble Empire Corp. directly.

Acknowledgements

• DeadZoneGarry: original decryption research
• Noble Empire Corp.: the game and its assets
• three.js contributors: the viewer runtime (MIT, vendored)
• Contributors to the original WOG Dump project