FunTalismans

Custom Talismans, Spheres and Passive Equipment for Paper/Purpur 1.21.x and 26.x.

FunTalismans is a highly configurable RPG equipment system that allows server owners to create custom talismans, spheres, passive equipment and custom Totems of Undying using clean HOCON configuration files.

Create items with custom names, lore, models, attributes, passive potion effects, rarities, equipment requirements, advanced rules, custom TotemPop abilities and much more — without modifying plugin code.

Download the FunTalismans Resource Pack to preview and test the included custom talisman models in-game.

Compatibility

• Server software: Paper / Purpur
• Minecraft: 1.21.x, 26.1.x and 26.2
• Java: Java 21
• Configuration format: HOCON
• Required dependency: PacketEvents
• Optional integrations: WorldGuard and PlaceholderAPI
• Optional resource pack: Minecraft 1.21.1 through 26.2

FunTalismans does not require NBT-API.

Important: PacketEvents is required by current FunTalismans versions. Make sure it is installed before starting the server.

Features

• Create unlimited custom talismans, spheres and equipment items.
• Configure custom Totems of Undying with unique activation abilities.
• Apply custom effects when a talisman totem is consumed.
• Keep or completely disable the vanilla Totem of Undying potion effects.
• Display the talisman's own Custom Model Data during the totem activation animation.
• Reliable totem activation detection across different damage sources.
• Apply passive potion effects depending on where an item is equipped.
• Add attribute modifiers such as health, damage, speed, armor, attack speed, luck and more.
• Support main hand, offhand, armor slots and inventory passive effects.
• Configure custom names, lore, legacy colors, HEX colors and MiniMessage gradients.
• Use numeric or modern string Custom Model Data.
• Use player-head textures through Minecraft texture URLs, base64: values or raw Base64.
• Configure enchantments, glow, durability, unbreakable items and item flags.
• Configure custom maximum stack sizes.
• Add Persistent Data / custom NBT-style values.
• Create configurable rarity systems.
• Support armor trims and dyed equipment.
• Support custom fireworks, goat horns and written books.
• Create advanced world, region, permission and gamemode requirements.
• Build complex rules using and, or and oneof.
• Use built-in placeholders without PlaceholderAPI.
• Use PlaceholderAPI placeholders when PlaceholderAPI is installed.
• Use WorldGuard regions and shared global flags.
• Reload definitions without restarting the server.
• Safely update already existing talismans.
• Automatically load .conf files from the /talismans directory and its subfolders.

Custom TotemPop system

Any FunTalisman using:

material: "totem_of_undying"

can use the custom totemPop system.

Example:

totemPop {
  enabled: true
  vanillaEffects: false
  delayTicks: 1

  ambient: false
  particles: true
  icon: true

  effects: [
    {
      type: "speed"
      amplifier: 1
      duration: 10
    },
    {
      type: "strength"
      amplifier: 0
      durationTicks: 100
      durationMode: "SET"
    }
  ]
}

vanillaEffects controls the normal Minecraft Totem of Undying potion effects:

vanillaEffects: true

Keeps the normal vanilla effects and also applies your custom effects.

vanillaEffects: false

Keeps the resurrection mechanic but suppresses the normal vanilla Regeneration, Absorption and Fire Resistance effects.

Only the effects defined inside totemPop.effects are applied.

TotemPop duration

You can use seconds:

duration: 10

or Minecraft ticks:

durationTicks: 200

20 ticks = 1 second.

durationMode is optional:

durationMode: "SET"

Uses the configured duration.

durationMode: "ADD"

Adds the configured duration to a compatible existing effect.

If omitted, SET is used automatically.

Passive effects

Passive effects stay active while the talisman remains in a valid configured slot.

Supported slots:

• mainhand
• hand
• offhand
• hands
• head
• chest
• legs
• feet
• armor
• any
• inventory

Example:

effects {
  slot: "offhand"
  ambient: true
  particles: false
  icon: true

  list: [
    {
      type: "speed"
      amplifier: 1
    },
    {
      type: "fire_resistance"
      amplifier: 0
    }
  ]
}

Potion amplifiers are zero-based:

0 = Level I
1 = Level II
2 = Level III

Effects may also override visual settings individually:

{
  type: "regeneration"
  amplifier: 1
  ambient: false
  particles: true
  icon: false
}

inventory is intended for passive potion effects. Attribute modifiers should use equipment slots such as mainhand, offhand or armor slots.

Attributes

Talismans can add or modify Minecraft attributes.

Example:

