CloudTotems — the totem that doesn't end after the first save

The vanilla Totem of Undying is a one-use consumable. It triggers, vanishes, and is forgotten. CloudTotems breaks that rule: a totem holds charges and survives not one save but several in a row. And it doesn't just leave you standing at half a heart in the middle of a crowd — each totem type has its own ability that fires at the moment of the save. A knockback wave, an explosion at the death site that can't hurt you, a teleport away from danger, an army of summoned mobs, a full heal, mirrored thorns, or plain but reliable invulnerability for a few seconds. One item in your left hand — ten different answers to "what happens if you get killed".

The plugin doesn't invent anything on top of the vanilla mechanic: same item material, same slot, same "would have died — didn't" principle. But behind that facade is a precise damage-handling priority system, owner tags via PersistentDataContainer, and ten fully configurable abilities where every number (radius, second, effect level, mob count) is a line in config.yml, not a constant in code.

Ten totems — ten different answers to the same question: "what do you do when you almost got killed".

What it is and how it works

Visually, a CloudTotems totem is the same TOTEM_OF_UNDYING item as in vanilla: the same material name, the same sound (ITEM_TOTEM_USE), and the same particle (TOTEM_RESURRECT) when it triggers. The difference is in the item metadata. Each totem has a type encoded in PersistentDataContainer (keys totem_type and totem_charges in the totems namespace), its own colored name, and a charge counter that shows right in the item tooltip and drops by one with each save. Charges and type are stored on the item itself, not in a separate database — so they survive being dropped on the ground, a chest, dying without using the totem, and a server restart with no loss.

The totem must be held in the left hand (offhand) — the plugin checks only that slot, and in the main hand a totem will never trigger. It fires not on any damage but only on lethal damage: the plugin compares the final damage of the hit (after armor and enchantments) with the player's current health, and if the hit is smaller the totem stays silent, the charge stays intact, and the event proceeds as normal.

Hit processing order

The damage listener runs at HIGHEST priority and processes each hit on a player in strict order — this is not a minor detail, the order really changes the outcome:

• Blessing. If the player has an active invulnerability window, the damage is canceled entirely and immediately, with no further checks. Even if the hit is lethal and there's a totem in the offhand, no charge is spent: the event is canceled before the plugin gets a chance to look at the left hand.
• Your own summoned mob. Damage from a creature marked as summoned by that same player (the Summon totem) is canceled unconditionally — regardless of health, blessing, and everything else.
• Thorns. If the player has an active thorns window, damage to the attacker is mirrored in the same amount. The player still takes damage too, nothing is blocked — it's not a shield, it's a trade.
• Lethal damage + totem in the offhand. Only if the previous three checks didn't apply and the hit can still kill does the save begin.

The save: charge, health, effects

On a save, the plugin zeroes the damage, deducts one charge from the item in the offhand (if it was the last charge, the totem disappears from the inventory by itself), sets health, and extinguishes the player if they were burning. Health after the save is calculated by the formula Math.max(0.5, Math.min(revive-hp, макс. здоровье игрока)). In practice this means: the config value (1.0 by default, i.e. half a heart — like the vanilla totem) won't let health exceed the player's maximum from above and won't drop it below 0.5 HP from below, even if the config mistakenly has 0 or a negative number. An instant second death is technically ruled out.

The ability launches not on the same tick but on the next one — as a separate scheduler task. This is deliberate, so that the ability call (teleport, explosion, mob summon) doesn't overlap with a damage event that hasn't been fully processed yet.

Ten totem types

Ability radii (Wave, Blindness, Summon) are a cube around the player along the X/Y/Z axes, not a perfect sphere; in practice the difference is noticeable only at the very edge of the zone. The effect level in the config (for example, speed-level: 2) is exactly the level the player sees on screen (II); the plugin handles conversion to the amplifier.

Totem of Power — buff

Three positive effects at once for 30 seconds (abilities.buff.duration-seconds): Speed II (speed-level: 2), Jump Boost III (jump-level: 3), Strength I (strength-level: 1). All three apply as one package and last exactly half a minute, regardless of what exactly almost killed the player.

Totem of the Wave — shockwave

Knocks back all living entities in an area of 8 blocks (radius: 8.0) from the player — except the player. The knockback direction is calculated from the player to the target, the force is 2.5 (power), plus a fixed vertical lift of 0.6 on top regardless of force — so the crowd doesn't just scatter horizontally but also hops up. If an enemy is standing right up against you (zero direction vector), the knockback goes straight up.

