Configuration Guide

Configuration Guide

This guide explains how to configure Zenith-Mod and its modules.

Hot Reload

Use /zenith reload to apply configuration changes without restarting your server!

📁 Configuration Files

Zenith-Mod uses a modular configuration system with separate files for each module:

plugins/Zenith-Mod/
├── config.yml          # Main configuration
├── messages.yml         # All messages and translations
└── modules/
    ├── ban.yml         # Ban module configuration
    ├── mutes.yml       # Mute module configuration
    ├── warn.yml        # Warn module configuration
    ├── freeze.yml      # Freeze module configuration
    ├── essentials.yml  # Essentials module configuration
    ├── notes.yml       # Notes module configuration
    └── web-api.yml     # Web API configuration

File Structure

Each module has its own configuration file, making it easy to manage specific features independently.

⚙️ Main Configuration

config.yml

File-based (H2/SQLite)

# Zenith-Mod Configuration
# Version: 1.1.4

# Debug settings
debug:
  enabled: true
  console: true
  file: true

# Console settings
console:
  name: "Console"

# Database configuration
database:
  type: "sqlite"  # or "h2"
  file: "zenith"  # Database filename (without extension)

  # H2 Database Security Settings (only for H2)
  h2_password: "zenith123"
  h2_user: "zenith"

  table_prefix: "zn_"
  suppress_hikari_logs: true

Network (MySQL/MariaDB)

# Zenith-Mod Configuration
# Version: 1.1.4

# Debug settings
debug:
  enabled: true
  console: true
  file: true

# Console settings
console:
  name: "Console"

# Database configuration
database:
  type: "mysql"  # or "mariadb"
  host: "localhost"
  port: 3306
  database: "zenith"
  username: "zenith"
  password: "password"
  ssl: false
  table_prefix: "zn_"
  suppress_hikari_logs: true

Database Type

• SQLite: Best for small servers, single file database
• H2: Good for development, supports external access
• MySQL/MariaDB: Best for large servers, supports multiple connections

📝 Logging Configuration

config.yml - Logging Settings

# Logging settings for different log levels
logging:
  # Console output settings for each log level
  console:
    debug: true      # Show DEBUG messages in console
    info: true       # Show INFO messages in console (always enabled)
    warning: true    # Show WARNING messages in console (always enabled)
    error: true      # Show ERROR messages in console (always enabled)
    critical: true   # Show CRITICAL messages in console (always enabled)
    database: true   # Show DATABASE messages in console
    command: true    # Show COMMAND messages in console
    config: false    # Show CONFIG messages in console (default: false)
    reload: true     # Show RELOAD messages in console

  # File output settings for each log level
  file:
    debug: true      # Write DEBUG messages to file
    info: true       # Write INFO messages to file
    warning: true    # Write WARNING messages to file
    error: true      # Write ERROR messages to file
    critical: true   # Write CRITICAL messages to file
    database: true   # Write DATABASE messages to file
    command: true    # Write COMMAND messages to file
    config: true     # Write CONFIG messages to file
    reload: true     # Write RELOAD messages to file

Logging Benefits

• Production Ready: Reduce console spam by disabling verbose logs
• Debugging: Enable all logs for development and troubleshooting
• Performance: Selective logging improves server performance
• Hot Reload: Changes apply immediately with /zenith reload

🗨️ Messages Configuration

messages.yml

# Zenith-Mod Messages Configuration
# All messages support color codes and placeholders

# Global Messages
prefix: "&#00FFAA[Zenith-Mod] "
no-permission: "{prefix}&cYou don't have permission to use this command!"
player-not-found: "{prefix}&cPlayer not found!"
invalid-arguments: "{prefix}&cInvalid arguments!"
command-disabled: "{prefix}&cThis command is disabled!"

# Ban Messages
ban:
  success: "{prefix}&aPlayer {player} has been banned for {duration}!"
  success-permanent: "{prefix}&aPlayer {player} has been permanently banned!"
  success-template: "{prefix}&aPlayer {player} has been banned using template {template}!"
  already-banned: "{prefix}&cPlayer {player} is already banned!"
  not-banned: "{prefix}&cPlayer {player} is not banned!"
  unban-success: "{prefix}&aPlayer {player} has been unbanned!"
  ip-ban-success: "{prefix}&aPlayer {player} and their IP have been banned!"

# Mute Messages
mute:
  success: "{prefix}&aPlayer {player} has been muted for {duration}!"
  success-permanent: "{prefix}&aPlayer {player} has been permanently muted!"
  success-template: "{prefix}&aPlayer {player} has been muted using template {template}!"
  already-muted: "{prefix}&cPlayer {player} is already muted!"
  not-muted: "{prefix}&cPlayer {player} is not muted!"
  unmute-success: "{prefix}&aPlayer {player} has been unmuted!"
  chat-blocked: "{prefix}&cYou are muted! Reason: {reason} | Expires: {expires}"

# Warn Messages
warn:
  success: "{prefix}&aPlayer {player} has been warned!"
  success-template: "{prefix}&aPlayer {player} has been warned using template {template}!"
  escalation: "{prefix}&cPlayer {player} has reached {count} warnings! Escalating to {action}!"

# Freeze Messages
freeze:
  success: "{prefix}&aPlayer {player} has been frozen!"
  unfreeze-success: "{prefix}&aPlayer {player} has been unfrozen!"
  frozen-message: "{prefix}&cYou are frozen! Reason: {reason}"

# Essentials Messages
essentials:
  god-enabled: "{prefix}&aGod mode enabled!"
  god-disabled: "{prefix}&cGod mode disabled!"
  fly-enabled: "{prefix}&aFly mode enabled!"
  fly-disabled: "{prefix}&cFly mode disabled!"
  healed: "{prefix}&aYou have been healed!"
  fed: "{prefix}&aYou have been fed!"
  cleared: "{prefix}&aYour inventory has been cleared!"

# Notes Messages
notes:
  added: "{prefix}&aNote added to {player}!"
  not-found: "{prefix}&cNo notes found for {player}!"
  cleared: "{prefix}&aNotes cleared for {player}!"

# Error Messages
errors:
  database-connection: "{prefix}&cDatabase connection failed!"
  invalid-duration: "{prefix}&cInvalid duration format!"
  template-not-found: "{prefix}&cTemplate not found!"
  case-not-found: "{prefix}&cCase not found!"
  appeal-not-found: "{prefix}&cAppeal not found!"

🔧 Module Configurations

Ban Module (modules/ban.yml)

# Ban Module Configuration
enabled: true

# Ban Settings
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"

  spam:
    duration: "1d"
    reason: "Spam"
    escalation:
      - duration: "1h"
        reason: "First offense - Spam"
      - duration: "1d"
        reason: "Second offense - Spam"
      - duration: "7d"
        reason: "Third offense - Spam"

# Messages
messages:
  staff:
    usage_ban: "&#FF5555Usage: /ban <player> <duration> <reason> OR /ban <player> <template> [reason]"
    usage_unban: "&#FF5555Usage: /unban <player> [reason]"
    usage_ipban: "&#FF5555Usage: /ipban <player> <duration> <reason>"

  player:
    banned: "&#FF5555You have been banned! Reason: {reason} | Expires: {expires}"
    banned_permanent: "&#FF5555You have been permanently banned! Reason: {reason}"
    unbanned: "&#FF5555You have been unbanned! Reason: {reason}"

Mute Module (modules/mutes.yml)

# Mute Module Configuration
enabled: true

# Mute Settings
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"

# Messages
messages:
  staff:
    usage_mute: "&#FF5555Usage: /mute <player> <duration> <reason> OR /mute <player> <template> [reason]"
    usage_unmute: "&#FF5555Usage: /unmute <player> [reason]"

  player:
    muted: "&#FF5555You have been muted! Reason: {reason} | Expires: {expires}"
    muted_permanent: "&#FF5555You have been permanently muted! Reason: {reason}"
    unmuted: "&#FF5555You have been unmuted! Reason: {reason}"
    chat_blocked: "&#FF5555You are muted! Reason: {reason} | Expires: {expires}"

Web API Module (modules/web-api.yml)

# Web API Module Configuration
enabled: true

# API Settings
settings:
  port: 8080
  host: "0.0.0.0"
  rate-limit: 100
  rate-limit-window: 60
  cors-enabled: true
  cors-origins:
    - "http://localhost:3000"
    - "https://yourdomain.com"

# Authentication
auth:
  token-length: 32
  token-expiry: 30d
  require-permission: "zenith.api.access"

# Endpoints
endpoints:
  player-info: true
  player-history: true
  case-lookup: true
  ip-analysis: true
  alt-detection: true
  moderation-actions: true
  statistics: true
  appeals: true

# Rate Limiting
rate-limiting:
  enabled: true
  requests-per-minute: 100
  burst-limit: 20
  whitelist:
    - "127.0.0.1"
    - "::1"

# Logging
logging:
  enabled: true
  log-requests: true
  log-responses: false
  log-errors: true

🎨 Color Codes

Zenith-Mod supports both traditional Minecraft color codes and hex colors:

Traditional Color Codes

• &0 - Black
• &1 - Dark Blue
• &2 - Dark Green
• &3 - Dark Aqua
• &4 - Dark Red
• &5 - Dark Purple
• &6 - Gold
• &7 - Gray
• &8 - Dark Gray
• &9 - Blue
• &a - Green
• &b - Aqua
• &c - Red
• &d - Light Purple
• &e - Yellow
• &f - White

Hex Color Codes

• &#FF0000 - Red
• &#00FF00 - Green
• &#0000FF - Blue
• &#FFFF00 - Yellow
• &#FF00FF - Magenta
• &#00FFFF - Cyan
• &#FFFFFF - White
• &#000000 - Black

Formatting Codes

• &l - Bold
• &m - Strikethrough
• &n - Underline
• &o - Italic
• &k - Obfuscated
• &r - Reset

🎭 Vanish Module Configuration

modules/vanish.yml

# Vanish Module Configuration
enabled: true

# Vanish settings
vanish:
  # Custom messages for vanish actions
  messages:
    enabled: "{prefix}&#00FF00You are now vanished!"
    disabled: "{prefix}&#FF0000You are no longer vanished!"
    already_vanished: "{prefix}&#FFAA00You are already vanished!"
    not_vanished: "{prefix}&#FFAA00You are not vanished!"
    join_vanished: "{prefix}&#FFAA00You joined while vanished!"

  # Disconnect/Connect messages for vanished players
  disconnect_message: "&#FFAA00{player} left the game"
  connect_message: "&#FFAA00{player} joined the game"

  # ActionBar settings
  actionbar:
    enabled: true
    vanished_message: "{prefix}&#00FF00%smcaps%VANISH: ON%smreset%"
    not_vanished_message: "{prefix}&#FF0000%smcaps%VANISH: OFF%smreset%"
    not_vanished_duration: 60

  # Vanish effects
  effects:
    hide_from_tab: true
    hide_from_list: true
    make_invisible: true
    hide_name_tag: true
    prevent_item_pickup: true
    prevent_block_interaction: true
    prevent_block_breaking: true
    auto_god_mode: true
    prevent_damage: true
    prevent_mob_targeting: true
    prevent_dealing_damage: true
    allow_flying: true
    flying_speed: 0.1

🔍 Client Detection Module Configuration

modules/client-detector.yml

# Client Detector Module Configuration
enabled: true

# Notification settings
notifications:
  enabled: true
  message_format: "{prefix}&#FFFFFF{player} &#7F7F7Fjoined using &#FFFF00{client}"

  # Hover event settings
  hover:
    enabled: true
    text:
      - "&#FFAA00Player Information"
      - "&#FFFFFFName: &#FFFF00{player} &#FFFFFF| &#FFFF00{uuid}"
      - "&#FFFFFFIP: &#FFFF00{ip} &#FFFFFF| Ping: &#FFFF00{ping}ms"
      - "&#FFFFFFClient: &#FFFF00{client} &#FFFFFF| Version: &#FFFF00{version}"
      - "&#FFFFFFWorld: &#FFFF00{world} &#FFFFFF| Mode: &#FFFF00{gamemode}"
      - "&#FFFFFFHealth: &#FFFF00{health}/20 &#FFFFFF| Food: &#FFFF00{food}/20"
      - "&#FFFFFFLocation: &#FFFF00{x}, {y}, {z}"

📋 History Module Configuration

modules/history.yml

# History Module Configuration
enabled: true

# History settings
history:
  entries_per_page: 8

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

    # Spacing settings
    spacing:
      # Add empty line above header
      above_header: true
      # Add empty line below footer
      below_footer: true

    # Navigation messages (clickable)
    navigation:
      previous_page: "&#FFAA00[← Previous]"
      next_page: "&#FFAA00[Next →]"
      page_separator: "&#7F7F7F | "
      no_previous: "&#555555[← Previous]"
      no_next: "&#555555[Next →]"

  # Entry format configuration
  entry_format:
    message: "&#FFAA00[{case_id}] &#FFFFFF{type} &#7F7F7F- {reason}"

    # Hover text
    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}"

    # Separator lines between entries
    separators:
      enabled: true
      lines:
        - ""  # Empty line between entries
        - "&#555555─────────────────────────"  # Separator line
        - ""  # Another empty line

  # Date formatting
  date:
    format: "dd.MM.yyyy HH:mm:ss"
    timezone: "Europe/Berlin"

🔍 Check Module Configuration

modules/check.yml

# Check Module Configuration
enabled: true

# Check settings
check:
  # Main message format
  messages:
    header: "{prefix}&#FFAA00Alt Check for &#FFFF00{player}"
    footer: "{prefix}&#7F7F7FClick on usernames for more information"
    no_alts: "{prefix}&#FFAA00No alt accounts found for &#FFFF00{player}"
    player_not_found: "{prefix}&#FF0000Player &#FFFF00{player} &#FF0000not found!"
    no_permission: "{prefix}&#FF0000You don't have permission to use this command!"
    error: "{prefix}&#FF0000An error occurred while checking alt accounts!"

  # Player information display
  player_info:
    enabled: true
    format:
      - "&#FFAA00Player Status:"
      - "&#FFFFFFBanned: &#FFFF00{banned}"
      - "&#FFFFFFMuted: &#FFFF00{muted}"
      - "&#FFFFFFTotal Warns: &#FFFF00{total_warns}"
      - "&#FFFFFFTotal History Entries: &#FFFF00{total_history}"
    position: "top"

  # Alt account display settings
  alt_display:
    format: "{status_color}{username}&#7F7F7F ({status_text})"
    status_colors:
      online: "&#00FF00"      # Green
      muted: "&#FFAA00"       # Orange
      banned: "&#FF0000"      # Red
      offline: "&#7F7F7F"     # Gray
    separator: "&#7F7F7F, "
    max_display: 10

  # Hover information
  hover:
    enabled: true
    text:
      - "&#FFAA00Player Information"
      - "&#FFFFFFName: &#FFFF00{username}"
      - "&#FFFFFFUUID: &#FFFF00{uuid}"
      - "&#FFFFFFIP: &#FFFF00{ip}"
      - "&#FFFFFFStatus: &#FFFF00{status}"
      - "&#FFFFFFLast Seen: &#FFFF00{last_seen}"
      - "&#FFFFFFShared IPs: &#FFFF00{shared_ips}"
      - ""
      - "&#FFAA00Actions"
      - "&#FFFFFFClick for History: &#FFFF00/history {username}"
      - "&#FFFFFFClick for Notes: &#FFFF00/notes {username}"

  # Legend and accuracy
  legend:
    enabled: true
    format: "&#7F7F7FLegend: {online_color}Online &#7F7F7F| {muted_color}Muted &#7F7F7F| {banned_color}Banned &#7F7F7F| {offline_color}Offline"
    position: "bottom"

  accuracy:
    enabled: true
    format: "&#7F7F7FAccuracy: &#FFFF00{accuracy}% &#7F7F7F({method})"
    position: "top"
    display_accuracy: 95
    detection_method: "IP Analysis"

  # Spacing settings
  spacing:
    above_header: true
    below_footer: true
    between_legend_alts: true
    between_alts_accuracy: true

🔄 Hot Reload

Zenith-Mod supports hot reloading of configuration files without server restart:

/zenith reload

This command reloads:

• All configuration files
• All message files
• All module configurations
• Template configurations
• Database connections

📊 Performance Tuning

Database Optimization

For high-traffic servers, consider these database optimizations:

database:
  # Use MySQL/MariaDB for better performance on high-traffic servers
  type: "mysql"  # or "mariadb"

  # Optimize connection settings
  suppress_hikari_logs: true  # Reduces log spam

  # For MySQL/MariaDB, ensure your database server has:
  # - Adequate connection pool size
  # - Proper indexing on frequently queried tables
  # - Regular maintenance and optimization

Debug Optimization

For production servers, disable debug logging:

debug:
  enabled: false  # Disable debug logging for better performance
  console: false  # Don't log debug to console
  file: false     # Don't log debug to files

Console Optimization

console:
  # Use a shorter name to reduce log file size
  name: "SYS"  # Instead of "Console"

🛠️ Troubleshooting

Common Issues

1. Database Connection Failed

   • Check database credentials
   • Ensure database server is running
   • Verify network connectivity

2. Permission Denied

   • Check permission plugin configuration
   • Verify user has correct permissions
   • Check console for permission errors

3. Template Not Found

   • Verify template exists in configuration
   • Check template name spelling
   • Ensure module is enabled

4. API Not Working

   • Check if Web API module is enabled
   • Verify port is not in use
   • Check firewall settings

Debug Mode

Enable debug mode for detailed logging:

debug:
  enabled: true
  console: true  # Show debug messages in console
  file: true     # Write debug messages to log files

---

Need help with configuration? Join our Discord: https://discord.gg/2qCMn6KHj4