Installation

1. Pre-flight

Plugin	Required	Notes
AstralCore	Yes	Must load before AstralItems. Provides menus, registries, item wrappers.
AstralSync	Yes	`UpgradeListener` consumes `PlayerDataLoadedEvent` to rebuild outdated items on join.
CraftEngine	Yes	The plugin registers an item stack supplier and hooks `CraftEngineReloadEvent`.
PacketEvents	Yes	Used by `AnvilService` for the packet-level custom anvil.
Java 25	Yes	The shaded JAR is compiled to `--release 25`.

2. Drop the JAR

Place AstralItems-<version>.jar in your server's plugins/ directory alongside AstralCore and CraftEngine.

3. First start

On first start the plugin creates:

plugins/AstralItems/
├── blueprints/        ← drop your *.yml here
├── rarities/          ← drop your *.yml here
├── menus/             ← AstralCore menus opened by /items
├── messages.yml
└── config.yml         ← reserved scaffolding

4. Add your content

Rarities go in plugins/AstralItems/rarities/ — see Rarity YAML Reference.
Blueprints go in plugins/AstralItems/blueprints/ — see Blueprint YAML Reference. Sub-folders are scanned recursively.
Menus go in plugins/AstralItems/menus/ — standard AstralCore menus (see Menu System). The built-in items-rarities menu is the entry point opened by /items; supply your own items-items menu with %parameters_rarity_*% placeholders to render the per-rarity blueprint list.

plugins/AstralItems/
├── rarities/
│   ├── common.yml
│   ├── rare.yml
│   └── legendary.yml
└── blueprints/
    ├── tools/
    │   ├── hammer.yml
    │   └── magnet.yml
    └── weapons/
        └── starfall_blade.yml

Reload at runtime with /items reload — no restart required.

5. Hand out items

Items are exposed through CraftEngine's stack supplier system under the namespace astralitems. Any place that resolves a CraftEngine key works — the AstralCore action framework, menus, shops, custom commands:

actions:
  - "[give-item] astralitems:rare/hammer"

The resolved key format is astralitems:<rarity-namespace>/<blueprint-id> — the rarity namespace is part of the key because ItemBlueprint.id is built as Key.key(rarity.namespace(), id).

Permissions

Node	Default	Description
`items.command`	op	Required to use any `/items` subcommand. Granted automatically to ops.
`items.reload`	op	Reload rarities, blueprints, messages, and menus with `/items reload`.

The /items no-arg form (open rarities menu) and /items anvil (open the custom anvil) need only items.command. Right-clicking a vanilla anvil block is intercepted by AnvilListener and opens the same custom anvil — there's no separate permission for that path.

Last modified: 25 July 2026