Totem of Teleport — teleport

Moves you to a random point within 50 blocks (radius: 50) — X and Z are calculated independently, each in the range −50…+50, so in a straight line from the player's death point you can sometimes be carried as far as 70 blocks diagonally. The landing height is taken from the actual terrain (the highest block in the column +1) — the player is guaranteed to end up on the surface, not hanging in the air or stuck in rock. Fall distance is reset before the teleport, so the move itself deals no damage.

Totem of Detonation — detonation

An explosion right at the save location with a power of 4.0 (power, marked in the config as the "creeper level"), which by default breaks blocks (break-blocks: true) and doesn't set fires (set-fire: false). The explosion doesn't hurt its owner: for 2 game ticks (0.1 seconds) the plugin makes the player invulnerable right before triggering the explosion and immediately restores the previous invulnerability status — the protection is designed specifically for your own explosion, not as permanent armor.

Totem of Blessing — blessing

Opens a window of full invulnerability for 5 seconds (abilities.blessing.seconds). This isn't damage reduction — it cancels the damage event entirely, from any source, at the earliest stage of processing. A side effect: for all 5 seconds, lethal hits never reach the "is there a totem in the offhand" check at all, which means they don't spend charges on any totem while this window lasts.

Totem of Heavenly Wrath — heavenly_wrath

Launches the player straight up 55 blocks (height) from the save location and immediately applies Slow Falling I for 15 seconds (slow-fall-seconds). Fall distance is reset to zero before the teleport, so the launch itself doesn't count toward later fall damage — and 15 seconds of gentle descent is usually more than enough to land safely.

Totem of Summoning — summoner

Summons 10 to 15 mobs (count-min / count-max, the number is random within that range each time) in an area of 5 blocks (radius) around the player, from the set ZOMBIE, SKELETON, HUSK, CREEPER (types — the same set is hardcoded as a fallback if the list in the config is empty). Each mob lands at the actual terrain height rather than floating in the air. These mobs don't touch their owner, with double insurance: they physically never pick the owner as a target (the targeting event is intercepted), and even accidental damage from a tagged mob or its projectile is separately canceled in the damage handler. But the tag protects only the owner — for other players and allies nearby it's an ordinary hostile crowd.

Totem of Blindness — blindness

Blinds all living entities in an area of 10 blocks (radius) for 5 seconds (seconds) — with no friend-or-foe distinction: hostile mobs, pets, allies, and villagers all get hit if they happen to be close enough at the moment of the save.

Totem of the Fortress of Spirit — fortress

The only type without separate numeric settings in the config and the only one where health after the save isn't limited by the revive-hp value. On the save tick, health first drops to the shared value like everyone else's (half a heart by default), and on the next tick the ability forcibly sets it to the player's maximum (the GENERIC_MAX_HEALTH attribute, 20 by default) — visually it feels like an instant full heal right after the save.

Totem of Thorns — thorns

Opens a window of 10 seconds (abilities.thorns.seconds) during which every hit the player takes from a creature (including from a projectile — then the shooter takes it, not the arrow) is mirrored back at the same amount of final damage. The key point: it's not a block — the player takes damage as usual, and the totem merely punishes the attacker with the same number. There is nothing to reflect from falling, lava, hunger, or suffocation — the effect reacts only to hits from creatures.

How to tell totems apart in your inventory

Each type has its own colored item name so you don't mix them up in the heat of a fight:

• buff — yellow
• shockwave — light blue (aqua)
• teleport — light purple
• detonation — red
• blessing — white
• heavenly_wrath — blue
• summoner — dark green
• blindness — dark gray
• fortress — gold
• thorns — dark red

The item tooltip is always built from four lines: the ability description, an empty line, "Charges: N", and the reminder "Hold in your left hand." — the charge counter in the tooltip updates on every save.

Windows and combinations

Eight of the ten abilities fire once, at the moment of the save, and that's it. Blessing and Thorns work differently — they don't "fire" once but open a window in time, inside which a rule applies (full invulnerability or damage mirroring), set by a separate per-player timer.

Several non-obvious combinations follow from this:

