📢 Ancient-Broadcast

Ancient-Broadcast is a modern, lightweight, and highly configurable broadcast plugin for Paper / Spigot 1.20+, built with Java 21.
✨ Designed to be lag-free, scalable, and easy to manage for both small and large servers.

Ancient-Broadcast allows server owners to send professional-looking broadcasts to all online players, either automatically on a schedule ⏱️ or manually via commands 🧑‍💻. Everything can be configured in-game or via the configuration file.

---

🧩 What Ancient-Broadcast does

Ancient-Broadcast periodically sends messages (broadcasts) to all online players 👥.

Every broadcast is always sent in the same clean format 🧼:

• ➖ one empty spacer line
• 📢 the broadcast message block (single-line or multi-line group)
• ➖ one empty spacer line

🔊 Optionally, a sound is played for all players when the broadcast is sent.
This keeps chat readable and prevents spam 🚫.

---

✨ Features (complete and explained)

⏱️ Scheduled broadcasts

Each broadcast has its own scheduler and runs independently from others.
Supported interval units:

• ⏲️ SECONDS
• ⏰ MINUTES
• 🕒 HOURS

This allows you to run multiple broadcasts at different intervals at the same time.

---

🔁 Rotation system

If a broadcast contains multiple messages or multiple groups, rotation can be enabled.

Rotation modes:

• 🔢 SEQUENTIAL – messages or groups are sent in order
• 🎲 RANDOM – a random message or group is selected each time

Rotation is controlled globally and can be enabled, disabled, and switched between modes.

---

⭐ Grouped broadcasts (multi-line as ONE broadcast)

Grouped broadcasts allow multiple lines to be linked together and sent as one complete broadcast block.

🔄 Rotation happens per group, not per line.

Grouped broadcasts are ideal for:

• 💡 tips with multiple lines
• 📣 announcements
• 🏷️ server information blocks
• 🔗 messages containing clickable links

When sent, a grouped broadcast appears between one spacer line above and one spacer line below.

---

🎨 Colors & formatting

Ancient-Broadcast supports both modern and classic formatting systems.

🧩 MiniMessage is fully supported, including colors, gradients, formatting, and click events.

🎨 Minecraft & color codes are also supported:

• &0 – &9
• &a – &f
• &l bold
• &o italic
• &n underline
• &m strikethrough
• &k magic
• &r reset
• 🌈 HEX colors using &#RRGGBB

MiniMessage and & color codes can be mixed in the same message.

---

🔗 Clickable links & websites

Clickable links are supported using MiniMessage click events 🖱️.

This allows linking:

• 🌍 websites
• 💬 Discord invites
• 🛒 web shops
• 🔗 any external URL

---

🔊 Sounds

Each broadcast can optionally play a sound 🎵.

Sound features:

• 🔇 enable or disable sounds per broadcast
• 🔔 choose a custom sound per broadcast
• 🔊 custom volume
• 🎚️ custom pitch
• 🎛️ a global default sound

The default sound is also used by the broadcast-now command.

📄 On first startup, the plugin automatically generates a sounds.yml file in the plugin folder.
This file contains all valid sound names you can use in the configuration or commands.

---

🔌 PlaceholderAPI support

If PlaceholderAPI is installed, placeholders work automatically 🧩.

Examples:

• %player_name%
• %vault_eco_balance%

Placeholders are resolved per player, meaning each player sees their own data 👤.

PlaceholderAPI is optional — the plugin works perfectly without it.

---

⚡ Performance & optimization

Ancient-Broadcast is optimized to be fast and lag-free 🚀:

• ⚙️ uses the Paper scheduler
• 🚫 no blocking operations
• 🧠 cached message parsing
• 🔍 PlaceholderAPI only used if installed and needed
• 🛡️ safe sound resolution (Paper 1.21+ compatible)

---

📦 Requirements

• ☕ Java 21
• 🧱 Paper / Spigot 1.20+ (Paper recommended)
• 🧩 Optional: PlaceholderAPI

---

🚀 Installation

1️⃣ Download the Ancient-Broadcast jar file
2️⃣ Place it into the server plugins folder
3️⃣ Start the server once (generates config.yml and sounds.yml)
4️⃣ Edit plugins/Ancient-Broadcast/config.yml
5️⃣ Apply changes using /ab reload
6️⃣ Enable broadcasting globally using /ab toggle

⚠️ The plugin is disabled by default.

---

🔐 Permissions

All commands require OP or the following permission 🔑:

ancientbroadcast.admin

Default: OP

---

🧑‍💻 Commands (complete list with explanation)

📋 General

• /ab help – 📖 shows all available commands
• /ab reload – 🔄 reloads the configuration file
• /ab toggle – 🔌 global enable or disable switch
• /ab list – 📄 lists all broadcasts and their status

📢 Broadcast management

• /ab add <id> – ➕ create a new broadcast
• /ab remove <id> – ❌ delete a broadcast
• /ab enable <id> – ✅ enable a broadcast
• /ab disable <id> – 🚫 disable a broadcast

✏️ Message editing

• /ab setmessage <id> <message> – ✍️ set a single message (overwrites groups and messages)
• /ab addline <id> <message> – ➕ add a rotating single-line message
• /ab clearlines <id> – 🧹 clear rotating messages

⭐ Grouped broadcast management

• /ab addgroup <id> – 📦 add a new empty group
• /ab addgroupline <id> <groupIndex> <message> – 📝 add a line to a group (groupIndex starts at 0)
• /ab listgroups <id> – 📊 list all groups and line counts

⏲️ Interval & scheduler

• /ab setinterval <id> <value> <SECONDS|MINUTES|HOURS>

🔊 Sounds

• /ab setsound <id> <on|off> [sound] [volume] [pitch]
• /ab defaultsound <on|off> [sound] [volume] [pitch]

🔁 Rotation

• /ab rotation <on|off>
• /ab setmode <SEQUENTIAL|RANDOM>

🧪 Testing & instant broadcasts

• /ab test <id> – ⚡ instantly sends the next broadcast
• /ab broadcastnow <message> – 📢 sends a one-time broadcast

---

⚙️ Configuration overview

The configuration file contains the following sections 🧾:

• 🔌 Global enabled toggle
• 🔁 Rotation settings (enabled and mode)
• 🔊 Default sound settings (enabled, sound, volume, pitch)
• 📢 Broadcast definitions

Each broadcast contains:

• ✅ enabled toggle
• ⏱️ interval value and unit
• 🔊 sound settings
• 💬 message, messages, or groups

Message types:

• 🟢 message – single-line broadcast
• 🔵 messages – rotating single-line broadcasts
• ⭐ groups – rotating multi-line broadcasts sent as one block

If groups are defined, message and messages are ignored.

---

❤️ Support

Need help, found a bug, or have a feature request? 🛠️

• 🐞 Open an issue on Modrinth
• 💬 Or contact the author directly

Enjoy using Ancient-Broadcast 🎉