Configuration

EmberMC's settings live next to Paper's, use the same file conventions, and are loaded by the same machinery - Paper's Configurate-based system, reused rather than duplicated. If you know paper-global.yml, you already know how these work.

File	Scope
config/ember-global.yml	the server
config/ember-world-defaults.yml	every world, unless a world overrides a key
<world>/ember-world.yml	one world's overrides - only the keys it changes. Lives next to Paper's paper-world.yml, e.g. world/dimensions/minecraft/overworld/ember-world.yml on current world layouts

Paper's own files are untouched. EmberMC never reads or writes paper-global.yml.

The rules

Every option is real. An option appears in the file only when something in the build reads it. Sections for the entity engine, Packet Guard and the adaptive engine arrive with the milestones that implement them. The one exception is marked as such (entities.optimization, read and shown today, applied from Milestone 4) so world files can be prepared ahead of it.

Every option is documented here, with its reload semantics. The YAML loader Paper ships writes a header comment per file but not per-key comments - Paper's own paper-global.yml is the same - so this page is the reference. Each option is either reload-safe (/ember reload applies it) or restart-only, and /ember reload tells you which values it applied and which need a restart.

Versioned. _version at the top of each file. When a key moves, a transformation migrates old files in code; a value you set is never silently dropped.

Presets are defaults, not locks. profile decides what an unset option means. Anything you set explicitly wins over the preset.

ember-global.yml

_version: 1

# VANILLA, BALANCED, PERFORMANCE or EXTREME (case-insensitive when read). Decides what unset options mean;
# anything set explicitly wins. Read by later milestones. Restart-only.
profile: BALANCED

console:
  # Print the EmberMC box at startup. Restart-only.
  banner: true
  # truecolor, indexed-256, indexed-16 or none. Panel consoles render truecolor;
  # a plain terminal showing garbage wants indexed-16 or none. Restart-only.
  color-level: TRUECOLOR

status:
  # Show "live heap after last GC" in /ember status. Used heap counts uncollected
  # garbage; live heap is the footprint. Reload-safe.
  show-live-heap: true

update-checker:
  # One line at startup naming the build. Never contacts the network. Reload-safe.
  startup-message: true

ember-world-defaults.yml and <world>/ember-world.yml

_version: 1

entities:
  # inherit (use the server profile), vanilla, balanced, performance or extreme.
  # NOT YET APPLIED: the entity engine arrives in Milestone 4. Read and shown in
  # /ember config today so world files can be prepared ahead of it.
  optimization: INHERIT

A world file starts empty apart from _version. Add only what that world changes:

# world_resource/dimensions/minecraft/overworld/ember-world.yml
_version: 1
entities:
  optimization: EXTREME

Entity tiers, profiler, adaptive engine, metrics

Added by Milestones 3, 4 and 9. All in ember-global.yml; all reload-safe unless marked.

entities:
  tiers:
    enabled: true              # split Paper's activation range into full ring + outer ring
    full-range-fraction: 0.0   # 0 = from profile (BALANCED 0.75, PERFORMANCE 0.5, EXTREME 0.4)
    reduced-interval: 0        # 0 = from profile (2, 2, 4): outer-ring entities tick fully every N ticks

profiler:
  spike-threshold-ms: 100            # a tick longer than this writes a report to ember-reports/
  spike-report-cooldown-seconds: 30
  keep-spike-reports: 50
  spike-reports-dir: ember-reports
  default-session-seconds: 60        # /ember profiler start with no duration

adaptive:
  enabled: true                # respond to load: light / moderate / aggressive
  light-above-ms: 35.0         # tick p95 (5 s) thresholds
  moderate-above-ms: 45.0
  aggressive-above-ms: 50.0
  exit-margin-ms: 5.0          # leave a level only this far below its entry threshold
  hold-up-seconds: 5           # sustained above before rising one level
  hold-down-seconds: 20        # sustained below before falling one level
  ceiling: aggressive          # highest level allowed

metrics:
  endpoint:
    enabled: false             # Prometheus text at http://<bind>:<port>/metrics. Restart-only.
    bind: 127.0.0.1
    port: 9464

The adaptive engine changes exactly one thing today: it scales the entity tiers' full ring (never below 25% of the range) and outer-ring interval (never above 10). Every level change is one console line with the p95 that caused it, and /ember status shows the current level.

Pathfinding, item and XP limits, chunks, memory

Added by Milestones 5, 6, 7 and 10. All in ember-global.yml, all reload-safe. Each has a full write-up under How it works.

entities:
  tiers:
    always-full: []            # entity type paths pinned to full ticks regardless of distance
                               # e.g. [villager, piglin] for a trading hall. Empty = zero cost.
  pathfinding:
    enabled: true              # stop mobs re-running A* against a target they cannot reach
    failures-before-backoff: 8 # consecutive failed searches to the same target before backing off
    backoff-ticks: 40          # how long the backoff lasts once armed
  item-limits:
    enabled: false             # cap dropped-item entities per loaded chunk (anti dupe-flood)
    max-per-chunk: 300
    sweep-seconds: 10
  xp-limits:
    enabled: false             # cap XP-orb entities per chunk by folding overflow into survivors
    max-per-chunk: 200         # no experience is ever lost, only entity count drops
    sweep-seconds: 10

chunks:
  retention-diagnostics: true  # /ember chunks shows what holds chunks loaded; warns on a leak
  warn-threshold: 400          # plugin-held chunks in one world before a rate-limited warning
  warn-cooldown-seconds: 300

memory:
  idle-trim:
    enabled: true              # hand idle heap back to the OS after the server is empty a while
    after-minutes: 5           # needs uncommit-friendly JVM flags to actually shrink; see the docs

security:
  packet-guard:
    plugin-message: { per-second: 20, burst: 60, max-bytes: 32768, action: throttle }

The adaptive engine (adaptive.* above) also tightens the pathfinding backoff on its own under sustained load, within bounded limits; at normal load it changes nothing.

Presets

Preset	Intent
vanilla	EmberMC systems present but passive: observe and report, change nothing about gameplay timing
balanced	Production default. Optimisations no player can notice; protections on with generous limits
performance	Larger activation ranges, longer inactive intervals, tighter limits. Test your farms
extreme	Lobbies, minigames, resource worlds. Distant entities barely tick. Not for a main survival world

Commands

Command	Permission	Does
/ember config	ember.command.config	Active profile, console settings, file locations, each world's effective values
/ember reload	ember.command.reload	Re-reads all three kinds of file; reports what applied and what needs a restart