Native Wheels, Suspension, Axles, and Hybrid ModelEngine Rigs

This is the page for the part of Vehicle MC that usually confuses people the most:

• native wheel rigs
• steering pivots
• suspension probes
• axle roll
• hybrid setups where ModelEngine drives the body and Vehicle MC still drives the wheels

The good news is that the system is more structured than it first looks. Once you treat the body, the wheel visuals, and the wheel behavior as separate layers, the file becomes much easier to reason about.

Important public note:

• the dirt bike is the planned free starting path
• the jeep, hybrid, tank-style, and helicopter rigs are the wider reference lane
• the advanced examples are still useful because they teach real patterns, even when they are not all in the default free pack

The three practical rig patterns

Vehicle MC already supports three strong public patterns:

1. full native rig with Vehicle MC parts and Vehicle MC wheels
2. full ModelEngine body with backend-driven states
3. hybrid rig where ModelEngine handles the body and Vehicle MC handles wheel behavior

Pattern three is the important one when you want rich body visuals but still want real steering, suspension, and axle control.

Which current example to open first

Use the current examples as pattern teachers:

• dirtbike_steering_parts_v2 for a bike-style front assembly that swings with steering input
• jeep_me_imc_native_test for a four-wheel native DISPLAY rig
• jeep_me_imc_hybrid_test for a ModelEngine body plus native wheels

Those three examples explain most of the rig decisions people struggle with.

Dirt bike: when pivot: ROOT is the right answer

The dirt bike front wheel is different from a normal car wheel:

parts:
  - id: handlebars
    steeringYaw:
      enabled: true
      maxDeg: 19.0
      smoothing: 0.35
      invert: true
      pivot: SELF
 
wheels:
  - partId: front_wheel
    pivotOffset: [0.048125, -2.1140625, 2.329196]
    radius: 0.32
    spinEnabled: true
    spinAxis: X
    steer:
      enabled: true
      invert: true
      maxDeg: 19.0
      smoothing: 0.35
      pivot: ROOT
      pivotOffset: [0.0, 0.2, 2.41]

Why:

• the handlebars are one visual steering cue
• the wheel needs to move with that steering column
• pivot: ROOT lets the front wheel swing around a steering pivot instead of only turning in place

That is the right pattern for:

• dirt bikes
• motorcycles
• scooters

It is usually the wrong pattern for a normal car or jeep wheel.

Native four-wheel jeep: when pivot: SELF is the right answer

The front-left wheel of jeep_me_imc_native_test is the clearer car-style reference:

- partId: front_left_wheel
  pivotOffset: [-2.281214, -1.896391, 3.022524]
  radius: 0.418
  spinEnabled: true
  spinAxis: X
  suspension:
    enabled: true
    travelUp: 0.40
    travelDown: 0.45
    probeDepth: 1.20
    everyTicks: 1
    smoothing: 0.35
  steer:
    enabled: true
    invert: true
    maxDeg: 25.0
    smoothing: 0.30
    pivot: SELF
    pivotOffset: [1.8, -1.896391, 3.022524]

This teaches the car-wheel rule:

• the wheel still needs pivotOffset for clean spin
• the steering visual mostly turns in place
• pivot: SELF is the stable choice for that

If you put a jeep front wheel on pivot: ROOT, it will often look like the wheel assembly is swinging too far instead of behaving like a real steering rack.

Rear axle roll is for linked heavy wheel pairs

The same jeep example also shows the rear axle pattern:

- partId: rear_axle
  pivotOffset: [0.076804, -1.900774, -2.349829]
  radius: 0.418
  spinEnabled: true
  spinAxis: X
  axle:
    enabled: true
    leftProbeOffset: [-2.353665, -1.900774, -2.349829]
    rightProbeOffset: [2.507272, -1.900774, -2.349829]
    maxRollDeg: 10.0
    smoothing: 0.35
    invertRoll: false

Use axle roll when:

• one visible axle part represents a left and right wheel pair
• the vehicle should visibly lean across uneven terrain
• a heavier vehicle needs that rear assembly feel

Do not add axle roll just because it exists. Use it when the vehicle actually has a shared axle concept.

Why hybrid rigs exist

ModelEngine is great for:

• large vehicle bodies
• clean animation states
• polished visual presentation

Vehicle MC native wheels are still useful for:

• steering angles
• pivot correction
• suspension travel
• axle roll
• wheel-specific tuning per side

That is why a hybrid rig often gives you the best result for cars, trucks, armored vehicles, and other premium body setups.

Minimal hybrid shape

A practical hybrid structure looks like this:

rig:
  backend: MODELENGINE
  modelEngine:
    modelId: "jeep_imc"
    applyPitchToRoot: true
    hideBaseEntity: true
    states:
      idle:
        animation: "idle"
      drive:
        animation: "drive"
      reverse:
        animation: "reverse"
      turn_left:
        animation: "turn_left"
        overlay: true
      turn_right:
        animation: "turn_right"
        overlay: true
  root:
    entity: ARMOR_STAND
    equipment:
      helmet: minecraft:diamond_hoe{Damage:4}
  wheels:
    - partId: front_left_wheel
      radius: 0.38
      spinEnabled: true
      spinAxis: X
      steer:
        enabled: true
        maxDeg: 25.0
        smoothing: 0.30
        pivot: SELF

