https://github.com/bitsfdb/velocityrl
Swap the visual appearance of any Rocket League item. Free and open source.
https://github.com/bitsfdb/velocityrl
game-modding item-swap linux open-source rocket-league rust tauri upk velocityrl windows
Last synced: 6 days ago
JSON representation
Swap the visual appearance of any Rocket League item. Free and open source.
- Host: GitHub
- URL: https://github.com/bitsfdb/velocityrl
- Owner: bitsfdb
- Created: 2026-05-07T02:09:33.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-31T02:59:22.000Z (12 days ago)
- Last Synced: 2026-05-31T04:20:17.195Z (12 days ago)
- Topics: game-modding, item-swap, linux, open-source, rocket-league, rust, tauri, upk, velocityrl, windows
- Language: Python
- Homepage: https://velocityrl.tech
- Size: 12.1 MB
- Stars: 4
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# VelocityRL 🚀
A powerful, user-friendly tool for performing visual asset swaps in Rocket League.
> **Note**: The NPM package for this tool is named `rl-item-mod`.
## Overview
**VelocityRL** provides an interactive terminal wizard and a premium desktop interface that allows you to swap in-game items (e.g., swapping a standard boost for Alpha Reward). Under the hood, it seamlessly invokes an advanced Python engine to accurately parse `.upk` encryption, perfectly expand Name Table string offsets, and rebuild the package architecture without causing game crashes.
## Features
- **Interactive Wizard**: A beautiful command-line interface to search for and select your source and target items.
- **Python Interop**: Leverages a robust Python backend to handle complex LZO decompression, AES decryption, and binary offset shifting.
- **Automated Backups**: Automatically backs up original game assets before patching, with a one-click CLI restore feature.
- **Item Database**: Uses a built-in `items.json` database for fuzzy-searching and mapping in-game item names directly to their underlying UPK files.
## ⚠️ Warning - Some Swaps Will Crash the Game
> **Swapping certain asset types is not yet fully supported and will cause Rocket League to crash on load.** This is a known limitation of the current version and is being worked on. Until a fix is released, avoid swapping the following:
> Thumbnails in general cause a lot of crashes, as well as bodies and goal explosions.
> If a swap you attempt causes a crash, you should validate game files, and when a crash occurs on an item use the **Restore backups** as shown in this screenshot
## Installation
### Prerequisites
- Node.js (v18+)
- Python 3.8+ (must be available in your system PATH)
### Global Install (Recommended)
```bash
npm install -g rl-item-mod
```
```bash
pip install cryptography
```
### Local Development
```bash
git clone https://github.com/bitsfdb/RLItemMod.git
cd RLItemMod
npm install
npm run build
npm link
```
## Usage
Simply launch the interactive wizard from your terminal:
```bash
rl-item-mod
```
Or run directly via npx:
```bash
npx rl-item-mod@latest
```
## Credits
Massive credits to [CrunchyRL/RLUPKTools](https://github.com/CrunchyRL/RLUPKTools) for making this repository possible. The advanced Python engineering for parsing and shifting Unreal Engine 3 UPK binaries was instrumental in making this project work safely.
## Support
Contact me on discord: @sfdb
Or on the support server https://discord.gg/2HhBNbrGMj
## License
MIT
## Code Signing Policy
Free code signing provided by [SignPath.io](https://signpath.io), certificate by [SignPath Foundation](https://signpath.org).
| Role | Member |
|------|--------|
| Committers & Approvers | [@bitsfdb](https://github.com/bitsfdb) |
## Privacy Policy
This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. Anonymous diagnostic reports may be sent to velocityrl.tech solely for crash analysis.