Описание
**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](https://www.mediafire.com/file/e0lrjb3hjy4tmk0/FunTalismans-1.21.1-to-26.2.zip/file) 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](https://modrinth.com/plugin/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:
```json
material: "totem_of_undying"
````
can use the custom `totemPop` system.
Example:
```json
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:
```text
vanillaEffects: true
```
Keeps the normal vanilla effects and also applies your custom effects.
```text
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:
```json
duration: 10
```
or Minecraft ticks:
```json
durationTicks: 200
```
20 ticks = 1 second.
`durationMode` is optional:
```json
durationMode: "SET"
```
Uses the configured duration.
```json
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:
```json
effects {
slot: "offhand"
ambient: true
particles: false
icon: true
list: [
{
type: "speed"
amplifier: 1
},
{
type: "fire_resistance"
amplifier: 0
}
]
}
```
Potion amplifiers are zero-based:
```text
0 = Level I
1 = Level II
2 = Level III
```
Effects may also override visual settings individually:
```json
{
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:
```json
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:
```json
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**:
```text
%player_name%
%player_world%
%player_uuid%
%player_gm%
```
Target-player variants are also available:
```text
%target_player_name%
%target_player_world%
%target_player_uuid%
%target_player_gm%
```
Example:
```json
if: "%player_gm% === SURVIVAL"
```
When PlaceholderAPI is installed, built-in placeholders and PlaceholderAPI placeholders can be used together.
Example:
```json
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:
```text
plugins/FunTalismans/talismans/
```
Subfolders are supported.
Example:
```text
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:
```text
/rg flag fun-talismans-passive deny
```
or:
```text
/rg flag 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:
```text
/ftalismans reload
```
after normal configuration changes.
Use:
```text
/ftalismans forceupdate
```
when you want a wider scan of already loaded talisman items.
---
## Commands
```text
/ftalismans give [amount]
/ftalismans reload
/ftalismans forceupdate
```
Aliases:
```text
/ft
/talisman
/tali
/talismans
```
Permissions:
```text
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.
```json
talismans {
infinity-totem {
# ------------------------------------------------------------
# ITEM IDENTITY
# ------------------------------------------------------------
name: "Infinity Talisman"
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.",
"",
"Passive: Speed, Resistance and regeneration",
"TotemPop: 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
```json
material: "player_head"
texture: "http://textures.minecraft.net/texture/"
```
`texture` accepts:
* Minecraft texture URLs.
* `base64:` values.
* Raw Base64 texture values.
### Dyed items
Compatible colored items such as leather armor can use:
```json
color: "#18FF00"
```
### Armor trims
Compatible armor can use:
```json
armorTrim {
material: "gold"
pattern: "silence"
}
```
### Fireworks
`firework_rocket` supports:
```json
fireworkData {
power: 2
effects: [
{
type: "BALL_LARGE"
trail: true
colors: ["#FF0000", "GOLD"]
fadeColors: ["#FFFFFF"]
}
]
}
```
### Goat horns
`goat_horn` supports:
```hocon
instrumentData {
instrument: "yearn_goat_horn"
}
```
### Written books
`written_book` supports:
```json
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](https://www.mediafire.com/file/e0lrjb3hjy4tmk0/FunTalismans-1.21.1-to-26.2.zip/file)
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:
```text
/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**.