# GLoot: item prototypes, prototrees and inventory constraints for Godot 4.4

> GLoot is an MIT-licensed inventory plugin for the Godot engine that separates item data from item behaviour through JSON prototype trees, applies capacity rules as child nodes, and ships ready-made UI controls for early prototyping. The 3.0 line is not backwards compatible with 2.x, so upgrade planning is part of adopting it.

**peter-kish/gloot** — A universal inventory system for the Godot game engine.

- Repository: https://github.com/peter-kish/gloot
- Stars: 986 · Forks: 46
- Language: GDScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/peter-kish-gloot

## What problem GLoot solves in a Godot project

GLoot is a universal inventory system for the Godot game engine, and it targets version 4.4 and newer. The problem it addresses is the one every game project hits eventually: how items are defined, how stacks behave, what limits how much a player can carry, and how that logic should be separated from the code that consumes items.

The design answer is to make item data declarative. The InventoryItem class represents an item stack, and every stack has a default stack size and maximum stack size of 1. Everything beyond that comes from item prototypes, so an item's properties live in data rather than in a class hierarchy of one script per item type.

The audience is Godot developers who want a working inventory early enough in a project to design around, without writing the storage layer themselves. The documentation is explicit that user interfaces are usually unique per project, and that GLoot's UI controls exist to have something usable during early development phases and for testing, not to be the final HUD.

The scope is worth stating plainly: this is inventory storage with capacity constraints. Nothing in the documentation describes equipment rules, item effects, crafting, or durability. GLoot gives you slots, stacks and limits, and what you do with the contents of those slots is your code.

## Prototrees: JSON prototypes that inherit and override

Prototypes define common properties for inventory items, and items based on a prototype share those properties. An item may override some of them or define new ones that are not present on the prototype at all. Prototypes can inherit other prototypes, forming a tree-like structure called a Prototree.

That tree is stored as JSON, as a JSON resource. The practical effect is that your entire item catalogue is one data file you can diff, review and edit outside the editor, and a prototype is identified by its path in that tree. A prototype tree needs a minimum structure to be recognised, and the documentation covers the minimal prototree plus the specific properties stack_size and max_stack_size, and then the grid and weight constraint properties.

Inheritance is the part that pays off at scale. Rather than duplicating a shared block of properties on dozens of prototypes, a weapon prototype can inherit from a generic item prototype and override only what differs, and a project-specific prototype can add properties that do not exist anywhere else in the tree.

The cost is that a prototype path becomes a load-bearing string in your project data. If a node is renamed in the tree, every reference to that path has to move with it, and the documentation does not describe a rename or migration helper for the JSON resource.

## Constraints attached as child nodes, not configuration flags

Capacity is modelled by three constraint classes, and the mechanism is structural rather than a setting: each constraint is added as a child node of the Inventory node.

GridConstraint limits the inventory to a 2d grid of a given width and height. WeightConstraint limits the inventory to a given weight capacity, where the default unit weight of an item is 1. ItemCountConstraint limits the inventory to a given item count. Several can be combined on one inventory, which is how a bag with both a slot count and a weight budget is expressed.

The child node arrangement has an obvious upside. A constraint becomes a visible part of the scene tree, so it is obvious which rules apply to which inventory, and swapping a rule means attaching a different node. It also means the Inventory node itself stays free of a growing set of toggles.

The limitation is real though. Constraints are structural, so an inventory that needs a rule the three classes do not express, such as a per-item-type capacity or a rule that depends on game state, cannot be covered by configuration alone and needs custom code. Each constraint has its own documentation file under docs/, which is where the exact properties and signals live.

## Installing the plugin from AssetLib or from GitHub

Installation is a short manual procedure rather than a package manager command. The documentation asks you to create an addons directory inside your project directory, get the plugin from the AssetLib or from GitHub, and then enable the plugin in Project Settings > Plugins.

From the AssetLib, the route is to open the AssetLib from the Godot editor, search for GLoot, click download, and deselect everything except the addons directory when importing. That last step matters: importing the whole archive puts project files where the addon does not belong.

From GitHub, the plugin is cloned and the contents of the addons directory are copied into your project's addons directory:

```bash
git clone https://github.com/peter-kish/gloot.git
```

From there, copying the contents of the addons directory into the project is the remaining step, and then enabling the plugin in Project Settings > Plugins is what registers it with the editor.

There is no build step or package install in the traditional sense, since the plugin is GDScript that ships ready to use. The repository root contains a project.godot file and a tests directory, so the project itself is openable in the editor, and there are helper scripts at the root, generate_docs.py and xml_to_md.py, that are used to produce the documentation.

## First use: a prototree, an Inventory node and a call to add an item

The documented usage order is short. First create a JSON resource holding all the item prototypes used by the inventory. Then create an Inventory node in your scene and point its prototree_json property at that resource. Then, optionally, add constraints as child nodes of the inventory node. Items can be added from the inspector, or from code.

The code path creates an item and adds it in one step, based on a prototype path:

```gdscript
inventory.create_and_add_item("melee_weapons/knife")
```

