Rig Debug Commands, Pivot Tools, and Live Diagnostics

When a Vehicle MC rig looks wrong, you need to figure out which layer is actually broken:

• the vehicle controller
• the visual rig math
• the ModelEngine state layer
• the hitbox or interaction layer

This page is the public debug workflow for that.

The first three debug questions

Before changing values at random, ask:

1. Is the vehicle driving wrong, or only looking wrong?
2. Is the problem in one part, one wheel, or the whole rig?
3. Is the problem happening in native DISPLAY logic, ModelEngine logic, or both?

That simple split saves a lot of wasted edits.

/vehicle debug command lane

The source already exposes a useful runtime debug command surface:

/vehicle debug
/vehicle debug on
/vehicle debug off
/vehicle debug toggle
/vehicle debug status
/vehicle debug reset
/vehicle debug state <key|clear>
/vehicle debug play <animationId> [lerpinticks] [lerpoutticks] [speed] [force]
/vehicle debug stop <animationId>
/vehicle debug stopall

What these are for:

• /vehicle debug shows the target vehicle info and backend state
• on|off|toggle|status|reset controls runtime diagnostics without making a permanent config edit
• state <key|clear> is useful for testing ModelEngine state routing
• play, stop, and stopall are useful for raw animation testing on a ModelEngine-backed rig

This is especially helpful when a hybrid or ModelEngine rig is selecting the wrong animation state.

Config-side debug toggles

Vehicle MC also exposes config-side diagnostics:

debug:
  enabled: false
  hitboxParticles:
    enabled: false
    everyTicks: 2
  rigTransforms:
    enabled: false
    everyTicks: 20
  logLevel: INFO
 
modelengine:
  rotationSync:
    enabled: false
    smoothingTicks: 0
    debug: false

How to use them:

• debug.enabled turns on the broad runtime debug lane
• hitboxParticles.enabled is for seeing collision boxes and impact math in the world
• rigTransforms.enabled is for logging part-level transform math when wheels or parts are drifting
• modelengine.rotationSync.debug helps when the ModelEngine body is not following Vehicle MC pose the way you expect

Do not leave these on permanently in production unless you actively need them.

When to use rigTransforms

Turn on debug.rigTransforms.enabled when:

• a wheel appears to orbit instead of spin
• the steering angle looks correct but the wheel translation is wrong
• a hybrid ModelEngine body is fine, but the native wheel layer is drifting
• a rotor or animated part is snapping to the wrong place

This is the right tool when the problem is transform math, not gameplay balance.

Hitbox particles are for collision questions, not art questions

Turn on debug.hitboxParticles.enabled when:

• players are colliding too early or too late
• a vehicle feels wider or taller than it looks
• impacts make no sense compared to the visible model

Leave it off when the issue is only visual alignment. Hitbox particles do not solve wheel-pivot problems.

Wheel pivots: use the included pivot calculator

Vehicle MC's source docs already point at a wheel helper tool:

docs/wheel_tools/vmc_pivotcalc.py

Use that when:

• a wheel spins around an invisible point
• a wheel or axle was exported off-center from Blockbench
• you need a starting pivotOffset instead of guessing by hand

The source docs describe the intended workflow:

1. export the wheel or axle model JSON
2. run the pivot calculator against that model
3. copy the suggested pivotOffsetVehicleMC into rig.wheels[item].pivotOffset
4. if it is an axle model, also use the suggested left and right probe offsets for wheels[item].axle

That is the cleanest starting point for native wheels.

When the right pivot mode is the real problem

Sometimes the wheel math is fine and the wrong pivot mode is the actual issue:

• use pivot: SELF when the wheel should turn in place like a normal car wheel
• use pivot: ROOT when the wheel should orbit around a steering-column point, like a bike front assembly

If a car wheel is swinging like a motorcycle fork, the pivot mode is likely wrong.
If a motorcycle front wheel is staying flat in place while the handlebars swing away from it, the pivot mode is likely wrong.

ModelEngine state debugging

Use the ModelEngine debug commands when:

• the vehicle is choosing the wrong animation state
• the body should be in drive, reverse, or turn_left but remains idle
• you need to test an animation directly before tuning the automatic state logic

A practical sequence:

1. confirm the rig backend really is MODELENGINE
2. use /vehicle debug to inspect backend state
3. force a state with /vehicle debug state <key>
4. if needed, test a raw animation with /vehicle debug play <animationId>

That tells you whether the problem is the animation file, the state name, or the route into the state machine.

Good live-debug order

1. Confirm the controller and base movement feel correct.
2. Confirm the rig backend is the one you intended.
3. Fix obvious root offset mistakes.
4. Fix wheel pivotOffset and pivot mode problems.
5. Add suspension and axle roll after the core wheel motion works.
6. Only then debug ModelEngine state routing or premium body polish.

That order prevents you from debugging animation layers before the vehicle itself is even behaving correctly.

Related pages

• rig Backends, Display Parts, Wheels, and ModelEngine
• native Wheels, Suspension, Axles, and Hybrid ModelEngine Rigs
• advanced Rig Examples: Dirt Bikes, Jeeps, Tanks, Helicopters, and Input-Driven Parts