Troubleshooting

This document covers the most common problems people hit with RCC and how to fix them. If your specific issue isn't listed, also check 29 — FAQ, the inline Console errors in Unity, or contact support at bonecrackergames@gmail.com.

Installation Issues

"I get hundreds of compile errors right after importing"

The most common cause is missing the Input System package. RCC requires it.

Fix: 1. Open Window → Package Manager → Unity Registry. 2. Search for Input System. 3. Install it. Click Yes when prompted to enable the new backends. 4. Restart Unity.

If that doesn't fix it, also check:

• Active Input Handling is set to "Input System Package (New)" or "Both" in Project Settings → Player.
• You're on Unity 2022.3 LTS or newer.
• There are no leftover scripts from removed addons. Delete any Photon, EnterExit, or BCG Shared Assets folders if they exist.

"Welcome window keeps appearing every time I open Unity"

The welcome window is only supposed to appear on first install. If it persists, the dismiss flag isn't being saved. Try:

1. Click the "Don't show again" checkbox if visible.
2. Manually close it via Tools → BoneCracker Games → Realistic Car Controller → Welcome Window and dismiss it.
3. If that doesn't work, clear Unity's Library/ cache (close Unity, delete Library/, reopen).

"All materials are pink after import"

You're on URP or HDRP. Run the converter:

Tools → BoneCracker Games → Realistic Car Controller → Render Pipeline Converter

See 22 — URP & HDRP Conversion for the full procedure.

"Layer 'RCC_Vehicle' is missing"

RCC adds custom layers on import. If the import was interrupted or partial, the layers may not have been created.

Fix: 1. Open Edit → Project Settings → Tags and Layers. 2. Add user layers named RCC_Vehicle, RCC_WheelCollider, RCC_DetachablePart, RCC_Prop. 3. Save.

Alternatively, re-import the package — RCC's init script runs again on import.

Driving / Physics Issues

"The car spawned but I can't control it"

Most likely the vehicle isn't registered as the player. Three checks:

1. Tag is "Player" — the Scene Manager auto-registers tagged vehicles.
2. Scene has an RCC_SceneManager — without it, no input flows.
3. canControl is true on the vehicle's RCC_CarControllerV4.

Also verify the Input System is enabled (see installation section above).

"Throttle works but the car barely moves"

Usually one of:

• Brake is stuck on. Check brakeInput in the controller's Inspector during Play mode.
• Handbrake is on. Check handbrakeInput.
• Engine isn't running. Check engineRunning.
• Mass is way too high. A car with 50000 kg mass barely moves at default torque.

"The car flips over for no reason"

Center of mass (COM) is too high, OR the car is upside-down at spawn.

Fix:

• Click the COM child transform on the vehicle.
• Move it lower (closer to the ground, slightly forward of center).
• For a sports car: COM Y around 0.2–0.4 m above ground.
• For an SUV: 0.5–0.7 m.

If the car flips at spawn, check that the vehicle prefab's rotation is (0, 0, 0) and Y position is positive.

"The wheels look sunken into the ground"

The wheel collider radius is wrong, or the suspension distance is wrong.

Fix:

• Click each wheel collider GameObject (under Wheel Colliders/).
• Set the WheelCollider.Radius to the actual visible wheel radius.
• Increase Suspension Distance if needed.

"The wheels look detached from the vehicle (gap visible)"

The wheel collider's position doesn't match the wheel mesh's position.

Fix:

• Open the vehicle prefab.
• Compare the position of each wheel mesh transform with its corresponding wheel collider child.
• They should be at the same world position. Move whichever is off.

"The car wobbles or vibrates at rest"

The wheels aren't symmetric, OR the COM is unstable.

Fix:

• Make sure all four wheel colliders have identical values for Radius, Suspension Spring, Damper, Target Position.
• Verify the COM transform is below the wheel resting positions.
• Try increasing the Wheel Damping Rate on each WheelCollider.

"Vehicle stutters / vibrates at high speed"

Physics fixed timestep is too slow.

Fix:

• In RCC_Settings.asset, set Fixed Time Step to 0.01 (100 Hz physics).
• Or in Unity's Edit → Project Settings → Time, set Fixed Timestep to 0.01.

