Reference
Troubleshooting
Find your symptom or health check message and follow the fix. Most problems come from a missing reference, a non-humanoid model, or an input setup that does not match the package.
Health check messages#
The Setup Wizard's final step and the PlayerController Inspector both report these messages. Error blocks the wizard. Warning and Info do not.
| Message | Level | Fix |
|---|---|---|
Player root is null | Error | Set the player root in Step 1. |
Player Settings asset is missing. | Warning | Create or assign a PlayerSettings asset in Step 2. |
Input Actions asset is missing. | Warning | Assign FBInputActions in Step 2 (Search button). |
CharacterController is missing (required by PlayerLocomotion) | Error | Add it to the root, or run Step 4. |
Main Logic Hub (PlayerController) is missing, Input Reader (PlayerInputHandler) is missing, Walking Logic (PlayerLocomotion) is missing, Camera & Look Logic (PlayerCameraController) is missing, Animation Manager (PlayerAnimatorController) is missing, Hand Item Socket is missing, Item Switcher (Inventory) is missing | Error | Run Step 4 to add the component on the root. |
No Character Model (Animator) found | Error | Assign the model in Step 2. |
Character Model is not set to 'Humanoid' | Error | Set the model's Animation Type to Humanoid and click Apply. |
Animator Controller is missing. Assign Player.controller or another compatible controller. | Warning | Assign Player.controller from Assets/FBSystem/Project/Animations/ to the Animator. |
Head Look IK is missing from model, Hand Placement IK is missing from model, Body Stabilizer is missing from model | Error | Run Step 4 to add the components on the model. |
Foot IK is missing from model (optional, recommended), Finger grips (HandPoseController) are missing from model (optional, recommended) | Warning | Add PlayerFootPlanting and HandPoseController to the model, or ignore the warning. |
Check: 'IK Pass' must be enabled on your Animator Layer | Info | In the Animator window, open the layer settings and enable IK Pass. |
Camera Target (Eye Level) helper not found | Warning | Run Step 5. |
Item Container not found in hand hierarchy, ItemSwitcher: No ItemContainer found in children. | Warning | Run Step 5 to create the item container under the right hand. |
PlayerCameraController: CameraTarget is not assigned. | Error | Run Step 6 (Connect All Systems). |
Use Fix next to an issue or FIX ALL ISSUES in the PlayerController Inspector to apply automatic fixes where the validator offers one.
Problems and fixes#
| Symptom | Fix |
|---|---|
| The player does not move | Check that PlayerInputHandler has the FBInputActions asset and the action map is named Player. Check that Active Input Handling in Player Settings includes the Input System Package (or Both). Check that a CharacterController is on the root. If your code calls SetInputEnabled(false) or DisableAllControls(), call SetInputEnabled(true) or EnableAllControls() again. |
| The camera is inside the head, or the head is visible | Use the FPCutter variant of the character, and call SetFirstPerson() on its FPCutterController. Check that Head is in Hide In First Person. See FPCutter. |
| There is no camera view | PlayerCameraController looks for a Cinemachine camera in the scene when none is assigned. Add FBSystem_CameraRig, or a Cinemachine camera and a Cinemachine Brain on the Main Camera. |
| Look feels too fast or too slow | Change lookSensitivity (default 0.1) on PlayerCameraController. verticalLookLimit comes from the PlayerSettings asset when one is assigned, otherwise from the component. |
| Movement speeds do not match the Inspector | When a PlayerSettings asset is assigned, its values override the fields on the components, for example walk speed. Change the value in the asset. |
| An item does not equip | The item must be in the Items list of the container, and it needs an ItemHoldData. The container needs its hand socket. Step 6 connects it. |
| The item sits in the wrong place | Tune it with Tune Grip Mode or the Scene view handles, then save the result as an IK preset. See Tune an item in the scene. |
| Pickup does nothing | The world item's id must match an item in the container. The pickup's Interactable Layer must include the layer of the world item, which needs a collider. |
| Fingers bend the wrong way or not at all | The model must be Humanoid, with finger bones mapped in the avatar. Press Calibrate on HandPoseController, and check the finger muscle limits in the avatar configuration. |
| Feet slide or float | Check Ground Layers on PlayerFootPlanting. Make sure no other foot IK runs on the character. |
| The holster feels too slow or too fast | Adjust Holster Duration and Draw Duration on PlayerHandIK, or turn off Smooth Transitions on HandItemSocket. |
| Hands or the body look wrong after a model change | Run the Setup Wizard again from Step 3 so the bones are detected on the new rig. Use Transfer Configuration to keep your tuning. See Transfer Configuration. |
| Health or stamina does not change | PlayerVitals must be on the player root, next to PlayerLocomotion. ApplyDamage returns false for dead players and for amounts of zero or less. |
| Footstep sounds are missing | Add PlayerFootsteps to the root and assign Step Clips. It is not added by the wizard. |
| Foot settings reset after an update | Version 1.6 renamed the foot component. Note your values before you update, then re-enter them. See 1.6.0. |
| Compile errors after updating an add-on | Add-on packages from older versions do not compile against 1.6. Re-import the FishNet or PurrNet add-on after you update the base package. |
| Hidden parts are visible or magenta | The invisible material is missing or uses a different shader. Assign a material that uses FPCutter/InvisibleShadowCaster to Invisible Material. On GLES, WebGL or Android, update to 1.6. |
Binding Previous or Next does not switch items | No shipped script reads these actions. Item switching uses the keys directly in ItemSwitcher. |
Multiplayer spawn errors such as PrefabId 65535 | The player spawner must reference a prefab asset, not a scene object. See FishNet troubleshooting. |
Pink or magenta materials#
The project must use the Universal Render Pipeline. Set the pipeline asset in Project Settings › Graphics. Then re-import or convert the materials to a URP shader.
Still stuck?#
Email karakask2004@gmail.com. Include:
- Unity version and render pipeline.
- FBSystem version (1.6.0, as shown in
CHANGELOG.md) and the add-on version, if you use one. - The health check messages, and the Console errors with the full stack trace.
- What you tried and what happened.