Skip to content
Zenith Docs

History Module

History Module

Section titled “History Module”

The History Module displays player punishment history with pagination and detailed information for each entry.

🚀 Features

Section titled “🚀 Features”

Core Functionality

Section titled “Core Functionality”
  • Complete History - View all punishment history for a player
  • Pagination - Navigate through multiple pages of history
  • Detailed Information - Case IDs, reasons, staff, dates
  • Interactive Navigation - Click to navigate pages

Advanced Features

Section titled “Advanced Features”
  • Hover Information - Detailed entry info on hover
  • Type-Specific Colors - Color-coded by punishment type
  • Status Display - Active/Expired/Permanent indicators
  • Duration Formatting - Human-readable duration display
  • IP Tracking - Shows IP addresses for each entry

📋 Commands

Section titled “📋 Commands”

/history <player> [page]

Section titled “/history <player> [page]”

View player’s punishment history.

Permission: zenith.history

Parameters:

  • player - Player name or UUID
  • page - Page number (optional, defaults to 1)

Examples:

Terminal window
/history Player123        # View first page
/history Player123 2      # View second page
/history Player123 3      # View third page

⚙️ Configuration

Section titled “⚙️ Configuration”

Module Settings

Section titled “Module Settings”
modules/history.yml
enabled: true


history:
  entries_per_page: 8


  messages:
    header: "{prefix}&#FFAA00History for &#FFFF00{player} &#FFAA00(Page {current_page}/{total_pages})"
    footer: "{prefix}&#7F7F7FUse &#FFFF00/history {player} <page> &#7F7F7Fto view other pages"


    no_history: "{prefix}&#FFAA00No history found for &#FFFF00{player}"
    invalid_page: "{prefix}&#FF0000Invalid page number! Available pages: 1-{max_pages}"
    player_not_found: "{prefix}&#FF0000Player &#FFFF00{player} &#FF0000not found!"

Entry Format

Section titled “Entry Format”
entry_format:
  message: "&#FFAA00[{case_id}] &#FFFFFF{type} &#7F7F7F- {reason}"


  hover:
    enabled: true
    text:
      - "&#FFAA00Case #{case_id}"
      - "&#FFFFFFType: &#FFFF00{type}"
      - "&#FFFFFFReason: &#FFFF00{reason}"
      - "&#FFFFFFStaff: &#FFFF00{staff}"
      - "&#FFFFFFDate: &#FFFF00{date}"
      - "&#FFFFFFDuration: &#FFFF00{duration}"
      - "&#FFFFFFStatus: &#FFFF00{active}"
      - "&#FFFFFFIP: &#FFFF00{ip}"

Type-Specific Formatting

Section titled “Type-Specific Formatting”
types:
  BAN:
    color: "&#FF0000"
    display_name: "BAN"
  IP_BAN:
    color: "&#FF0000"
    display_name: "IP BAN"
  MUTE:
    color: "&#FFAA00"
    display_name: "MUTE"
  WARN:
    color: "&#FFFF00"
    display_name: "WARN"
  KICK:
    color: "&#FF8800"
    display_name: "KICK"
  UNBAN:
    color: "&#00FF00"
    display_name: "UNBAN"
  UNMUTE:
    color: "&#00FF00"
    display_name: "UNMUTE"

📊 Available Variables

Section titled “📊 Available Variables”

Message Variables

Section titled “Message Variables”
VariableDescriptionExample
{player}Player namePlayer123
{current_page}Current page number1
{total_pages}Total pages3
{max_pages}Maximum pages5

Entry Variables

Section titled “Entry Variables”
VariableDescriptionExample
{case_id}Unique case IDBAN-123
{type}Punishment typeBAN, MUTE, WARN
{reason}Punishment reasonCheating detected
{staff}Staff memberAdmin123
{date}Timestamp2025-01-14 15:30
{duration}Duration7 days
{active}Active statusActive, Expired
{ip}IP address192.168.1.1

Status Variables

Section titled “Status Variables”
VariableDescriptionExample
{active}Current statusActive, Expired, Permanent

🎨 Display Examples

Section titled “🎨 Display Examples”

History Display (Page 1)

