Installation

1. Requirements

AstralEssentials is a Paper plugin (main class com.astralrealms.essentials.AstralEssentials, extending AstralPaperPlugin) targeting api-version: '1.21'. Its plugin.yml declares four hard dependencies and one soft dependency:

name: AstralEssentials
main: com.astralrealms.essentials.AstralEssentials
api-version: '1.21'
depend:
  - AstralCore
  - AstralItems
  - AstralSync
  - CraftEngine
softdepend:
  - packetevents

Plugin	Required	Notes
AstralCore	Yes	Must load first. Provides the plugin base class, menus, actions, cooldown service, and configuration loading.
AstralItems	Yes	Hard dependency in `plugin.yml` and functionally required: `/repair` calls `ItemsAPI.isCustomItem()` to exclude AstralItems custom items from repair, `/anvil` opens its anvil UI via `ItemsAPI.openAnvil()`, and `EnchantmentListener` listens for AstralItems' `AnvilResultEvent` to enforce `max-enchantment-levels`.
AstralSync	Yes	`SyncAPI.registerAdapter(new PlayerTimeSnapshotAdapter())` is called on enable — see AstralSync integration below.
CraftEngine	Yes	Hard dependency in `plugin.yml`; `FurnitureConversionListener` uses CraftEngine's furniture API to convert legacy ItemsAdder-placed furniture entities to CraftEngine furniture on chunk load.
PacketEvents	Soft	Declared as a soft dependency, but `EnderDragonPacketListener` is registered unconditionally against the PacketEvents API during `onEnable()` — in practice the PacketEvents plugin must be present and loaded or the plugin will fail to enable. See PacketEvents integration.

Because depend forces load order, AstralCore, AstralItems, AstralSync, and CraftEngine are guaranteed to be enabled before AstralEssentials. PacketEvents is not guaranteed by softdepend alone — only load order is guaranteed, not presence — so treat it as required in practice.

2. Drop-in installation

Place AstralEssentials-<version>.jar in plugins/ alongside AstralCore, AstralItems, AstralSync, CraftEngine, and the PacketEvents plugin. Because of the depend/softdepend order above, no particular drop-in order is required beyond "all of them present before the server starts" — Paper resolves load order from plugin.yml automatically.

3. First start

On first enable the plugin generates, under plugins/AstralEssentials/:

plugins/AstralEssentials/
├── config.yml
├── cooldowns.yml
├── containers.yml
└── messages.yml

config.yml, cooldowns.yml, containers.yml, and messages.yml are copied from the plugin's shipped defaults the first time each is loaded (they are left untouched on subsequent starts if already present). See Configuration and Messages.

Custom recipe authoring lives in the standalone AstralRecipes plugin, not here — see its own installation/data-folder layout in that product's docs.

PacketEvents integration

AstralEssentials uses PacketEvents for two independent things:

EnderDragonPacketListener — registered directly against PacketEvents.getAPI().getEventManager() during onEnable(), unconditionally (not gated by the hook system below). It listens at MONITOR priority for outgoing Play.Server.EFFECT packets and cancels the one with effect ID 1028 (the vanilla ender-dragon-death effect), suppressing the vanilla death animation/sound broadcast.
PacketEventsHook — registered through AstralCore's hook manager (this.hooks().register("packetevents", PacketEventsHook::new)) and activated by this.hooks().check(), which only instantiates and enables the hook if a plugin named packetevents is actually enabled on the server. Once active, it registers a PacketEvents listener that rewrites the outgoing minecraft:brand plugin-message payload (both the configuration-phase and play-phase variants) to AstralServer, replacing whatever brand PacketEvents would otherwise report to the client.

AstralSync integration

On enable, AstralEssentials calls SyncAPI.registerAdapter(new PlayerTimeSnapshotAdapter()), registering a snapshot adapter keyed astralessentials:player_time. This adapter backs per-player time and weather (PlayerTimeCommand, PlayerWeatherCommand): the player's personal time/weather override is stored and restored through AstralSync rather than in a plugin-local file, so it follows the player across servers that share the same AstralSync backend. AstralSync must therefore be functioning (not just present) for per-player time/weather to persist and sync correctly.

4. Reloading configuration

/essentials reload (permission essentials.command) calls the same loadConfiguration() routine the plugin runs on enable:

Reloads messages.yml into EssentialsMessages.
Reloads config.yml, cooldowns.yml, and containers.yml into their respective configuration records.
Reloads recipes (RecipeService.load()) — existing Bukkit recipes registered by the plugin are removed and re-registered from whatever is currently on disk under recipes/. This does not re-seed shaped.yml/shapeless.yml if you deleted them, since seeding only happens when the recipes/ directory itself is missing.
Reloads menus (MenuContainer.load()).
Re-applies unregistered-commands from config.yml, unregistering each named command from the server's command map.

Reloading does not re-run the one-time enable logic — the locator-bar game rule, beehive-regeneration tasks, disabled-craft recipe removal, the EntityLimitTask timer, the PacketEvents listeners, and the AstralSync adapter registration are all set up once at onEnable() and are unaffected by /essentials reload. Restart the server to pick up changes to those.

Server-group-scoped behavior

Several config.yml sections are keyed by server group and only take effect on servers whose AstralPaperAPI.serverInformation().group() matches a key in the map — installing the plugin does not by itself activate these on every server:

entity-limits (per-chunk entity caps, via entityLimitsForGroup())
spawn-protection.enabled-groups (per-world spawn protection, via SpawnProtection#isProtected)
beehive-regeneration-times (per-world beehive regen tasks — scheduled once, one tick after enable, for each world already loaded at that point; worlds loaded later are not picked up until a restart)
disabled-spawners-groups (fully blocks placing spawners on matching groups, independent of the per-chunk spawners-limits cap — both checks live in SpawnerListener, which is only registered at all if spawners-limits.enabled is true)
disabled-mob-spawning-groups (per-group mob spawn suppression)
groups-blocked-commands (per-group, per-world blocked commands)

See World & Server Management and Configuration for the per-key details.

Permissions

Node	Default	Description
`essentials.command`	op	Required for every `/essentials` subcommand, including `/essentials reload`. Class-level `@CommandPermission`, so it applies to the whole command.

Individual features (gamemode, fly speed, sudo, etc.) are gated by their own per-command permissions — see Commands.

Last modified: 25 July 2026