🎒 Unity Inventory System

🖼️ Introduction

This repository contains a Unity Inventory System designed for handling item storage, interactions (e.g., moving, swapping, merging items), and visualizing states efficiently in Unity-based projects. It includes core functionality, test modules, and the foundational structure for extending inventory systems in Unity.

📁 Project Structure

Here’s an overview of the project:

.
├── Core                 # Core logic, system operations, and data management
│   ├── Data             # Data models representing items and their states
│   │   ├── StoragePage.cs
│   │   ├── ItemInstance.cs
│   │   └── ItemDisplayState.cs
│   ├── Operations       # Core logic for handling inventory operations
│       ├── BaseOperation.cs
│       ├── MoveOperation.cs
│       ├── SwapOperation.cs
│       └── MergeOperation.cs
├── View                 # UI and visualization components (future expansion)
├── Test                 # Unit and integration tests (pending deeper inspection)
└── Definitions          # General definitions like enums and constants

⚙️ Features of the System

This inventory system offers essential features for Unity projects:

• Data Handling (Core/Data)

  • Represents individual items (ItemInstance.cs) with their data and states.
  • Manages storage pages (StoragePage.cs) for grouping items (e.g., inventory tabs, storage grids, etc.).
  • Handles display states (ItemDisplayState.cs) for visual representation.

• Inventory Operations (Core/Operations)

  • MoveOperation: Logic for moving items within the inventory or to/from storage.
  • SwapOperation: Handles swapping items between inventory slots or grids.
  • MergeOperation: Implements merging logic for items (e.g., stacking or combining).
  • BaseOperation: A shared foundation enabling easy extension by inheriting common behavior.

• Scalable Architecture

  • Abstraction-centric design ensures that developers can add new operations (drag-and-drop, split-stack, craft recipes, etc.) by extending the BaseOperation class.
  • Separation of concerns ensures that data handling and operations are decoupled from UI for clarity and flexibility.

• Test-Driven Development

  • Robust test coverage (in the Test folder) ensures core functionality like item state changes, movement, and swapping works as expected.

🏗️ Unity Setup Guide

Prerequisites

1. Unity Version: Ensure your Unity Editor build is compatible with .cs files in the repository.

2. Environment Requirements:

   • Tested on Unity (Specify version recommendation, e.g., 2023.X.X or higher).
   • Optional: .NET runtime version for advanced scripting.

3. IDE: Use JetBrains Rider, Visual Studio, or any Unity-compatible code editor.

Steps to Integrate

1. Open your Unity project and clone the repository directly into your Assets folder.

   cd <your-unity-project-path>/Assets
   git clone <repository-url>

1. Alternatively, manually copy the folder structure into your Assets/InventorySystem directory.

2. Configure Inventory Manager:

   • Create a new empty GameObject in your Unity scene.
   • Add a script/component (not explored yet; assume InventoryManager as placeholder name) to manage inventory actions and tie them to UI or gameplay events.

3. If testing is required, ensure the Unity Test Framework is enabled:

   • From Window → Package Manager, install or enable Test Framework.

Run tests via:

   Unity Test Runner

🧑‍💻 Why the Code is Designed This Way 🛠️

The design of this Unity inventory system follows best practices for maintainable systems:

Core > Data

1. StoragePage.cs

   • Abstraction of inventory "pages" or "containers", such as:

     • Backpack tabs
     • Storage chests
     • Hotbar groups

   • Ensures flexibility by supporting any container-based inventory system.

   • Maintains modularity to adapt to different types of inventories.

2. ItemInstance.cs

   • Represents individual items in the inventory.
   • Designed to store item metadata, including unique ID, display name, and possible item-specific properties (weights, rarity, stats, etc.).
   • Keeps data storage efficient, avoiding responsibility overlaps with UI code.

3. ItemDisplayState.cs

   • Designed to handle visual representations (selected, highlighted, cooldown overlays, etc.) easily.
   • By separating display logic from data, the system avoids tightly coupling UI changes with backend changes.
   • Enables designers and coders to collaborate seamlessly by interacting with clear states.

Core > Operations

1. BaseOperation.cs

   • A parent class with reusable logic common to all inventory-related operations. Adheres to the DRY Principle by reducing repeated code across specific operations (e.g., input checks, result validation).

2. MoveOperation.cs

   • Focused entirely on relocating items.
   • An intentional design, as moving is one of the most frequent actions in an inventory system.
   • Extensible for additional logic (e.g., if moving an item has weight or slot dependencies).

3. SwapOperation.cs

   • Simplifies swapping items between slots (or pages).
   • Follows Single Responsibility Principle, ensuring no code outside of this class performs swapping logic.

4. MergeOperation.cs

   • Handles complex behaviors like stacking or merging items (e.g., ores, resources).
   • Preserves extensibility for behaviors like rules-based merges (e.g., same item type, compatible modifiers).

🚀 Extending the System

Adding a New Operation

1. Create a new .cs file in Core/Operations/.
2. Inherit from BaseOperation.
3. Override required methods:

   public override void Execute(ItemInstance source, ItemInstance target) {
       // Define your operation logic here
   }

Supporting New Item Types

Simply extend the ItemInstance class or add new item properties to support traits or behaviors like durability, rarity, or stack limits.