attributes: [
  {
    type: "max_health"
    amount: 4.0
    operation: "ADD_NUMBER"
    slot: "offhand"
  },
  {
    type: "movement_speed"
    amount: 0.10
    operation: "ADD_SCALAR"
    slot: "offhand"
  },
  {
    type: "attack_damage"
    amount: 0.15
    operation: "MULTIPLY_SCALAR_1"
    slot: "mainhand"
  }
]

Supported operations include:

• ADD_NUMBER
• ADD_SCALAR
• MULTIPLY_SCALAR_1

Rules and requirements

Talismans can be restricted by:

• World
• World whitelist / blacklist
• WorldGuard region
• Region whitelist / blacklist
• Permission
• Gamemode
• Placeholder expressions
• Nested and conditions
• Nested or conditions
• Ordered oneof conditions

Example:

rules {
  gamemode: "SURVIVAL"
  permission: "funtalismans.example.use"

  worlds {
    enabled: true
    mode: "BLACKLIST"
    list: ["lobby", "spawn_world"]
  }

  regions {
    enabled: true
    mode: "BLACKLIST"
    list: ["safezone", "afk"]
  }

  or: [
    {
      world: "world"
    },
    {
      permission: "funtalismans.example.bypass"
    }
  ]

  denyActions {
    message: "&cYou do not meet the requirements to use this talisman."
    sound: "ENTITY_VILLAGER_NO"
  }
}

Rule actions respect the configured talisman slot. For example, an offhand passive talisman will not execute its rule actions while being held only in the main hand.

Built-in placeholders

FunTalismans includes internal placeholders that do not require PlaceholderAPI:

%player_name%
%player_world%
%player_uuid%
%player_gm%

Target-player variants are also available:

%target_player_name%
%target_player_world%
%target_player_uuid%
%target_player_gm%

Example:

if: "%player_gm% === SURVIVAL"

When PlaceholderAPI is installed, built-in placeholders and PlaceholderAPI placeholders can be used together.

Example:

if: "%player_gm% === SURVIVAL && %vault_eco_balance% >= 1000"

FunTalismans resolves its internal placeholders first and then processes PlaceholderAPI placeholders.

Automatic talisman configuration loading

FunTalismans automatically loads .conf files located inside:

plugins/FunTalismans/talismans/

Subfolders are supported.

Example:

plugins/FunTalismans/talismans/
├── talismans.conf
├── spheres.conf
├── example.conf
├── events/
│   ├── halloween.conf
│   └── christmas.conf
└── custom/
    └── server-talismans.conf

Bundled .conf files included with the plugin are automatically exported when they do not already exist.

Existing configuration files are never automatically overwritten.

This allows future FunTalismans releases to include additional example or content packs without requiring every file to be manually registered.

WorldGuard support

WorldGuard integration is optional.

FunTalismans uses shared global flags instead of creating a separate flag for every talisman.

• fun-talismans-passive controls passive talisman effects inside a region.
• fun-talismans-use controls general talisman use mechanics.

Example:

/rg flag <region> fun-talismans-passive deny

or:

/rg flag <region> fun-talismans-use deny

Region requirements can also be configured directly inside individual talisman rules.

Restart the server when changing custom WorldGuard flag names in config.conf.

Normal talisman configuration changes can use /ftalismans reload.

Live reload and item updates

FunTalismans can reload talisman definitions without requiring a normal server restart.

The item update system can safely refresh talismans stored in:

• Player inventories.
• Main hand and offhand.
• Armor slots.
• Dropped items near online players.
• Item Frames.
• Glow Item Frames.
• Open containers.
• Chests.
• Shulker Boxes.
• Loaded chunks through configurable per-tick limits.

This allows administrators to rebalance attributes, change effects, replace models or update lore while keeping already-created talismans synchronized.

Use:

/ftalismans reload

after normal configuration changes.

Use:

/ftalismans forceupdate

when you want a wider scan of already loaded talisman items.

Commands

/ftalismans give <player> <id> [amount]
/ftalismans reload
/ftalismans forceupdate

Aliases:

/ft
/talisman
/tali
/talismans

Permissions:

funtalismans.give
funtalismans.reload
funtalismans.update

Complete custom Totem Talisman example

The following example demonstrates most options that are relevant to a custom Totem of Undying talisman.

