VoxelAI Logo

VoxelAI Configuration Guide

Essential

This guide provides a detailed explanation of VoxelAI's configuration options. All settings can be found in the config.yml file.

Table of Contents

Core Settings

Basic plugin configuration and debug options

Gemini API

API key setup and model configuration

AI Assistant

Assistant settings and command blocking

ChatWarden

Chat moderation and batch processing

Punishment System

Thresholds and escalation settings

Core Settings

Basic Configuration

Essential plugin settings

core:
  debug_mode: false    # Enable for detailed logging
  log_violations: true # Log all detected violations
  version: "2.0.0"    # Plugin version

debug_mode: Enables detailed logging for troubleshooting

log_violations: Records all violations to log files

version: Current plugin version (auto-managed)

Gemini API Configuration

API Key Configuration

Set up your Google Gemini API key

gemini:
  api-key: "YOUR_API_KEY_HERE"  # Get from https://aistudio.google.com/app/apikey

AI Assistant Configuration

Basic Settings

assistant:
  enabled: true
  max-tokens: 2048
  temperature: 0.7        # 0.0 = deterministic, 1.0 = creative
  command-execution: true # Enable command suggestions

temperature: Controls AI creativity (0.0-1.0)

max-tokens: Maximum response length

command-execution: Allow AI to suggest commands

Blocked Commands

Commands that the AI assistant will never suggest

blocked-commands:
  - "stop"
  - "restart"
  - "reload"
  - "ban"
  - "pardon"
  - "op"
  - "deop"
  # ... and more

ChatWarden Configuration

Batch Processing Settings

Configure message processing efficiency

batch_processing:
  enabled: true
  chunk_size: 25                # Messages per batch
  process_interval_seconds: 20  # Process every 20 seconds
  max_batch_delay_minutes: 2    # Maximum delay for any message
  queue_limit: 200             # Maximum queued messages

Punishment Configuration

Score Thresholds

Violation score thresholds for different punishment levels

punishment_score_thresholds:
  warn: 1.5     # Very low - even severity 1 gets warning
  mute: 4.0     # Requires severity 6+ for spam to mute
  tempban: 8.0  # High threshold - severity 5 with escalation
  ban: 20.0     # Requires severe/repeated violations

Punishment Duration Escalation

Progressive punishment durations for repeat offenders

punishment_escalation:
  mute:
    - "10m"  # 1st offense
    - "30m"  # 2nd offense
    - "1h"   # 3rd offense
    - "3h"   # 4th offense
    - "6h"   # 5th+ offense
  tempban:
    - "1h"   # 1st offense
    - "6h"   # 2nd offense
    - "12h"  # 3rd offense
    - "1d"   # 4th offense
    - "3d"   # 5th offense
    - "7d"   # 6th+ offense

Custom Punishment Messages

Personalized messages based on violation type and escalation level

punishment_messages:
  spam:
    1: "Please do not spam the chat."
    2: "Final warning: Continued spamming will result in a mute."
    3: "You have been muted for spamming."
    4: "You have been muted for repeated spam."
    5: "You have been temporarily banned for persistent spam."
    6: "You have been permanently banned for extreme spam."
  toxicity:
    1: "Please be respectful to others."
    2: "Final warning: Continued toxic behavior will result in a mute."
    3: "You have been muted for toxic behavior."
    # ... more levels for each violation type

Escalation levels: Messages get progressively more severe

Violation-specific: Different messages for different violation types

Customizable: Server owners can modify all messages

Escalation Calculation

How escalation multipliers are calculated

escalation:
  calculation_method: "severity"  # "count" or "severity"
  base_multiplier: 1.0
  count_factor: 0.5              # For "count" method
  severity_factor: 0.1           # For "severity" method
  max_multiplier: 3.0            # Maximum escalation

severity method: Escalation based on violation severity sum

count method: Escalation based on violation count

Configuration Tips

Getting Started

• Start with default settings

• Test with a small group first

• Monitor violation patterns

• Adjust gradually

Fine-tuning

• Adjust confidence thresholds

• Modify punishment thresholds

• Customize escalation factors

• Review regularly

Common Issues

• Too many false positives

• Missing real violations

• Punishments too harsh/lenient

• API quota exceeded