> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/pinnaprison/core/enchants.md). # Enchants PinnaPrison ships with 40+ custom enchants and you can add your own. Each enchant is **one file** in `enchants/.yml` — the filename is the enchant id. Shared settings (menu text, prestige stars) live in `config.yml` under `enchants:` (see [Main Configuration](/p/pinnaprison/getting-started/main-configuration.md)). Players buy and upgrade enchants in the enchant menus (the pickaxe right-click GUI and the token/gem enchant menus). ## Enchant types | `type` | What it does | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `api` | An **active** enchant that rolls a chance on each mined block. Used for AOE/animated enchants, greed (currency) enchants and bonus-reward enchants. | | `effect` | A **passive** enchant that applies a potion effect (Speed, Haste, …) while the player holds the pickaxe. The level becomes the effect amplifier. | ## Chance & how a proc works Active (`api`) enchants roll a chance **per mined block**. The chance scales with the enchant level: ``` chance = (level / max-level) × max-chance (+ prestige bonus) ``` So at max level the chance equals `max-chance`. Set **`always-max-chance: true`** to make the chance a flat `max-chance` at any level (the level no longer matters once owned). ## Common keys ```yaml color: primary: '&4' secondary: '&c' starting-level: 100 # level the enchant starts at when first bought max-chance: 4 # max proc chance (%) — reached at max-level always-max-chance: false # true = always max-chance regardless of level max-level: 10000 material: NETHERITE_PICKAXE # icon in the menus / pickaxe lore type: 'api' # api or effect display-name: 'Jackhammer' cooldown-ticks: 0 # min ticks between procs (0 = none) requirement: economy: 'pickaxelevel' # leveling track that gates this enchant amount: 10 # level required to unlock it cost: currency: tokens # currency used to buy/upgrade starting-cost: 100 # cost of the first level increase-cost-by: 500 # added to the cost per level ``` | Key | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------- | | `color.primary` / `color.secondary` | The two colours used for this enchant in lore and menus (`{prim-color}` / `{sec-color}`). | | `starting-level` | The level the enchant begins at when first purchased. | | `max-chance` | The maximum proc chance in percent. | | `always-max-chance` | When `true`, the proc chance is always `max-chance` (plus prestige), ignoring the level. | | `max-level` | The highest level the enchant can reach. | | `material` | The icon material (also supports `texture-` heads). | | `type` | `api` or `effect`. | | `display-name` | Display name used in menus, lore and messages. | | `cooldown-ticks` | Minimum ticks between procs (stops animated enchants from spamming). | | `requirement.economy` | A [leveling track](/p/pinnaprison/core/leveling.md) id the player must reach to unlock the enchant. | | `requirement.amount` | The level required on that track. | | `cost.currency` | The currency the enchant is bought/upgraded with. | | `cost.starting-cost` | The cost of the first level. | | `cost.increase-cost-by` | Added to the cost for each subsequent level. | ## `settings` — what the proc does The `settings` block configures the active behaviour. The keys differ slightly per enchant style. ```yaml settings: affect-autosell: true # blocks the enchant breaks go to the backpack / autosell affect-tokengreed: true # broken blocks also pay the Token Greed enchant affect-block-currencies: false # broken blocks pay block currencies (rankup/pickaxe xp) affect-enchants: false # broken blocks can trigger OTHER enchants (chaining) message: '&fJackhammer &7earned you &a%pinnaprison_notation_{tokens}% &fTokens!' ``` | Key | Description | | ------------------------- | ---------------------------------------------------------------------------- | | `affect-autosell` | Blocks broken by this enchant are added to the player's backpack / autosell. | | `affect-tokengreed` | Broken blocks also pay the **Token Greed** bonus. | | `affect-block-currencies` | Broken blocks pay block currencies (rankup XP, pickaxe XP). | | `affect-enchants` | Broken blocks can roll **other** enchants (lets enchants chain). | | `message` | Greed-style chat message on proc. `''` to disable. | ### Greed / currency enchants A greed enchant pays a currency per proc. It uses `settings.currency` + `settings.amount`, where `amount` supports math and `{level}`: ```yaml settings: currency: tokens amount: '1000+{level}' # paid per proc, scales with the enchant level message: '&fToken Greed &7earned you &a%pinnaprison_notation_{amount}% &fTokens!' ``` ### Bonus reward (per swept block) Add a `reward` block to pay a **bonus currency per block the enchant sweeps**, on top of the normal block income. `per-block` supports math, `{level}` and PlaceholderAPI: ```yaml reward: type: gems # 'blocks' (default, no bonus) or a currency id per-block: '2+{level}/150' ``` ### Animated / AOE enchants The big visual enchants (Armageddon, Meteor, Black Hole, Nuke, …) add their own FX keys under `settings`, for example: ```yaml settings: affect-autosell: true affect-tokengreed: true meteors: 12 drop-interval-ticks: 4 target-radius: 16 crater-radius: 3 finale-radius: 8 fall-speed: 1.8 proc-message: '&c&l[!] &7Your &6&lARMAGEDDON &7cratered &6{blocks} blocks &7from orbit!' ``` These extra keys (meteor counts, radii, speeds, particle/sound options) vary per enchant — open the enchant's file to see and tweak its values. `proc-message` is the chat line shown on proc (`{blocks}` = blocks broken). ## `effect` enchants Passive enchants apply a potion effect while the pickaxe is held. The level becomes the effect amplifier. ```yaml color: { primary: '&f', secondary: '&b' } max-level: 10 material: FEATHER type: 'effect' effect: 'speed' # any vanilla potion effect id display-name: 'Speed' cost: currency: tokens starting-cost: 100 increase-cost-by: 500 ``` | Key | Description | | -------- | ---------------------------------------------------------- | | `effect` | The vanilla potion effect applied (e.g. `speed`, `haste`). | The effect is applied when the player holds the pickaxe and removed when they switch away, and respects the per-enchant on/off toggle (see below). ## Prestige Prestige lets a player re-max an enchant for a permanently higher max chance. ```yaml prestige: enabled: true max-prestige: 5 max-chance-per-prestige: 1 # +1% max chance per prestige level reset-level: true # reset the level to 0 on prestige requirements: tokens: type: currency # 'currency' or 'level' amount: 500000 remove: true # consume the amount on prestige scale-with-prestige: true # amount × the prestige being bought ``` | Key | Description | | ------------------------- | ----------------------------------------------------------------------------- | | `enabled` | Whether this enchant can be prestiged at all. | | `max-prestige` | The highest prestige level. | | `max-chance-per-prestige` | Flat max-chance bonus (%) added per prestige level. | | `reset-level` | Reset the enchant level to 0 when prestiging. | | `requirements` | One or more gates (currency cost or leveling threshold) the player must meet. | Each requirement: `type` (`currency`/`level`), `amount`, `remove` (consume it — defaults to yes for currency, no for level) and `scale-with-prestige` (multiply the amount by the prestige being bought). ## Player toggles In the enchant upgrade menu players can: * **Toggle the enchant on/off** — a disabled enchant won't proc and (for effect enchants) its potion is removed. * **Toggle the proc message per enchant** — mute just that enchant's chat message. There is also a global `/settings` toggle to mute all enchant messages. ## Admin commands Modify a player's enchants with `/pinna enchant`: ``` /pinna enchant ``` `add`/`subtract`/`set` change the **level**; `prestige` sets the **prestige** (prestigeable enchants only). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://edseries-plugins.gitbook.io/p/pinnaprison/core/enchants.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.