PowerfulBans - Total bans control 1.0.0

PowerfulBans is a complete, database-backed ban system for Rust. It runs perfectly on its own (chat and console commands, login enforcement, and its own SQLite or MySQL database), and when you also run PowerfulAdmin it adds a full in-game ban management panel.

>>> No dependency required. Install PowerfulAdmin only if you want the UI.

Why PowerfulBans?

• Works on its own. Commands, enforcement and storage all work with no other plugin installed. PowerfulAdmin is optional and only adds the in-game panel.
• Your own database. Bans live in SQLite (zero setup) or MySQL/MariaDB, ready to share across your whole server network.
• One banlist for your network. Point every server at the same MySQL database and a ban on one server applies on all of them, instantly.
• A real in-game panel. Search, page, ban, extend and unban from a polished UI that follows your PowerfulAdmin theme (requires PowerfulAdmin).
• Steam-aware. Optional VAC/Game ban checks and auto-kick using your own Steam Web API key.
• Safe by design. If the database is unreachable, bans are blocked with a clear message instead of silently failing, and a broken connection is reported on startup.

The in-game panel (requires PowerfulAdmin)

A dedicated Bans section in the Tools category:

• Live ban list with search (by name or SteamID) and pagination.
• Each entry shows the name, SteamID, reason, who issued it, and a clean live remaining-time countdown (e.g. "9d 1h 10m" or "permanent").
• One-click Extend and Unban (with a confirmation step).
• A Ban dialog with:
•   - a searchable, paged player picker showing online status, VAC/Game ban flags and Rust hours;
•   - reason templates plus a free-text reason and a staff-only comment;
•   - duration presets (1h, 6h, 1d, 7d, 30d, permanent) or a custom duration like `1d12h`.
• A Ban action right in the player popup, anywhere in the panel.
• Theme-aware: colors, fonts and switches follow your active theme.

Every action is written to PowerfulAdmin's Logs.

Database and multi-server

• SQLite (default): nothing to configure, the database file is created automatically. Perfect for a single server.
• MySQL / MariaDB: share one banlist across many servers. Each server can carry its own name in the shared data.
• Switch storage and migrate your data right from the Settings page, with row-count verification that reports a clear error if anything goes wrong.
• Prefer the console? Migrate without the UI from the server console: pb.migrate <sqlite|mysql>

• Bans are checked directly against the database on every login (no stale cache), so cross-server bans take effect immediately.

Steam integration (optional)

Set your Steam Web API key in the PowerfulBans config (or from the Settings page)and PowerfulBans can:

• show VAC / Game ban status on the player picker;
• automatically kick players who have a recent VAC/Game ban, with a configurable threshold in days.

This works with or without PowerfulAdmin. Rust playtime on the picker is shownwhen PowerfulAdmin is present. Steam results are cached in the plugin's own database and refreshed automatically, respecting Steam's rate limits.

Commands

Chat:

• /ban <name|steamid> [duration] [reason]
• /unban <name|steamid>
• /baninfo <name|steamid>
• /ban help                  - show all commands

Console / RCON:

• pb.ban <name|steamid> [duration] [reason]
• pb.unban <name|steamid>
• pb.info <name|steamid>
• pb.list [page]             - paged active ban list
• pb.migrate <sqlite|mysql>  - migrate storage to another backend (server console only)

Duration examples: "30m", "2h", "7d", "1d12h". Empty or "0" = permanent.

Permissions

• powerfulbans.ban - Ban and extend bans
• powerfulbans.unban - Unban
• powerfulbans.view - Open the Bans section and use /baninfo

---

Configuration

{
  "Storage": "Sqlite",
  "MySql": {
    "Host": "127.0.0.1",
    "Port": 3306,
    "Database": "powerfulbans",
    "User": "root",
    "Password": ""
  },
  "ServerName": "Main #1",
  "BroadcastBans": true,
  "AppealUrl": "https://discord.gg/...",
  "KickRecentSteamBan": false,
  "RecentSteamBanDays": 30,
  "SteamApiKey": ""
}

You can also change storage, credentials, the Steam API key and these options live from the Settings page when PowerfulAdmin is installed.

Installation

1. Drop PowerfulBans.cs into your plugins folder (Carbon: carbon/plugins/, Oxide: oxide/plugins/).
2. The plugin loads and creates its SQLite database automatically. No setup is required to start banning.
3. Grant the permissions above to your staff groups.
4. (Optional) For a shared/network banlist, open the config, set Storage to MySql, fill in your credentials, and reload the plugin.
5. (Optional) For Steam VAC/Game checks, put your Steam Web API key into SteamApiKey in the config (or the Settings page).
6. (Optional) Install PowerfulAdmin to get the in-game ban panel and Rust playtime.
7. Done. Use the commands above, or open the Bans section in the panel (Tools category) if PowerfulAdmin is installed.

