Skip to main content

Enchantment Creator

Custom enchantments with 70+ ready-made effects, books, loot and trades. No extra plugin required.

Freev0.11RPG & progression
RequiresTypeWriter0.9Paper1.21+Basic extension
DownloadSource codeSupport

Overview​

Enchantment Creator adds real enchantments to your server, defined entirely from the TypeWriter web panel. They are registered in Minecraft's own enchantment registry under the typewriter namespace, so they appear on items, in anvils and in the enchanting table like vanilla ones, without any resource pack or extra plugin.

You describe the enchantment in a definition entry (name, color, supported items, maximum level, costs, active slots), then give it behaviour. There are two ways: a standard definition runs TypeWriter triggers while the enchanted item is worn or held, and a custom definition lists mechanics, each reacting to a game event (attack, block break, bow shot, fall damage...) and running actions. The extension ships more than 70 ready-made action entries (lifesteal, vein miner, homing arrows, frozen armor...) that you plug into mechanics.

Features​

  • Real enchantments — registered in the server's enchantment registry, with a colored name, max level, anvil cost, weight and enchanting-table costs.
  • Two definition types — trigger-based (enchantment_definition) or mechanic-based (custom_enchantment_definition).
  • 16 game events — attack, defend, block break, bow shot, projectile hit, fall damage, item damage, armor equip, movement, sneak, sprint and more.
  • 70+ ready-made effects — armor, bow, combat, tool and special actions, each with its own fields.
  • Enchanted books — give books from an action or from a command, with a custom name and lore.
  • World integration — books appear in generated loot chests (treasureChance) and in librarian trades (tradeChance).
  • Enchanting table and anvil — custom enchantments can be offered by the enchanting table, restricted to supported items, and made mutually exclusive in the anvil.
  • Vanilla blacklist — remove chosen vanilla enchantments from the enchanting table.
  • Per-mechanic chance and level — run a mechanic only a percentage of the time, or only at one enchantment level.
  • Client-side particles — a particle action shown only to the player.

Installation​

  1. Use a Paper server 1.21 or later, with Java 21. The extension builds enchantments through the server's registry, so it does not work on older versions.
  2. Make sure the Basic extension of TypeWriter is installed (see the TypeWriter documentation).
  3. Put the Enchantment Creator JAR in plugins/Typewriter/extensions/ and restart the server.

No other plugin is required.

Getting started​

Create a "Vampiric Strike" sword enchantment that heals the wielder on each hit:

  1. In the TypeWriter web panel, open a manifest page and add a Custom Enchantment Definition.
  2. Set name to Vampiric Strike, displayName to Vampiric Strike, nameColor to dark_red, maxLevel to 3, and add the sword materials to supportedItems.
  3. Add a Lifesteal action entry on a sequence page, and set healPercentage to 0.2.
  4. Back in the definition, add a mechanic in mechanics. Set event to PLAYER_ATTACK, and select the Lifesteal entry in actions.
  5. Add a Give Enchantment Book action, select your definition in customEnchantment, and set level. Publish.
  6. Trigger the action to get the book, or run /enchantcreator give <player> Vampiric_Strike 2 after adding an Enchantment Command Manifest. Combine the book with a sword in an anvil, and hit a mob.
tip

The effect does not scale with the enchantment level on its own. To make level 3 stronger, add several mechanics with runOnLevel set to 1, 2 and 3, each running an action with different values. runOnLevel 0 means every level.

How it works​

The extension checks every online player every 5 ticks (a quarter of a second) to know which of your enchantments they are using. Only the main hand, off-hand and armor count, and only items whose material is in supportedItems. The highest level found is the level used. A short delay can therefore pass between equipping an item and its effects starting.

The two definition types work differently:

  • A standard definition (enchantment_definition) runs activeTriggers for the current level. With cooldownEnabled on, they run again every cooldown while the enchantment is active; with it off, they run once when it becomes active. inactiveTriggers run when it stops. criteria must pass.
  • A custom definition (custom_enchantment_definition) runs its mechanics when the matching game event happens.

Action entries read the game event that triggered them. An action only does something when it is used in a mechanic with the event it was written for (for example, Vein Miner only works on BLOCK_BREAK).

Enchantment events​

A mechanic's event is one of:

EventFires when
PLAYER_ATTACKThe player directly hits an entity.
PLAYER_DEFENDThe player is damaged by an entity.
SHIELD_BLOCKThe player is hit while blocking with a shield.
BLOCK_BREAKThe player breaks a block.
BOW_SHOOTThe player shoots a bow or crossbow.
PROJECTILE_HITA projectile shot by the player hits something.
ITEM_CONSUMEThe player eats or drinks.
PLAYER_DEATHThe player dies.
PLAYER_INTERACTThe player right- or left-clicks.
ARMOR_EQUIPThe player equips or unequips armor.
ITEM_DAMAGEAn item loses durability.
FALL_DAMAGEThe player takes fall damage.
ENVIRONMENTAL_DAMAGEThe player takes damage not caused by an entity (also fires for fall damage).
PLAYER_MOVEThe player moves to another block (checked every fourth tick).
SNEAKThe player starts sneaking.
SPRINTThe player starts sprinting.
note

