Getting Started

Here we go!

What Does Vault Do For Me?

Vault provides editor tooling for building a database of any data and designing the content within it. It also provides a template for a Networked Inventory System and provides UI prefabs as a strong foundation for your game.

Any data is real! Think openly, you can store anything in the database. Character Attributes, Stats, Ability/Spell data (and methods/functions!) or Localization string groups! Not just Items!

What Am I Expected To Do?

You as a developer are expected to extend the DataEntity system and Inventory system to suit the needs of your game. For instance not all games have a context menu for the inventory and there is not one provided in the first release. You would be expected to add that if you wanted it. The database tool is quite abstract so you could actually use it for completely different things instead of traditional "items" - such as things like Character Attributes or perhaps data and methods for the Ability System. Take advantage of the generalization of the system!

Vault tries to stay as compartmentalized as possible and not add bloaty features that wouldn't be useful to the majority userbase or that would narrow the functionality potential down. This is inconvenient in rare cases since some users are expecting what they would consider 'common' features for this type of module but in reality aren't fundamental baseline features that are used in all games.

In the future you can expect to do less of this work since updates will add more and more optional components without changing the core system.

Getting Started With Vault Inventory

Vault Inventory is a pretty straightforward module with a simple integration API. The vast majority of the heavy lifting is already done for you and the code focuses on event based interactions to keep runtime expenses to a minimum.

The architecture was designed to keep in mind a variety of projects that may want different features and to avoid coding ourselves into a corner where we couldn't support different approaches and integrations. The example project is just one approach to the broad concept of Inventory management.

Most of the interaction with the Inventory system will be event based and very painless. Clients essentially do nothing except request the Server to do simple events with Slot Indexes and wait for a return with what the new slot looks like.

Here's the primary classes you want to be familiar with:

public partial class Inventory : NetworkBehaviour
public class ItemUiPlug : MonoBehaviour
public class InventoryUi : MonoBehaviour
public static class Vault

These are the backbones of the module.

Your characters and things with pockets are going to implement an Inventory class which is where the actual real-time data is stored and the inventory interactions are piped through.

Your UI spaces will use an InventoryUi class to handle displaying the current state of an Inventory that it's aimed at.

Your UI slots displaying item icons and handling navigation will be using the ItemUiPlug component to facilitate dragging, dropping, moving, splitting, discarding and otherwise potatoing with your Items inside the UI space.

Your powerhouse back-end is the Vault where all database items are stored. Check it out!

References to sprites, objects, numerical values, restrictions, descriptions, titles, and everything else you want to cram into your database are all in the Vault. If you need an Item you can linear search by name or direct fetch by index. Other search methods are planned in future releases.

So how do I put stuff in the Vault?

Fortunately you don't have to code your items in XML or create assets by hand, or work with an external SQL database, or pull data in from Google Sheets. While these are all legitimate ways to approach a game database of varying sizes, it's not the one we're doing here. Vault is targeting those who want a solution within Unity with no fuss.

What we have here is a ScriptableObject asset based approach. The Vault Dashboard is a space where you can design items and it will automatically create an asset of any vaild class via dropdown menu, automatically reference it in the database for runtime access and allow you to modify it with ease from within the Vault Dashboard. It is designed with UI Elements and custom property drawers will work fine.

The Vault Dashboard is accessible by pressing Ctrl+Shift+I or going to Tools > Cleverous > Vault Dashboard. From the Vault Dashboard you can create a new item of any class that derives from DataEntity and you can spawn any item in the world that derives from RootItem.

So how do I get stuff out of the Vault?

Easy! Here's what you need to know :

In the Editor space

There's a fancy dropdown attribute that you can put on fields to give you every asset of that type to choose from. Check it out!

You can place this nifty Dropdown on a field like this:

[AssetDropdown(typeof(SlotRestriction))]
public SlotRestriction[] Restrictions;

Now those fields are referencing actual ScriptableObject assets in your project files! That means that the field is simply a reference to an asset in the project - so you can do whatever you want with it at that point, editor or runtime. No weird wizardry going on here.

In the Runtime space

If it's at Runtime and you don't have a field reference to the item then you can search the database for the item you want.

RootItem source = (RootItem)Vault.Get(itemDbKey);
RootItem source = (RootItem)Vault.Db.Get(itemExactTitle); // [Obsolete] warning.

// you can cache the db key, if you're into that kind of thing.

int coolAxeDbKey = source.GetDbKey();

// or just get all of the things because why not

List<Weapon> everyWeaponInTheGame = Vault.GetAll<Weapon>();

If you need other ways to poke the Vault then you can easy make extension methods to scrub over the database.

So how does the UI stuff work then?

The UI consists of an InventoryUi component with a Grid and SlotRestriction information waiting for something to fire it's public static Action OnPlayerSpawn event in order to hook into that interface's Inventory component and display the current state of that Inventory on it's Grid.

To display that information, the InventoryUi component will fill it's Grid with a bunch of template prefab instances. The template prefab will have an ItemUiPlug component which facilitates dragging, dropping, moving, discarding and other functions for the item.

When a user interacts with the ItemUiPlug it will figure out what the action is and request that to be done over the network through the Inventory script. This will send a message to the Server, the server will say "hmm, can Slot X do that with Slot Y? If so, how?" then send an update to clients for any affected slot numbers after it takes action - if it can. The Clients have no control over the results.

There's lots of hooks available to integrate functionality, for example check out the provided component for handling sound in the example project:

        private void Start()
        {
            // hook into the UI's event for when a player is spawned
            InventoryUi.OnPlayerSpawn += SpawnHook;
        }

        protected virtual void SpawnHook(IUseInventory player)
        {
            Player = player;
            SoundPlayer = Player.MyTransform.GetComponent<AudioSource>();

            // Now let's subscribe to some events to get some actionable callbacks!
            ItemUiPlug.OnMoveItemBegin += OnLift;
            ItemUiPlug.OnMoveItemEnd += OnDrop;
            Player.Inventory.OnNewItemAdded += OnNewAdded;
        }

        protected virtual void OnLift(ItemUiPlug originSlot)
        {
            SoundPlayer.clip = ClipMoveBegin;
            SoundPlayer.Play();
        }

        protected virtual void OnDrop(ItemUiPlug destinationSlot)
        {
            SoundPlayer.clip = ClipMoveEnd;
            SoundPlayer.Play();
        }

        protected virtual void OnNewAdded(int slotId)
        {
            // We can easily check what kind of item it is and play unique sounds.
            // Or check item weight, and play heavier type sounds.
            // Or put specific sounds onto the Item itself and reference those directly instead of defining them here.

            if (Player.Inventory.Get(slotId).Source == CoinItem) SoundPlayer.clip = ClipCoin;
            else if (Player.Inventory.Get(slotId).Source.Rarity == RootItem.ItemRarity.Inconcievable) SoundPlayer.clip = ClipVictory;
            else SoundPlayer.clip = ClipPickup;

            SoundPlayer.Play();
        }

There's plenty of options for extension at this point and if you find that you've got a scenario where you think a new callback event would be useful then feel free to suggest it! We're happy to add new features and requests.

So how do I equip things and slay monsters?

The scope of Vault is to provide a functioning and stable Database to store DataEntity types, an API to access them, a Dashboard to design them, Editor tools to reference them and a UI system to support general inventory management of them at runtime - plus server authoritative network functionality.

The example project provides that and the rest is up to you. If you want armor to appear on your character, or you need weapons to do damage, or space monkeys to invade when a new player joins your game then write some new code or extend the existing code to support doing that! Vault will support you with editor tools and a strong back end.

Last updated