Pip-Boy 3000 Companion

Sync your Fallout: New Vegas and Fallout 3 player stats and inventory to The Wand Company's Pip-Boy 3000 replica in real-time over USB.

⚠ DISCLAIMER: This is an unofficial fan project. Not affiliated with or endorsed by Bethesda Softworks, The Wand Company, or any other entity.

⚠ WARNING: Compatibility with mods and modpacks that add or modify items and/or modify gameplay is not guaranteed. YUP is specifically known to have issues because the mod changes the formid's on some vanilla items. I am one person, so bugs are innevitable, please open an issue if you run into any bugs or errors. Donations help me to continue this project.

How It Works

┌──────────────────┐    Named Pipe     ┌──────────────────┐    USB Serial    ┌──────────────────┐
│   Fallout 3/NV   │ ───────────────── │  Companion App   │ ──────────────── │  Pip-Boy 3000    │
│  (FOSE/NVSE DLL) │  JSON snapshots   │    (Node.js)     │    JS commands   │   (Espruino)     │
└──────────────────┘                   └──────────────────┘                  └──────────────────┘

1. Game Plugin (C++ DLL) hooks into Fallout via FOSE/xNVSE, reads player state on update
2. Companion App (Node.js) receives JSON snapshots over a Windows Named Pipe, diffs against previous state
3. Pip-Boy commands Espruino commands are sent over USB serial to update the device

You can find an in depth feature walkthrough here

Initial Setup

• Download the latest companion app exe from the Releases page
• Install NVSE or FOSE depending on your game, if using Fallout 3 GOTY Edition, the Anniversary Patcher is needed for FOSE support.
• Install the latest plugin version from Nexus Mods for Fallout New Vegas or Fallout 3 by clicking the Mod manager download (currently unavailable as the mod is being approved by Nexus. The mod zip is included on the Releases page temporarily), alternatively manually download and install the ZIP via your mod managers manual mod install, or manually install the DLL from the Releases page to your NVSE/FOSE plugins folder.
• Plug in your Pip-Boy 3000 with a USB C cable, make sure to use a USB cable that supports data transfer, not just charging. The one that came with your Pip-Boy works great.
• Make sure your Pip-Boy is set to the same mode as the game you want to sync with by going to DATA>Settings>Pip-Boy mode and selecting New Vegas or Fallout 3.
• Open the companion app and click "Install Companion Menus & Boot Patch" to install the companion firmware to your device. Wait for it to reboot and connect to the app.
• Launch your game via your mod manager, or script extender loader (nvse_loader.exe/fose_loader.exe).

Post-Setup Usage

• Set the Pip-Boy mode for the Fallout you will be playing
• Open the companion app
• Start the Fallout you chose

Note: If you have factory reset or updated your Pip-Boy, you will need to click "Install Companion Menus & Boot Patch" first.

⚠ NOTE: To restore to stock Pip-Boy OS:

• Go to the official TWC upgrade page
• Click Fallout 3 / New Vegas
• Then click Advanced options
• Click Factory Reset

Known Issues

• Equip/unequip sounds on Pip-Boy can sometimes be delayed slightly
• Dropping or picking up many items at once (20+) can cause the Pip-Boy to freeze for about 2-3 seconds after the last item is picked up/dropped.
• Holotapes may suffer from memory issues, and have been known to crash the Pip-Boy when loading. (This issue is largely eliminated, but might still be present under certain conditions, so is kept as a warning)

Limitations

• YUP is known to cause issues because it changes Form IDs on some vanilla items.
• XP does not sync on every change, and only updates on a full sync, load sync, or on level up.
• Bleak Venom is not usable from the Pip-Boy due to issues with how the game handles usage.

Building From Source

Prerequisites

• Node.js 18+
• Visual Studio 2022+

Desktop UI (Windows executable)

cd CompanionApp
npm install
npm run build-fw              # Build firmware files
npm run build:win             # Build portable .exe in release/

Install companion firmware (CLI)

npm run build-fw
npm run flash-fw

Building the Game Plugins

Both game plugins require:

• Visual Studio 2022+ with C++ Desktop Development (includes CMake)
• xNVSE's SDK is a bundled submodule: git submodule update --init
• FOSE's SDK is not on GitHub - download it from fose.silverlock.org and extract it to GamePlugin/FOSE (containing fose/ and common/ directories)

The Visual Studio solutions are generated by CMake (they contain machine-specific paths, so they are not committed) - run the matching configure command once from a Developer Command Prompt in GamePlugin\, then either build on the command line or open the generated .sln. Each build tree contains only its own game's plugin.

Fallout: New Vegas (xNVSE)

cmake -S . -B build-nv -A Win32 -DBUILD_FO3_PLUGIN=OFF
cmake --build build-nv --config Release

• Or open build-nv\FalloutPipBoySync.sln and Build -> Build Solution
• The DLL will be built to build-nv\Release\FalloutPipBoySyncNV.dll (install to Data\NVSE\Plugins\)

Fallout 3 (FOSE)

cmake -S . -B build-fo3 -A Win32 -DBUILD_NV_PLUGIN=OFF
cmake --build build-fo3 --config Release

• Or open build-fo3\FalloutPipBoySync.sln and Build -> Build Solution
• The DLL will be built to build-fo3\Release\FalloutPipBoySyncF3.dll (install to Data\FOSE\Plugins\)

Roadmap

• Item mod display support (+)

Credits

• Author: Aidan's Lab
• Pip-Boy 3000: The Wand Company
• Script extenders: xNVSE and FOSE teams
• Helpful Resources: JIP-LN-NVSE and Command Extender
• Testers: Special thanks to Theeohn and Jim D for initial testing, as well as BeanutPudder, Ferehn, and Lore for later testing.

License

See LICENSE file.