NWH Vehicle Physics

Export

Use the NWH Vehicle Physics integration when an Ultimate Character Controller character should enter a vehicle, hand driving input and camera control to NWH Vehicle Physics 2, then return to ordinary character control on exit.

Supported package boundary

This guide is verified against the released Ultimate Character Controller Version 3 NWHDriveSource bridge and the checked-in NWH test project, whose AssetInfo reports 10.20f. The bridge package was last source-updated in July 2023 and does not declare a minimum or maximum NWH version. NWH has published later releases, so this is not a blanket compatibility guarantee for every 13.x package.

Before upgrading an existing project, import the current Opsive bridge into a copy and confirm that NWH still exposes NWH.Common.Vehicles.Vehicle and NWH.Common.Cameras.CameraChanger. Follow the NWH Vehicle Physics documentation and changelog for package-specific vehicle setup and migration changes.

Before you begin

Build and test the Ultimate Character Controller Version 3 character, camera, and Drive ability before connecting the vehicle.
Build and test the NWH vehicle on its own. Its wheels, Rigidbody, powertrain, input provider, and cameras remain NWH responsibilities.
Decide which NWH input provider owns the vehicle controls. The bridge enables the NWH Vehicle component; it does not translate Ultimate Character Controller character input into NWH steering, throttle, or brake values.
Add an NWH vehicle camera. The stock bridge disables the Ultimate Character Controller Camera Controller GameObject while driving and has no option to keep that camera active.

Install the integration

Install NWH Vehicle Physics 2 and verify a vehicle in Play Mode.
Sign in to Opsive Downloads and download the NWH Vehicle Physics integration. The bridge is not included in the base product’s Integrations folder before this download.
Import the downloaded bridge after NWH has compiled. Importing it creates the integration files in the project.
Allow Unity to compile. Resolve the first Console error before continuing; the bridge requires both Ultimate Character Controller and the NWH Vehicle and CameraChanger APIs.
Confirm that NWH Drive Source is available from Add Component.

Reimport the current bridge after updating Ultimate Character Controller or NWH. If its source no longer compiles, restore the last working package combination or adapt the bridge to the installed NWH API before changing the scene setup.

Connect the vehicle

Select the vehicle root containing NWH’s Vehicle Controller component. Add NWH Drive Source to this same GameObject; the bridge looks for the NWH Vehicle component beside itself.
Create a child Transform named Driver Location. Position and rotate it where the character should sit, then assign it to NWH Drive Source > Driver Location.
Set Animator ID. Keep 0 when using the default Drive animation set, or use a distinct base ID when the Animator contains vehicle-specific Enter, Drive, and Exit states.
Add one or more Move Towards Location children beside doors or other safe entry and exit points. Drive requires at least one clear location even when Teleport Enter Exit is enabled.
Add the collider or trigger that Drive should detect. Put its actual layer in Drive > Detect Layers; do not assume an NWH prefab uses a particular layer.
Keep every vehicle collider that should ignore the seated character active below the NWH Drive Source GameObject when the scene starts. The bridge caches active child colliders once during Start.

The current bridge disables the NWH Vehicle component during Start and enables it after the character finishes entering. Do not follow older instructions to change NWH’s removed Awake On Start option; that legacy screenshot and field no longer describe the audited package.

Configure NWH input

Choose and configure an NWH input provider independently of the character’s Ultimate Character Controller input:

Use Input System Vehicle Input Provider for NWH’s Unity Input System route, or Input Manager Vehicle Input Provider for its legacy Input Manager route. Configure the NWH actions or axes and verify them on a vehicle before adding Ultimate Character Controller.
Leave the NWH Vehicle Controller’s Auto Set Input enabled when it should collect values from the active scene provider. Swap Input In R is enabled by default and swaps throttle and brake while reversing.
Disable Auto Set Input when AI or project code writes NWH vehicle input states directly.
If the Ultimate Character Controller character also uses Unity Input System, install and configure the Ultimate Character Controller Unity Input System integration separately. That integration controls the character and the Action used to start or stop Drive; it does not configure NWH’s vehicle action asset.

Use only one local provider for a single vehicle test. Multiple global providers can make it unclear which device is supplying NWH’s combined input.

Configure the NWH camera

Add Camera Changer below the vehicle root so it can find the parent Vehicle Controller.
Add the desired camera GameObjects below Camera Changer.
Leave Auto Find Cameras enabled to collect child cameras automatically, or disable it and populate Cameras manually.
Set Current Camera Index to the camera which should appear first.

NWH Drive Source finds the first Camera Changer below its GameObject. After entry, it disables the entire Ultimate Character Controller Camera Controller GameObject and enables the NWH Vehicle and Camera Changer. On exit, it disables the NWH camera GameObjects and re-enables the Ultimate Character Controller camera.

