How to ...

Table of Contents

• About
• Storages Database
  • Access database
  • Create a clear database
  • Create a storage at database
  • Delete a storage from database
  • Save database
• Storages Service
  • Rent Storage entity
  • Release Storage entity
  • Auto load storages on a scene
• Transaction Service
  • Add items to exists storage
  • Remove items from exists storage
  • Transfer between storages
    • Instant transfer
    • Manual transfer
  • Find orders

About

Following subject attempts to clarify best practices of work with the module's features.
The subject skips details of services work process. You may find detailed information by reading of following subjects.

• Storages Database
• Storages Service
• Trasaction Service

You also may find useful exploration of demo scenes shared with the package.

• Demo: Shops inspector
• Demo: Storages Inspector

---

Storages Database

Access database

StoragesDatabase works as a singleton instance that can be accessed by following call:

var db = Doloro.InvetorySystem.StoragesDatabase.Active;

Database is never null.

Create a clear database

To clear the database enough to call Clear() handler by following template:

Doloro.InvetorySystem.StoragesDatabase.Active.Clear();

Database clearance supposed to release entire related on-scene instances in case they object managed by the database or services. Be sure to include any custom objects into Dispose handlers where are supported or release they in OnDestroy callbacks.

Create a storage at database

To create a new storage entry, you have to follow the next template:

usign Doloro.InvetorySystem;
 
// Defining items that should be applied to the container.
StoragesDatabase.ItemContainer[] items = ...
 
// Creating a new container inside the database.
Guid storageID = StoragesDatabase.Active.CreateStorage(items)

During creation we're receiving an ID provided by the database to a new storage.
Using this ID, you may access the container lately.

You also may create a new storage directly from a scene using StorageCaller component.
Read more about: Auto load storages on a scene.

Delete a storage from database

To delete a storage at database you need to know its id.

StoragesDatabase.Active.DestroyStorage(STORAGE_ID).

Save database

The data base is serializable object and can be easily saved by using of the Serialization Tools features.

Following example shows the way to save database to file system at the application's folder.

using UnityEngine;
using Doloro.DataManagement.Serialization;
 
// Defining destination full path to a file
// that will contain serialized database.
// The file will be created \ overridden depending from its existence state.
string path = Application.dataPath + "\\" + FILE_NAME + "." + FILE_EXTENSION;
 
// Calling serialization of the database to the file.
BinarySerializationTool.Serialize(StoragesDatabase.Active, path);

The next example demonstrates a conversion to binary data that can be used lately as you need.

using UnityEngine;
using Doloro.DataManagement.Serialization;
 
// Binary array tha will contain serialized database.
byte[] binaryData;
 
// Calling serialization.
BinarySerializationTool.Serialize(StoragesDatabase.Active, out binaryData);

Save database

The data base is serializable object and can be easily load by using of the Serialization Tools features.

To load database, you have to provide binary data \ binary file.

using UnityEngine;
using Doloro.DataManagement.Serialization;
 
// Defining path in file system to a binary database representaion.
string FILE_PATH = ...
 
// Loading the instnace using DDM module features.
var db = BinarySerializationTool.Deserialize<StoragesDatabase>(FILE_PATH);
 
// Applying database instance as active.
StoragesDatabase.Active = db;

Alternatively, you may load database from binary array other than file system.

// Getting previously serialized data in binary view.
byte[] BINARY_DATA = ...
 
// Reading data as the database.
var db = BinarySerializationTool.Deserialize<StoragesDatabase>(BINARY_DATA);
 
// Applying database instance as active.
StoragesDatabase.Active = db;

---

Storages Service

Rent Storage entity

To operate a StorageDatabase.StorageContainer you have to call an Storage instance bond with the database entry.

There are several ways to rent an entity but the traditional one is to ask for entity with the Storage.id provided by the StoragesDatabase during storage registration.

using Doloro.InvetorySystem;

Renting by storage ID:

Guid storageId = YOUR_ID;
var storageEntity = StoragesService.RentStorageEntity(storageId);

Renting by database entry:

// Getting target container.
StoragesDatabase.StorageContainer data = ...
 
var storageEntity = StoragesService.RentStorageEntity(data);
// OR literally the same
var storageEntity = data.RentStorageEntity();

Both the Storage is disposable object so you may access it with using keyword.

using (StoragesService.RentStorageEntity(STORAGE_ID))
{
    // Do something with the storage.
}
// Rented entity has been automatically released
// along with entire loaded resources.
// Changes will be automatically saved to the database.

Release Storage entity

When you are done with entity access, and it's not required anymore you have to release it with the same source as it was rented.

using Doloro.InvetorySystem;

Release by ID:

Guid storageId = YOUR_ID;
StoragesService.ReleaseRentedEntity(storageId);

Release by on-scene entity:

// Getting rented entity reference
Storage rentedEntity = ...
 
StoragesService.ReleaseRentedEntity(rentedEntity);
// OR literally the same
rentedEntity.ReleaseRentedEntity();

Release by data sources:

// Getting target container.
StoragesDatabase.StorageContainer data = ...
 
StoragesService.ReleaseRentedEntity(data);
// OR literally the same
data.ReleaseRentedEntity();

Both the Storage and StorageContainer is disposable objects so you may access them with using keyword.