PLAYER_ATTACK fires when the player is the direct damager, which means melee hits. Damage dealt by an arrow is dealt by the arrow, so it does not fire PLAYER_ATTACK in the current version. The arrow actions that read a damage event (marked below) therefore only act on direct hits.

Ready-made actions​

All action entries are used inside a mechanic (actions), or from any sequence. Each has the standard criteria, modifiers and triggers fields, plus its own fields: see the entry pages. The event column tells which event of the mechanic the action needs.

GroupActionsEvent
CombatArmor Pierce, Beheading, Bleed, Blindness Strike, Cleave, Disarm, Executioner, Freeze Strike, Lifesteal, Lightning Strike, Poison Strike, Silence, Vampiric Aura, Wither StrikePLAYER_ATTACK
Armor, when hitDeflect, Enlightened Armor, Evasion, Frozen Armor, Molten Armor, Regeneration Aura, Resistance Aura, Thorns Advanced, Toxic Aura, Voodoo Armor, GearingPLAYER_DEFEND
Armor, damageAngel WingsFALL_DAMAGE
Armor, damageImplosion Armor, Curse of Vulnerabilityany damage event (PLAYER_DEFEND, FALL_DAMAGE, ENVIRONMENTAL_DAMAGE)
Armor, equipAnti Knockback, Health BoostARMOR_EQUIP
Armor, durabilityHardened ArmorITEM_DAMAGE
Bow, shotHoming Arrow, Volley ArrowBOW_SHOOT
Bow, impactExplosive Arrow, Teleport ArrowPROJECTILE_HIT
Bow, damageEnder Arrow, Healing Arrow, Lightning Arrow, Piercing Shot, Pull Arrow, Push Arrow, Sniper Arrow, Venom Arrow, Web Arrow, Wither ArrowPLAYER_ATTACK (direct hits only, see note)
ToolsArea Miner, Auto Smelt, Experience Boost, Haste, Indestructible, Magnet, Oxygenate, Spawners Silk Touch, Telepathy, Timber, Treasure Hunter, Vein MinerBLOCK_BREAK
ToolsBedrock Breaker, Green Thumb, Night VisionPLAYER_INTERACT
ToolsAgricultural HarvestBLOCK_BREAK; it harvests the mature crops around the broken block (up to radius 8)
SpecialAquatic Speed, Feeder, Lava WalkerPLAYER_MOVE
SpecialElytra Boost, LaunchPLAYER_INTERACT
SpecialCurse of SluggishnessPLAYER_ATTACK
SpecialElytra ShieldENVIRONMENTAL_DAMAGE
SpecialSoulboundPLAYER_DEATH
UtilityClient Particle Effect, Give Enchantment Bookany

Commands​

The command is a Enchantment Command Manifest entry that you create. Its name, permission and messages are fields of the entry; the defaults are shown.

CommandDescription
/enchantcreator give <player> <enchant> [level]Give an enchanted book to an online player. <enchant> is the entry name or displayName, with underscores in place of spaces. Level defaults to 1.

Permissions​

PermissionGrants
enchantcreator.admin/enchantcreator give (the adminPermission field of the entry).

Entries​

75 entries, generated from the extension source.

Actions71
Commands1
Manifests3

Troubleshooting​

The effect does nothing. The action must match the mechanic's event (see the table above): an action reading a block-break event does nothing on PLAYER_ATTACK. The item must be in supportedItems, held in a hand or worn as armor, and the mechanic's criteria, chance and runOnLevel must pass. A mechanic with runOnLevel 2 only runs when the highest level is exactly 2.

The enchantment is missing in game. Definitions are registered when the extension starts, when a player joins, and when a book is given. Check the console for Failed to reflectively register or Failed to register enchantments during pre-login, and make sure the server is Paper 1.21 or later.

The book cannot be applied to my item. In the anvil, a book can only be applied to items listed in supportedItems. Two enchantments listed in each other's exclusiveWith cannot be combined: the anvil result is removed. This exclusivity is only enforced in the anvil.

Players never see my enchantment in the enchanting table. In the table, weight is used as a percentage: 1 means about a 1% chance per roll. Raise it, or set treasureChance and tradeChance to hand out books through loot and librarians. A weight of 0 disables the table offer.

/enchantcreator give says the enchantment is unknown. The name is matched against the entry name or displayName, lower-cased with spaces turned into underscores. Use the exact name from the entry, and publish the page first.

A vanilla enchantment still appears. The blacklist only removes offers from the enchanting table; anvils, loot and trades are not affected. The console reports Unable to resolve vanilla enchantments for blacklist if a name is invalid.