Tether Players

Two souls. One lifeline. Tether players into a group, share every hit, and turn teamwork into a real mechanic.

---

🔗 About Tether Players

Tether Players is a co-op survival mechanic that binds players into a tethered group with one shared lifeline. Every hit on one member is mirrored to the others, and the bond lasts until the group itself decides to break it.

Unlike classic "party" plugins, the bond here is physically real: damage is transferred fully by default, the group is limited in size, leadership is passed automatically when the leader leaves, and every join or leave is celebrated with sounds, particles and chat messages. It turns ordinary survival and PvP into a tense co-op experience where one player's mistake hurts everyone.

The plugin is fully configurable: damage sharing, distance limits, passive effects, HUD mode, group size, session duration and join/leave effects can all be tuned — or switched off to keep a pure damage link.

---

✨ Features

👥 Tether Groups

• Create a group with /tether create — your friends join with /tether join <player>.
• Up to 4 members by default (max-group-size).
• Kick (/tether kick), leave (/tether leave) and disband (/tether disband) with leader-only control.
• If the leader leaves, dies or gets kicked, leadership is passed automatically to the next online member — no stuck groups.

🩸 Shared Damage

• 100% of every hit on one member is mirrored to the other members by default (share-percent, no cap).
• Exact HP mirroring (raw-share: true) — the partner loses the same hearts, armour is not applied twice.
• Members don't damage each other (configurable friendly-fire multiplier).
• Shared damage is reported in chat, so everyone knows who is hurting whom.

♾️ Unlimited Lifetime

• The tether has no time limit by default — it lives until players leave, get kicked or disband the group.
• The HUD shows ∞ while unlimited.
• Prefer timed sessions? Set duration above 0 and the group gets a countdown that /tether extend <minutes> can push up to max-duration.

📏 Optional Distance Rules

• Out of the box the tether has no distance limit: members can be anywhere on the map.
• Want classic tension? Set max-distance / break-distance and get warning particles, sounds, debuffs and snap damage with lightning or pull-back.

📊 HUD

• Boss bar or action bar with group size, distance to the leader and time left.
• Boss bar turns red and fills with tension when distance rules are enabled and the limit is close.

🎉 Join & Leave Effects

• Fun sound + particle burst when a player joins a group (totem by default) and when a player leaves or is kicked (soul particles by default).
• Fully configurable in effects: — or disable with effects.enabled: false.

💀 Death Handling

• A member's death removes them from the group and notifies the others.
• Optional partner-death damage and regeneration/XP sharing are available, but off by default for a pure damage link.

🌍 Localization

• Complete English and Russian message files out of the box.
• Per-player language via the tether.lang.ru permission.

🛠️ Developer API

• TetherCreateEvent — fired before a player joins a group, cancellable.
• TetherBreakEvent — fired when a member leaves or is removed, with reason (EXPIRED, COMMAND, DISTANCE, DEATH, LOGOUT, FORCE, PLUGIN_DISABLE).
• TetherDamageShareEvent — fired when damage is transferred, cancellable.

🔔 Quality of Life

• Update notifications for admins with a clickable download link, shown on every join.
• /tether reload keeps the previous config if the new one is broken.
• Anonymous bStats metrics (id 34810), fully disableable.

---

🎮 Commands

Command	Description	Permission
/tether create	Create a group	tether.use
/tether join <player>	Join a player's group	tether.use
/tether leave	Leave your group	tether.use
/tether group	Show group info (members, roles, distance, time)	tether.use
/tether extend <minutes>	Extend the tether (timed mode only)	tether.use
/tether kick <player>	Kick a member	tether.use + leader
/tether disband	Disband the group	tether.use + leader
/tether list	List all active groups	tether.admin
/tether force <a> [b]	Force a group between players or break it	tether.admin
/tether reload	Reload the configuration	tether.admin
/tether help	Show command list	—

Alias: /teth. Full tab-completion for subcommands and player names.

---

🔑 Permissions

Permission	Default	Description
tether.use	true	Use the tether commands
tether.admin	op	list, force, reload
tether.bypass	op	Ignore tether restrictions
tether.lang.ru	false	Receive Russian messages

---

⚙️ Default Configuration

prefix: '&f[&cTether Players&f]'
language: en
max-group-size: 4
duration: 0                    # seconds, 0 = unlimited (until players leave or disband)
max-duration: 3600             # only for timed mode: cap for /tether extend

# Damage: 100% mirrored, no cap, exact HP
share-percent: 100.0
max-share-damage: 0.0
raw-share: true
friendly-fire-multiplier: 0.0

# Distance: 0 = no limit, no strain, no snapping
max-distance: 0.0
break-distance: 0.0
snap-damage: 0.0
snap-effect: NONE
pull-mode: NONE

# Passive effects (off = pure damage link)
partner-death-damage: 0.0
regen: false
xp-share-percent: 0.0

# Visuals
visuals: false
sounds: true
hud: BOSSBAR
bossbar-color: RED

# Fun effects on joining / leaving a group
effects:
  enabled: true
  join-sound: ENTITY_PLAYER_LEVELUP
  leave-sound: BLOCK_BEACON_DEACTIVATE
  join-particle: TOTEM_OF_UNDYING
  leave-particle: SOUL_FIRE_FLAME

---

📦 Installation

1. Pick the jar that matches your server:
   • TetherPlayers-1.2-1.20.jar — Paper 1.20.x
   • TetherPlayers-1.2-1.21.jar — Paper 1.21.x
   • TetherPlayers-1.2-26.1.jar — Paper 26.1.x
   • TetherPlayers-1.2-26.3.jar — Paper 26.3.x
2. Drop it into your plugins/ folder and restart the server.
3. Open plugins/TetherPlayers/config.yml and tune it to your server.
4. Run /tether reload — done.

No dependencies required. Messages live in messages_en.yml / messages_ru.yml.

---

🧩 Compatibility

Platform	Supported
Paper 1.20.x	✅ (-1.20 jar, Java 17+)
Paper 1.21.x	✅ (-1.21 jar, Java 21+)
Paper 26.1.x	✅ (-26.1 jar, Java 25+)
Paper 26.3.x	✅ (-26.3 jar, Java 25+)
Spigot / Bukkit	❌ (Paper API required)
Folia	❌
Proxies (BungeeCord, Velocity)	❌

---

💬 Support

• Issues and suggestions: use the Modrinth issue tracker of this project.

---

Tether Players — because sometimes one player is not enough.