⏰ Keville — Smart Messaging for Minecraft Servers

Keville is a powerful, flexible, and lightweight messaging plugin for Minecraft servers.
It allows you to send messages to players automatically based on time, conditions, triggers, and targets — without command spam or manual intervention.

From simple reminders to complex, condition-based announcements, Keville ensures the right message reaches the right players at the right moment.

⚠️ Status: BETA
Keville is currently in beta.
Features are stable, but configuration structure and behavior may still evolve.
Feedback and bug reports are very welcome!

---

✨ Core Features

🕒 Scheduled Messages

Send messages at specific times using a simple and readable configuration.

• Schedule messages using 24-hour time format (HH:mm)
• Limit execution to specific days (or all days)
• Supports multiple message types:
  • Chat
  • Actionbar
  • Title
• Optional sounds per message
• Fully automated once configured

Perfect for:

• Daily announcements
• Event reminders
• Rule notices
• Server-wide alerts

---

🔁 Repeater Messages (Playtime-Based)

Send messages at a fixed interval based on Minecraft playtime.

• Interval defined in Minecraft seconds (20 ticks = 1 second)
• Can be limited to specific days
• Supports random messages and sounds
• Optional conditions and targets

Great for:

• Vote reminders
• Tips & hints
• Repeating informational messages

---

⚡ Triggered Messages

Send messages once when conditions become true.

• Fires only when conditions change from false → true
• Does not spam or loop
• Uses the same message system as scheduler & repeater
• Can execute a predefined custom command

Ideal for:

• Player count milestones
• World-based alerts
• Special server states (busy hours, events, etc.)

---

🧠 Conditions System

Keville includes a powerful and reusable conditions engine.

• Conditions are grouped and reusable
• All conditions in a group must be true
• Supports comparisons using:
  • Built-in placeholders ({online}, {world}, {time}, etc.)
  • PlaceholderAPI placeholders (%player_level%, %vault_balance%, etc.)
• Supported operators:
  • =, >, >=, <, <=

Example use cases:

• Only send messages when enough players are online
• Target specific worlds
• Trigger messages based on player stats or permissions

---

🎯 Target Groups

Precisely control who receives messages.

Target groups are reusable and support:

• All players
• Specific worlds (Multiverse-Core supported)
• Permissions (LuckPerms supported)
• LuckPerms groups
• Individual players

Targets can be applied to scheduled, repeater, and triggered messages.

---

🧩 Custom Commands

Define reusable message actions and trigger them dynamically.

• Custom commands can send messages, play sounds, and apply conditions/targets
• Messages and sounds can be randomly selected
• Can be referenced from triggered messages

This avoids duplication and keeps complex setups clean and maintainable.

---

🔌 Plugin Integrations

Keville integrates seamlessly with popular server plugins:

• PlaceholderAPI — advanced dynamic placeholders
• Multiverse-Core — world-aware targeting and conditions
• LuckPerms — permissions and group-based targeting

---

🕰 Time & Timezone Support

Keville handles time correctly across environments.

• Configurable IANA timezone
• Optional NTP synchronization for drift-free accuracy
• Consistent behavior across restarts

---

📝 Logging

Optional logging of all sent messages.

• Fully configurable log template
• Includes placeholders like:
  • {time}, {section}, {type}, {player}, {message}
• Useful for moderation, auditing, or debugging

---

⌨ Commands

Keville includes a clean command interface:

• /keville schedule — create scheduled messages
• /keville message — send messages manually
• /keville conditions — list condition groups
• /keville today — see today’s scheduled messages
• /keville debug — inspect internal state
• /keville reload — reload configuration
• Alias: /kev

Each command supports permissions and OP overrides.

---

⚙️ Lightweight & Production-Ready

Keville is designed to be:

• Easy to configure
• Lightweight on performance
• Quiet in the background
• Reliable even on busy servers

---

🧪 Take some special notes

Keville is currently in BETA.

• Configuration format may evolve
• New features are actively being developed
• Feedback is highly appreciated
• The Plugin is known on your server as kwallieKeville

---

🚨 Help needed? Issue found?

You can contact me at pascal@boschma.wtf. I'll help you as soon as I can. If you find an issue, please let me know too!