Section titled “History Display (Page 1)”
┌──────────────────────────────────────────┐
│ History for Player123 (Page 1/3)        │
│                                          │
│ [BAN-123] BAN - Cheating detected       │
│                                          │
│ [MUTE-124] MUTE - Spam                   │
│                                          │
│ [WARN-125] WARN - Griefing               │
│                                          │
│ [KICK-126] KICK - Inappropriate behavior │
│                                          │
│ [BAN-127] BAN - Repeated violations      │
│                                          │
│ [MUTE-128] MUTE - Harassment             │
│                                          │
│ [WARN-129] WARN - Rule violation         │
│                                          │
│ [BAN-130] BAN - Toxic behavior           │
│                                          │
│ ← Previous | Next →                      │
│                                          │
│ Use /history Player123 <page>            │
└──────────────────────────────────────────┘

Hover Information

Section titled “Hover Information”

When hovering over an entry:

┌─────────────────────────────┐
│ Case #BAN-123               │
│ Type: BAN                   │
│ Reason: Cheating detected   │
│ Staff: Admin123            │
│ Date: 2025-01-14 15:30:00  │
│ Duration: 7 days           │
│ Status: Active             │
│ IP: 192.168.1.1            │
└─────────────────────────────┘

🔄 Navigation

Section titled “🔄 Navigation”

Page Navigation

Section titled “Page Navigation”

Players can navigate through history pages:

Terminal window
/history Player123 1

Displays entries 1-8 (first page)
Section titled “Navigation Messages”
navigation:
  previous_page: "&#FFAA00[← Previous]"
  next_page: "&#FFAA00[Next →]"
  page_separator: "&#7F7F7F | "
  no_previous: "&#555555[← Previous]"
  no_next: "&#555555[Next →]"

📅 Date Formatting

Section titled “📅 Date Formatting”

Date Configuration

Section titled “Date Configuration”
date:
  format: "dd.MM.yyyy HH:mm:ss"
  timezone: "Europe/Berlin"

Duration Formatting

Section titled “Duration Formatting”
duration:
  permanent: "&#FF0000Permanent"
  expired: "&#7F7F7FExpired"
  active: "&#00FF00Active"
  format: "&#FFFF00{duration}"

Examples:

  • Active: 7 days (green)
  • Expired: Expired (gray)
  • Permanent: Permanent (red)

🔐 Permissions

Section titled “🔐 Permissions”

Required Permissions

Section titled “Required Permissions”
PermissionDescription
zenith.historyView player history

🛠️ Troubleshooting

Section titled “🛠️ Troubleshooting”

Common Issues

Section titled “Common Issues”

Issue: “No history found” when history exists

  • Check database connection
  • Verify player has history entries
  • Check if history module is enabled

Issue: Wrong entries displayed

  • Check pagination logic
  • Verify entries per page setting
  • Review database queries

Issue: Hover information not showing

  • Check if hover is enabled
  • Verify hover text configuration
  • Check for syntax errors

Issue: Invalid page error

  • Verify page number is within range
  • Check total pages calculation
  • Review database query results

Debug Mode

Section titled “Debug Mode”

Enable debug mode for detailed logging:

debug:
  enabled: true
  console: true
  file: true

📈 Performance

Section titled “📈 Performance”

Optimization Tips

Section titled “Optimization Tips”
  • Paginated Results - Limits displayed entries (8 per page default)
  • Efficient Queries - Indexed player UUID lookups
  • Lazy Loading - Only loads current page
  • Caching - Caches page results temporarily

Configuration for Large History

Section titled “Configuration for Large History”

For players with extensive history:

history:
  entries_per_page: 5  # Reduce entries per page

For quick overview:

history:
  entries_per_page: 10  # Show more entries

📊 Database Schema

Section titled “📊 Database Schema”

History Table

Section titled “History Table”
CREATE TABLE zn_history (
    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,
    punishment_type VARCHAR(20) NOT NULL,
    reason TEXT NOT NULL,
    duration BIGINT,
    expiry_time BIGINT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    additional_data TEXT,
    ip_address VARCHAR(45)
);

Query Example

Section titled “Query Example”
-- Get paginated history for a player
SELECT * FROM zn_history
WHERE player_uuid = ?
ORDER BY created_at DESC
LIMIT ? OFFSET ?;

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