This costs more CPU but stabilizes high-speed simulation.

"Vehicle clips through walls or terrain at high speed"

Collision detection mode is too lazy.

Fix:

• Click the vehicle's Rigidbody.
• Change Collision Detection from "Discrete" to "Continuous Dynamic" or "Continuous".

This costs more CPU but prevents tunneling.

"Auto Reset keeps flipping the vehicle when it's actually upright"

The detection threshold is too sensitive.

Fix:

• Open RCC_Settings.asset.
• Uncheck Auto Reset to disable it entirely.
• Or modify the threshold (currently in RCC_CarControllerV4's Update — search for "reset" in the script).

Camera Issues

"The camera doesn't follow the vehicle"

Either there's no RCC_Camera in the scene, OR the player vehicle isn't registered.

Fix:

1. Tools → BoneCracker Games → Realistic Car Controller → Create → Cameras → Add RCC Camera To Scene.
2. Delete the default Main Camera.
3. Make sure your vehicle is tagged "Player" or registered via RCC.RegisterPlayerVehicle().

"Two cameras are conflicting"

Most often: you have both the default Unity Main Camera AND RCC_Camera in the scene. Delete the default Main Camera.

"The camera goes inside the vehicle / clips through walls"

There's no built-in collision avoidance. Increase the camera distance, or write your own occlusion logic using raycasts. See 13 — Camera System.

"Hood camera shows the inside of the body mesh"

The hood camera anchor is positioned inside the model. Move it forward / upward until it's outside the cabin geometry.

Audio Issues

"I don't hear engine sounds"

Check:

1. The vehicle's Audio Type isn't set to Off.
2. The audio clips are assigned in the Inspector.
3. The scene has an AudioListener (on the camera). Only one should exist.
4. Unity's master volume / OS master volume isn't muted.

"Engine sound is too high-pitched (chipmunk effect)"

Max Engine Sound Pitch is too high. Set to 1.5 or 1.6 instead of 1.8+.

"Crash sound plays for tiny scrapes"

The crash threshold is too sensitive. Lower maxCrashSoundVolume in RCC_Settings, or modify the velocity threshold in RCC_CarControllerV4.OnCollisionEnter (advanced).

"Audio cuts in and out when there are many vehicles"

Unity is hitting the max audio voices limit (default 256). Reduce the number of active vehicles, or reduce the per-vehicle audio source count (use TwoSource instead of ThreeSource).

Lighting Issues

"Headlights don't illuminate the scene"

Either:

• The Unity Light component is disabled (check the GameObject).
• The light's Range is too short (try 30 m for headlights).
• In URP, the Additional Lights mode is set to Disabled or Per Vertex (change to Per Pixel in the URP Asset).

"Lights are too bright in HDRP"

HDRP uses lumens, which are much larger numbers than the Built-in / URP scale. Reduce intensity to 500–2000 lumens for vehicle lights.

"Indicators don't blink"

The RCC_Light.lightType is wrong. It needs to be IndicatorLeft, IndicatorRight, or IndicatorHazard — not BrakeLight or other.

"Headlights light my own car interior"

Set the light's Culling Mask to exclude the vehicle's own layer (RCC_Vehicle).

UI Issues

"Speedometer reads 0 even when driving"

The UI canvas isn't bound to a vehicle.

Fix: Most RCC UI widgets find the active player vehicle automatically via RCC_SceneManager.Instance.activePlayerVehicle. If they're not finding it:

• Make sure the vehicle is registered as the player.
• Make sure the UI canvas (RCC_Canvas prefab) is in the scene.
• Make sure the scene has an EventSystem.

"Touch buttons appear but don't respond"

The scene is missing an EventSystem. Add it: GameObject → UI → Event System.

"Touch buttons appear on desktop too (unwanted)"

You enabled Mobile Controller Enabled in RCC_Settings. Turn it off for desktop builds. The mobile UI canvas auto-detects platform if its components are configured correctly.

Customization Issues

"Paint changes don't apply to the body"

The PaintManager's Paint Targets array isn't pointing at the right Renderer. Open the vehicle prefab, find the PaintManager, and assign the body MeshRenderer.

"Wheel customization doesn't show new wheels"

The available wheels list (in RCC_ChangableWheels.asset) doesn't include your new wheel prefab. Add it.

"Saved customization doesn't load on next play"

PlayerPrefs storage may differ between platforms. On WebGL, PlayerPrefs is browser-storage-based and can be cleared by the user. On iOS, it persists indefinitely. Test on your actual target platform.

AI Issues

"AI doesn't follow my waypoints"

Check:

1. The AI vehicle's RCC_AICarController has its Waypoints Container field assigned.
2. Navigation Mode is set to Following Waypoints.
3. The waypoints container actually contains child waypoints.

"AI keeps spinning out"

Tune down AI Steering Speed to ~5-6, or enable Override Behavior on the AI vehicle and configure friction values manually.

"AI cars get stuck against walls"

Enable Use Obstacle Avoidance on the RCC_AICarController. Tune Ray Distance to match your scene layout.

"AI flips over on jumps"

The AI's Max Speed is too high for the geometry. Lower it.

Performance Issues

"Frame rate drops with multiple AI vehicles"

Each AI has 4 WheelColliders and an AI controller running. The cost adds up.

Fixes (in order of impact):

1. Reduce number of active AI vehicles.
2. Add RCC_LOD to vehicles for distance-based throttling.
3. Disable particle effects globally (RCC_Settings.dontUseAnyParticleEffects).
4. Disable skidmarks (RCC_Settings.dontUseSkidmarks).
5. Switch lights to vertex lighting where possible.

"FPS is low on mobile even with one vehicle"

Mobile is more sensitive. In addition to the above:

• Set Fixed Time Step to 0.04 (25 Hz physics).
• Use URP (not HDRP) for the render pipeline.
• Set Quality Settings → Shadows to disabled or Lowest.
• Reduce shadow distance.

"Memory grows over a long play session"

Skidmarks accumulate. They cap eventually but the cap can be large. Reduce maxMarks on the RCC_SkidmarksManager, or call RCC.CleanSkidmarks() periodically.

Build Issues

"Build fails with a 'missing reference' error"

Most often: editor-only scripts are referenced from runtime code. Check the Console for the specific class — usually it's something inside #if UNITY_EDITOR that's accidentally being referenced outside of that block.

Re-importing the package usually fixes it.

"Standalone build crashes on launch"

Check the player log:

• Windows: %appdata%\..\LocalLow\<CompanyName>\<ProductName>\Player.log.
• macOS: ~/Library/Logs/<CompanyName>/<ProductName>/Player.log.
• Linux: ~/.config/unity3d/<CompanyName>/<ProductName>/Player.log.

Common causes: missing audio mixer asset (re-import RCC), missing prefab reference (check RCC_Settings.asset).

"Mobile build crashes when first vehicle spawns"

Often a memory issue. Reduce vehicle quality:

• Disable particle effects globally.
• Use Mobile Diffuse or URP/Lit shaders.
• Reduce texture sizes for the vehicle.

Compile Symbol Issues

"Code in #if BCG_URP doesn't run even though I'm using URP"

The BCG_URP define isn't set. Run the Render Pipeline Converter — it sets the define automatically. Or manually add it: Project Settings → Player → Scripting Define Symbols.

"I see #if RCC_PHOTON or BCG_ENTEREXIT — should I remove the define?"

Yes, both addons were removed in V5. Remove the defines from your project's Scripting Define Symbols.

When Nothing Works

If you've tried everything above and the issue persists:

1. Create a minimal repro. Make a new scene with just the Scene Manager, one vehicle, and a UI canvas. If the bug happens here, it's a bug in RCC. If it doesn't, your project has a conflict — narrow it down.
2. Check the Console. Even a single warning can give you the hint. Filter by Errors / Warnings and read them.
3. Look at the demo scenes. If a demo scene works correctly, compare what it does differently from your scene.
4. Email support. bonecrackergames@gmail.com. Include: - Unity version. - RCC version. - Render pipeline (Built-in / URP / HDRP). - A description of the problem. - Screenshots of the Console and your scene Hierarchy.

Next Steps

• 29 — FAQ — frequently asked questions.
• 00 — Table of Contents — back to the index.