The stock source therefore requires an NWH camera for a visible driving view. If the project must keep an Ultimate Character Controller View Type while driving, create a project-specific IDriveSource which does not deactivate the Ultimate Character Controller camera; there is no Inspector toggle for that behavior.

Configure the character

Add Drive under Ultimate Character Locomotion > Abilities. The default Action input starts and stops the ability.
For animated entry, add Move Towards above Drive and add OnAnimatorEnteredVehicle and OnAnimatorExitedVehicle to every reachable entry and exit animation.
Enable Teleport Enter Exit when the character should move immediately between a Move Towards Location and Driver Location without those animation events.
Configure Object Detection, Detect Layers, and optional Object ID so Drive detects the vehicle collider.
Choose item behavior with the selected Drive ability’s General > Allow Equipped Items controls, Can Aim, and Disable Mesh Renderers. With the default empty allowed-slots mask, Drive blocks item abilities while seated. Use Item Equip Verifier when items should be unequipped before entry and restored afterward.
Follow the complete Drive ability workflow for entry clearance, exit clearance, collision handling, animation events, and vehicle-specific Animator IDs.

NWH owns the controls after entry. Ultimate Character Controller’s Drive ability still owns the seated character, entry and exit, item restrictions, collision ignores, and alignment with Driver Location.

How it runs

During Start, NWH Drive Source caches its GameObject, Transform, and active child colliders. It finds the NWH Vehicle and first child Camera Changer, then disables both sides of the NWH vehicle view.
Ultimate Character Controller Drive detects the source and approaches or teleports to a Move Towards Location. NWH remains disabled while the character enters.
When entry finishes, Ultimate Character Controller calls EnteredVehicle. The bridge remembers the character, enables NWH’s Vehicle component, disables the Ultimate Character Controller camera GameObject, and enables the NWH Camera Changer.
NWH’s active input provider supplies steering, throttle, brake, and other vehicle controls. Ultimate Character Controller keeps the character aligned with Driver Location and ignores the cached vehicle colliders.
When a valid exit begins, Ultimate Character Controller calls ExitVehicle. The bridge disables NWH’s Vehicle and cameras, returns the Ultimate Character Controller camera, and releases its character reference before the exit finishes.
Ultimate Character Controller completes the exit and restores the character’s collision, parenting, movement, and configured items.

Key choices and limitations

Choice	Use it when	Important consequence
Teleport Enter Exit	No enter or exit animations are available	Entry and exit are immediate, but a clear Move Towards Location is still required.
Animated entry and exit	The character should approach a door and play seated transitions	Animator events must call `OnAnimatorEnteredVehicle` and `OnAnimatorExitedVehicle` at the handoff points.
NWH Input System provider	The vehicle should use NWH’s action asset and supported devices	It remains separate from the Ultimate Character Controller character’s Input System integration.
NWH Input Manager provider	The vehicle should use NWH’s legacy named inputs	Those inputs are global and do not inherit Ultimate Character Controller player ownership.
Automatic NWH input	A local player provider should control the vehicle	Keep Auto Set Input enabled and avoid competing scene providers.
AI or custom input	Code should write the vehicle controls	Disable Auto Set Input and assign the NWH states from the owning system.
Stock camera handoff	NWH child cameras should control the driving view	The bridge deactivates the complete Ultimate Character Controller Camera Controller GameObject while occupied.

The stock bridge assumes one local driver. It contains no per-player device assignment, network ownership, vehicle-state replication, or save data. It also snapshots only colliders that are active below the source during Start.

A forced stop is another important boundary. Ultimate Character Controller restores its character-side Drive state when force-stopped, but NWH Drive Source performs its Vehicle and camera cleanup in the normal ExitVehicle callback. Death, destruction, scene changes, or custom code that interrupts Drive while seated should explicitly disable NWH vehicle control and restore the correct camera.

Verify in Play Mode

Enter Play Mode without entering the vehicle. The NWH Vehicle and every NWH vehicle camera should be disabled, while the Ultimate Character Controller gameplay camera remains active.
Approach the entry collider. Drive’s inherited Detected Object should show the intended vehicle.
Press the configured Action input. Confirm that the character reaches the expected Move Towards Location or teleports, then aligns with Driver Location.
During an entry animation, the vehicle should not accept driving input. It should enable only after the OnAnimatorEnteredVehicle event completes entry.
Confirm that the Ultimate Character Controller camera turns off and the camera at Current Camera Index turns on after entry. There should be one active Camera and one active Audio Listener.
Test steering, throttle, braking, reverse, and any configured camera-change input. Only the occupied vehicle should respond.
Press Action with a clear exit location. NWH control and cameras should turn off as exit begins; the Ultimate Character Controller camera and ordinary character movement should return.
Block one exit and retry. Drive should remain active until another Move Towards Location is clear.
Test death, a forced ability stop, scene loading, and vehicle destruction while seated. Confirm that project cleanup restores the camera and disables the NWH Vehicle in every supported interruption.
If the project supports saving or multiplayer, repeat the test after a save/load cycle and with every local or remote ownership role.

