Mute Module

The Mute Module provides comprehensive player muting functionality to prevent chat spam and harassment.

🚀 Features

Core Functionality

Manual Mutes - Custom duration and reason
Template Mutes - Predefined punishment templates
Offline Mutes - Mute players who are not online
Automatic Unmute - Time-based mute expiration
Chat Blocking - Prevent muted players from chatting
Command Blocking - Block certain commands for muted players

Advanced Features

Escalation System - Automatic punishment escalation
Mute History - Complete mute tracking
Case IDs - Unique identifier for each mute
Staff Tracking - Who issued the mute
Reason Templates - Predefined mute reasons
Staff Notifications - Real-time alerts when muted players attempt to chat

📋 Commands

`/mute <player> <duration> <reason>`

Mute a player with custom duration and reason.

Permission: zenith.mute

Parameters:

player - Player name to mute
duration - Mute duration (1d, 2h, 30m, permanent)
reason - Reason for the mute

Examples:

/mute Player123 1h Spam in chat
/mute Player123 permanent Harassment
/mute Player123 30m Inappropriate language

`/mute <player> <template> [reason]`

Mute a player using a predefined template.

Permission: zenith.mute.template.only + zenith.mute.template.<template>

Parameters:

player - Player name to mute
template - Template name (spam, harassment, cheating)
reason - Optional custom reason

Examples:

/mute Player123 spam
/mute Player123 harassment Stop being toxic
/mute Player123 cheating

Unmute Commands

`/unmute <player> [reason]`

Remove a mute from a player.

Permission: zenith.unmute

Parameters:

player - Player name to unmute
reason - Optional reason for unmute

Examples:

/unmute Player123
/unmute Player123 Appeal accepted

🔔 Staff Notifications

Chat Attempt Notifications

When a muted player tries to send a chat message, staff members with the appropriate permission will receive a real-time notification.

Configuration

staff_notifications:
  chat_attempt:
    enabled: true # Enable/disable chat attempt notifications
    message: "&#FF8800{player} &#FF0000tried to chat but is muted &#FFAAAA({duration_left})" # Variables: {player} - Player name, {duration_left} - Remaining mute duration
    # Note: Staff members need the permission "zenith.mute.chat.notifications" to receive these notifications

Message Variables

Variable	Description	Example
`{player}`	Name of the muted player	`Player123`
`{duration_left}`	Remaining mute duration	`1h 30m`

Example Notification

When a muted player tries to chat, staff will see:

Player123 tried to chat but is muted (1h 30m)

Permissions

Staff members need the following permission to receive chat attempt notifications:

zenith.mute.chat.notifications - Receive notifications when muted players try to chat

Customization

You can customize the notification message in the configuration:

staff_notifications:
  chat_attempt:
    enabled: true
    message: "⚠️ {player} attempted to chat while muted! Time remaining: {duration_left}"

Disabling Notifications

To disable chat attempt notifications:

staff_notifications:
  chat_attempt:
    enabled: false

⚙️ Configuration

Module Settings

enabled: true

settings:
  auto-unmute: true
  chat-blocking: true
  command-blocking: true
  case-id-prefix: "MUTE"
  max-duration: "365d"
  default-duration: "1h"

Templates

templates:
  spam:
    duration: "1h"
    reason: "Chat spam"
    escalation:
      - duration: "15m"
        reason: "First offense - Spam"
      - duration: "1h"
        reason: "Second offense - Spam"
      - duration: "1d"
        reason: "Third offense - Spam"

  harassment:
    duration: "2h"
    reason: "Harassment"
    escalation:
      - duration: "30m"
        reason: "First offense - Harassment"
      - duration: "2h"
        reason: "Second offense - Harassment"
      - duration: "1d"
        reason: "Third offense - Harassment"

🔐 Permissions

Required Permissions

Permission	Description
`zenith.mute.use`	Use mute commands
`zenith.mute`	Full mute access (manual + templates)
`zenith.mute.template.only`	Template-only access
`zenith.mute.template.<name>`	Access to specific template
`zenith.unmute`	Unmute players
`zenith.mute.notifications`	Receive mute notifications
`zenith.mute.chat.notifications`	Receive chat attempt notifications

Permission Examples

Full Administrator
Template Moderator

permissions:
  - zenith.mute: true
  - zenith.unmute: true
  - zenith.mute.notifications: true
  - zenith.mute.chat.notifications: true

What they can do:

✅ Manual mutes with custom duration
✅ Template mutes
✅ Unmute players
✅ Receive mute notifications
✅ Receive chat attempt notifications

permissions:
  - zenith.mute.use: true
  - zenith.mute.template.only: true
  - zenith.mute.template.spam: true
  - zenith.mute.template.harassment: true
  - zenith.unmute: true
  - zenith.mute.chat.notifications: true

What they can do:

✅ Template mutes only
✅ Unmute players
✅ Receive chat attempt notifications
❌ Manual mutes with custom duration

📊 Database Schema

Mute Table Structure

CREATE TABLE zn_mutes (
    id INT PRIMARY KEY AUTO_INCREMENT,
    case_id VARCHAR(50) UNIQUE NOT NULL,
    player_uuid VARCHAR(36) NOT NULL,
    player_name VARCHAR(16) NOT NULL,
    staff_uuid VARCHAR(36) NOT NULL,
    staff_name VARCHAR(16) NOT NULL,
    reason TEXT NOT NULL,
    duration VARCHAR(20),
    expires_at TIMESTAMP NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    active BOOLEAN DEFAULT TRUE,
    template_name VARCHAR(50)
);

🔧 API Integration

Mute via API

POST /zenith/api/mute
Authorization: Bearer your-token-here

{
  "player": "Player123",
  "reason": "Spam in chat",
  "duration": "1h"
}

Unmute via API

POST /zenith/api/unmute
Authorization: Bearer your-token-here

{
  "player": "Player123",
  "reason": "Appeal accepted"
}

🛠️ Troubleshooting

Common Issues

Issue: Mute not working

Check if module is enabled
Verify permissions
Check database connection
Ensure chat handler is working

Issue: Player can still chat

Check mute status in database
Verify chat event handler
Check for permission bypasses
Restart server if needed

Issue: Template not found

Verify template exists in configuration
Check template permissions
Ensure correct template name

Debug Mode

Enable debug mode for detailed logging:

debug:
  enabled: true
  console: true
  file: true

📈 Performance

Optimization Tips

Use MySQL/MariaDB for large servers
Enable suppress_hikari_logs for production
Regular database maintenance
Monitor mute table size

Monitoring

Track mute frequency
Monitor appeal rates
Check template usage
Review staff activity

Need help with the Mute Module? Join our Discord: https://discord.gg/2qCMn6KHj4