Core Concepts & Architecture

Understand the underlying systems that power Tidy Up! — Sorting & Shelving Simulator Toolkit.

The 5-Header Scene Standard

Every level in Tidy Up! strictly adheres to the 5-header organizational standard:

Scene Hierarchy
├── --- ENVIRONMENT ---  (Walls, floors, architectural geometry)
├── --- LIGHTING ---     (Directional light, point lights, reflection probes)
├── --- GAMEPLAY ---     (Player rig, shelves, delivery boxes, pile spawners)
├── --- MANAGERS ---     (CompletionTracker, Currency, Upgrades, SaveManager)
└── --- UI ---           (HUDView, ShopMenuView, SettingsMenuView, Modals)

1. Data-Driven Definitions

All gameplay elements are driven by ScriptableObjects created via Create > Tidy Up! - Sorting & Shelving:

• CategoryDefinition: Groups items (e.g. Potions, Gems, Tools, Artifacts). Defines unique ID, display name, theme color tint, UI icon, and optional custom placement audio clip.
• ItemDefinition: Configures an item archetype: visual 3D prefab, category assignment, base currency reward, base score reward, hold scale modifier, hold position offset, and placed rotation offsets.
• UpgradeDefinition: Defines tiered progression in the shop: Carry Capacity, Walk Speed, Interact Reach, and Item Highlighting.

2. Automatic Physics Sleeper (PhysicsSleeper)

In physics-heavy sorting games, loose props rolling or resting in piles can cause severe PhysX CPU bottlenecks.

The PhysicsSleeper component solves this:

• Monitors linear and angular velocity against settling thresholds.
• When an item remains still for timeUntilSleep (default 0.6s), it transitions the Rigidbody to kinematic sleep.
• Kinematic rigidbodies consume 0 PhysX CPU cycles, allowing scenes with hundreds of items to run smoothly at 60+ FPS.
• Includes neighbor wake-up radius: touching or nudging one sleeping item immediately awakens adjacent items.

3. Shelving & Snapping Pipeline

The shelving framework is split into three coordinated components:

• ShelfZone: High-level classification zone assigned to a piece of furniture. Holds a reference to a CategoryDefinition and tracks total capacity vs current occupants.
• ProceduralShelf: Editor utility that automatically calculates slot positions and instantiates a grid of ShelfSlot objects across rows and columns.
• ShelfSlot: Individual placement point. Validates whether an item matches the zone category via CanAcceptItem, smoothly positions the item at its snap offset, and triggers PlacementJuice (spring bounce, particle puff, and placement sound).

4. Carry System & Player Mechanics

The player rig uses physics-smoothed interaction:

• FirstPersonController: Smooth walk, sprint, jump, and head bob.
• CarrySystem: Holds items in front of the camera using a smoothed spring anchor. Players can adjust carry distance using the mouse scroll wheel, or throw items with impulse velocity.
• InteractionController: Continuous raycasting detects grabbable items and shelf slots, displaying reticle hover indicators and category theme colors.

5. Single Source of Truth (CompletionTracker)

Level progression is managed centrally by CompletionTracker:

• Listens to global placement and removal events.
• Tracks TotalItemsToPlace, ItemsPlaced, and ItemsRemaining.
• Evaluates level elapsed time against Par Time targets to award 1, 2, or 3 stars on victory.