diff --git a/README.md b/README.md index b4e5288..1285596 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,225 @@ -# PartID.Redirection.Plugin +# PartID Redirection Plugin +A BepInEx plugin that provides seamless redirection of obsolete part IDs to their current equivalents in PC Building Simulator. +This plugin maintains backward compatibility with legacy save files and configurations when part IDs change due to game updates or mod revisions. +## 📋 Table of Contents +* [Features](#features) +* [Requirements](#requirements) +* [Installation](#installation) +* [Configuration](#configuration) +* [How It Works](#how-it-works) +* [Usage Examples](#usage-examples) +* [Troubleshooting](#troubleshooting) + +## ✨ Features +* **Automatic Part ID Redirection**: Transparently redirects old part IDs to new ones during gameplay +* **Save Game Compatibility**: Maintains compatibility with save files containing obsolete part identifiers +* **Configuration-Based**: Easy-to-edit text configuration file for managing redirects +* **Multi-line Part Name Support**: Handles part names with embedded formatting and newlines +* **Performance Optimized**: Dictionary-based lookups with minimal overhead +* **Comprehensive Logging**: Debug information for troubleshooting redirect operations + +## 🔧 Requirements +* **BepInEx**: 5.x or higher +* **HarmonyLib**: 2.x (included with BepInEx) +* **.NET Framework**: 3.5 or higher +* **Game**: PC Building Simulator + +## 📦 Installation +### Step 1: Install BepInEx + +1. Download BepInEx from [GitHub](https://github.com/BepInEx/BepInEx/releases) +2. Extract the BepInEx files into your game directory +3. Run the game once to generate the BepInEx folder structure + +### Step 2: Install PartID Redirection Plugin + +1. Download the latest release of [PartID.Redirection.Plugin]() +2. Copy the DLL file to: `/BepInEx/plugins/` +3. Copy `PartID_Redirects.cfg` to: `/BepInEx/config/` +4. Launch the game + +### Verification + +Check the BepInEx console log for: + +``` +[Info: PartID Redirection Plugin] Loaded x part ID redirect(s) from '.../BepInEx/config/PartID_Redirects.cfg' +[Info: PartID Redirection Plugin] Successfully patched PartsDatabase.GetDesc +``` + +## ⚙️ Configuration + +The configuration file `PartID_Redirects.cfg` is located in `BepInEx/config/`. + +### File Format + +```ini +# This is a comment line +OLD_PART_ID = NEW_PART_ID + +# Example redirects +ALPHACOOL_WC_CPU_114 = ALPHACOOL_WC_CPU_107 +CPU_Intel_352 = CPU_Intel_325 +``` + +### Configuration Rules + +* **Format**: `OLD_ID = NEW_ID` (one redirect per line) +* **Comments**: Lines starting with `#` are ignored +* **Empty Lines**: Blank lines are ignored +* **Whitespace**: Leading and trailing spaces are automatically trimmed +* **Case Sensitivity**: Part IDs are case-sensitive (use exact capitalization) +* **Duplicates**: If the same OLD_ID appears multiple times, the last definition wins + +### Example Configuration + +```ini +# ======================================================================== +# PartID Redirection Configuration +# ======================================================================== + +# ---------------------------------------- +# Water Cooling Components +# ---------------------------------------- +ALPHACOOL_WC_CPU_112 = ALPHACOOL_WC_CPU_106 +ALPHACOOL_WC_CPU_114 = ALPHACOOL_WC_CPU_107 + +# ---------------------------------------- +# Air Coolers +# ---------------------------------------- +Air_Cooler_ARCTIC\169 = Air_Cooler_ARCTIC_149 + +# ---------------------------------------- +# CPUs +# ---------------------------------------- +CPU_Intel_352 = CPU_Intel_325 +CPU_Intel_353 = CPU_Intel_326 +CPU_Intel_354 = CPU_Intel_327 +# ... add more as needed +``` +## 🔬 How It Works + +The plugin uses Harmony to intercept part lookup operations in the game's `PartsDatabase` class: + +1. **Harmony Patching**: Patches the `PartsDatabase.GetDesc` method at runtime +2. **Part Name Sanitization**: Extracts the actual part ID from multi-line formatted names +3. **Dictionary Lookup**: Checks if the part ID has a configured redirect +4. **Transparent Replacement**: Replaces the old ID with the new ID before the game processes it + +### Technical Flow + +``` +Game requests part "ALPHACOOL_WC_CPU_114" + ↓ +Plugin intercepts via Harmony Prefix + ↓ +Sanitizes part name (removes formatting) + ↓ +Checks redirect dictionary + ↓ +Replaces with "ALPHACOOL_WC_CPU_107" + ↓ +Game continues with new part ID +``` +## 📖 Usage Examples + +### Scenario 1: Mod Update Changed Part IDs + +A mod updated and changed CPU part IDs from the 352-378 range to 325-351 range. + +**Solution**: Add redirects to maintain save game compatibility: + +```ini +CPU_Intel_352 = CPU_Intel_325 +CPU_Intel_353 = CPU_Intel_326 +# ... etc +``` + +### Scenario 2: Removed Parts + +A part was removed from the game and replaced with a newer model. + +**Solution**: Redirect the old part to its replacement: + +```ini +OLD_OBSOLETE_GPU_001 = NEW_REPLACEMENT_GPU_050 +``` + +### Scenario 3: Consolidated Parts + +Multiple similar parts were consolidated into a single part. + +**Solution**: Redirect all old variants to the new consolidated part: + +```ini +COOLER_VARIANT_A = COOLER_UNIFIED +COOLER_VARIANT_B = COOLER_UNIFIED +COOLER_VARIANT_C = COOLER_UNIFIED +``` +## 🐛 Troubleshooting + +### Plugin Not Loading + +**Symptoms**: No log messages from "PartID Redirection Plugin" + +**Solutions**: + +* Verify BepInEx is installed correctly +* Check that the DLL is in `BepInEx/plugins/` +* Enable BepInEx console to see startup messages +* Check BepInEx log file: `BepInEx/LogOutput.log` + +### Redirects Not Working + +**Symptoms**: "Unknown part" errors still appear + +**Solutions**: + +1. **Check Part ID Capitalization**: IDs are case-sensitive + +```ini + # Wrong + alphacool_wc_cpu_114 = ALPHACOOL_WC_CPU_107 + + # Correct + ALPHACOOL_WC_CPU_114 = ALPHACOOL_WC_CPU_107 +``` + +2. **Verify Target Part Exists**: The NEW_ID must be a valid part in the game + + * Check if the target part appears in the game's parts database + * Test by searching for the part in-game + +3. **Check Configuration File Location**: Must be in `BepInEx/config/PartID_Redirects.cfg` +4. **Enable Debug Logging**: Check BepInEx logs for redirect messages: + +``` + [Debug: PartID Redirection Plugin] Redirecting part ID: 'ALPHACOOL_WC_CPU_114' → 'ALPHACOOL_WC_CPU_107' +``` + +### Configuration Not Loading + +**Symptoms**: Log shows "Loaded 0 part ID redirect(s)" + +**Solutions**: + +* Verify file name is exactly: `PartID_Redirects.cfg` +* Check file encoding is UTF-8 or ANSI (not UTF-16) +* Ensure lines follow the `OLD=NEW` format +* Remove any invisible characters or BOM markers + +### Game Crashes or Errors + +**Symptoms**: Game crashes after installing plugin + +**Solutions**: + +* Verify .NET Framework compatibility (3.5+) +* Check for conflicts with other Harmony mods +* Temporarily remove the plugin to confirm it's the cause +* Check BepInEx error logs for exception details + +--- + +**Made with ❤️ by anonymus637** \ No newline at end of file