using (StoragesService.RentStorageEntity(STORAGE_ID))
{
    // Do something with the storage.
}
// Rented entity has been automatically released
// along with entire loaded resources.
// Changes will be automatically saved to the database.

You also may access directly a database entry without loading related Storage resource entity with it.

using (var storage = StoragesDatabase.Active[STORAGE_ID])
{
    // Doing something with items.
 
    // Getting an item by its signature.
    StoragesDatabase.ItemContainer itemData = storage.Find(BUNDLE, KEY);
 
    // Calling item entity if needed.
    // It will be disposed along with the storage container
    // automatically.
    var entity = itemData.Resource;
 
    // Doing something with the `Item` instance bond with the container.
 
    // Applying container changes.
    // Comparing to use of `Storage` in this case it must be
    // called manually.
    itemData.SaveSessionData();
}
// Entire called entity resources has been released automatically.

Auto load storages on a scene

You may force call of Storage entity on a scene using StorageCaller component on any object at the scene, avoiding manual API calls.

The component allows both:

1. Load existing storage database entry to a scene.
2. Create a new entry at the database along with parameters defined over the StorageCaller component.

In case of creating a new entry at the database reads entire AStorageFetuare components data and sets they to the entry. That allows you to fully configurate the Storage at a scene it must be located avoiding manual code declaration.

Read more: Features and provided In-box implementations.
Explore API: Doloro.InvetorySystem.StorageCaller

---

Transaction Service

The system no allows manual modification of the storage that allows to prevent frequent bugs with items. All the transactions with storages managed with the Trasaction Service via orders.

Add items to exists storage

To add items to a storage you need to know a destination storage ID or has reference to its data container or rented entity.

Then you need to call TransactionService API member named as ExecuteAddOrder most suitable from your arguments. As example:

Doloro.InvetorySystem.TransactionService.ExecuteAddOrder(
    // Id of storage that will attempt to receive the items.
    STORAGE_ID,
    // Item resource that will be added.
    ITEM,           
    // Count of items to add.
    COUNT               
    );

The add order may fail transaction and return false in case the storage has mask features that not allows item or its amount to be added.

Remove items from exists storage

To remove items from a storage you have to know target storage ID or has reference to its data container, or rented entity.

Then you need to call TransactionService API member named as ExecuteRemoveOrder most suitable from your arguments. As example:

Doloro.InvetorySystem.TransactionService.ExecuteRemoveOrder(
    // Id of storage to operate
    STORAGE_ID, 
    // Item resource that will be removed.
    ITEM,           
    // Count of items to remove.
    COUNT               
    );

The remove order will be failed and return false in case the resource not found in the storage, or it has no enough amount.

Transfer between storages

To transfer some items from one storage to other you have to execute TransactionOrder between them.

For this you have a 2 ways: Instant, Manual.

Instant transfer

To execute a transfer order between two storages instantly you enough to call one of TransactionService API members named as InstantTransactionOrder with most suitable arguments. As example:

Doloro.InvetorySystem.TransactionService.InstantTransactionOrder(
    // Id of storage selected as source of items.
    FROM_STORAGE_ID,    
    // Id of storage selected as transfer destination.
    TO_STORAGE_ID,      
    // Item resource that will be transferred.
    ITEM,                       
    // Count of items to transfer.
    COUNT                           
    );

Transaction may fail and return false in case the storage has mask features that do not allow item or its amount to be added to destination storage.

Manual transfer

For some systems you may need to place a transaction that will make an items \ space reservation at storages but not execute it instantly leaving an opportunity to cancel the transaction.

For such operations you have to use TransactionService API members named as PlaceTransactionOrder.
Such a handler makes reservation of items. Also it can call reservation process at AStorageFeature components related to a storage with IReservationAgent interface.
Read more: Reservation Agent

using Doloro.InvetorySystem;
 
// Variable that will hold Id of placed order.
Guid orderID;
 
// Placing a transaction order.
orderID = TransactionService.PlaceTransactionOrder(
    // Id of storage selected as source of items.
    FROM_STORAGE_ID,
    // Id of storage selected as transfer destination.
    TO_STORAGE_ID,      
    // Item resource that will be transferred.
    ITEM,                       
    // Count of items to transfer.
    COUNT                           
    );

Next you may confirm or cancel the order via the TransactionService by calling of ConfirmTransactionOrder or CancelTransactionOrder member.

To confirm:

Doloro.InvetorySystem.TransactionService.ConfirmTransactionOrder(orderID);

To cancel:

Doloro.InvetorySystem.TransactionService.CancelTransactionOrder(orderID);

Find orders

You may find entire orders place for a storage or orders placed between 2 storages using TrasactionService API members names as FindOrders.

// Looking orders placed to a certain storage.
Guid[] orders = FindOrders(TARGET_STORAGE);
 
// Handling related orders.
foreach (Guid id in TARGET_STORAGE)
{
    // Getting order by its ID.
  TransactionOrder order = GetOrder(id);
 
    // Doing something with it here`
}

The API also allows you to filter order to discard from selection some not passing a condition.

Following example demonstrates a case when you are selecting only orders with a certain service code applied to the order during its place process.

var orders = TransactionService.FindOrders(
            STORAGE1.id,
            STORAGE2.id,
            OrderFilter);
 
// Condition filter that pass only with a certain service code.
private bool OrderFilter(TransactionService.TransactionOrder order) =>
    order.code.Equals(TRANSACTIONS_SEVICE_CODE);