Saving and multiplayer

NWH Drive Source does not save the current driver, Vehicle enabled state, vehicle transform, powertrain, input owner, camera owner, or item state. Save those through the project’s vehicle and character save systems. A reliable baseline is to restore both character and vehicle unoccupied, unless the project deliberately reconstructs an occupied Drive session.

The bridge also sends no network messages. Ultimate Character Controller’s multiplayer Drive path expects the IDriveSource to notify remote players, while NWH’s optional multiplayer support manages its own Vehicle ownership and MultiplayerIsRemote behavior. A multiplayer project must coordinate those layers, assign input and cameras only to the local owner, replicate the vehicle through its chosen NWH networking package, and test entry and exit authority on every peer.

Troubleshooting

Symptom	Check	Fix
Unity reports missing NWH types after import	NWH may be absent, may not have compiled before the bridge, or may expose a later incompatible API	Install and compile NWH first, then import the current Ultimate Character Controller bridge. Compare its `Vehicle` and `CameraChanger` APIs before adapting the source.
The Console says NWH Drive Source requires a Vehicle	NWH Drive Source and NWH’s Vehicle Controller may be on different GameObjects	Put NWH Drive Source on the same vehicle root as the component derived from `NWH.Common.Vehicles.Vehicle`.
Drive never detects the vehicle	The collider layer may be excluded, the source may not be on a detected parent, or no Move Towards Location may be clear	Correct Detect Layers, keep the source in the detected hierarchy, and add a clear entry or exit location.
The character enters but the vehicle does not respond	NWH Vehicle may not have enabled, no NWH provider may be active, Auto Set Input may be off, or animated entry may still be waiting	Inspect the components after entry, add `OnAnimatorEnteredVehicle`, configure one NWH provider, and enable Auto Set Input for player control.
The Ultimate Character Controller Input System works but the vehicle does not	The character and vehicle use separate input integrations	Configure NWH’s Input System Vehicle Input Provider and its action asset in addition to Ultimate Character Controller’s Input System integration.
The vehicle responds before entry or another vehicle also responds	Another script may enable NWH Vehicle, or a global input provider may be supplying more than the intended vehicle	Give the bridge sole enabled-state ownership and use an explicit per-vehicle or per-player NWH input route.
The screen goes blank after entry	The bridge disables the Ultimate Character Controller Camera Controller GameObject but did not find a usable child Camera Changer and camera	Put Camera Changer and its camera GameObjects below the vehicle root and verify Current Camera Index before entry.
Two Cameras or Audio Listeners remain active	An extra scene camera may be outside the NWH Camera Changer list, or another system may reactivate it	Choose one camera owner and include or disable every vehicle camera deliberately.
Exit input does nothing	No Move Towards Location may be clear	Add another exit point or clear the overlap around its optional clearance collider.
Vehicle control or the NWH camera remains active after death or a forced stop	The normal `ExitVehicle` callback may have been bypassed	Add interruption cleanup that disables the NWH Vehicle and cameras and reactivates the correct Ultimate Character Controller camera.
The seated character collides with a collider added after startup	NWH Drive Source caches active child colliders only once in `Start`	Keep required colliders active below the source at startup or refresh the collider list in a custom source when the vehicle changes.

Developer reference

NWHDriveSource implements Ultimate Character Controller’s IDriveSource. Its Inspector exposes only Driver Location and Animator ID. It supplies the source GameObject, Transform, cached child colliders, and animation ID to Drive.

Its lifecycle callbacks divide the handoff as follows:

EnterVehicle(Drive) does nothing while the character approaches or animates into the vehicle.
EnteredVehicle(Drive) stores the character and enables the NWH Vehicle and camera handoff.
ExitVehicle(Drive) disables NWH, returns the Ultimate Character Controller camera, and clears the stored character when a valid exit begins.
ExitedVehicle(Drive) does nothing after Ultimate Character Controller finishes restoring the character.

At startup, the source uses GetComponent<Vehicle>(), GetComponentsInChildren<Collider>(), and GetComponentInChildren<CameraChanger>(). These calls explain the same-GameObject Vehicle requirement, the active startup collider snapshot, and the first-child Camera Changer behavior.

The bridge toggles Vehicle.enabled; it does not call NWH input APIs directly. NWH’s Auto Set Input gathers values from its active input providers, while a custom or AI integration can disable that option and write NWH’s vehicle input states itself. A custom source should preserve the same entry, normal exit, forced-stop, camera, input-owner, and remote-owner cleanup guarantees.