talismans {

  infinity-totem {

    # ------------------------------------------------------------
    # ITEM IDENTITY
    # ------------------------------------------------------------

    name: "<gradient:#18FF00:#50FFA4><b>Infinity Talisman</b></gradient>"
    material: "totem_of_undying"
    rarity: "epic"

    # Numeric Custom Model Data.
    custom_model_data: 101

    # Modern string Custom Model Data can also be used instead:
    # custom_model_data: "funtalismans:infinity_totem"

    lore: [
      "",
      "&7A mysterious talisman that protects its owner.",
      "&7Equip it in the offhand to activate its passive power.",
      "",
      "<#18FF00>Passive: <#FFFFFF>Speed, Resistance and regeneration",
      "<#18FF00>TotemPop: <#FFFFFF>Custom resurrection effects",
      ""
    ]

    # ------------------------------------------------------------
    # BASIC ITEM OPTIONS
    # ------------------------------------------------------------

    unbreakable: false

    # Adds visual enchantment glow.
    glow: true

    # Disables enchantment glint even if enchantments/glow exist.
    disableEnchantGlow: false

    # false = item disappears normally when the player dies.
    keepItemOnDeath: false

    # Usually false for a totem.
    glider: false

    # ------------------------------------------------------------
    # CUSTOM STACK SIZE
    # ------------------------------------------------------------

    useMaxStack: false
    maxStack: 1

    # ------------------------------------------------------------
    # DURABILITY
    # ------------------------------------------------------------

    # Usually unnecessary for a Totem of Undying.
    # -1 means FunTalismans does not force the value.

    damage: -1
    maxDurability: -1
    durability: -1
    isDurabilityBasedOnUsage: false

    # ------------------------------------------------------------
    # DEFAULT MATERIAL ATTRIBUTES
    # ------------------------------------------------------------

    keepDefaultAttributes: true
    ignoreKeepDefaultAttributesFeature: false
    sumDefaultAttributes: false

    # ------------------------------------------------------------
    # DROPPED ITEM SETTINGS
    # ------------------------------------------------------------

    dropSettings {
      glowDrop: true
      glowDropColor: "GREEN"
      displayNameDrop: true
    }

    # ------------------------------------------------------------
    # ITEM FLAGS
    # ------------------------------------------------------------

    flags: [
      "hide_attributes",
      "hide_enchants",
      "hide_unbreakable"
    ]

    # ------------------------------------------------------------
    # ENCHANTMENTS
    # ------------------------------------------------------------

    enchantments {
      unbreaking: 3
    }

    # ------------------------------------------------------------
    # ATTRIBUTES
    # ------------------------------------------------------------

    attributes: [
      {
        type: "max_health"
        amount: 4.0
        operation: "ADD_NUMBER"
        slot: "offhand"
      },
      {
        type: "movement_speed"
        amount: 0.05
        operation: "ADD_SCALAR"
        slot: "offhand"
      }
    ]

    # ------------------------------------------------------------
    # PASSIVE EFFECTS
    # ------------------------------------------------------------

    effects {
      slot: "offhand"

      ambient: true
      particles: false
      icon: true

      list: [
        {
          type: "speed"
          amplifier: 1
        },
        {
          type: "fire_resistance"
          amplifier: 0
        },
        {
          type: "water_breathing"
          amplifier: 0
        },
        {
          type: "health_boost"
          amplifier: 0
        },
        {
          type: "regeneration"
          amplifier: 0
        },
        {
          type: "resistance"
          amplifier: 0
        }
      ]
    }

    # ------------------------------------------------------------
    # CUSTOM TOTEM POP
    # ------------------------------------------------------------

    totemPop {

      enabled: true

      # true:
      # Keep vanilla Regeneration, Absorption and Fire Resistance.
      #
      # false:
      # Keep resurrection but suppress vanilla potion effects.
      vanillaEffects: false

      # Delay before applying custom effects.
      delayTicks: 1

      # Default visual settings for all TotemPop effects.
      ambient: false
      particles: true
      icon: true

      effects: [

        {
          type: "speed"

          # amplifier 0 = Speed I
          # amplifier 1 = Speed II
          amplifier: 1

          # Duration in seconds.
          duration: 10

          # Optional. Defaults to SET.
          durationMode: "SET"
        },

        {
          type: "strength"
          amplifier: 0

          # Alternative duration using Minecraft ticks.
          # 20 ticks = 1 second.
          durationTicks: 100

          durationMode: "SET"

          # Per-effect visual overrides.
          ambient: false
          particles: true
          icon: true
        },

        {
          type: "regeneration"
          amplifier: 1
          duration: 5

          # ADD adds time to a compatible existing effect.
          durationMode: "ADD"
        }
      ]
    }

    # ------------------------------------------------------------
    # RULES
    # ------------------------------------------------------------

    rules {

      # Native gamemode rule.
      gamemode: "SURVIVAL"

      # Optional permission requirement.
      permission: "funtalismans.infinity.use"

      # Built-in placeholder expressions are supported.
      #
      # Examples:
      #
      # if: "%player_gm% === SURVIVAL"
      #
      # With PlaceholderAPI:
      #
      # if: "%player_gm% === SURVIVAL && %vault_eco_balance% >= 1000"

      worlds {
        enabled: true

        # BLACKLIST / DENY / BLOCK
        # WHITELIST / ALLOW / ONLY
        mode: "BLACKLIST"

        list: [
          "lobby",
          "spawn_world"
        ]
      }

      regions {
        enabled: true
        mode: "BLACKLIST"

        list: [
          "safezone",
          "afk"
        ]
      }

      # All entries in `and` must pass.
      and: [
        {
          gamemode: "SURVIVAL"
        }
      ]

      # At least one entry in `or` must pass.
      or: [
        {
          world: "world"
        },
        {
          permission: "funtalismans.infinity.bypass"
        }
      ]

      # ONEOF checks entries in order and selects the first valid one.
      #
      # Actions only run while the talisman is in a valid configured slot.
      oneof: [

        {
          region: [
            "pvp",
            "arena"
          ]

          actions {
            message: "&cCombat talisman mode enabled."
            sound: "entity.player.levelup"
          }
        },

        {
          gamemode: "SURVIVAL"

          actions {
            message: "&aStandard talisman mode enabled."
            sound: "block.amethyst_block.chime"
          }
        }
      ]

      denyActions {
        message: "&cYou do not meet the requirements to use this talisman."
        sound: "entity.villager.no"
      }
    }

    # ------------------------------------------------------------
    # CUSTOM PERSISTENT DATA
    # ------------------------------------------------------------

    nbt {
      category: "totem"
      series: "infinity"

      power: 100
      multiplier: 1.25

      tradeable: true

      "1" {
        key: "custom_example"
        value: "example_value"
      }
    }
  }
}

