🎯 ZionTPS

Troubleshooting

Work through the relevant checks below before changing multiple settings at once. Start with a clean scene, a generated player, and simple colliders.

Character Does Not Move

• Confirm the Unity Input System is enabled and the Input Actions asset is assigned.
• Confirm the generated player is active and has ground beneath it.
• Check that no other movement script is driving the same player root.
• Run Diagnostics and inspect the generated player references.

Input Works in the Editor but Not in a Build

• Confirm the Input System is enabled in Project Settings.
• Confirm every required action has an actual binding, not only an unassigned reference.
• Confirm the Player action map is enabled at runtime.
• Build and test from a clean scene using the generated player.

Character Floats, Sinks, or Grounds Poorly

• Check CharacterController height, radius, and centre.
• Confirm the visual model is correctly aligned under the player root.
• Check model scale and floor collider placement.
• Test on a simple flat Cube or plane collider before testing custom geometry.

Character Stays Crouched

This is expected while an overhead collider blocks standing. Move out from beneath the ceiling and release crouch again.

• Check the stand-clearance mask includes ceilings and cover.
• Check the player hierarchy is ignored by the stand-clearance test.
• Use colliders on low cover; visual meshes alone cannot block standing.

Crouch or Roll Repeats Unexpectedly

• Check that only one input path triggers crouch and roll.
• Remove duplicate input components or custom scripts calling the same state change.
• Confirm the project uses the current 1.2 movement scripts together rather than a mixture of older and newer versions.

Camera Does Not Follow or Orbit

• Confirm Follow Target, Yaw Pivot, Pitch Pivot, Camera Transform, and Camera Component are assigned.
• Confirm the Camera Rig is active and there is no second camera controller taking control.
• Confirm Look action references are assigned and the action map is enabled.

Camera Profiles Do Not Appear to Change

• Confirm Default, Combat, and Aim profile assets are assigned to the Camera Rig Runtime Profiles section.
• Confirm the input action is bound and assigned to ThirdPersonInput.
• Make the profiles visibly different in distance, FOV, or shoulder X offset before judging switching.
• Do not test by changing the Camera Rig's inspector display field during Play Mode; call a profile action or use the runtime API.

Camera Framing Is Too High or the Player Leaves the View

• Keep CameraTarget at the desired upper-body height.
• Set Pivot Offset Y to 0 for standard profiles.
• Use Pivot Offset X for shoulder framing instead of moving the profile upward.
• Reduce maximum pitch while testing walls, ramps, and crouch cover.
• Make sure level walls, ceilings, and tunnels have colliders included in the camera Collision Mask.

Foot IK Looks Wrong

• Verify IK Pass is enabled on the Animator Controller layer.
• Reduce aggressive IK settings and test on simple collision geometry.
• Check stair and ramp colliders for uneven or overly thin geometry.
• Disable Foot IK for a character if its source animation produces worse results than the original animation.

Console Warnings or Errors

Always investigate recurring Console warnings before release. Typical causes include missing references, duplicate generated objects, invalid Avatar setup, old generated assets still referenced by a scene, or a mixture of scripts from different ZionTPS versions.

Systematic Debug Order

1. Create a clean test scene.
2. Use a newly generated ZionTPS player.
3. Use a simple humanoid model and flat floor.
4. Test Move, Look, Jump, Sprint, Crouch, Roll, and Camera Recenter.
5. Test camera collision against a wall and low cover.
6. Reintroduce custom character, input, combat, UI, or module code one system at a time.