Open-source cosmic enchantments for your server.
Enchantments, armor sets, crystals, masks, pets, and weapon reforges, all configured in plain YAML. A built-in migrator brings your old configs across.

✦ 88 effects    ✦ Armor sets & crystals    ✦ Souls economy    ✦ Paper + Folia    ✦ 1.8, 1.17.1-26.1.2

Unified effect engine Enchantments, armor-set bonuses, crystals, masks, pets, and weapon reforges all feed one engine: 88 effects, 25 triggers, 18 selectors, and a conditions DSL over 49 live variables, on top of rarity tiers, applies/targets, and per-level options (chance, cooldown, souls, condition).	Item & economy systems Enchant books, scrolls (white, holy-white, black, transmog, godly-transmog, randomizer), success dust, soul gems and the souls economy they feed, slot-expander orbs, item nametags, crystals, weapon reforges, and right-click use-items. The pack also ships 14 masks (textured heads you drag onto a helmet for a passive ability, which re-skin the worn helmet) and 21 pets: levelling textured-head companions you carry in the hotbar, with an active or passive ability, fed on Pet Food.
Armor sets & reforges Full armour sets with a set-completion bonus and an optional matched set weapon, plus Heroic upgrades that raise damage, reduction and durability. The other half of the loadout is the 10 weapon reforges: one socketable signature ability per sword or axe, fired with shift+right-click. Both are just more sources of effects feeding the same engine.	In-game GUIs Menus are the main way to run the plugin, and all of them are configurable. Players get nine direct commands (permission starenchants.use, granted to everyone by default): /enchants or /enchanter opens the Enchanter bench, where tiered mystery books cost XP levels; /alchemist combines two identical books into the next level; /tinkerer trades books back for XP; and /sets, /crystals, /catalogue (the Enchant Codex), /pets and /masks open the browsers. Operators still get the full console at /se menu to mint anything, drill into sets and reforges, and reload.
Integrations WorldGuard, Towny, Lands, SuperiorSkyblock, Factions, Vault, PlaceholderAPI, Mental, GrimAC, mcMMO, MythicMobs, ItemsAdder and Oraxen. All optional, none required.	Built-in migrator Your existing EliteEnchantments, EliteArmor and AdvancedEnchantments configs come straight into the unified schema with one command: /se migrate.

Installation, configuration, commands, the full reference & an interactive Enchant Creator live on the docs site:

owengregson.github.io/StarEnchants →

