Storage & Logistics

Overview

The Storage System is a foundation feature for handling items and cargo in a structured, predictable way. It aims to make object movement feel intentional and readable: the player (and later automated systems) can store, retrieve, and reposition objects while always seeing what is targeted, what is valid to move, and where the object will end up.

The system is designed around three pillars: clarity (strong visual feedback and consistent rules), stability (safe interactions with clean failure cases), and performance (no expensive per-frame work, minimal allocations, and scalable behavior as storage volume grows).

Related: Manual pickup/placement is typically driven by the Hand Module System.

Key features

• Readable targeting: clear indication of the currently targeted item and its state (movable / blocked / invalid).
• Placement preview: shows the intended landing slot/position (snap + constraints) before committing.
• Safe placement rules: validated placement prevents overlaps, unreliable stacking, and “mystery physics”.
• Consistent outcomes: the same input produces the same result (snap rules, boundaries, and constraints stay predictable).
• Feedback-first UX: clear success/failure reasons (blocked, out of bounds, occupied, invalid rotation, etc.).
• Automation-ready: robots/vehicles can call the same pickup/place rules and get the same validation results.

Interaction flow (high level)

1. Acquire target: detect a candidate object and confirm it is eligible for storage handling.
2. Preview placement: show where the object would land (snap, boundaries, orientation hints).
3. Validate: check collisions, occupancy, constraints, and any gameplay limits.
4. Commit: move/store the object and update internal state (occupancy, links, ownership, etc.).
5. Confirm: show success feedback (or a clear reason for failure).

Design notes

• Clarity over cleverness: the player should always understand what will happen before it happens.
• Stable rules: avoid “almost works” behavior; either it places cleanly or it fails cleanly.
• Performance discipline: do the heavy work on interaction events, not every frame.
• Single source of truth: one validation path for players, robots, and vehicles to prevent desync bugs.

Planned extensions

• Robotics integration: storage robots request the same pickup/place actions through a task layer.
• Vehicle cargo support: standardized cargo volumes and attachment rules for transport and logistics.
• More feedback layers: UI prompts, state icons, and faster at-a-glance readability.

Current status

In progress — core interactions are functional, polish & edge cases ongoing.

Changelog

• 2026-01-14 — Added initial wiki entry skeleton.
• 2026-01-17 — Added system overview, key features, and interaction flow.