How to read this:

• Vehicle MC still owns the physical vehicle
• ModelEngine handles the main body art and animation
• the wheel layer still has its own real behavior

partId connects the wheel logic to a real visual part

Each wheel entry points at a real part id:

wheels:
  - partId: front_left_wheel

That partId must match the part you want Vehicle MC to manipulate.

If the part id is wrong, the wheel logic may load but the visible wheel will not respond the way you expect.

pivotOffset fixes orbiting wheels

pivotOffset is one of the most important wheel fields in the whole plugin.

wheels:
  - partId: front_left_wheel
    pivotOffset: [-2.281214, -1.896391, 3.022524]

Use it when:

• the wheel spins around the wrong center
• the wheel looks like it is orbiting instead of rotating
• the exported wheel mesh does not line up with the actual wheel center

Public rule:

• if the wheel steers correctly but spins badly, check pivotOffset
• if the whole wheel rig looks offset, check the part offset and root offset too

steer.* handles the yaw behavior of the wheel

Front wheels usually need their own steering block:

steer:
  enabled: true
  invert: false
  maxDeg: 25.0
  smoothing: 0.30
  pivot: SELF

What these do:

• enabled turns steering on for that wheel
• invert fixes left and right direction when needed
• maxDeg sets how sharp the visible wheel can turn
• smoothing keeps the steering motion from looking jittery
• pivot: SELF keeps the wheel turning around itself instead of swinging in a big arc

For most modern car-style wheel setups, pivot: SELF is the expected choice.

Suspension is the visual travel layer

Suspension is a wheel-local behavior:

suspension:
  enabled: true
  travelUp: 0.40
  travelDown: 0.45
  probeDepth: 1.20
  everyTicks: 1
  smoothing: 0.35

How to interpret it:

• travelUp and travelDown set how far the wheel can visually compress or extend
• probeDepth decides how far the plugin checks for the ground
• everyTicks is the update rate
• smoothing controls how quickly the movement settles

Use modest values first. Oversized travel is one of the fastest ways to make a rig feel unstable.

Native DISPLAY rigs are still the cleanest place to debug wheels

If wheel behavior is badly wrong, testing the family with a native DISPLAY wheel setup is often the fastest way to isolate the issue.

Why:

• fewer moving parts than a full hybrid body
• easier to see whether the issue is pivot math, part offsets, or exported art
• easier to confirm if steering and suspension are correct before bringing ModelEngine back in

That is exactly why the current source includes test-style native wheel examples in vehicles.yml.

ModelEngine states should stay simple and readable

The canonical state vocabulary is already clear:

• idle
• drive
• reverse
• airborne
• turn_left
• turn_right

That is enough for most vehicles.

Keep state naming stable between the Vehicle MC config and the actual ModelEngine project. When the names drift apart, animation problems get much harder to debug.

The current source also includes dirtbike_me_tank7_test_v2, which is a good reminder that this ModelEngine lane is not only for cars. It is also the right place to test heavy or tank-like bodies before you start layering on custom turrets, combat interfaces, or more specialized animation routing.

Anchors and seats still matter in hybrid rigs

Hybrid rigs still use backend-agnostic support systems:

• seatEntities for mount behavior
• anchors for muzzle, smoke, exhaust, hose, and other attachment points

That means you can keep:

• the same seat layout
• the same exhaust anchor
• the same smoke anchor

even if you swap the body from native parts to a ModelEngine model.

Practical tuning order

1. Make the vehicle drive correctly first.
2. Confirm the root and seat positions.
3. Get one wheel spinning correctly.
4. Fix steering direction and pivotOffset.
5. Add suspension.
6. Add axle roll only if the vehicle actually needs it.
7. Bring in ModelEngine body states after the wheel behavior is already believable.

If you need the exact current reference families spelled out in more detail, continue into advanced Rig Examples: Dirt Bikes, Jeeps, Tanks, Helicopters, and Input-Driven Parts.

If the rig still looks wrong after that, continue into rig Debug Commands, Pivot Tools, and Live Diagnostics.

Related pages

• free Starter Dirt Bike Quick Start and Upgrade Path
• rig Backends, Display Parts, Wheels, and ModelEngine
• advanced Rig Examples: Dirt Bikes, Jeeps, Tanks, Helicopters, and Input-Driven Parts
• rig Debug Commands, Pivot Tools, and Live Diagnostics
• vehicle Bases, Controllers, Stats, Seats, and Hitboxes
• runtime Modules, Physics, and Safety
• surfaces, FX, and Terrain Response
• combat Components, Duck Shot Bridge, Projectiles, and Loadouts