_{The docs are generated from the engine, so they're always current. The rest of this README is for developers building or contributing to StarEnchants.}

StarEnchants builds with the bundled Gradle wrapper, so there's no global toolchain to install. scripts/build-mega-jar.sh produces one jar that runs on Paper 1.17.1-26.1.2 and Folia (Java 17+) and on Minecraft 1.8.x (Java 8). It's a Multi-Release jar, so each server's JVM loads the bytecode tree that matches it: modern v61, or the downgraded legacy v52. scripts/legacy-smoke.sh gates the 1.8 tree on a real server (see docs/legacy-1.8.9-codeshare-design.md).

git clone https://github.com/owengregson/StarEnchants.git
cd StarEnchants
scripts/setup-dev.sh          # prereqs + git hooks + build (idempotent)
./gradlew build               # compile + pure unit tests

The shaded fat jar lands in bootstrap/build/libs/; drop it into any server in the range.

Project layout

The module tree under se/ is flat and single-segment: each module's package is one segment (engine, item, …), with sources in src/ and tests in test/, never src/main/java. Shaded deps are relocated under their own root so the short roots never collide.

Module	Responsibility
schema	the DSL grammar, ParamSpec/types, diagnostics
compile	YAML → an immutable Snapshot (the content compiler)
engine	the data-oriented runtime: systems, effects, conditions, selectors, triggers, the Sink
item	the one item-data layer: PDC codec, ItemView cache, WornState, lore render
feature	feature interactions, services, the /se commands, GUIs
platform	cross-version resolvers + the Folia-safe scheduling abstraction
integrate	the bundled, soft third-party integrations
migrate	the EE / EA / AE config importer
pack	the config-pack (ZIP snapshot) format
bootstrap	the Bukkit entry point + composition root (the shaded fat jar)
tester	the in-server Paper + Folia integration suites
api	the public surface: activation/reload events + the add-on SPI & StarEnchantsApi service (curated, on schema; ADR-0038)
compat-folia	the Folia scheduler shim

Verification gate

./gradlew build          # compile + pure unit tests, always first
scripts/run-matrix.sh    # boot real Paper AND Folia servers across the range, run the live suites

A green Paper run says nothing about Folia, so both must pass fresh. The matrix boots real servers across the whole range, which is what the universal jar rests on: a version-agnostic core, boot-time resolvers for the version-volatile surfaces, and one Folia-safe scheduling abstraction. Full procedure: docs/dev/verification-gate.md.

Every developer doc lives in one place. Start at the hub and follow the trail:

docs/dev/  ·  the developer documentation hub →

The hub splits into getting started, internals (how the engine works), and guides (how to extend it), all linked from the sections below. Player- and operator-facing docs (install, configuration, commands, the DSL reference, the Enchant Creator) live on the generated site at owengregson.github.io/StarEnchants instead, where they can't drift from the engine.

The architecture is self-derived: a content compiler that lowers YAML into an immutable snapshot, and a data-oriented runtime that executes it. Read the design top down, then go to the subsystem you're touching.

• docs/architecture.md covers the whole self-derived engine design, top to bottom.
• docs/decisions/ holds the ADRs, the why behind every major choice.
• docs/glossary.md defines the domain vocabulary (effect, trigger, selector, Sink, Affinity, WornState, …).

Subsystem internals:

Doc	Covers
effect-engine.md	stateless systems, the activation pipeline, gate order, the Ability record, the Sink, dispatch
item-data-model.md	item state, the PDC codec, the ItemView cache, component stores, WornState, lore/name render
compiler-and-config.md	resolve → typecheck → lower → erase → snapshot, diagnostics, transactional reload
feature-interactions.md	damage stacking, enchant/group/type suppression, souls, slots, crystals, omni/multi-set completion
cross-version-api.md	the 1.17.1 → 26.1.x surface, the 1.20.5 mapping flip, enum→registry breaks, boot-time resolvers
folia-scheduling.md	Folia's region/entity/global thread model and the scheduling abstraction that makes one codebase correct on both
performance-hot-paths.md	the combat/item hot path, declared Affinity, the Sink/cache/interning, the lint + JMH gate
the-migrator.md	the EE / EA / AE config importer and the legacy-item migration path
config-packs.md	the config-pack (ZIP snapshot) format: export, import, share

Adding a feature is local: one interface plus one registration. Each how-to walks the whole loop, from declaring the kind to the live test that proves it works.

Add a…	Guide
new effect	developing-an-effect.md
new condition	developing-a-condition.md
new selector	developing-a-selector.md
new trigger	developing-a-trigger.md
new DSL grammar	extending-the-dsl-grammar.md
new item type	adding-an-item-type.md
new integration	adding-an-integration.md
new config option	adding-a-config-option.md
new command	adding-a-command.md

Contributions are welcome. The flow is feature branch → frequent Conventional Commits → PR (CI green) → rebase-merge (never squash). Enable the hooks once with scripts/setup-hooks.sh.

• CONTRIBUTING.md has the full workflow, branching model, and commit conventions.
• docs/dev/getting-started.md covers clone-to-first-change, the dev loop, and where things live.
• docs/dev/verification-gate.md explains ./gradlew build then scripts/run-matrix.sh, and how to read the results honestly (Paper green is not Folia green).
• docs/dev/writing-a-live-test.md walks through authoring an in-server Paper + Folia integration test.
• docs/dev/regenerating-generated-docs.md: the DSL reference and Enchant Creator are generated from the live registries, so run ./gradlew regenDocs (a drift test fails the build if you skip it).
• docs/dev/release-process.md covers cutting a tagged release.
• CLAUDE.md and .claude/skills/ carry the engineering invariants and the hard-won, per-area knowledge to check before working in an area.

Released under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.

_{STARENCHANTS  ·  made with a little starlight ✦}