MeowMC

Files and precedence

MeowMC's configuration is four files, separate from Paper's own config files, with the inheritance model operators already know.

The four files

| File | Scope | Created | | --- | --- | --- | | config/meowmc-global.yml | Everything that is not per-world. | Written by the fork. | | config/meowmc-world-defaults.yml | The defaults every world inherits. | Written by the fork. | | <world>/meowmc-world.yml | The keys one world overrides. | Created empty (header only) the first time its world loads — defaults are never copied into it. | | config/meowmc-plugin-policies.yml | How plugins are treated. | Written by the fork. |

The per-world file is created with a header only, and that is deliberate: copying the defaults into it is how a file silently freezes a stale value when the defaults file is later improved. If your per-world file is nothing but the header, your world is running the defaults.

Precedence

Lowest to highest:

hardcoded Java field default  <  meowmc-world-defaults.yml  <  <world>/meowmc-world.yml
                                     ▲
                                     └── for global keys, meowmc-global.yml is the only level

  • Absent means inherit. A key that is not present in a world's file takes the world-defaults value; a key that is not present in the world-defaults file takes the Java field default. This is the Paper idiom — no special MeowMC logic is involved.

  • Absence is the default. Do not write null or inherit to mean "default". Just leave the line out.

The INHERIT sentinel

A small number of world keys are meaningfully world-overridable — a hub world wants 64-chunk sections, a survival world does not. For exactly those keys, the world file may carry the literal string INHERIT:

| Key | Notes | | --- | --- | | exec.mode | Resolve to the global value. | | exec.region-grid-exponent | Resolve to the global value; 3 gives 64-chunk sections for hub worlds. |

INHERIT exists so an operator can say "whatever the global says" after having written a world-specific value once: it resolves to the global value at load time, so a later read never pays an inheritance lookup.

Everything else in the world file is absent-by-default, never INHERIT.

Mode precedence is one-way

exec.mode may be INHERIT or a concrete mode — it may not declare a different tier from global. If global is compat and a world declares regionized, the server fails loudly at startup, naming the world and the offending path: the regionizer is a server-wide machine.

Enforcement floors with tier, not with config: exec.threading.enforcement is off | log | throw, default off, and its effective value is max(configured, tier-implied) — at regionized it floors at log. (exec.verification-mode: true forces throw regardless.)

_version

Both the global and the world files carry _version: 1 — the MeowMC schema counter, in MeowMC's own numbering space (never Paper's V29_*…V31_*).

  • A version bump happens when a key is renamed, moved, or its semantics change — not when one is added. A new field's Java default covers it.
  • meowmc-plugin-policies.yml carries no _version. It is keyed by plugin name and has no nested versioned schema.

The current value is visible in any report artifact as server.configSchemaVersion.

Renamed and retired keys

Two rules protect operator muscle memory:

  • Renamed keys stay accepted, with a warning naming the new path.
  • Retired keys are removed by a transform, not silently ignored — so stale YAML is cleaned with a message rather than left as a knob that does nothing.

| Retired key | Why | | --- | --- | | world.optimization.netty-recv-cap | A channel belongs to a bind, not a world — the key moved to global network.recv-byte-cap. | | world.optimization.lazy-entity-ai, world.mob-caps.mode | Declared and read by nothing. The lazy-AI lane is already covered by an upstream feature, and the two-ary mob-caps mode was structurally wrong — the mob-cap levers that actually exist are Paper's own paper-world.yml keys. |

Invalid input fails loudly

Invalid input fails loudly at startup, naming the offending path. No lenient fallback, no "default the field and carry on" — a typo in a key name is an error you see at boot rather than a knob that silently does nothing.

One naming rule, and how to read the yml

Every MeowMC key is under a single meowmc: root in its file — the files are flat, so meowmc.exec.mode in the documentation is:

meowmc:
  exec:
    mode: compat          # compat | regionized | regionized_aggressive | vertical | diagnostic

Comments in the shipped YAML files are load-bearing — read them.