Configuration

Configuration Guide

config.yml is organized by feature group. The exact, fully commented 4.6.1 file is available at Default Config.

Core

config-version: "4.6.1"
enabled: false

update-check:
  enabled: true

• config-version is a configuration review marker.
• enabled is the global BlueMapWebChat switch.
• update-check.enabled checks Modrinth for a newer stable release. Timing, channel, join delay, and download links use built-in defaults and are intentionally not exposed as separate config keys.

Network and web hosting

Main blocks:

• http
• web-addon
• standalone-web

Common options:

Setting	Default	Purpose
http.host	0.0.0.0	Direct listener address. Use 127.0.0.1 behind a local reverse proxy.
http.port	8899	Internal HTTP port
http.path-prefix	/api	API base path
http.cors-origin	*	Browser origin policy; set the actual HTTPS origin for public authenticated deployments
http.trusted-proxies	[]	Reverse proxies trusted for forwarded client IPs
web-addon.auto-install	true	Install/update the BlueMap addon assets
web-addon.auto-patch-webapp-conf	true	Patch the BlueMap webapp config automatically
web-addon.api-base-url	empty	Public API URL/path used by the BlueMap addon
standalone-web.enabled	false	Enable the plugin-hosted standalone page
standalone-web.path	/chat	Standalone page path

Public chat and message features

Main blocks:

• chat
• search
• announcements
• reply
• pinned

New configs use SQLite history by default. Retention and maximum history size are configurable; 0 means unlimited/no count limit where documented by the option comment.

Private messaging and server relay

Main blocks:

• direct-message
• group-chat
• server-relay

DM storage is separate from public history and is disabled by default:

direct-message:
  enabled: false
  storage: "auto"
  retention-days: 0
  capture-game-whispers: true
  admin-audit:
    enabled: false

Cross-server chat is also opt-in:

server-relay:
  enabled: false
  server-id: "server-1"
  server-name: "Server 1"
  shared-secret: ""
  peers: []

See Direct Messages and Server Relay.

Accounts, permissions, and moderation

Main blocks:

• player-display
• guest
• captcha
• auth
• security
• admin
• private-chat-super-admins
• audit
• moderation
• commands

For a public server, review login limits, admin source-IP restrictions, trusted proxies, upload limits, and whether the web command panel should be enabled.

Web UI and notifications

Main blocks:

• ui
• notifications
• web-push
• web-fonts

Supported built-in UI languages:

en-US
ko-KR
ja-JP
zh-CN

Integrations

• discordsrv
• emoji
• upload
• preview

See DiscordSRV, Uploads, Emoji, and Previews, and ImageEmojis-Bero.

Applying config changes

Most settings can be reloaded with:

/bmchat reload

Replacing the plugin JAR requires a server restart.