CustomCars

A BepInEx mod for New Star GP that allows you to use custom car models in-game.

Compatibility

This mod has been tested on:

• Windows (Steam)
• Steam Deck

It should also work on Linux, but has not been extensively tested.

---

Installation

Step 1: Install BepInEx

1. Download BepInEx 5.4.23.2 from the BepInEx releases page

   • Download the file: BepInEx_x64_5.4.23.2.zip (or latest 5.4.x version)

2. Locate your New Star GP game folder:

   • Open Steam
   • Right-click on "New Star GP" in your library
   • Select "Manage" > "Browse local files"
   • This opens the folder containing NewStarGP.exe (or similar game executable)

3. Extract the BepInEx zip file:

   • Extract all contents of the BepInEx zip directly into your game folder
   • The folder structure should look like this:

     NewStarGP/
     ├── NewStarGP.exe (or game executable)
     ├── BepInEx/
     │   ├── core/
     │   ├── plugins/
     │   └── config/
     ├── doorstop_config.ini
     └── winhttp.dll
     

4. Run the game once:

   • Launch New Star GP through Steam
   • Let it load to the main menu
   • This initializes BepInEx and creates necessary folders
   • Close the game

Step 2: Install CustomCars Mod

1. Download the latest CustomCars.dll from the Releases page

2. Create the CustomCars folder structure:

   • Navigate to: BepInEx/plugins/
   • Create a new folder called CustomCars
   • Inside CustomCars, create a folder called AssetBundles
   • Your structure should be: BepInEx/plugins/CustomCars/AssetBundles/

3. Place the mod files:

   • Copy CustomCars.dll into BepInEx/plugins/CustomCars/

Step 3: Add Car Models

1. Download car models from the Models folder in this repository

   • Available cars: cozycoupe, cybertruck, keitruck

2. Copy the car model files (without file extensions) into:

   • BepInEx/plugins/CustomCars/AssetBundles/

3. Your final structure should look like:

   BepInEx/plugins/CustomCars/
   ├── CustomCars.dll
   └── AssetBundles/
       ├── cozycoupe
       ├── cybertruck
       └── keitruck
   

Step 4: Configure Car Overrides

Option 1: In-Game Configuration (Recommended)

1. Launch the game
2. Press F8 (default) to open the car configuration UI
3. Select a player tab (Player 1-4)
4. Click on a car to select it for that player
5. Click "Save Configuration"
6. Changes apply to your next race!

Option 2: Manual Configuration

1. Launch the game once with the mod installed

   • This generates the configuration file

2. Close the game and navigate to:

   • BepInEx/config/CustomCars.cfg

3. Open CustomCars.cfg in a text editor

4. Set your car overrides using the exact model names (lowercase, no file extensions):

   [Player 1]
   Car = cybertruck
   
   [Player 2]
   Car = cozycoupe
   
   [Player 3]
   Car = keitruck
   
   [Player 4]
   Car = null

5. Available car names are listed in the [Available Cars] section of the config file

---

Usage Notes

• Custom car models will only appear during races (in-game matches)
• Models may take a few seconds to load after the race starts
• The original car physics and hitboxes remain unchanged - only visuals are replaced
• If a car override is left empty or set to an invalid name, the default car will be used

In-Game Controls

F8 - Car Configuration UI

• Select one car per player
• Visually choose from all installed cars
• See which car is currently selected (highlighted in blue)
• Changes apply to your next race
• No restart required

F6 - Model Browser

• Browse all available car models from the catalog
• Download models directly to your game
• See descriptions, authors, and file sizes
• Track download progress
• Restart required after downloading

After downloading a model:

1. Restart the game to load the new model
2. Press F8 to select it
3. Enjoy your new car!

You can change the hotkeys in the config file:

[Model Browser]
OpenBrowserKey = F6
OpenCarConfigKey = F8

---

[Model Browser] OpenBrowserKey = F6 AutoCheckForNewModels = true

---

## Troubleshooting

- Check the BepInEx console log for errors: `BepInEx/LogOutput.log`
- Ensure car model names in the config match the asset bundle filenames exactly (case-insensitive)
- Make sure asset bundles are in the correct folder: `BepInEx/plugins/CustomCars/AssetBundles/`
- Verify BepInEx is properly installed by checking if the `BepInEx` folder was created after first launch

---

## Contributing