• The plugin looks only at the item in the offhand at the moment of the hit — you can freely carry several types in your inventory, and only the one physically moved to the left hand takes effect.
• A totem with several charges saves as many times as it has charges: three lethal hits in a row — three saves, three ability launches, three charges spent.
• When Blessing triggers, it effectively pauses charge consumption of any totems for 5 seconds — the damage is canceled before the plugin gets a chance to look at the offhand.
• Thorns, by contrast, don't interfere with the next save: if a new lethal hit lands during their 10 seconds and there's a totem in the offhand, both effects fire at once: the player is saved, and the attacker simultaneously takes mirrored damage.
• revive-hp applies to nine of the ten types — Fortress of Spirit ignores it and heals to full health one tick later.

How to use: scenarios

Pick the totem type for the situation rather than carrying one for every case — changing the type is just "move a different item to the left hand".

PvP and arenas. Thorns punish whoever tries to finish you off right after the save. Blessing gives 5 seconds of iron armor to break out of an encirclement or, conversely, to finish the fight yourself. Wave scatters opponents crowding around you. Blindness takes out a crowd for 5 seconds, but note: it will hit allies too if they're nearby.

Farming and grinding (mob farms, dangerous trips). Fortress of Spirit is a full heal without potions or food, the most predictable option for long farming. Summoning: 10-15 mobs draw danger onto themselves and give XP/drops, but they don't distinguish allies from random players nearby. Heavenly Wrath gets you out of a dense crowd vertically, with 15 seconds in the air to think.

Survival and expeditions. Teleport takes the player away from lava, a cave-in, or another mob wave, up to 70 blocks diagonally. Detonation clears rubble or a site with an explosion without risk of hitting yourself. Power gives 30 seconds of speed, jump boost, and damage after the save, to quickly leave a dangerous spot or, conversely, finish whatever almost killed you.

The general rule: keep 2-3 types at hand (in neighboring hotbar slots) and move the one you need to the offhand in advance, before a risky action — not after the hit has already landed.

Commands

Examples: /totem give Виталий buff 5 gives a "Totem of Power" with 5 charges; /totem give Виталий fortress without a number gives a "Totem of the Fortress of Spirit" with the default charges from the config; /totem list shows all ids at once: buff, shockwave, teleport, detonation, blessing, heavenly_wrath, summoner, blindness, fortress, thorns.

An important nuance of give: the player is looked up only among those currently on the server (exact name match) — you can't give a totem to an offline player this way. If a number of charges is specified, it can't be less than 1 — the plugin raises any lower value to 1 itself. An unknown type replies "Unknown type: … (see /totem list)", and non-numeric charges reply "Charges must be a number."

The command responds to the aliases /totems, /тотем, /тотемы. Tab completion works on all three arguments: the first is give/list/reload, the second (after give) is the names of online players, and the third is the totem type ids.

Permissions

One nuance worth knowing in advance: the totem.use permission is declared in plugin.yml and granted to everyone by default, but the save mechanic in the code doesn't check it separately — it works for anyone who physically has a totem in the offhand, regardless of permissions. In practice this rarely matters since the permission is on for everyone anyway, but if you ever need to forbid a specific group from using totems, the plugin has no built-in check for that, and you'll need an external permissions layer on top.

Configuration and compatibility

CloudTotems is a plugin for Paper 1.19.4 (api-version: "1.19"). Every number from the breakdown above is not a constant in code but a line in config.yml: health after the save, default charges, effect durations and levels, radii, explosion and knockback power, and the composition of summoned mobs. Change a value, run /totem reload, and the server picks up the new rules without a restart. The list of ten types is hardcoded (it isn't configurable), but the strength and duration of each lives entirely in the config.

The full list of configurable config.yml blocks:

• revive-hp — health after the save (1.0 by default)
• default-charges — default charges for /totem give without a number (3)
• abilities.buff — duration and levels of speed/jump boost/strength
• abilities.shockwave — knockback radius and power
• abilities.teleport — teleport radius
• abilities.detonation — explosion power, whether it breaks blocks, whether it sets fires
• abilities.blessing — invulnerability duration
• abilities.heavenly-wrath — launch height and slow-fall seconds
• abilities.summoner — minimum/maximum mobs, radius, type list
• abilities.blindness — blindness radius and seconds
• abilities.thorns — reflection seconds

The license block lives separately in the config — the plugin's license check: enabled (false by default — the license is off for testing, and the plugin starts with no restrictions at all), the license server's key and url, and grace-hours (24 by default) — how many hours the plugin keeps working from the local cache if the license server is temporarily unavailable. The check runs once, when the plugin is enabled, before commands and event handlers are registered.

The vanilla totem gives you one chance not to die. CloudTotems gives you ten ways to decide what happens next — and leaves you the right to rewrite any number behind that decision.