rl-item-mod 1.0.0

package/README.md

@@ -0,0 +1,59 @@
+# RLItemMod
+
+A powerful, user-friendly Node.js CLI tool for performing visual asset swaps in Rocket League.
+
+## Overview
+
+`RLItemMod` provides an interactive terminal wizard that allows you to swap in-game items (e.g., swapping a standard boost for Alpha Reward). Under the hood, it seamlessly invokes the advanced `RLUPKTools` 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.
+
+## 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
+```
+
+### 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.
+
+## License
+
+MIT

package/dist/assets.js

@@ -0,0 +1,110 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import stringSimilarity from 'string-similarity';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Load and transform items.json into ASSET_MAP
+const ITEMS_JSON_PATH = path.join(__dirname, '../python/items.json');
+let loadedAssets = [];
+try {
+    if (fs.existsSync(ITEMS_JSON_PATH)) {
+        const rawData = JSON.parse(fs.readFileSync(ITEMS_JSON_PATH, 'utf8'));
+        if (rawData.Items) {
+            loadedAssets = rawData.Items.map((p) => ({
+                name: p["Product"],
+                productId: p["ID"],
+                packageName: p["AssetPackage"] ? p["AssetPackage"].replace('.upk', '') : '',
+                assetPath: p["AssetPath"],
+                slot: p["Slot"]
+            })).filter((a) => a.packageName !== '');
+        }
+    }
+}
+catch (e) {
+    console.warn(" Warning: Failed to load items.json. Using minimal fallback list.");
+}
+export const ASSET_MAP = loadedAssets.length > 0 ? loadedAssets : [
+    { name: "Standard Boost", packageName: "Standard_Boost_SF", productId: 63 },
+    { name: "Flamethrower", packageName: "Flamethrower_SF", productId: 36 },
+    { name: "(Alpha Reward) Gold Rush", packageName: "Boost_AlphaReward_SF", productId: 32 },
+    { name: "Octane", packageName: "Body_Octane_SF", productId: 23 },
+];
+/**
+ * Performs a fuzzy/case-insensitive search for an item name or product ID.
+ * If mapping fails, it scans the provided directory for potential matches.
+ */
+export async function resolvePackagePath(query, cookedDir) {
+    const q = query.toLowerCase();
+    // 1. Check Internal Map first
+    let match = ASSET_MAP.find(a => a.name.toLowerCase() === q || a.productId?.toString() === q);
+    if (match) {
+        const fullPath = path.join(cookedDir, `${match.packageName}.upk`);
+        if (fs.existsSync(fullPath)) {
+            return { path: fullPath, name: match.packageName };
+        }
+    }
+    // 2. Directory Scan + Keyword Search
+    if (!fs.existsSync(cookedDir)) {
+        console.warn(` Warning: CookedPCConsole directory not found at: ${cookedDir}`);
+        return null;
+    }
+    const files = fs.readdirSync(cookedDir)
+        .filter(f => f.endsWith('.upk'))
+        .filter(f => !f.toLowerCase().includes('t_sf') && !f.toLowerCase().includes('sf_t'));
+    const keywords = q.split(' ').filter(k => k.length > 2); // only words > 2 chars
+    // Find files containing ALL keywords
+    let keywordMatches = files.filter(f => {
+        const lowerF = f.toLowerCase();
+        return keywords.every(k => lowerF.includes(k));
+    });
+    if (keywordMatches.length === 1) {
+        return {
+            path: path.join(cookedDir, keywordMatches[0]),
+            name: keywordMatches[0].replace('.upk', '')
+        };
+    }
+    else if (keywordMatches.length > 1) {
+        return { candidates: keywordMatches };
+    }
+    // 3. String Similarity (Fuzzy Matching)
+    const matches = stringSimilarity.findBestMatch(q, files);
+    const topMatches = matches.ratings
+        .sort((a, b) => b.rating - a.rating)
+        .slice(0, 5)
+        .filter(m => m.rating > 0.3); // Threshold for sanity
+    if (topMatches.length > 0) {
+        // If the best match is very high, return it, otherwise return candidates
+        if (topMatches[0].rating > 0.8) {
+            return {
+                path: path.join(cookedDir, topMatches[0].target),
+                name: topMatches[0].target.replace('.upk', '')
+            };
+        }
+        return { candidates: topMatches.map(m => m.target) };
+    }
+    return null;
+}
+export function getClosestFiles(query, cookedDir) {
+    if (!fs.existsSync(cookedDir))
+        return [];
+    const files = fs.readdirSync(cookedDir)
+        .filter(f => f.endsWith('.upk'))
+        .filter(f => !f.toLowerCase().includes('t_sf') && !f.toLowerCase().includes('sf_t'));
+    const matches = stringSimilarity.findBestMatch(query.toLowerCase(), files);
+    return matches.ratings
+        .sort((a, b) => b.rating - a.rating)
+        .slice(0, 5)
+        .map(m => m.target);
+}
+export function searchAssets(term) {
+    const q = term.toLowerCase();
+    return ASSET_MAP.filter(a => {
+        const nameMatch = a.name.toLowerCase().includes(q);
+        const pkgMatch = a.packageName && a.packageName.toLowerCase().includes(q);
+        const idMatch = a.productId?.toString() === q;
+        const slotMatch = a.slot?.toLowerCase().includes(q);
+        const matches = nameMatch || pkgMatch || idMatch || slotMatch;
+        const isThumbnail = a.packageName && (a.packageName.toLowerCase().includes('t_sf') || a.packageName.toLowerCase().includes('sf_t'));
+        return matches && !isThumbnail;
+    }).slice(0, 20); // Limit to top 20 for CLI readability
+}

package/dist/index.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import inquirer from 'inquirer';
+import { UPKFile } from './upk.js';
+import { resolvePackagePath, searchAssets } from './assets.js';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const program = new Command();
+program
+    .name('RLItemMod')
+    .description('Rocket League Surgical UPK Patcher')
+    .version('1.3.0');
+const API_ENDPOINT = 'https://dank/rlapi';
+const DEFAULT_COOKED_DIR = 'E:\\games\\rocketleague\\TAGame\\CookedPCConsole';
+/**
+ * Interactive Wizard Flow
+ */
+async function runInteractiveWizard() {
+    let active = true;
+    while (active) {
+        console.clear();
+        console.log('Welcome to RLItemMod, What would you like to do?');
+        console.log('-----------------------------------------------------');
+        const { action } = await inquirer.prompt([{
+                type: 'rawlist',
+                name: 'action',
+                message: 'What would you like to do?',
+                choices: [
+                    { name: 'Swap Item (Visual & Offset Shifting)', value: 'swap' },
+                    { name: 'Search Asset Database', value: 'search' },
+                    { name: 'Restore Backups', value: 'restore' },
+                    { name: 'Configure Game Directory', value: 'config' },
+                    { name: 'Exit', value: 'exit' }
+                ]
+            }]);
+        if (action === 'exit') {
+            active = false;
+            break;
+        }
+        if (action === 'config') {
+            const { newDir } = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'newDir',
+                    message: 'Path to CookedPCConsole:',
+                    default: global.COOKED_DIR || DEFAULT_COOKED_DIR
+                }]);
+            global.COOKED_DIR = newDir;
+            console.log(` Game directory updated to: ${newDir}`);
+            await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+            continue;
+        }
+        if (action === 'search') {
+            const { term } = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'term',
+                    message: 'Enter search term (Item Name or Package):'
+                }]);
+            const results = searchAssets(term);
+            console.table(results);
+            await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+            continue;
+        }
+        if (action === 'swap') {
+            const cookedDir = global.COOKED_DIR || DEFAULT_COOKED_DIR;
+            console.log('\n--- STEP 1: Target Item (The one you OWN) ---');
+            const target = await promptForItemAndUPK('Search for your OWNED item:', cookedDir);
+            if (!target) {
+                await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+                continue;
+            }
+            console.log('\n--- STEP 2: Source Item (The one you WANT) ---');
+            const source = await promptForItemAndUPK('Search for the item you WANT:', cookedDir);
+            if (!source) {
+                await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+                continue;
+            }
+            console.log(`\n Swapping ${target.item.name} for ${source.item.name}...`);
+            const targetUpk = new UPKFile(target.path);
+            try {
+                const pythonScriptPath = path.resolve(__dirname, '../python/rl_asset_swapper.py');
+                backupFile(target.path);
+                const cmd = `python "${pythonScriptPath}" --no-gui --target "${target.item.name}" --donor "${source.item.name}" --no-preserve-header-offsets --overwrite --donor-dir "${cookedDir}" --output-dir "${cookedDir}"`;
+                console.log(`\n Executing advanced Python offset-shifter...`);
+                execSync(cmd, { stdio: 'inherit' });
+                console.log(' SUCCESS: Visual Swap complete! please restart your game and view your new item!');
+            }
+            catch (e) {
+                console.error(` Failed: ${e.message}`);
+            }
+            await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+            continue;
+        }
+        if (action === 'restore') {
+            const cookedDir = global.COOKED_DIR || DEFAULT_COOKED_DIR;
+            console.log('\n--- Restoring Backups ---');
+            try {
+                const files = fs.readdirSync(cookedDir);
+                const backups = files.filter(f => f.endsWith('.bak'));
+                if (backups.length === 0) {
+                    console.log(' No backups found.');
+                }
+                else {
+                    for (const bak of backups) {
+                        const original = bak.replace('.bak', '');
+                        const bakPath = path.join(cookedDir, bak);
+                        const originalPath = path.join(cookedDir, original);
+                        console.log(` Restoring ${original}...`);
+                        fs.copyFileSync(bakPath, originalPath);
+                        fs.unlinkSync(bakPath);
+                    }
+                    console.log(' SUCCESS: All backups restored!');
+                }
+            }
+            catch (e) {
+                console.error(` Failed: ${e.message}`);
+            }
+            await inquirer.prompt([{ type: 'input', name: 'pause', message: 'Press Enter to continue...' }]);
+            continue;
+        }
+    }
+}
+/**
+ * Helper to handle the "Search -> Refine -> Pick" flow for a UPK item
+ */
+async function promptForItemAndUPK(message, cookedDir) {
+    const { searchTerm } = await inquirer.prompt([{
+            type: 'input',
+            name: 'searchTerm',
+            message
+        }]);
+    const matches = searchAssets(searchTerm);
+    if (matches.length === 0) {
+        console.error(` No items found matching "${searchTerm}".`);
+        return null;
+    }
+    const { selectedItem } = await inquirer.prompt([{
+            type: 'rawlist',
+            name: 'selectedItem',
+            message: 'Select the item:',
+            choices: matches.map(m => ({
+                name: `${m.name} [ID: ${m.productId}] (${m.packageName})`,
+                value: m
+            }))
+        }]);
+    const owned = selectedItem.productId.toString();
+    const result = await resolvePackagePath(owned, cookedDir);
+    if (!result) {
+        console.error(` Could not resolve "${owned}".`);
+        return null;
+    }
+    let finalUpkPath = '';
+    if ('candidates' in result) {
+        let currentCandidates = result.candidates;
+        while (currentCandidates.length > 20) {
+            console.log(` Found ${currentCandidates.length} potential matches.`);
+            const { refine } = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'refine',
+                    message: 'Too many files found! Enter a sub-keyword to narrow it down (or press Enter to see all):'
+                }]);
+            if (!refine)
+                break;
+            const filtered = currentCandidates.filter(c => c.toLowerCase().includes(refine.toLowerCase()));
+            if (filtered.length > 0)
+                currentCandidates = filtered;
+        }
+        const { selected } = await inquirer.prompt([{
+                type: 'rawlist',
+                name: 'selected',
+                message: `Multiple matches found. Select one (Showing top ${Math.min(currentCandidates.length, 50)}):`,
+                choices: currentCandidates.slice(0, 50)
+            }]);
+        finalUpkPath = path.join(cookedDir, selected);
+    }
+    else {
+        finalUpkPath = result.path;
+    }
+    return { path: finalUpkPath, item: selectedItem };
+}
+async function executePatch(upkPath, data, exportIndex) {
+    try {
+        console.log(` Patching ${upkPath}...`);
+        backupFile(upkPath);
+        const upk = new UPKFile(upkPath);
+        upk.readSummary();
+        upk.readExportMap();
+        if (exportIndex === -1) {
+            exportIndex = upk.exports.reduce((maxIdx, curr, idx, arr) => curr.serialSize > arr[maxIdx].serialSize ? idx : maxIdx, 0);
+            console.log(` Auto-selected Export[${exportIndex}] (Size: ${upk.exports[exportIndex].serialSize} bytes)`);
+        }
+        const newHex = (typeof data === 'string') ? fs.readFileSync(data) : data;
+        upk.patchExport(exportIndex, newHex);
+        console.log(' SUCCESS: Patch complete!');
+    }
+    catch (error) {
+        console.error(' CRITICAL FAILURE:', error.message);
+    }
+}
+function backupFile(filePath) {
+    const backupPath = `${filePath}.bak`;
+    if (!fs.existsSync(backupPath)) {
+        console.log(` Creating backup: ${path.basename(backupPath)}`);
+        fs.copyFileSync(filePath, backupPath);
+    }
+}
+// --- CLI COMMANDS ---
+program
+    .command('list')
+    .description('Shows user\'s owned items from the API')
+    .action(async () => {
+    // Existing list logic...
+    console.log('Fetching items... (Placeholder)');
+});
+program
+    .command('search')
+    .argument('<term>', 'Keyword to search for')
+    .action((term) => {
+    const results = searchAssets(term);
+    console.table(results);
+});
+program
+    .command('swap')
+    .requiredOption('--owned <itemName>', 'Item name or Product ID')
+    .requiredOption('--target <targetHexFile>', 'Hex file path')
+    .option('--upk <path>', 'Explicit UPK path')
+    .option('--dir <path>', 'Cooked dir', DEFAULT_COOKED_DIR)
+    .option('--export <index>', 'Export index')
+    .action(async (options) => {
+    // Call executePatch with resolved paths...
+    let upkPath = options.upk;
+    let cookedDir = options.dir;
+    if (!fs.existsSync(cookedDir)) {
+        console.error(` Error: CookedPCConsole directory not found at: ${cookedDir}`);
+        console.log('Use --dir <path> to specify the correct game directory.');
+        return;
+    }
+    if (!upkPath) {
+        const res = await resolvePackagePath(options.owned, cookedDir);
+        if (res && 'path' in res)
+            upkPath = res.path;
+    }
+    if (!upkPath) {
+        console.error(` Error: Could not resolve item "${options.owned}" in ${cookedDir}.`);
+        return;
+    }
+    await executePatch(upkPath, options.target, options.export ? parseInt(options.export) : -1);
+});
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+    console.log('\n Exiting RLItemMod. See you next time!');
+    process.exit(0);
+});
+async function runSafeWizard() {
+    try {
+        await runInteractiveWizard();
+    }
+    catch (e) {
+        if (e.name === 'ExitPromptError') {
+            console.log('\n Goodbye!');
+        }
+        else {
+            console.error('\n An unexpected error occurred:', e.message);
+        }
+        process.exit(0);
+    }
+}
+// Default to wizard if no command is provided
+if (process.argv.length <= 2) {
+    runSafeWizard();
+}
+else {
+    program.parse(process.argv);
+}

package/dist/scratch/ts_debug_exports.js

@@ -0,0 +1,33 @@
+import { UPKFile } from '../dist/upk.js';
+const upk = new UPKFile('E:\\games\\rocketleague\\TAGame\\CookedPCConsole\\explosion_badaboom_SF.upk');
+try {
+    upk.readSummary();
+    const r = upk.dataBuffer ? new (require('../dist/upk.js').BinaryReader)(upk.dataBuffer) : null;
+    if (r) {
+        r.pos = upk.summary.exportOffset;
+        for (let i = 0; i < upk.summary.exportCount; i++) {
+            const classIndex = r.readI32();
+            const superIndex = r.readI32();
+            const outerIndex = r.readI32();
+            const objectNameIndex = r.readI32();
+            const objectNameNumber = r.readI32();
+            const archetypeIndex = r.readI32();
+            const objectFlags = r.readU64();
+            const serialSize = r.readI32();
+            const serialOffset = r.readI32();
+            const exportFlags = r.readI32();
+            const netObjCount = r.readI32();
+            console.log(`Export ${i}: NetObjCount = ${netObjCount}, pos before skip: ${r.pos}`);
+            if (netObjCount < 0 || netObjCount > 1000) {
+                console.log(`Abnormal netObjCount: ${netObjCount} at export ${i}`);
+                break;
+            }
+            r.skip(netObjCount * 4);
+            r.skip(16); // PackageGuid
+            r.readI32(); // PackageFlags
+        }
+    }
+}
+catch (e) {
+    console.error(e);
+}

package/dist/swapper.js

@@ -0,0 +1,81 @@
+/**
+ * Implements the "Fixed Rename" logic from RLUPKTools.
+ * This renames a name table entry IN-PLACE by padding with nulls.
+ * This ensures the header size and all subsequent offsets remain identical.
+ */
+export class UPKSwapper {
+    upk;
+    constructor(upk) {
+        this.upk = upk;
+    }
+    /**
+     * Renames an existing name entry to a new name.
+     * The new name must be shorter than or equal to the original name's space.
+     */
+    fixedRename(oldName, newName) {
+        if (!this.upk.summary || !this.upk.getData())
+            return false;
+        const data = this.upk.getData();
+        const nameOffset = this.upk.summary.nameOffset;
+        let pos = nameOffset;
+        for (let i = 0; i < this.upk.summary.nameCount; i++) {
+            const entryStart = pos;
+            const length = data.readInt32LE(pos);
+            pos += 4;
+            let currentName;
+            let totalBytes;
+            if (length > 0) {
+                // ANSI
+                currentName = data.toString('utf8', pos, pos + length - 1);
+                totalBytes = length;
+                pos += length;
+            }
+            else if (length < 0) {
+                // UTF-16
+                const absLen = Math.abs(length) * 2;
+                currentName = data.toString('utf16le', pos, pos + absLen - 2);
+                totalBytes = absLen;
+                pos += absLen;
+            }
+            else {
+                pos += 8; // Skip flags
+                continue;
+            }
+            // Skip ObjectFlags (8 bytes)
+            pos += 8;
+            if (currentName === oldName) {
+                console.log(` Found name entry "${oldName}" at index ${i}. Renaming to "${newName}"...`);
+                // Prepare the new string
+                const newBuf = Buffer.alloc(totalBytes, 0);
+                if (length > 0) {
+                    newBuf.write(newName, 'utf8');
+                }
+                else {
+                    newBuf.write(newName, 'utf16le');
+                }
+                // Write it back
+                newBuf.copy(data, entryStart + 4);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Swaps all references of donorName to targetName in the package.
+     * This is useful for "tricking" the engine into loading one asset instead of another.
+     */
+    swapAssetReferences(targetAssetName, donorAssetName) {
+        console.log(` Swapping references: ${targetAssetName} <-> ${donorAssetName}`);
+        // We actually want to rename the TARGET name to something else,
+        // and the DONOR name (which we might have imported) to the TARGET name.
+        // But for a simple swap where we just patch the file, we can just rename 
+        // the internal package name.
+        const success = this.fixedRename(targetAssetName, donorAssetName);
+        if (success) {
+            console.log(` Successfully swapped ${targetAssetName} for ${donorAssetName} references.`);
+        }
+        else {
+            console.warn(` Failed to find name entry for ${targetAssetName}.`);
+        }
+    }
+}