Item Types and Capability Matrix

Belongs to: Server Admin Guide　·　Related: Item Definition · Quality and Display

An item type determines "which category an item belongs to" and "which features it can use". Configuration file: plugins/QinhItems/item_types.yml.

📋 Want to see the full table of each type's default material / editor icon / library category? See Resource File Overview → Full item_types table.

---

1. What Is a Capability (TypeCapability)

Each type declares which capabilities it supports. A capability is an enum:

Capability	Meaning
SKILL	Supports skills / action triggers (e.g. the left_click trigger)
ATTRIBUTE	Supports attribute modifiers (e.g. providers.ap)
GEM_SOCKET	Supports gem sockets (gem-sockets field)
SET	Supports Set bonuses
RENDER	Supports custom rendering (resource pack / model data)
CONSUMABLE	Consumable actions (consume trigger)
PROJECTILE	Projectile behavior (bow / crossbow / trident)

The capability matrix defines boundaries: adding gem-sockets to a currency item (which only has RENDER) is meaningless, because it does not support GEM_SOCKET.

Query interface (developers):

TypeCapabilityMatrix.capabilitiesOf(typeId): Set<TypeCapability>   // Includes capabilities inherited from parent types
TypeCapabilityMatrix.supports(typeId, capability): Boolean

---

2. Complete List of Built-in Types

The table below lists all of QI's built-in types (from QinhItemTypeRegistry.builtinDefaults()), grouped by purpose. The Aliases column lists the alternative spellings that can be used interchangeably at type:.

Combat

Type	Aliases	Capabilities
weapon	sword/weapons	SKILL · ATTRIBUTE · GEM_SOCKET · RENDER
armor	armour	ATTRIBUTE · RENDER
helmet	(parent: armor)	ATTRIBUTE · RENDER
chestplate	(parent: armor)	ATTRIBUTE · RENDER
leggings	(parent: armor)	ATTRIBUTE · RENDER
boots	(parent: armor)	ATTRIBUTE · RENDER
shield		ATTRIBUTE · RENDER · SET
projectile	ammo	PROJECTILE · RENDER
bow		PROJECTILE · ATTRIBUTE · RENDER
crossbow		PROJECTILE · ATTRIBUTE · RENDER
trident		PROJECTILE · SKILL · ATTRIBUTE · RENDER

Accessories

Type	Aliases	Capabilities
ring		SKILL · ATTRIBUTE · GEM_SOCKET · RENDER
necklace		SKILL · ATTRIBUTE · GEM_SOCKET · RENDER
bracelet	wristlet/band	SKILL · ATTRIBUTE · GEM_SOCKET · RENDER
accessory		SKILL · ATTRIBUTE · GEM_SOCKET · RENDER

Crafting / Materials

Type	Aliases	Capabilities
gem	jewel	RENDER · ATTRIBUTE
material	mat/materials	RENDER · SET

Consumables

Type	Aliases	Capabilities
consumable	useable	CONSUMABLE · RENDER · SET
food	edible/foods	CONSUMABLE · RENDER
scroll		CONSUMABLE · SKILL · RENDER
seed	crops	CONSUMABLE · RENDER
bait		CONSUMABLE · RENDER

Tools / Miscellaneous

Type	Aliases	Capabilities
tool	tools	RENDER · ATTRIBUTE
fishing_rod		RENDER · SET
wand	staff	SKILL · ATTRIBUTE · GEM_SOCKET · RENDER
horse_armor		ATTRIBUTE · RENDER
horse	mount	RENDER · SET
skull	head	RENDER
currency	coin/coins/money	RENDER
token	tickets	RENDER · CONSUMABLE
trophy	award/prize	RENDER · CONSUMABLE
prop	gadget/props	SKILL · CONSUMABLE · RENDER
misc	other/miscellaneous	RENDER (fallback type)

---

3. Parent Types and Capability Inheritance

Some types have a parent type and inherit the parent's capabilities. The most typical case is armor:

armor
├── helmet      (inherits armor's ATTRIBUTE · RENDER)
├── chestplate
├── leggings
└── boots

So helmet does not need to declare its capabilities separately; it inherits them from armor. TypeCapabilityMatrix.capabilitiesOf("helmet") returns the inherited capabilities as well.

---

4. item_types.yml Structure

item_types.yml defines type IDs, display names, capabilities, parent types, library categories, and so on. The structure roughly looks like:

types:
  weapon:
    display: "武器"
    aliases: [sword, weapons]
    capabilities: [SKILL, ATTRIBUTE, GEM_SOCKET, RENDER]
    library-category: weapons
  helmet:
    display: "头盔"
    parent: armor          # Inherits armor's capabilities
    capabilities: [ATTRIBUTE, RENDER]

In general you do not need to edit this file; the built-in types already cover the vast majority of needs. Only add a brand-new type when you need one. display is shown on the item's Lore in the "Item Type: xxx" line.

---

5. Custom Types

To add a brand-new type, add an entry under types: with at least display and capabilities, then run /qi reload. The item can then use type: your-new-type.

Note: the type must exist, otherwise the item will be unhealthy due to "unknown type" (see Item Definition → Health Check).

---

6. Types and "Libraries"

A type can be assigned to a library category (library-category). A library (LibraryManifest) is metadata that packages a group of types / capabilities into a distributable content pack, mainly used for content distribution / editor grouping. For developer details, see Layers and Assembly → Library Manifest.

---

Next Steps

• Quality and Display: Add quality to types and control Lore layout
• Attributes and Values: Add combat attributes to ATTRIBUTE types
• Gem Sockets: Socket GEM_SOCKET types