Troubleshooting & FAQ

Solutions for common configuration questions in Tidy Up! — Sorting & Shelving Simulator Toolkit.

❓ Common Issues & Solutions

1. Items fall through shelves or table surfaces

Cause: Discrete physics collision detection tunneling through thin geometry at high speeds.
Fix:

• On the item prefab's Rigidbody, set Collision Detection to Continuous or Continuous Dynamic.
• Ensure shelf boards have adequate collider depth. Avoid 2-sided zero-thickness planes; use Box Colliders with at least 0.05 units of thickness.

2. Items do not transition to sleep or keep micro-jittering

Cause: Velocity thresholds are set too low or physics materials have zero friction.
Fix:

• Select the item prefab and inspect PhysicsSleeper.
• Increase Linear Velocity Threshold (default 0.08) and Settling Linear Damping (default 3.0).
• Assign a PhysicMaterial with moderate static and dynamic friction (e.g. 0.6).

3. Level count stuck or shelf slot rejects item

Cause: Category mismatch between ItemDefinition and ShelfZone.
Fix:

• In the Inspector, verify that ItemDefinition.Category matches the ShelfZone.TargetCategory.
• Open Tools > Nipun Interactive > Tidy Up! - Sorting & Shelving Simulator Toolkit > Level Health & Auditor, click Scan Active Scene, and review the Category Balance matrix.

4. Scene balance warning: "Shelves cannot hold all items"

Cause: The number of spawned items for a category exceeds the number of generated ShelfSlot objects.
Fix:

• Open the Level Health & Auditor window.
• Click ✨ Auto-Fix All Issues to automatically instantiate the missing slots or balance the pile generator counts.

5. TextMeshPro text appears pink or missing

Cause: TMP Essential Resources or the Fredoka font asset have not been imported.
Fix:

• Open Window > TextMeshPro > Import TMP Essential Resources.
• Ensure the included Fredoka font asset under Assets/SortAndShelveToolkit/Art/Fonts/ is assigned in your UI TextMeshPro components.

💬 Frequently Asked Questions

How many demo scenes are included?

The framework includes 3 turnkey scenes:

1. MainMenuScene: Dynamic 3D living diorama with level select and settings modals.
2. ApothecaryDemoScene: Level 1 with 48 items across 4 categories and 180s par time.
3. WorkshopDemoScene: Level 2 with 60 items across 5 categories and 240s par time.

Can I create levels with hundreds of loose items?

Yes. Thanks to PhysicsSleeper, resting items transition to zero-cost kinematic state, enabling hundreds of items to exist simultaneously in piles or boxes with smooth 60+ FPS.

Can I customize the upgrade tree?

Yes. Upgrade definitions are ScriptableObjects (UpgradeDefinition) located under Assets/SortAndShelveToolkit/ScriptableObjects/Upgrades/. You can easily adjust costs, max tiers, and attribute multipliers in the Inspector.

Is full source code included?

Yes. 100% complete, un-obfuscated C# source code with clean namespaces and XML documentation is included.