Bug reports, feature requests, and contributions are welcome! Please use the [GitHub Issues](https://github.com/JosFa1/CustomCars/issues) page.

---

## Creating Custom Car Models

You have two options for creating custom car models:

### Option 1: Create Your Own (Free)

#### Requirements
- Unity Editor version **2022.3.39f1** (must match exactly)
  - Download from the [Unity Download Archive](https://unity.com/releases/editor/archive)
  - Select "Unity 2022.x" tab, find version 2022.3.39f1

#### Setup Process

1. Install Unity 2022.3.39f1
   - Run the Unity Hub
   - Go to "Installs" > "Install Editor"
   - Choose version 2022.3.39f1
   - During installation, include "Windows Build Support" (or your platform)

2. Create a new Unity project:
   - Open Unity Hub
   - Click "New Project"
   - Select "3D" template
   - Name your project (e.g., "CustomCarModding")
   - Click "Create"

3. Add the editor scripts:
   - In your Unity project, locate the `Assets` folder in the Project window
   - Create a new folder called `Editor` (must be named exactly "Editor")
   - Copy all scripts from this repository's `/UnityEditorScripts/` folder into your `Assets/Editor/` folder:
     - `CarAssetBundleBuilder.cs`
     - `CarPrefabValidator.cs`
     - `QuickCarSetup.cs`
   
   **IMPORTANT**: The scripts MUST be in an `Editor` folder or they will not work properly.

4. Import reference models:
   - Download the existing car models from `/Models/` in this repository
   - In Unity, go to "Tools" > "Car Asset Bundle Builder"
   - Click "Import Asset Bundle" and select one of the reference models
   - This shows you the correct scale and structure

5. Create your custom car:
   - Import your 3D model (FBX, OBJ, or other format) into Unity
   - Drag it into the Scene or Hierarchy
   - Scale and position your model to match the reference cars
   - **Recommended size**: Compare visually with imported reference models

6. Set up your car prefab:
   - Select your car model in the Hierarchy
   - Right-click > "Setup as Car Prefab"
   - This automatically adds required components (MeshFilter, MeshRenderer)

7. Create the asset bundle:
   - Select your prefab in the Project window
   - In the Inspector (bottom), find "AssetBundle" dropdown
   - Click dropdown > "New..."
   - Enter your car name in **lowercase** (e.g., `sportscar`, `racecar`, `mycar`)
   - Press Enter

8. Validate and build:
   - Go to "Tools" > "Car Asset Bundle Builder"
   - Click "Validate All Car Prefabs" to check for issues
   - Fix any errors shown
   - Click "Build Asset Bundles"
   - Your asset bundle will be created in `Assets/../AssetBundles/` (one folder up from Assets)

9. Deploy to game:
   - Find your asset bundle file (it has no file extension, just the name you gave it)
   - Copy it to: `BepInEx/plugins/CustomCars/AssetBundles/`
   - **Do NOT copy** `.manifest` or `.meta` files
   - Add the car name to your config file
   - Launch the game

#### Asset Bundle Structure

Your car prefab must follow this structure:

YourCarName (Root GameObject) ├─ MeshFilter (contains your 3D mesh) └─ MeshRenderer (contains materials/textures)

The mod will:
- Hide the original car body and wings
- Apply your custom mesh and materials
- Keep the original physics and collision

#### Tips for Success

- Use lowercase names for consistency (e.g., `mycar`, not `MyCar`)
- Keep polygon count reasonable (under 10,000 triangles recommended)
- Ensure materials/textures are embedded in the asset bundle
- Test scale by comparing with reference models
- The car's rotation in Unity will affect how it appears in-game

### Option 2: Commission a Model (Paid)

If you'd prefer to have a custom model created for you:

- Contact me on Discord: **josfa**
- Pricing starts at $1 USD and increases based on complexity
- You can choose to keep the model private or have it added to this repository
- Turnaround time varies depending on complexity

---

## License

This project is open source. Feel free to view, modify, and contribute to the code.

---

## For Developers: Setting Up Releases

If you're forking this project or want to set up automatic update notifications and model catalog:

### Creating the Model Catalog

The mod fetches available models from `catalog.json` in your repository root. Update this file when adding new models:

1. Edit [catalog.json](catalog.json)
2. Add your new model entry:

```json
{
  "name": "mycar",
  "displayName": "My Custom Car",
  "description": "A cool custom car model",
  "author": "YourName",
  "version": "1.0",
  "downloadUrl": "https://raw.githubusercontent.com/JosFa1/CustomCars/main/Models/mycar",
  "previewUrl": "",
  "fileSize": "0.5"
}

3. Commit and push to GitHub
4. Users can now download it via the in-game browser (F6)

Important: The downloadUrl should point to the raw GitHub file, not the HTML page. Use the format:

https://raw.githubusercontent.com/[username]/[repo]/[branch]/Models/[modelname]

Creating Releases on GitHub

1. Go to your repository on GitHub
2. Click "Releases" in the right sidebar
3. Click "Create a new release"

Release Format Requirements

For the update checker to work properly:

Tag Version Format:

• Use semantic versioning: v1.0.0, v1.0.1, v1.1.0, etc.
• Must start with v followed by MAJOR.MINOR.PATCH
• Example: v1.0.1

Release Title:

• Can be anything descriptive (e.g., "CustomCars v1.0.1 - Bug Fixes")

Release Assets:

• Upload the compiled CustomCars.dll file
• Optionally include car model files
• Include a changelog in the release description

Example Release Process

1. Update version in CustomCars.csproj:

   <Version>1.0.1</Version>

2. Build the project to generate the DLL

3. Commit and push changes to GitHub

4. Create a new release:

   • Tag: v1.0.1
   • Title: CustomCars v1.0.1
   • Description: List changes and new features
   • Upload: CustomCars.dll

5. Publish the release

Update Notification Behavior

• Checks for updates on game launch (if enabled in config)
• Compares current version against latest GitHub release tag
• Shows in-game popup if newer version is available
• Users can:
  • View the release page (opens in browser)
  • Skip the update
  • Silence future notifications

Disabling Update Checks

Users can disable update checks in BepInEx/config/CustomCars.cfg:

[Update Checker]
CheckForUpdates = false