The path argument is a prototype path inside the prototree, which is why the tree structure matters: the folder-like prefix in that example is part of the data, not a filesystem location.

After that, the sequence continues with optional item slots for things like the currently equipped weapon or armor, UI controls to display the inventory and its contents, and then calls to add_item() and remove_item() from your scripts to manipulate inventory nodes.

The documentation points to the docs directory for the available properties, methods and signals of each class, which is where the real API detail lives. The README is a summary, and the per-class documents are the reference.

## UI controls built for early phases rather than for shipping

GLoot ships four controls, and their stated purpose is to save time during earlier development phases and for testing.

CtrlInventory is a control node for displaying inventories as an ItemList. CtrlInventoryCapacity displays inventory capacity as a progress bar, which is the case where a WeightConstraint or an ItemCountConstraint is attached to the inventory. CtrlInventoryGrid displays inventories that have a GridConstraint on a 2d grid. CtrlItemSlot is a control node representing an inventory slot, that is, an ItemSlot.

The underlying ItemSlot class represents a slot that can hold one inventory item. That single-item model is the foundation for equipment and hotbar patterns, where each slot has its own semantics and the item inside it changes.

The honest framing is that these are conveniences, not a finished interface. A shipping game will have custom art, custom interaction, and usually a different information hierarchy from a list or a progress bar, so expect to replace them. What they buy you is a working display on day one, which matters when the item system itself is still being designed.

The examples directory reinforces that practical intent. It holds several scenes and scripts covering grid transfer and stacked transfer, including inventory_grid_transfer, inventory_grid_stacked_transfer, inventory_stacked_transfer and inventory_transfer, each with its scene and script, so the mechanics can be inspected as working code.

## Version 3.0 broke compatibility with 2.x, and the upgrade path is documented

The version history is the main thing to read before adopting GLoot in an existing project. Version 3.0 has been merged to master and includes changes that are not backwards compatible with version 2.x. The documentation provides a short transition guide at docs/gloot_2_to_3_transition_guide.md for anyone moving from version 2 to version 3, and the older version remains available on the v2.x branch if a project decides to stay where it is.

That arrangement is the practical detail. A project that cannot absorb the migration can remain on the v2.x branch rather than freeze, so the choice is a decision rather than a trap.

The releases themselves are close together. v3.0.0 was published on 2025-01-05, v3.0.1 on 2025-04-30 and v3.0.2 on 2026-07-05, and the last push to the repository was on 2026-07-14. The project is not archived, but the gap between the last release and the last commit is short enough that active work is happening between tagged versions.

The licence is MIT, which is permissive and carries no particular obligation for a game project that only uses the addon. The documentation itself is generated, with scripts at the repository root for producing it, and per-class reference pages live under docs/, covering the InventoryItem, Prototree, Inventory, the three constraint classes, ItemSlot and each of the controls.

## Conclusion

Adopt GLoot if your Godot 4.4 or newer project needs a data-driven item system where prototypes, stacks and capacity rules are separated from game code, and if you are starting fresh rather than migrating. Skip it if you are on the 2.x API and the transition cost is not worth it, or if your project needs equipment rules, durability or item effects that the constraint set does not model, since GLoot covers storage rather than item semantics. Before installing, read docs/gloot_2_to_3_transition_guide.md if you are coming from version 2, decide where the prototree JSON resource will live, and check the constraint classes you need against the ones that exist.

## FAQ

### How do I install GLoot in a Godot project?

Create an addons directory in your project, download the plugin from the AssetLib or clone it from GitHub with git clone https://github.com/peter-kish/gloot.git, copy the contents of the addons directory into your project's addons directory, and enable the plugin in Project Settings > Plugins. When importing from the AssetLib, deselect everything except the addons directory.

### What Godot version does GLoot require?

GLoot targets Godot version 4.4 and newer. The repository is a GDScript project with a project.godot file and a tests directory, so the plugin itself needs no build step.

### What are prototrees in GLoot?

A prototree is the JSON resource that holds your item prototypes, with prototypes able to inherit other prototypes to form a tree. Items based on a prototype inherit its properties and can override them or add new ones, and a prototype is referenced by its path inside the tree.

### How do I limit how much an inventory can hold in GLoot?

Add constraint classes as child nodes of the Inventory node. GridConstraint limits the inventory to a 2d grid of a given width and height, WeightConstraint limits it to a weight capacity with a default unit item weight of 1, and ItemCountConstraint limits it to an item count.

### Can I upgrade from GLoot 2.x to 3.0?

Yes, but version 3.0 is not backwards compatible with version 2.x, and the documentation provides a transition guide at docs/gloot_2_to_3_transition_guide.md. Projects that prefer to stay on the old API can use the v2.x branch instead.

## Sources

- [Issues](https://github.com/peter-kish/gloot/issues)
- [License: MIT](https://github.com/peter-kish/gloot/blob/master/LICENSE)
- [peter-kish/gloot on GitHub](https://github.com/peter-kish/gloot)
- [README](https://github.com/peter-kish/gloot/blob/master/README.md)
- [Releases](https://github.com/peter-kish/gloot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/peter-kish-gloot