Installation & Environment

Previous: Overview　·　Next: 5-Minute Quick Start

1. Requirements

Item	Requirement	Note
Server	Paper / Purpur / Spigot 1.21.11+	plugin.yml declares api-version: '1.21'
Java	25+	Compiled for Java 25; older JVMs can't load it
Hard dependency	QinhCoreLib	Must be installed before QI, or QI refuses to start

⚠️ On onEnable, QI checks that QinhCoreLib is loaded and enabled, and that the server is compatible (ServerCompat.validateServer()). If either fails, QI aborts startup and logs an error.

2. Optional soft dependencies

These enable extra features when present and degrade gracefully when absent — they don't affect QI's core:

Soft dependency	Feature enabled
AttributePlus	Item combat attributes actually apply to players (numbers backend). See Attributes & Numbers
QinhSkills	qinhskills:cast in item actions casts skills. See Integration
PlaceholderAPI	%qinhitems_...% placeholders. See Placeholders
Legendinlay	Gem-socket backend A. See Gem Sockets
MagicGem	Gem-socket backend B
LegendCore	Registers QI items into LegendCore's ItemManagerAPI (qi- prefix)
MythicMobs	Mob / drop integration
CraftEngine / ItemsAdder / Nexo	Custom model / texture providers

3. Installation steps

1. Stop the server.
2. Put the QinhCoreLib jar into plugins/.
3. Put the QinhItems jar into plugins/.
4. (Optional) Add any soft-dependency plugins you want.
5. Start the server.

On first start, QI extracts its bundled example content to disk via BundledContentBootstrap (see below) and prints a startup summary.

4. What the first start generates

On its first start, QI releases a set of files under plugins/QinhItems/ and writes a marker file .bundled_initialized_v3 to mark "initialized".

Core files always released:

plugins/QinhItems/
├── config.yml                       # Main config (see Reference / Config)
├── item_types.yml                   # Item type definitions
├── item_tiers.yml                   # Quality / Tier definitions
├── enchant_limits.yml               # Enchant caps
├── items/                           # Item definitions (one file per type)
│   ├── weapon.yml  armor.yml  ring.yml  gem.yml  consumable.yml … (40+ files)
├── fragments/
│   └── weapon_base.yml              # Fragment example
├── sections/
│   └── example_sections.yml         # Section / affix / pool examples
├── sets/
│   └── sets.yml                     # Set examples
├── integrations/
│   ├── action_handlers.yml
│   ├── gem_socket_types.yml
│   ├── legendinlay_sockets.yml      legendinlay_guide.yml
│   ├── magicgem_sockets.yml         magicgem_guide.yml
│   ├── bridges.yml
│   └── resource_models.yml
└── legendcore/
    ├── QinhItemsModule.groovy       # LegendCore fallback script
    └── README.txt

📌 Example items are released only once, on first start. If you delete a bundled example under items/ and want it back, manually delete the .bundled_initialized_v3 marker or extract it from the jar — it won't auto-release again.

5. Verify the install

After joining:

/qi status

You'll see the number of loaded items, ActionTable count, and whether there are problems. Then:

/qi diagnose

shows a full diagnosis (whether the attribute backend is wired up, gem backends, bridge / layer / handler counts, etc.).

You can also grab a bundled example item to try (IDs in items/weapon.yml, e.g. Thunder Edge):

/qi give demo_thunder_edge

🖼️ [Image placeholder] Console / chat output of /qi diagnose · suggested assets/diagnose-output.png

6. Reading the startup log

The startup summary (QinhItemsStartupLog) looks roughly like this — watch a few fields:

Item definitions: 123 · ActionTable 45
Bridge: 3 · Layer: 4 · Handler: 12
Combat: enabled · Attribute backend: attributeplus (wired)
Gems: LI(LC✔·8 sockets) · MG(2 sockets)
Diagnostics: 30/30 OK

• Attribute backend showing attributeplus (wired) means AP is fine; noop means no AP detected — pure item-library mode.
• Combat: off (pure item library) means you turned off combat.enabled in config.yml.

Next → 5-Minute Quick Start