Ban Module

The Ban Module provides comprehensive player banning functionality with both manual and template-based systems.

🚀 Features

Core Functionality

Manual Bans - Custom duration and reason
Template Bans - Predefined punishment templates
IP Bans - Ban player and their IP address
Offline Bans - Ban players who are not online
Automatic Unban - Time-based ban expiration
Ban History - Complete ban tracking

Advanced Features

Escalation System - Automatic punishment escalation
Appeal System - Player appeal management
Case IDs - Unique identifier for each ban
Staff Tracking - Who issued the ban
Reason Templates - Predefined ban reasons
Staff Notifications - Real-time alerts when banned players attempt to join

📋 Commands

`/ban <player> <duration> <reason>`

Ban a player with custom duration and reason.

Permission: zenith.ban

Parameters:

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

Examples:

/ban Player123 1d Cheating detected
/ban Player123 permanent Griefing
/ban Player123 2h Spam

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

Ban a player using a predefined template.

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

Parameters:

player - Player name to ban
template - Template name (cheating, griefing, spam)
reason - Optional custom reason

Examples:

/ban Player123 cheating
/ban Player123 griefing Caught destroying builds
/ban Player123 spam

Unban Commands

`/unban <player> [reason]`

Remove a ban from a player.

Permission: zenith.unban

Parameters:

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

Examples:

/unban Player123
/unban Player123 Appeal accepted

IP Ban Commands

`/ipban <player> [duration] [reason]`

Ban a player and their IP address.

Permission: zenith.ipban

Parameters:

player - Player name to ban (must be online)
duration - Ban duration (optional, defaults to permanent)
reason - Reason for IP ban (optional, uses default reason if not provided)

Command Syntax (configurable):

If both duration and reason are required: /ipban <player> <duration> <reason>
If only duration is required: /ipban <player> <duration> [reason]
If only reason is required: /ipban <player> [duration] <reason>
If neither is required: /ipban <player> [duration] [reason]

🌐 Manual IP Banning Guide

What is IP Banning?

IP banning blocks a specific IP address from connecting to your server. This means that not only the banned player cannot connect, but anyone else using the same IP address (like family members, roommates, or people sharing the same internet connection) will also be blocked.

When to Use IP Bans

IP bans should be used in these situations:

Severe violations - Cheating, griefing, or harassment
Repeat offenders - Players who keep creating new accounts
Security threats - DDoS attacks or malicious behavior
Spam accounts - Multiple accounts from the same source

How to Manually IP Ban Someone

Step 1: Identify the Player

First, you need to identify the player you want to ban:

# Check if player is online (required for /ipban)
/ipban PlayerName

# Or check their IP address in logs
# Look for: "Player PlayerName[/IP_ADDRESS:PORT] logged in"

Step 2: Execute the IP Ban

Use the /ipban command with the player’s name:

# Basic IP ban (uses default duration and reason)
/ipban PlayerName

# IP ban with custom duration
/ipban PlayerName 7d

# IP ban with custom reason
/ipban PlayerName "Cheating and griefing"

# IP ban with both duration and reason
/ipban PlayerName 7d "Cheating and griefing"
/ipban PlayerName permanent "Severe harassment"
/ipban PlayerName 30d "Repeated rule violations"

Step 3: Verify the Ban

Check that the IP ban was applied:

# The player should be immediately disconnected
# Check ban list or logs to confirm

IP Ban Command Examples

Basic IP Ban (Uses Defaults)

# Uses default duration and reason from config
/ipban Player123

Temporary IP Ban

# Ban for 1 day
/ipban Player123 1d "Spam and harassment"

# Ban for 1 week
/ipban Player123 7d "Cheating detected"

# Ban for 1 month
/ipban Player123 30d "Griefing and toxicity"

Permanent IP Ban

# Permanent ban for severe violations
/ipban Player123 permanent "DDoS attacks"

# Permanent ban for repeat offenses
/ipban Player123 permanent "Multiple account creation"

Reason-Only IP Ban

# Uses default duration with custom reason
/ipban Player123 "Custom reason here"

Duration Formats

Format	Example	Description
`1m`	`1m`	1 minute
`1h`	`1h`	1 hour
`1d`	`1d`	1 day
`1w`	`1w`	1 week
`1mo`	`1mo`	1 month
`1y`	`1y`	1 year
`permanent`	`permanent`	Never expires

Managing IP Bans

Check IP Ban Status

# Check if a player is IP banned
/ban PlayerName 1d test
# If they're IP banned, they won't be able to connect

Remove IP Ban

# Unban the player (removes both player and IP ban)
/unban PlayerName Appeal accepted

Best Practices

Before IP Banning

Verify the violation - Make sure you have clear evidence
Check for shared IPs - Look for other players from the same IP
Consider alternatives - Regular bans might be sufficient
Document the reason - Keep detailed records

After IP Banning

Monitor for bypasses - Watch for VPN usage
Check appeals - Review unban requests carefully
Update staff - Inform other moderators
Log everything - Keep detailed ban records

Troubleshooting IP Bans

Player Still Can Connect

VPN usage: Player is using a VPN to change IP
Dynamic IP: Their ISP assigned a new IP address
Mobile data: Player switched to mobile internet
Ban not applied: Check command execution and permissions

Legitimate Player Affected

Shared household: Family member or roommate
School/work: Shared internet connection
Public WiFi: Multiple people using same network
Solution: Use /unban and consider regular ban instead

Ban Not Working

Check permissions: Ensure you have zenith.ban permission
Verify command: Make sure syntax is correct
Check logs: Look for error messages
Module status: Ensure ban module is enabled

🔔 Staff Notifications

Join Attempt Notifications

When a banned player tries to join the server, staff members with the appropriate permission will receive a real-time notification.

Configuration

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

Message Variables

Variable	Description	Example
`{player}`	Name of the banned player	`Player123`
`{duration_left}`	Remaining ban duration	`7d 12h`

Example Notification

When a banned player tries to join, staff will see:

Player123 tried to join but is banned (7d 12h)

Permissions

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

zenith.ban.join.notifications - Receive notifications when banned players try to join

Customization

You can customize the notification message in the configuration:

staff_notifications:
  join_attempt:
    enabled: true
    message: "🚫 {player} attempted to join while banned! Time remaining: {duration_left}"

Disabling Notifications

To disable join attempt notifications:

staff_notifications:
  join_attempt:
    enabled: false

Alternative Approaches

Regular Ban Instead

# Use regular ban for less severe cases
/ban PlayerName 7d Cheating detected

Template Ban

# Use predefined templates
/ban PlayerName cheating
/ban PlayerName griefing

Escalation System

The plugin’s escalation system automatically increases punishment severity:

First offense: Warning or short ban
Second offense: Longer ban
Third offense: IP ban or permanent ban

Monitoring and Analytics

Track IP Ban Effectiveness

Monitor ban appeals
Check for VPN usage patterns
Track repeat offender statistics
Analyze ban success rates

Staff Guidelines

Documentation: Always document IP ban reasons
Communication: Inform other staff members
Reviews: Regular review of IP ban decisions
Training: Ensure all staff understand IP ban implications

⚙️ Configuration

Module Settings

enabled: true

settings:
  auto-unban: true
  ip-ban-support: true
  case-id-prefix: "BAN"
  max-duration: "365d"
  default-duration: "7d"

Templates

templates:
  cheating:
    duration: "30d"
    reason: "Cheating detected"
    escalation:
      - duration: "7d"
        reason: "First offense - Cheating"
      - duration: "30d"
        reason: "Second offense - Cheating"
      - duration: "permanent"
        reason: "Third offense - Cheating"

  griefing:
    duration: "14d"
    reason: "Griefing"
    escalation:
      - duration: "3d"
        reason: "First offense - Griefing"
      - duration: "14d"
        reason: "Second offense - Griefing"
      - duration: "permanent"
        reason: "Third offense - Griefing"

🔐 Permissions

Required Permissions

Permission	Description
`zenith.ban.use`	Use ban commands
`zenith.ban`	Full ban access (manual + templates)
`zenith.ban.template.only`	Template-only access
`zenith.ban.template.<name>`	Access to specific template
`zenith.unban`	Unban players
`zenith.ban.notifications`	Receive ban notifications
`zenith.ban.join.notifications`	Receive join attempt notifications

Permission Examples

Full Administrator
Template Moderator

permissions:
  - zenith.ban: true
  - zenith.unban: true
  - zenith.ban.notifications: true
  - zenith.ban.join.notifications: true

What they can do:

✅ Manual bans with custom duration
✅ Template bans
✅ IP bans
✅ Unban players
✅ Receive ban notifications
✅ Receive join attempt notifications

permissions:
  - zenith.ban.use: true
  - zenith.ban.template.only: true
  - zenith.ban.template.cheating: true
  - zenith.ban.template.griefing: true
  - zenith.ban.template.spam: true
  - zenith.unban: true
  - zenith.ban.join.notifications: true

What they can do:

✅ Template bans only
✅ Unban players
✅ Receive join attempt notifications
❌ Manual bans with custom duration
❌ IP bans

📊 Database Schema

Ban Table Structure

CREATE TABLE zn_bans (
    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),
    ip_address VARCHAR(45)
);

🔧 API Integration

Ban via API

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

{
  "player": "Player123",
  "reason": "Cheating detected",
  "duration": "7d"
}

Unban via API

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

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

🛠️ Troubleshooting

Common Issues

Issue: Ban not working

Check if module is enabled
Verify permissions
Check database connection

Issue: Template not found

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

Issue: Auto-unban not working

Check if auto-unban is enabled
Verify database connection
Check server time synchronization

📈 Performance

Optimization Tips

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

Monitoring

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

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