Warn Module

The Warn Module provides a comprehensive warning system with escalation capabilities and player behavior tracking.

🚀 Features

Core Functionality

Template Warnings - Predefined warning templates
Escalation System - Automatic punishment escalation
Warning History - Complete warning tracking
Case IDs - Unique identifier for each warning
Staff Tracking - Who issued the warning

Advanced Features

IP-based Tracking - Track warnings across alt accounts
Warning Limits - Configurable warning thresholds
Automatic Escalation - Escalate to bans/mutes after X warnings
Reason Templates - Predefined warning reasons
Appeal System - Player appeal management

📋 Commands

Warn Commands

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

Warn a player using a predefined template.

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

Parameters:

player - Player name to warn
template - Template name (spam, harassment, inappropriate_language)
reason - Optional custom reason

Examples:

/warn Player123 spam
/warn Player123 harassment Stop being toxic
/warn Player123 inappropriate_language

⚙️ Configuration

Module Settings

enabled: true

settings:
  escalation: true
  max-warns: 5
  case-id-prefix: "WARN"
  auto-escalate: true
  escalation-action: "mute"  # mute, ban, kick

Templates

templates:
  spam:
    reason: "Spam warning"
    escalation:
      - warn_count: 1
        action: "warn"
        message: "First warning - Spam"
      - warn_count: 3
        action: "mute"
        duration: "1h"
        message: "Third warning - Escalated to mute"
      - warn_count: 5
        action: "ban"
        duration: "1d"
        message: "Fifth warning - Escalated to ban"

  harassment:
    reason: "Harassment warning"
    escalation:
      - warn_count: 1
        action: "warn"
        message: "First warning - Harassment"
      - warn_count: 2
        action: "mute"
        duration: "2h"
        message: "Second warning - Escalated to mute"
      - warn_count: 3
        action: "ban"
        duration: "7d"
        message: "Third warning - Escalated to ban"

🔐 Permissions

Required Permissions

Permission	Description
`zenith.warn.use`	Use warn commands
`zenith.warn.template.only`	Template-only access
`zenith.warn.template.<name>`	Access to specific template
`zenith.warn.notifications`	Receive warn notifications

permissions:
  - zenith.warn.use: true
  - zenith.warn.template.only: true
  - zenith.warn.template.spam: true
  - zenith.warn.template.harassment: true
  - zenith.warn.template.inappropriate_language: true
  - zenith.warn.notifications: true

What they can do:

✅ Issue warnings using templates
✅ Receive escalation notifications
❌ Manual warnings (not supported)

permissions:
  - zenith.warn.use: true
  - zenith.warn.template.only: true
  - zenith.warn.template.spam: true
  - zenith.warn.notifications: true

What they can do:

✅ Issue spam warnings only
✅ Receive notifications
❌ Other warning types

📊 Database Schema

Warn Table Structure

CREATE TABLE zn_warns (
    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,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    active BOOLEAN DEFAULT TRUE,
    template_name VARCHAR(50),
    ip_address VARCHAR(45)
);

🔧 API Integration

Warn via API

POST /zenith/api/warn?player=Player123&template=spam?reason=Excessive chat spam
Authorization: Bearer your-token-here

Response:

{
  "success": true,
  "message": "Player warned successfully",
  "data": {
    "caseId": "WARN-12347",
    "player": "Player123",
    "template": "spam",
    "reason": "Excessive chat spam",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Get Warning History

GET /zenith/api/warn/history?player=Player123&limit=10
Authorization: Bearer your-token-here

Response:

{
  "success": true,
  "data": {
    "player": "Player123",
    "totalWarnings": 5,
    "warnings": [
      {
        "caseId": "WARN-12347",
        "template": "spam",
        "reason": "Excessive chat spam",
        "createdAt": "2024-01-15T10:30:00Z",
        "staff": "Moderator123",
        "active": true
      }
    ]
  }
}

Get Available Templates

GET /zenith/api/warn/templates
Authorization: Bearer your-token-here

Response:

{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "spam",
        "reason": "Chat spam",
        "escalation": true
      },
      {
        "name": "harassment",
        "reason": "Harassment",
        "escalation": true
      },
      {
        "name": "inappropriate_language",
        "reason": "Inappropriate language",
        "escalation": true
      }
    ]
  }
}

📈 Escalation System

How Escalation Works

Player receives warning - Warning is logged with template
System checks warning count - Counts warnings for player
Escalation triggers - When threshold is reached
Automatic action - Mute, ban, or kick is applied
Notification sent - Staff are notified of escalation

Escalation Configuration

escalation:
  enabled: true
  check_interval: 300  # Check every 5 minutes
  max_warnings: 5
  escalation_actions:
    - warn_count: 3
      action: "mute"
      duration: "1h"
    - warn_count: 5
      action: "ban"
      duration: "1d"

🛠️ Troubleshooting

Common Issues

Issue: Warning not working

Check if module is enabled
Verify permissions
Check database connection
Ensure template exists

Issue: Escalation not working

Check escalation settings
Verify warning count in database
Check escalation permissions
Ensure escalation action permissions

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

📊 Monitoring

Key Metrics

Warning frequency - How often warnings are issued
Escalation rate - How often warnings escalate
Template usage - Which templates are used most
Staff activity - Who issues warnings

Reports

Player warning history - Complete warning record
Escalation reports - Escalation statistics
Template usage - Template effectiveness
Staff performance - Warning activity by staff

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