search

peter-kish / gloot

A universal inventory system for the Godot game engine.
MIT License
660 stars 28 forks source link
gdscript godot godot-engine godotengine inventory inventory-management inventory-management-system inventory-system plugin

readme

GLoot

A universal inventory system for the Godot game engine (version 4.2 and newer).

NOTE: The latest version of the plugin runs on Godot 4. The last Godot 3 compatible version is v2.1.4 and can be found on the godot_3 branch. (see Releases).

Table of Contents

  1. Features
    1. Item Prototypes
    2. Inventory Items
    3. Inventory Types
    4. Item Slots
    5. UI Controls
  2. Installation
  3. Usage
  4. Creating Item Prototypes
    1. Minimal Item Protoset JSON
    2. Item prototypes for a Stack Based Inventory
    3. Item prototypes for a Grid Based Inventory
    4. Additional Prototype Fields
    5. Using the Protoset Editor (WIP)
    6. Editing item properties
  5. Serialization
  6. The Documentation
  7. Examples

Features

Item Prototypes

Inventory Items

Inventory Types

Item Slots

UI Controls

User interfaces are usually unique for each project, but it often helps to have some basic UI elements ready for earlier development phases and testing. The following controls offer some basic interaction with the various inventory types.

Installation

  1. Create an addons directory inside your project directory.

  2. Get the plugin from the AssetLib or from GitHub

    • From the AssetLib: Open the AssetLib from the Godot editor and search for "GLoot". Click download and deselect everything except the addons directory when importing.

    • From GitHub: Run git clone https://github.com/peter-kish/gloot.git and copy the contents of the addons directory to your projects addons directory.
  3. Enable the plugin in Project Settings > Plugins.

Usage

  1. Create an ItemProtoset resource that will hold all the item prototypes used by the inventory. The resource has a single property json_data that holds all item prototype information in JSON format (see Creating Item Prototypes below).

  2. Create an inventory node in your scene. Set its capacity if needed (required for InventoryStacked and InventoryGrid) and set its item_protoset property (previously created).

  3. Add items to the inventory in one of the following ways:

    1. Add items using the custom control in the inspector:

    1. Add items by creating InventoryItem nodes as child nodes of the inventory node.

      NOTE: When an InventoryItem node is added to an inventory node, its protoset property is automatically set to be the same as the item_protoset property of the inventory node.

    2. Add items from code. Use create_and_add_item() to create and add items based on the given prototype ID:

      inventory.create_and_add_item("Item1")

  4. (Optional) Create item slots that will hold various items (for example the currently equipped weapon or armor).

  5. Create some UI controls to display the created inventory and its contents.

  6. Call add_item(), remove_item(), transfer_item() etc. from your scripts to move items around multiple inventory nodes. Refer to the documentation for more details about the available properties, methods and signals for each class.

Creating Item Prototypes

An item prototype is a set of item properties that all items based on that prototype will contain. Items based on a specific prototype can override these properties or add new properties that are not defined in the prototype.

Item protosets represent a number of item prototypes based on which future inventory items will be created. An item prototype is defined by its ID and its properties.

Minimal Item Protoset JSON

There are a few requirements each protoset JSON must fulfill:

Below is an example of a minimal item protoset JSON:

[
    {
        "id": "minimal_item"
    }
]

Item prototypes for a Stack Based Inventory

Prototypes of items contained in stack based inventories support the following additional properties:

Example:

[
    {
        "id": "stackable_item",
        "stack_size": 10
    },
    {
        "id": "heavy_item",
        "weight": 20.0
    },
    {
        "id": "very_heavy_item",
        "stack_size": 10,
        "weight": 20.0
    }
]

Item prototypes for a Grid Based Inventory

Prototypes of items contained in stack based inventories support the following additional properties:

Example:

[
    {
        "id": "1x1_knife",
        "width": 1,
        "height": 1
    },
    {
        "id": "1x3_spear",
        "width": 1,
        "height": 3
    },
    {
        "id": "2x2_bomb",
        "width": 2,
        "height": 2
    }
]

Additional Prototype Fields

Apart from the previously mentioned properties, item prototypes can hold all kinds of additional user-defined data. Properties like "name" or "description" are often used and can be easily added alongside the predefined properties.

Example:

[
    {
        "id": "knife_01",
        "weight": "2.0",
        "name": "Kitchen Knife",
        "description": "A knife intended to be used in food preparation."
    }
]

Any of the item properties can be accessed from code through the get_property() methods of the InventoryItem classes:

var item_name = item.get_property("name", "")
var item_description = item.get_property("description", "")

Using the Protoset Editor (WIP)

Protosets can also be edited with the GUI based protoset editor. It can be opened using "Edit Protoset" button in the inspector when a protoset resource is selected.

Editing item properties

Item properties defined in the ItemProtoset resource can be overridden for each individual item using the set_property() method and overridden property values can be cleared using the clear_property() method:

# Decrease the size of an item stack by 1
var stack_size: int = item.get_property("stack_size")
if stack_size > 0:
    item.set_property("stack_size", stack_size - 1)

Item properties can also be modified and overridden using the inspector when an InventoryItem is selected. Properties marked with green color represent overridden properties. Some properties are disabled for editing, as they are managed by the plugin itself (for example id and grid_position).

Serialization

All GLoot classes have a serialize() and a deserialize() method that can be used for serialization. The serialize() methods serializes the class into a dictionary, that can be further serialized into JSON, binary or some other format.

Example:

# Serialize the inventory into a JSON string
var inventory: Inventory = get_node("inventory")
var dict: Dictionary = inventory.serialize()
var json: String = JSON.stringify(dict)

The deserialize methods receive a dictionary as argument that has been previously generated with serialize() and apply the data to the current class instance.

Example:

# Deserialize the inventory from a JSON string
var inventory: Inventory = get_node("inventory")
var res: JSONParseResult = JSON.parse(json)
if res.error == OK:
    var dict = res.result
    inventory.deserialize(dict)

The Documentation

The docs can be found here.

Examples

Take a look at the examples directory for some example scenes: