debug-physics

name	debug-physics
description	Diagnose physics misbehaviour in the Genie Sim RT Engine — robot swings on spawn, contacts tunnel, joints drift past their limits, cloth blows up, the convex-hull proxy renders instead of the visual mesh, or the wrong physics backend is active. Walks the user through the engine's debug toggles (visualizers, marker array, GL viewer, `init_*` teleport, backend swap) and the common failure-mode fixes. Trigger: When the user reports "robot swings at start", "objects float / sink into the floor", "contact tunnelling", "joint went past limit", "robot vibrates / explodes", "shelf looks like a convex hull", "wrong gripper poses", "newton vs physx vs mjwarp difference", or asks to "debug the physics".
license	MPL-2.0
metadata	{"author":"genie-sim","version":"1.0"}
prerequisites	["geniesim_ros:launch-scene"]
inputs	[{"name":"symptom","desc":"Free-text description of the misbehaviour observed","required":true},{"name":"launcher_config","desc":"Current launcher (used for backend bisection)","required":false}]
outputs	[{"desc":"Identified failure mode (init, contact, render proxy, backend-specific) + targeted fix or workaround"}]

When to Use

• Visual / kinematic glitch on launch (swing, drift, float, sink).
• Contact behaviour wrong (tunnelling, no contact, no friction).
• Solver-specific symptoms — works on PhysX but not Newton, or vice versa.
• Render proxy showing instead of visual mesh (convex-hull look).
• Joint exceeds URDF <limit> and MoveIt rejects the start state.

Do not use for:

• Launch errors before physics even runs → check build-workspace skill output first.
• MoveIt planning failures with sane physics → that's moveit-wbc, in particular the fix_start_state + start_state_max_bounds_error knobs.
• Performance tuning (low FPS, JIT compile time) — different topic.

Critical Patterns

1. init_base_pose / init_joint_pos are non-physics teleport. The engine writes them to USD attributes before world.reset() on PhysX and to model.joint_q + control.joint_target_pos before the first solver tick on Newton — drive error is zero at t=0, so no startup swing. If you see a swing, your launcher / scene yaml is bypassing this path.
2. init_joint_pos is JSON-encoded, not a launch list. launch_ros mangles list-typed params; the engine reads init_joint_pos_json and decodes. Always edit it in scene yaml, not on the CLI.
3. The convex-hull look means the visual mesh was stripped. The engine blocks the physics:approximation token when collisionEnabled=False, so the GL viewer renders the visual mesh. If you still see the proxy, the USD set collisionEnabled=True with a convexDecomposition approximation and the visual mesh is missing.
4. Backend swap is one-arg. Whenever you suspect engine bugs, re-launch with the other launcher: launcher_ovrtx_isaac_physx (stable) vs launcher_newton_mjwarp (rigid, mujoco-warp). If only one backend reproduces, the issue is solver-side, not asset-side.
5. Use the GL viewer for ground truth. Newton-standalone + inline OVRtx can mask geometry issues with photoreal lighting. The Newton GL viewer renders raw visual + collision meshes, so it's the right tool for "is the asset actually there".