First run

A fresh MeowMC server boots into setup mode, which kicks every non-operator join until an operator finishes the setup wizard, then turns itself off.

The one config key

# config/meowmc-global.yml
meowmc:
  setup:
    setup-mode: auto          # auto | on | off

• auto (the default) resolves ON exactly once, at boot, when the install is demonstrably fresh: no config/meowmc-setup.state, no saved player data, and an empty ops.json. It then stays on until the wizard completes. Existing installs resolve OFF.
• on forces the gate for every non-operator join — useful for rehearsing the first run on an existing install.
• off disables the whole thing.

The runtime authority is the state file config/meowmc-setup.state. The wizard never writes the config key back, so the YAML choice and the live state cannot race.

The login gate

While setup mode is on, any non-operator who joins is disconnected:

MeowMC setup in progress
This server has not been configured yet.
Join as the server operator and run /setup to finish setup.

Server console:
[INFO] MeowMC setup mode resolved ON (auto).
[INFO] Player NotAnOp[/127.0.0.1:54120] was kicked: MeowMC setup in progress

A kick is expected behaviour on a fresh server, not an error: it logs at INFO, never at WARN or ERROR. Operators are never gated — the check uses the server's own op list.

The gate runs before the ban and whitelist checks. On a forced setup-mode: on install, a banned non-operator sees the setup message rather than their ban message; on a fresh install the ban list is empty.

The intro cinematic

The first operator to join while setup mode is on gets a roughly 16-second sequence, staged in a black-enclosed pocket at a reserved coordinate in the End: a black cat runs in, the "MeowMC" title scales in with a particle burst, a "WHAT YOU GET" panel shows the wizard's three presets, and a "Setup Required" title settles with a chat line telling the operator how to continue.

• It is a broadcast. Every player online sees the same sequence around themselves, relative to their own position and facing. In setup mode only operators can be online anyway.
• It works on a strictly vanilla client. No resource pack, no custom packets, no channel handshake.
• The call to action is clickable. It is an Interaction entity; clicking it opens the setup wizard. Typing /setup does the same thing — the hologram is a shortcut, not a requirement.

While the operator waits, one action-bar reminder appears every 8 seconds. If the operator disconnects or the call to action goes unanswered for five minutes, the intro ends cleanly and setup mode stays on.

The setup wizard

/setup opens the wizard in two surfaces, both backed by the same wizard state:

• The chat wizard (/setup, /setup done, /setup cancel).
• The dialog GUI — a vanilla Dialog that opens automatically for the triggering operator: the three presets as item rows, each with a summary, and a Done button.

The three presets

| Icon | Preset | What it is | | --- | --- | --- | | Clock | Balanced | The shipped defaults as they are in config/meowmc-world-defaults.yml. | | Netherite-upgrade | Performance | The scale-oriented keys switched on — the ones documented in these pages as opt-in rather than default. | | Shield | Compatible | Every MeowMC behavioural key switched off, for Paper-identical behaviour. |

Choosing a preset applies the write in memory first and persists it once, at Done — browsing the presets, or closing the dialog without finishing, does not touch your config files. The wizard creates no new keys.

Finishing setup

/setup done (or the dialog's Done button):

1. Teleports the operator to the overworld spawn point.
2. Flips setup mode off and rewrites config/meowmc-setup.state to {"setupMode": false, "since": …}.

From that boot onward, setup-mode: auto reads the state file — a finished install stays finished across restarts. After completion the gate costs nothing: it is a single boolean read on the login path, and that boolean is false.

/setup cancel closes the wizard for the moment and leaves setup mode on.

Notes an operator may care about

• The intro stage is not reclaimed. The cinematic writes roughly five hundred black concrete blocks into the End at 100000, 100, 100000, and the box is not torn down afterwards. It sits at a coordinate vanilla never generates, far from the main island — but it is a permanent structure on your disk.
• A corrupt state file is treated as absent, with a WARN line, and the freshness detection re-runs. The failure mode is chosen the safe way: a truncated write can never silently end setup.
• Two operators standing close together during the intro see duplicate actors — each viewer gets their own copy of the scene relative to themselves. In setup mode only operators can be online.