Requirements

• For MySQL storage: MySQL 8.0+ (recommended) or MariaDB 10.2+.

Localization

Fully localizable. English and Russian are included out of the box, and every message lives in the language files so you can translate or reword anything for your community.

API

//
//    object API_Ban(string steamId, string name, string duration,
//                   string reason, string by, string comment = "")
//
//    steamId   target SteamID64 as a string. Invalid id -> the call returns false.
//    name      display name stored with the record. If empty, PowerfulBans
//              resolves it from the online player, otherwise falls back to the steamId.
//    duration  see "Duration format" below. Empty / invalid -> permanent.
//    reason    public reason (shown to the player on kick and in broadcasts).
//    by        who issued the ban (admin/plugin name) - stored and logged.
//    comment   optional internal note, never shown to the banned player.
//
//    Returns true if the request was accepted, false if the plugin is not
//    ready or the steamId is invalid. The ban is written asynchronously and
//    is skipped if the player is already banned (existing bans are NOT
//    overwritten). An online target is kicked immediately.

    // Permanent ban
    PowerfulBans?.Call("API_Ban", steamId.ToString(), "Cheater", "perm", "Aimbot detected", "AntiCheat");

    // Temporary ban (7 days) with an internal comment
    PowerfulBans?.Call("API_Ban", "76561198000000000", "Player", "7d", "Toxic in chat", "ChatGuard", "3rd warning");

    // Name left empty -> resolved from the online player (or the steamId)
    PowerfulBans?.Call("API_Ban", steamId.ToString(), "", "2h30m", "Team griefing", "Server");



//    object API_Unban(string steamId, string by)
//
//    steamId   target SteamID64 as a string.
//    by        who lifted the ban. Empty -> "Server".
//
//    Returns true if the request was accepted, false if the plugin is not
//    ready or the steamId is invalid. Runs asynchronously; does nothing if
//    the player is not currently banned.

    PowerfulBans?.Call("API_Unban", steamId.ToString(), "AntiCheat");



//    object API_IsBanned(string steamId, Action<bool> callback)
//
//    The result is delivered through the callback, NOT the return value.
//    The return value only tells you whether the query was accepted (valid
//    steamId + non-null callback). Checking a ban also lazily expires it:
//    a temporary ban that is already past its end time reports false.

    PowerfulBans?.Call("API_IsBanned", steamId.ToString(), new Action<bool>(banned =>
    {
        if (banned)
            Puts($"{steamId} is currently banned");
    }));



//    bool API_IsReady()
//
//    True once the storage backend is connected and the tables exist.

    if (PowerfulBans?.Call("API_IsReady") is true)
    {
        // safe to call API_Ban / API_Unban / API_IsBanned
    }



// PowerfulBans fires these so you can mirror bans to Discord, a web panel,
// stats, etc.

//    OnPowerfulBanAdded(string steamId, string name, string reason,
//                       string by, long until, string comment)
//
//        Fired when a NEW ban is created (manually, by command, or via
//        API_Ban). NOT fired when an existing ban is only extended.
//        until = -1 for a permanent ban, otherwise the Unix timestamp
//        (seconds) at which the ban expires.

    private void OnPowerfulBanAdded(string steamId, string name, string reason, string by, long until, string comment)
    {
        var expires = until <= 0
            ? "permanent"
            : DateTimeOffset.FromUnixTimeSeconds(until).LocalDateTime.ToString("dd.MM.yyyy HH:mm");
        Puts($"{name} ({steamId}) banned by {by}: {reason} [{expires}]");
    }

//    OnPowerfulBanRemoved(string steamId, string name, string by)
//
//        Fired only on an explicit unban (command / UI / API_Unban). It is
//        NOT fired when a temporary ban expires on its own.

    private void OnPowerfulBanRemoved(string steamId, string name, string by)
    {
        Puts($"{name} ({steamId}) unbanned by {by}");
    }



// The duration string passed to API_Ban (and the /ban command) accepts:
//
//    "perm", "0", ""   permanent ban
//    "30"              a plain number is MINUTES (30 minutes)
//    "2h"              hours
//    "1d"              days
//    "90m"             minutes
//    "45s"             seconds
//    "1d12h"           compound, units: d (day) h (hour) m (minute) s (second)
//    "1d2h30m"         combine freely, evaluated left to right
//
// Anything that fails to parse falls back to a permanent ban.