AstralCollections Overview

AstralCollections is a Paper plugin that adds item collection challenges to the AstralRealms network. Server operators define collections of items in YAML; players discover those items through normal gameplay and earn rewards when a collection is completed.

What it does

Blueprints describe a collection: a display item, the set of entries (items to find), and the actions to fire when the collection is fully discovered.
Discovery is automatic. Whenever a player receives, picks up, or moves a matching item, the entry is marked as discovered.
Progress is persisted per player via AstralSync and survives server restarts.
A built-in menu (opened via /collections) lists every blueprint and its progress.

Requirements

Dependency	Required	Notes
Paper 1.21.11+	Yes	`api-version: 1.21.11`
AstralCore	Yes	Provides menus, configuration, placeholders, action framework
AstralSync	Yes	Player-data persistence
CraftEngine	Optional	Reload events trigger blueprint refresh; CraftEngine items can be used as entries
AstralItems	Optional	Provides additional item suppliers for entry matching

Architecture at a glance

plugins/AstralCollections/
├── blueprints/        ← YAML collection definitions
├── menus/             ← UI for /collections
└── messages.yml       ← localised strings

Service	Responsibility
`BlueprintService`	Loads blueprints from disk and indexes them for O(1) item lookup.
`CollectionService`	Marks entries as discovered, tracks progress, fires completion actions.
`MenuContainer`	Loads and opens the `collections` menu.

Listener	Trigger
`DiscoveryListener`	Hooks `PlayerItemGiveEvent`, `EntityPickupItemEvent`, `InventoryClickEvent`.
`CEListener`	Reloads blueprints when CraftEngine reloads.

Player data is stored as a CollectionPlayerData record persisted by the CollectionSnapshotAdapter registered with AstralSync.

Last modified: 25 July 2026