A lightweight wrapper and orchestration layer for retro emulators.
Project Braid is a netplay injector tool designed to simplify the multiplayer experience for retro gaming. Its primary goal is to abstract the technical hurdles of emulator configuration—such as network settings, ROM versions, and BIOS requirements—into a single, shareable link or executable.
Core Functionality
- Encapsulated Netplay: Wraps specific ROMs and emulator configurations together so two players can connect instantly without manual setup.
- Infrastructure: Developed as a Python prototype with plans to migrate to Rust or Go for better performance and easier distribution.
- User Experience: Focuses on a minimal, Y2K Nintendo-inspired aesthetic for the GUI and branding.
Key Objectives
- Automation: Automatically handles the “handshake” between emulators to ensure both players are in sync.
- Portability: Makes netplay as simple as clicking a link, removing the need for users to navigate complex emulator menus or manually exchange IP addresses.
1. Prerequisites
Before getting started, ensure you have the following installed on your system:
- Rust (1.75+): Required to build the prototype CLI.
- Python 3: Needed to run the signaling server.
- RetroArch: The default emulator backend used by Project Braid.
2. Installation
Clone the Repository
Open your terminal and clone the project:
git clone https://github.com/urboirad/project-braid.gitcd project-braid
Build the Project
Use Cargo to build the Rust components:
cargo build --release
The executable will be located in target/release/braid. For convenience, you can use the pre-configured braid wrapper in the root directory.
3. Running a Session
A typical session requires three components: a Signaling Server, a Host, and a Peer.
Step A: Start the Signaling Server
The signaling server acts as the “meeting point” for players to exchange session metadata.
python signaling_server.py
Default address: http://localhost:8080
Step B: Host a Game
To host, point Braid to your ROM file and the signaling server URL.
./braid host /path/to/your/game.sfc --signal-url http://localhost:8080 --launch-emulator
What happens next?
1. Braid hashes your ROM to ensure the peer has the exact same version.
2. It generates a braid:// session link.
3. Share this link with your friend.
Step C: Join a Game
The peer uses the link provided by the host to join the session.
./braid join "braid://<session_id>?signal=http://<host_ip>:8080" --rom /path/to/your/game.sfc --launch-emulator
Verification: Braid will check the peer’s ROM hash against the host’s manifest. If they don’t match, it will warn you to prevent desyncs before the emulator even starts.
4. CLI Commands Reference
| Command | Description |
host | Initializes a new session and generates a shareable link. |
join | Connects to an existing session using a braid:// URI. |
--launch-emulator | Automatically spawns RetroArch once the session is established. |
--emulator-bin | Point to a specific binary if RetroArch isn’t in your PATH. |
5. Troubleshooting & Tips
- Network Access: Ensure the signaling server port (default 8080) is accessible to the joining peer if they are not on your local network.
- Emulator Config: Braid defaults to
retroarch. If you use a different name for your binary (e.g.,retroarch-giton Arch), use the--emulator-binflag. - Prototype Status: Remember that real-time netcode and NAT traversal are currently handled by the underlying emulator; Braid manages the “handshake” and session orchestration.
UrBoiRAD 