Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lDEVinux/eaglercraft/llms.txt

Use this file to discover all available pages before exploring further.

EaglercraftBungee is configured via config.yml in the java/bungee_command/ directory. It extends standard BungeeCord configuration with Eaglercraft-specific fields for WebSocket handling, MOTD queries, authentication, rate limiting, and client origin filtering.

​
Listeners

The listeners block defines how EaglercraftBungee accepts incoming connections. Each entry in the list corresponds to a WebSocket listener. The default configuration ships with one listener bound to all interfaces on port 25565.
config.yml
listeners:
- host: 0.0.0.0:25565
  websocket: true
  default_server: lobby
  force_default_server: true
  forward_ip: false
  server_icon: server-icon.png
  motd1: '&6An Eaglercraft server'
  allow_motd: true
  allow_query: true
  max_players: 60
​
host
string
default:"0.0.0.0:25565"
The IP address and port on which EaglercraftBungee listens for incoming WebSocket connections. Use 0.0.0.0 to listen on all interfaces, or specify a particular IP to bind to a single interface.
​
websocket
boolean
default:"true"
Must be true for browser-based Eaglercraft clients. This enables the WebSocket-to-TCP translation layer that allows browser clients to communicate with the underlying Bukkit server.
​
default_server
string
The name of the server entry (defined in the servers block) that newly connected players are routed to by default. Must match a key in the servers map.
​
force_default_server
boolean
When true, players are always sent to default_server on join, even if they were previously connected to a different backend. Useful for hub/lobby setups.
​
motd1
string
The first line of the server’s MOTD (Message of the Day), shown in the server browser. Supports Minecraft & color and formatting codes (e.g. &6 for gold, &a for green).
​
motd2
string
An optional second line for the MOTD. Add this key to the listener block to display a second line beneath motd1 in the server browser.
​
max_players
integer
default:"60"
The maximum number of concurrent player connections this listener will accept. Additional connections beyond this limit are rejected.
​
forward_ip
boolean
default:"false"
When true, EaglercraftBungee reads the player’s real IP address from the X-Real-IP header forwarded by an upstream NGINX reverse proxy. Required for IP bans and rate limiting to function correctly.
​
server_icon
string
Path to a PNG image used as the server icon in the browser server list. The server list will automatically downscale the image to 64×64 pixels. Defaults to server-icon.png in the bungee_command directory.
​
allow_motd
boolean
When true, enables MOTD queries — allows clients and server-list sites to request the server’s player count, MOTD text, and icon via a WebSocket query.
​
allow_query
boolean
When true, enables custom WebSocket query handling. This fires a WebsocketQueryEvent that plugins can listen to, allowing custom statistics or data to be returned to server-list sites that support integrated WebSocket queries.
forward_ip: true requires NGINX to be configured as a reverse proxy and set proxy_set_header X-Real-IP $remote_addr in the proxy block. See NGINX Reverse Proxy for setup instructions. Without this, IP bans and rate limiting are disabled regardless of config settings.

​
Servers

The servers block maps logical server names to backend Bukkit server addresses. EaglercraftBungee uses these entries to route players to the correct backend.
config.yml
servers:
  lobby:
    address: localhost:25569
    restricted: false
Each key (e.g. lobby) is a logical name used in default_server, /server commands, and plugin calls. The address field is the host:port of the Bukkit backend server. Setting restricted: false allows all players to be sent to this server.

​
Redirect Entries

Instead of a address, a server entry can specify a redirect URL to signal the client to disconnect from the current EaglercraftBungee instance and reconnect to a completely different WebSocket server:
config.yml
test:
  redirect: wss://ServerHere/
  restricted: false
When a player is sent to the test server (e.g. via a portal or /server test), their client automatically disconnects and reconnects to wss://ServerHere/ as if they had used Direct Connect. This is useful for multi-node networks or routing players between separate deployments.

​
Authentication Service

EaglercraftBungee includes a built-in /login and /register system, configured under the authservice key. It uses an authentication database compatible with AuthMe.
config.yml
authservice:
  authfile: auths.db
  register_enabled: true
  ip_limit: 0
  join_messages:
  - '&3Welcome to my &aEaglercraftBungee &3server!'
  login_timeout: 30
  enabled: false