Remove any section that your talisman does not need.

Material-specific configuration

Some FunTalismans options only make sense for specific Minecraft materials and are therefore not included in the Totem of Undying example above.

Player Heads

material: "player_head"

texture: "http://textures.minecraft.net/texture/<texture-id>"

texture accepts:

• Minecraft texture URLs.
• base64: values.
• Raw Base64 texture values.

Dyed items

Compatible colored items such as leather armor can use:

color: "#18FF00"

Armor trims

Compatible armor can use:

armorTrim {
  material: "gold"
  pattern: "silence"
}

Fireworks

firework_rocket supports:

fireworkData {
  power: 2

  effects: [
    {
      type: "BALL_LARGE"
      trail: true
      colors: ["#FF0000", "GOLD"]
      fadeColors: ["#FFFFFF"]
    }
  ]
}

Goat horns

goat_horn supports:

instrumentData {
  instrument: "yearn_goat_horn"
}

Written books

written_book supports:

bookData {
  author: "FunTalismans"
  title: "&5&lAncient Tome"

  pages: [
    "&7Page one...",
    "&7Page two..."
  ]
}

Optional Resource Pack

The optional FunTalismans Resource Pack contains custom models designed for FunTalismans talismans and custom totems.

• Supports Minecraft clients from 1.21.1 through 26.2.
• Supports legacy and modern Custom Model Data formats.
• Includes custom totem models.
• Supports the custom TotemPop activation animation.
• Optimized model display for first person, third person, dropped items and GUI views.

Download the FunTalismans Resource Pack

Use the matching custom_model_data value in your talisman configuration to display the correct model.

Installation and updating

For a clean installation:

1. Stop the server.
2. Install PacketEvents.
3. Place the FunTalismans .jar inside /plugins.
4. Start the server.
5. Configure your talismans.
6. Install the optional resource pack if you use custom models.

When updating FunTalismans:

1. Stop the server completely.
2. Create a backup of /plugins/FunTalismans/.
3. Replace the old FunTalismans .jar.
4. Update PacketEvents if required by your Minecraft version.
5. Start the server normally.
6. Review new configuration examples or options.
7. Update the optional resource pack when a newer version is available.

Avoid using /reload, PlugMan or other plugin hot-reload systems when replacing the FunTalismans JAR.

Normal configuration changes can use:

/ftalismans reload

Notes

• PacketEvents is required.
• WorldGuard is optional.
• PlaceholderAPI is optional.
• Built-in FunTalismans placeholders work without PlaceholderAPI.
• The core plugin does not require NBT-API.
• Always create a backup before replacing configuration files.
• Use /ftalismans reload after normal configuration changes.
• Use /ftalismans forceupdate when existing talisman items need a wider refresh.
• Existing automatically exported .conf files are not overwritten.
• Additional .conf files inside the /talismans directory and its subfolders are loaded automatically.
• Use a full server restart when updating the plugin JAR.

FunTalismans provides a flexible foundation for RPG progression, collectible equipment, custom combat mechanics, passive artifacts, custom totems and configurable server progression systems.