Servers and scope

Global. The record applies everywhere that shares the database. Stored with scope global and no server ID.

Server. The record applies only on the server whose ID it was stored against. Stored with scope server and that ID.

A server enforces a record when the record is global, or when the record's server ID matches its own server.id. Records that match neither are still stored and still show in history. They are just not applied here, which is exactly what you want when a hub and a survival server share one database.

In settings.yml:

server:
  # Unique per server. Lowercase letters, digits, dots, dashes, underscores.
  id: "survival"

  # Shown to players and staff in messages.
  display-name: "Survival"

  # "server" or "global"
  scope: "server"

scope is the default applied when a command does not say otherwise. It does not restrict what staff can choose; it decides what happens when they choose nothing.

Server IDs are normalised before storage: lowercased, and any character outside a-z 0-9 . - _ becomes a dash. A blank ID becomes default. Pick the final ID before staff start punishing, because renaming it later orphans every record stored against the old one.

Any punishment command accepts --scope:

/ban Steve 30d Cheating --scope server:global
/mute Steve 1h Spam --scope server:this
/ban Steve 7d Griefing --scope server:creative

An unrecognised bare value is treated as a server ID, so --scope creative and --scope server:creative mean the same thing.

Scope is permission-gated so a moderator on one server cannot quietly ban someone from the whole network.

Punishing on your own server is always allowed with no scope node at all: if the resolved scope matches the local server.id, the check passes. Console bypasses the check entirely.

Single server, no proxy

server:
  id: "main"
  display-name: "The Server"
  scope: "global"

Global by default. There is no second server for a local scope to distinguish, and global records are simpler to reason about if you add a proxy later.

Network with a shared punishment policy

Every backend and the proxy point at the same database. Each has its own id. All of them set:

server:
  scope: "global"

Ban once, banned everywhere. Grant blazebans.scope.server.<id> to server-specific staff who should only be able to punish locally.

Network with independent servers

Same shared database, scope: "server" on each. A ban on the minigame server does not touch survival. History is still shared, so staff on either server can see the whole record before deciding. Grant blazebans.scope.global only to network administrators.

Scope controls enforcement, not visibility. /history and /lookup show every record for a player regardless of where it was issued, and the entry says which server it came from. That is deliberate: a moderator deciding on a punishment should see that the player was banned on another server last week.

The same applies to alt lookups, staff history, and the profile menus. Only enforcement is scoped.

Running BlazeBans on both the Velocity proxy and the backend servers is the usual network setup.

The proxy checks bans at connection time and refuses the connection before the player reaches a backend. That produces the ban screen on the server list rather than a join-then-kick, and it means one lookup instead of one per backend.

Backends still need BlazeBans for mutes, warnings, chat enforcement, the GUIs, and AutoMod, since none of those exist at the proxy layer. Give the proxy its own server.id (proxy works) so its own records are distinguishable.