Evidence BotWebsite Addons

Evidence Bot Optional Website Addons

Install and configure the separate Evidence Bot Staff Dashboard and Player Appeals website addons, including themes, domains, OAuth and security.

Evidence Bot Optional Website Addons

Evidence Bot has two optional website addons: Staff Dashboard and Player Appeals. They are separate products and are not included in the core bot download.

Install and manage an addon

  1. Purchase and download the addon separately.
  2. Extract its ZIP directly into the core bot's addons/ folder.
  3. Follow the README and config.json bundled with that addon. Do not put addon settings in the core .env.
  4. Restart the bot.

The core bot works with an empty or missing addons/ directory. Each addon is independent.

On startup, the bot discovers addon folders containing a config.json. Folders beginning with _ or ., flat JavaScript files and folders without a config are ignored.

  • Install, remove or reconfigure: restart the bot; live reload is not supported.
  • Disable: set "enabled": false in the addon's config.json, or add its ID to ADDONS_DISABLED.
  • Failure handling: if an addon fails to start, the core bot and other addons continue running. The failed addon's commands report that it is unavailable, and the error is logged.

Addons execute trusted code inside the bot process. Install only addons obtained from ZCraft Studios.

Domains, ports and OAuth

Both website addons print their listener address and port, public URL, and OAuth redirect in the startup console.

  • A missing, null, "auto" or 0 port lets the operating system choose an available port.
  • An explicit port is used as configured. Startup fails if it is already in use.
  • Local HTTP origins follow the actual listener port. HTTPS origins behind a reverse proxy remain fixed.
  • A blank baseUrl or domain defaults to local access. settings.domain accepts a custom hostname and defaults to HTTPS; baseUrl remains supported.

An automatically assigned port can change after a restart. Discord's OAuth redirect and reverse-proxy rules are external settings; they are not updated automatically. For production, use a fixed port, an HTTPS domain behind a reverse proxy, and the exact callback URL registered in Discord's OAuth2 settings.

Theme and appearance settings

Both addons include a light/dark mode toggle on the login page and signed-in navigation. A visitor's explicit choice is saved in their browser.

  • Default mode: Staff Dashboard defaults to dark; Player Appeals defaults to light.
  • Available modes: set settings.theme.mode to light, dark or system in the addon's config.json. System mode follows the visitor's device preference until they choose a mode.
  • Separate palettes: optional settings.theme.light and settings.theme.dark objects let you define each mode independently.
{
  "theme": {
    "mode": "system",
    "light": { "primary": "#4769e8", "primaryText": "#ffffff" },
    "dark": { "primary": "#6b8afd", "primaryText": "#090e1b" }
  }
}

Place the theme object under the addon's settings in its config.json. Colors are validated. Existing flat color settings still apply to the palette that matches their brightness.

Each addon exposes a validated whitelist of public theme and text settings. The addon's config.example.json lists the accepted keys. Unsupported keys are rejected with a configuration error. Customized text is rendered as plain text, not HTML; listener addresses, ports and OAuth secrets are not exposed through appearance settings. Unset values use the addon's defaults.

Staff Dashboard

The Staff Dashboard is a staff-only website addon for statistics, evidence review, assignments, case management, exports and appeal decisions.

  • Installs into addons/appeals-dashboard/. The folder and addon ID retain that older name for compatibility.
  • Uses Discord OAuth sign-in.
  • Checks current Discord staff roles on every staff action.
  • Excludes private staff data from player-facing responses.
  • Protects write requests with same-origin and CSRF checks, and rate-limits requests and submissions.
  • Uses indexed lookups and on-demand case history loading to keep the interface responsive.
  • Keeps sessions in memory; sessions end when the bot restarts.
  • Requires HTTPS for production URLs.

Follow the README included with the Staff Dashboard addon for its exact setup steps.

Player Appeals

Player Appeals is a separate player-facing website. Players sign in with Discord, submit an appeal and follow their own tickets and public review outcomes. It installs into addons/player-appeals/, does not depend on the Staff Dashboard and adds no slash commands.

How submissions work

  • The form collects the Minecraft name, punishment type and reason, an appeal statement and optional evidence. Discord identity comes from verified sign-in, not typed input.
  • Selecting an original case is optional. Without one, the bot matches the newest open punishment for that player, name and type. Ownership requires a recorded Discord identity.
  • If no matching case is found, an unlinked appeal is created. Imported punishment records do not include Discord identities, so staff must verify the player and link the appeal with /linkappeal.
  • Duplicate open appeals are rejected and submission attempts are rate-limited.
  • Intake and later decisions are added to the original case thread and timeline without changing the original punishment status.

Access boundaries

Player Appeals is player-only. Its API rejects staff queue and decision access, even for an authenticated administrator. Staff review appeals through the core Discord commands or the Staff Dashboard.

The site uses its own session cookies, OAuth callback and listener, separate from the Staff Dashboard. See Domains, ports and OAuth when configuring the callback URL.