​
authservice.enabled
boolean
Enables the /login and /register commands. When false (the default), authentication is disabled and all players can join without a password.
​
authservice.authfile
string
Path to the authentication database file. Defaults to auths.db in the bungee_command directory. The format is compatible with AuthMe, so existing AuthMe databases can be reused.
​
authservice.register_enabled
boolean
When true, the /register command is available to unregistered players. Set to false to disable new registrations while still allowing existing users to /login.
​
authservice.ip_limit
integer
The maximum number of accounts that can be registered from a single IP address. Set to 0 for unlimited registrations per IP.
​
authservice.join_messages
list
A list of messages sent to the player when they join. Supports & color codes. Each entry in the list is sent as a separate chat message.
​
authservice.login_timeout
integer
The number of seconds an unauthenticated player has to run /login before being automatically kicked from the server.

​
Rate Limiting

EaglercraftBungee has built-in DoS protection with per-IP rate limiting across four categories: ip (general connections), login, motd, and query. Each sub-section shares the same set of fields.
Rate limiting requires forward_ip: true in the listener config and an NGINX reverse proxy passing X-Real-IP. Without these, rate limiting is disabled regardless of the settings below. See NGINX Reverse Proxy.
config.yml
ratelimit:
  ip:
    enable: true
    period: 90
    limit: 60
    limit_lockout: 80
    lockout_duration: 1200
    exceptions: []
  login:
    enable: true
    period: 50
    limit: 5
    limit_lockout: 10
    lockout_duration: 300
    exceptions: []
  motd:
    enable: true
    period: 30
    limit: 5
    limit_lockout: 15
    lockout_duration: 300
    exceptions: []
  query:
    enable: true
    period: 30
    limit: 15
    limit_lockout: 25
    lockout_duration: 900
    exceptions: []
​
ratelimit.ip.enable
boolean
Enables or disables rate limiting for this category. Can be toggled independently per category (ip, login, motd, query).
​
ratelimit.ip.period
integer
The time window in seconds over which requests are counted. For the default ip category, a window of 90 seconds is used.
​
ratelimit.ip.limit
integer
The maximum number of requests allowed from a single IP within the period window before the connection is rejected.
​
ratelimit.ip.limit_lockout
integer
If an IP reaches this many requests within period seconds, it is locked out entirely for lockout_duration seconds instead of just being rate-limited.
​
ratelimit.ip.lockout_duration
integer
The number of seconds an IP is blocked after triggering the lockout threshold (limit_lockout). For the default ip category, this is 1200 seconds (20 minutes).
​
ratelimit.ip.exceptions
array
A list of IP addresses that are exempt from rate limiting. Local addresses such as 127.0.0.1 and 192.168.*.* are treated as exceptions by default even if not explicitly listed.
To reset the DoS protection state from the console, run: 
eag-ratelimit reset

​
Voice Chat

Voice chat is enabled by default in EaglercraftBungee. To disable it, set the following in config.yml:
config.yml
voice_enabled: false

​
MOTD Cache

The request_motd_cache block, nested inside the listener, controls how MOTD responses are cached and which online server list features are enabled:
config.yml
request_motd_cache:
  cache_ttl: 7200
  online_server_list_animation: false
  online_server_list_results: true
  online_server_list_trending: true
  online_server_list_portfolios: false
​
request_motd_cache.cache_ttl
integer
default:"7200"
Time-to-live for cached MOTD responses, in seconds. Cached responses avoid hitting the backend on every query. Default is 7200 (2 hours).
​
request_motd_cache.online_server_list_animation
boolean
default:"false"
Enables animated MOTD/icon cycling for online server list entries. For a full animated MOTD, consider installing EaglerMOTD.
​
request_motd_cache.online_server_list_results
boolean
default:"true"
Allows this server to appear in online server list search results.
​
request_motd_cache.online_server_list_trending
boolean
default:"true"
Allows this server to appear in the trending section of online server lists.
​
request_motd_cache.online_server_list_portfolios
boolean
default:"false"
Enables portfolio-style listings on supported online server list sites.

Build docs developers (and LLMs) love

Get started for freeTalk to us