CasualBans

CasualBans is the modern replacement for LiteBans, AdvancedBan, and similar punishment plugins. It's built from the ground up for Paper 1.21+ with cross-server sync, a powerful template system, Discord integration, and a clean developer API — all in a single zero-dependency JAR.

Features

• 8 Punishment Types — Ban, TempBan, IP-Ban, Mute, TempMute, IP-Mute, Warn, Kick
• Cross-Server Sync — Punishments, broadcasts, and notifications sync across all servers sharing a database
• 3 Storage Backends — JSON (default), H2, MySQL, MariaDB, PostgreSQL
• Template System — Ladder-based punishment escalation with weighted template groups
• Staff Tools — Rollback, history pruning, lockdown, mutechat, clearchat, staff notes
• Investigation Tools — DupeIP alt detection, IP history, name history, last session, GeoIP
• Discord Webhooks — Real-time notifications for punishments, alts, and staff actions
• Built-in Web Dashboard — Dark-themed UI with live stats, search, and REST API
• Plugin Integrations — PlaceholderAPI, ProtocolLib, Vault, LuckPerms
• Developer API — Full StorageProvider + PunishmentManager for programmatic control
• Import System — Migrate from LiteBans, AdvancedBan, Vanilla, or JSON
• Folia Support — Fully compatible with regionized threading
• Command Flags — -s silent, -S extra silent, -p public, -m modify, -d delete, -I IP
• Staff Groups — Configurable groups with cooldowns, duration limits, and weight hierarchy
• Customizable Messages — MiniMessage format with hex colors and gradients
• Zero Runtime Dependencies — HikariCP, Gson, H2, MySQL, PostgreSQL drivers all bundled

Quick Start

# 1. Download the latest release
# 2. Place CasualBans-<version>.jar in your plugins/ folder
# 3. Start the server (config files auto-generate)
# 4. Configure storage and features
# 5. Start moderating

# plugins/CasualBans/config.yml (essential settings)
server:
  name: 'my-server'
  default-scope: '*'
storage:
  driver: JSON  # or MYSQL, MARIADB, POSTGRESQL, H2

Commands

Permissions Overview

Configuration

# plugins/CasualBans/config.yml (abbreviated)
server:
  name: 'casualbans'
  default-scope: '*'

storage:
  driver: JSON
  sql:
    host: localhost
    port: 3306
    database: casualbans
    username: root
    password: ''

mutes:
  enabled: true
  command-blacklist: ['/me', '/say', '/msg']

warnings:
  expire-after: 30d
  actions:
    - '3:kick $player Final warning: $reason'
    - '4:tempban $player 7d Reached 4 warnings'

durations:
  limits:
    admin:
      permission: casualbans.group.admin
      tempban: 6 months
      cooldown-ban: 0s
      weight: 100

webhooks:
  enabled: false
  punishment-url: ''
  alt-url: ''
  staff-url: ''

web:
  enabled: false
  port: 8291

Documentation

Full documentation is available at https://kyssta-exe.github.io/casualbans

Built With

• Paper API — Minecraft server API
• HikariCP — Connection pooling
• Gson — JSON serialization
• MySQL Connector — MySQL driver
• PostgreSQL JDBC — PostgreSQL driver
• H2 Database — Embedded SQL
• Lombok — Boilerplate reduction
• GeoIP2 — IP geolocation
• Adventure — Modern Minecraft text API

License

This project is licensed under the MIT License. See LICENSE for details.

Support

• GitHub Issues — Bug reports & feature requests