Items

Items are things that a player can obtain, hoard, trade, and consume. They might buy items from shops or obtain them from loot tables.

Exactly what the items are is entirely up to you. The framework provides an extensible way to define behaviour for different categories of item. Once a category has its code, you can create item types in that category through the admin panel.

Design Goals

The intent for the item system is to keep the implementation for the various categories separated. With item systems, it is very easy to:

• Accumulate a lot of complicated spaghetti code in one controller as you add new categories over the years
• Have a gigantic item type table with 200 columns, most of which are null since they’re specific to one category

Kitto² will make it easy to avoid these situations.

Key Concepts

The ItemCategoryRegistry is the heart of the system: it has an array of models implementing the ItemTypeDetailsInterface interface.

Registering an item category in that array will include it in the database seeder and provides the inventory/admin panel screens with the necessary information to handle these items.

The registered category classes have methods that the common inventory-handling code will use to eager load the details, add information to the ite, tooltip, and add interaction links into the UI.

All the Filament form & relationship configuration for the admin panel is defined there too.

TODO

Insert an ER diagram here.

Item Categories

An item category is where behaviour is defined. Every item category needs code associated with it, so these can only be added by a developer.

The framework comes with a few showcasing various techniques:

Category	Behaviours
Toy	Increases the happiness pet stat.
Food	Increases the hunger level pet stat.
Paintbrush	Changes the colour of a pet. This has a many-to-many relationship.
Recipe	Consumes items to produce different items. This has a belongs-to and has-many relationship.
Loot Container	Gives the user roll(s) on a loot table, for items/currency rewards. This has a belongs-to relationship.

Once registered, the category becomes available in the admin panel, and you can begin adding ItemTypes to it.

Item Types

Item types define what sort of items your players will interact with. Every ItemType model has a corresponding details model, which implements the ItemTypeDetailsInterface.

The item type has properties that are common to every item type: the name, description, icon, rarity, whether it is readable, and whether it should stack when in player inventories. The details relationship will track any category-specific fields: loot containers, for example, would track their relationship to a LootTable model on the details model.

This keeps an item type “clean” — it does not have a bunch of null properties for all the other item types.

User Items

User items are instances of item types that have found their way to players. Most items will track a stack size, and unstackable items will have multiple UserItem records with a quantity of 1.

TODO

Write about user shops and stuff. When I design those.

Guide: Creating an Item Category

To create an item category, start by creating a new model, prefixed with ItemType, e.g. ItemTypeFishingRod:

php artisan make:model -fm ItemTypeFishingRod

Fill out the database migration and factory. If you need additional related models, add those as well.

Then open up ItemTypeFishingRod and implement the ItemTypeDetailsInterface interface on it. Each method in this interface has a load of documentation: your IDE should be able to show it to you if you hover over each method.