Dimensions: Configuration and customization

Configure your atlas

Global settings live in plugins/Dimensions/config.yml; map definitions and pins belong in plugins/Dimensions/maps/<id>.yml. New installs generate neutral names from loaded worlds, with no demo destinations. See per-map setup and UI/items/players/mobs customization. Legacy combined configs remain supported; /dimensions maps migrate splits them with a backup. Edit config.yml for the global defaults below. Keep IDs lowercase (a-z, 0-9, _, -), up to 48 characters. IDs are stable save keys: changing a waypoint ID creates a different unlock identity; changing its display name does not.

Server control

The owner chooses the atlas mode and whether the minimap is available. These settings apply with /dim reload.

dimensions.display and dimensions.minimap.toggle default to false, including for operators. Grant them explicitly if you enable player choice. Players still need dimensions.use and dimensions.minimap to see the minimap. A permission cannot bypass an owner lock. Saved choices stay in player-settings.yml, but are ignored while locked.

Reload closes active atlas views and rebuilds the HUD with the new settings. Invalid display.mode values are rejected before the running services are stopped. For older configs, ui.screen-space is used only when display.mode is absent; true means screen and false means native. Set display.mode explicitly when updating.

Upgrade note: minimap.enabled used to be a player default. It is now the master switch. Set it to true if you want the minimap available; old saved on choices cannot bypass false.

Maps

New setups use the per-map file format. The following combined form remains accepted for existing servers:

worlds:
  overworld:
    world: world
    name: Overworld
    subtitle: ''
    color: '#56E5BC'
    center-x: 0
    center-z: 0
    blocks-per-pixel: 8
    image: ''
    gateway: ''

Each map defines a world and the center used when switching to it. Opening the current world starts near your physical position; A/D centers on destinations. The plugin reads existing chunks and does not create worlds or generate missing terrain. Missing areas stay uncharted. W/S cycles legacy maps in config order, followed by per-map files in filename order.

display:
  mode: native
  allow-player-override: false
ui:
  canvas-distance: 3.6
  mouse-sensitivity: 1.2
  max-pan-pixels-per-tick: 6
  native:
    fov: 70
    aspect: 1.77777778
    fit: contain
    scale: 1.0
    update-interval-ticks: 4
    transitions:
      enabled: true
      ticks: 6
  update-interval-ticks: 2
  quests:
    - 'Explore the region'
    - 'Discover new destinations'
  events:
    - 'No active events'
map-players:
  enabled: true
  max-visible: 64
renderer:
  blocks-across: 112
  yaw: 25
  elevation: 60
  snapshots-per-tick: 8
  capture-time-budget-ms: 2
  height-padding: 32
  refresh-seconds: 60
  save-previews: false
  use-itemsadder-pack: true
  resource-packs: []

blocks-across controls the initial span, bounded to 64–256 blocks. Scroll changes it by 16. yaw turns the orthographic map; elevation controls its downward angle (35–80 degrees). At 25/60 the map is slightly isometric. Geometry and textures are depth tested before UI layers are composited. The compact compass bearing ruler shows the latest world-space pan heading.

Snapshot capture defaults to at most eight chunks per server tick (snapshots-per-tick, bounded to 1–16), with up to four asynchronous chunk loads in flight. capture-time-budget-ms: 2 stops starting additional snapshot work after the elapsed budget; a snapshot already in progress cannot be interrupted and can exceed that budget. height-padding: 32 adds projected coverage for hills and buildings beyond the visible footprint; increase it for unusually tall surroundings at the cost of capturing more terrain.

Geometry, texturing and depth rendering run on one worker. The renderer builds compact surface bands from cached chunk snapshots, retaining real cliffs and raised structures without copying every underground block. Unknown chunks and capture boundaries are treated as closed boundaries, suppressing artificial cut-wall curtains. Shared views coalesce into one render; recent frames and chunk snapshots are cached. Block placement, breaking and explosions invalidate the corresponding world cache. Open maps refresh in the background at the configured interval, keeping their current image until the replacement is ready.

The map canvas is 1024×640. Terrain fills the canvas behind compact panels made from the supplied dark pixel artwork. Look input pans terrain beneath the fixed player-head focus. Both modes move a private camera through cached terrain; the input seat and interface remain stable. ui.mouse-sensitivity is pixels of movement per degree (default 1.2). ui.max-pan-pixels-per-tick caps total movement per tick (default 6); excess input is discarded, so stopping the mouse stops the map without queued drift. Use Q to pin the focus/nearest destination, F to travel, A/D to select destinations, W/S to switch worlds, scroll to zoom and Shift to close. Nearby terrain is prefetched at most twice per second. If it is not ready, focus pauses at the cached edge and a small charting notice appears over the retained image. Opening, zooming and switching maps show a branded loader until the complete image and camera are ready. Ungenerated chunks remain uncharted.

display.mode: native is the default. Ordinary map frames are positioned using FOV and aspect saved by display setup; ui.native.fov and aspect remain fallback settings. The legacy /dimensions calibrate <fov> <aspect> command changes those two values only. FOV is bounded to 30–110, aspect to 0.5–4 and scale to 0.5–1.5. fit: contain keeps the complete interface visible with margins when window/canvas proportions differ. cover fills the window by cropping edges and can hide controls. Scale 1 uses the calculated fit; larger values enlarge it. The server cannot query exact FOV/window dimensions, so use /dim setup after client changes. Shader packs can alter lighting, exposure and appearance even in native mode.

When the owner enables display.allow-player-override and grants dimensions.display, /dim display native or /dim display screen saves that player's mode and reopens the atlas. Optional screen mode uses the marked-map shader included in the base pack: the HUD scales uniformly to fit, while terrain scales uniformly to cover the window. Wide windows leave terrain-visible margins around the HUD and crop some terrain vertically. Screen mode does not work with an active Iris shader pack. Having Iris installed with shader packs off is fine. ui.canvas-distance applies to that mode's staging; native distance comes from calibration. Neither mode changes client settings, intentionally freezes the client or guarantees universal fullscreen fitting.

Pixel-art PNGs use nearest-neighbor scaling. The panel preserves the supplied panels/bg.png rim through nine-slice rendering. Bitmap text, keys and icons retain their proportions. Fractional viewport scales do not guarantee one physical pixel per logical pixel. Native mode uses 112 terrain map frames and 40 TextDisplay interface tiles; optional screen mode uses 128 terrain map frames and 48 HUD map frames with dedicated metadata rows. The vanilla map palette limits map-frame colors; native interface glyphs retain RGB colors. Composition and palette conversion run asynchronously; changed tiles are bundled into the same client update. Cached views remain visible while replacement terrain is rendered.

ui.native.update-interval-ticks: 4 checks native interface changes five times per second at 20 TPS; it no longer controls pan smoothness. The camera and retained interface move each tick with client interpolation. The 112 terrain maps remain unchanged during cached panning. A new cached region or updated world markers can upload changed terrain tiles; the 40 interface TextDisplays update text only for changed tiles. The cadence setting is bounded to 2–20 ticks. Optional screen mode uses ui.update-interval-ticks: 2 (bounded to 1–4), checking changed textures up to ten times per second. Unchanged idle views skip composition. renderer.save-previews: false disables diagnostic PNG exports by default. These are work budgets, not a guarantee of no FPS drops.

First-use display setup

First atlas or minimap use opens a Paper dialog for actual game viewport width, height, FOV and numeric GUI scale. F3 shows the game's Display size; FOV is in Options and GUI Scale in Video Settings. Enter the game's viewport pixels rather than monitor dimensions, and choose a numeric GUI scale instead of Auto. Dimensions does not detect these values automatically. Saved raw inputs, derived atlas aspect/minimap GUI dimensions and versioned setup completion are written together to player-settings.yml.

The atlas camera starts only after a valid save. Cancel or Escape leaves first-use setup incomplete without moving the camera; the form also expires after five minutes. Existing users with older calibration preferences are prompted once, with known values prefilled and other preferences preserved. /dim setup, /dim calibrate with no arguments, or /dim minimap calibrate with no dimensions reopens the form after window, FOV or GUI-scale changes. The legacy numeric commands remain available but do not replace initial setup.

Accepted viewport sizes are 320–16384 pixels wide and 240–16384 high, FOV 30–110, and numeric GUI scale 1–16. Aspect must be 0.5–4. Scales that Minecraft would reduce because the viewport cannot fit a 320×240 logical GUI are rejected; the resulting GUI must also be at most 4096 pixels wide and 1000 high. No settings are partially saved when validation or disk writing fails.

Owners can edit these plain-text keys and run /dim reload:

calibration:
  title: Display setup
  instructions:
    - 'Enter the game viewport width and height shown beside Display on the F3 screen, not your monitor size.'
    - 'Use the FOV from Options and the numeric GUI Scale from Video Settings. Choose a number instead of Auto.'
    - 'Use /dim setup again after changing these settings.'
  save-label: Save and continue
  cancel-label: Not now

Title length is limited to 64 characters, instructions to four lines of 300 characters each, and button labels to 24 characters. Input identifiers and validation are fixed. The pack supplies scoped button artwork; see customization.

Layout

The default ui.layout.preset: right-panel groups region information, destination details, quests and events in one bordered right panel. ui.layout.right-panel.sections sets their order; each section has a visibility flag, height and text/item limits. Header, logo, footer, compass, focus and notice positions are also configurable. Coordinates use the 1024×640 logical canvas, not monitor pixels. Text stays at its bitmap size; resizing a panel clips overflow rather than stretching letters. Run /dimensions reload after changing layout. See the complete layout example; art paths and colors remain in ui.yml.

Optional minimap

The minimap samples a 72×72 top-down terrain grid by default and uses custom resource-pack font glyphs in the normal title GUI channel. The default display occupies 156×156 logical GUI pixels, including a three-cell panel rim (312×312 screen pixels at client GUI scale 2), inset four logical pixels from the corner. It reads loaded terrain only, never loads chunks, and is separate from the textured isometric atlas. The current pack and completed display setup are required. Its player markers respect map visibility settings and opt-outs.

minimap:
  enabled: false
  default-enabled: true
  allow-player-toggle: false
  scale: 3
  frame: panels/bg.png
  resolution: 72
  radius: 48
  left: 4
  top: 4
  update-ticks: 20
  marker-update-ticks: 4
  columns-per-tick: 512
  sampling-budget-ms: 1
  cache-refresh-ticks: 100
  player-head: true
  heading: true
  players: true
  max-players: 8
  external-title-hold-ticks: 100

Set minimap.enabled: true to make the minimap available. False disables it for everyone. default-enabled controls its starting state and the state of players who cannot choose. To allow /dim minimap on|off, set allow-player-toggle: true and grant dimensions.minimap.toggle; players also need dimensions.use and dimensions.minimap. Radius is bounded to 12–96 blocks, update interval to 20–100 ticks, player count to 0–16 and external-title holdoff to 20–1200 ticks. left and top are logical GUI offsets. The preview pauses for setup, the atlas, active Dimensions effects and other plugins' titles, with the configured holdoff after an external title.

scale is bounded to 1–3: the framed display is respectively 60×60, 108×108 or 156×156 logical GUI pixels. Each display cell occupies two logical GUI pixels, with a fixed three-cell rim on every side. resolution independently controls terrain sampling detail, bounded to 24–72 samples per side. Enlarging the display does not increase the configured sampling workload. frame is a PNG path relative to plugins/Dimensions/ui/, defaulting to the supplied panels/bg.png. Run /dim reload after changing size or artwork. This display scale is separate from the client's GUI scale used for calibration.

Terrain jobs share columns-per-tick (32–2048) and sampling-budget-ms (0.1–4 ms) across viewers. The time budget stops additional reads; an individual read can exceed it. cache-refresh-ticks is bounded to 20–1200 ticks. update-ticks sets the wait between stationary terrain jobs. Walking into another sample cell starts the next job sooner. Nearby updates keep the last complete frame visible until the replacement is ready. World changes or large movement discard stale views.

player-head: true shows your skin face with a dark rim; false restores the small dot. heading adds a small facing arrow. The face stays upright and the map stays north-up. Skin downloads run in the background and use a cache; a default head appears while the first download is pending. MineSkin is not used. These options apply to your own marker; players controls other players' dots.

Cached terrain has a separate limit of 8,192 lookups per tick under the same time budget. A fully cached grid can finish in one tick if time allows, without spending the world-read allowance. New terrain still uses the configured read limit.

marker-update-ticks sets the position and facing refresh target, from 4 to 20 ticks (default 4, about 200 ms at 20 TPS). Marker updates do not wait for terrain sampling. Only one minimap is composed per server tick across all viewers, so busy servers update each player's map less often. Unchanged images normally renew only their display timer, with a full refresh every five seconds to recover from connection stalls. Changed pixels are sent at the next update. This reduces repeat packets but does not provide frame-by-frame animation or remove network delay.

Admins can run /dimensions status PlayerName from chat or console to inspect the minimap's pause reason, Dimensions pack readiness, saved GUI size, send count and title conflicts. Built-in hosting tracks its own pack UUID; another pack's latest status cannot disable it. Enabling the minimap requests the pack again if its successful load has not been confirmed.

Use /dim setup after changing viewport size, FOV or GUI scale. It updates native atlas fit and minimap placement together. The legacy /dimensions minimap calibrate <width> <height> <gui-scale> command updates minimap values only and does not complete first-use setup. Allowed on/off choices and calibration persist per player. Owner locks always take precedence.

Logo, quests and events

The default Dimensions logo is copied to plugins/Dimensions/ui/logo.png. Replace that PNG and run /dimensions reload to change branding. Preserve transparency; avoid pre-blurring small pixel artwork. The supplied icon PNGs and green arrow/pin models are included in the packs, with editable sources retained in resourcepack-source/.

ui.quests and ui.events are lists of text lines displayed in the unified right panel. %player_name%, %world% and %online% work directly. Installing PlaceholderAPI allows its expansions, for example a quest plugin's registered progress placeholder; install the relevant expansion separately. The atlas displays these values and does not create quests or run arbitrary commands. Keep entries short for the bitmap font. Formatting codes are removed because the canvas owns the panel typography and colors.

Player heads and privacy

map-players.enabled controls nearby-player markers; max-visible bounds displayed candidates to 1–128 (default 64). Only online players in the map's physical world who are visible through Bukkit's canSee check and have not opted out are considered. Faces use cached 8×8 skin pixels, including the hat layer. Skin downloads are asynchronous and bounded; a default face appears while a skin is unavailable.

/dimensions follow false hides your head from other players' maps; true shows it again. This requires dimensions.follow (default true) and is saved in player-settings.yml. It changes map visibility, not another player's location or guidance target. Personal pins and navigation displays are private to their owner. Back up player-settings.yml with the other plugin save files.

Terrain resources

resource-packs lists local ZIP paths, in increasing priority order; relative paths start at plugins/Dimensions/. The renderer also reads plugins/ItemsAdder/output/generated.zip when enabled. Unreadable optional images/models are logged and skipped, preserving existing assets; an unreadable generated ItemsAdder archive does not disable Dimensions. Protected generated packs may require a readable source pack in resource-packs for their custom terrain textures. Run /dim reload after regenerating the ItemsAdder pack so new block-state/model overrides are loaded. This affects rendered blocks, not pack distribution; choose one client pack distribution mode as described in ITEMSADDER.md.

For a cutaway view, optionally add render-min-y and render-max-y to an individual world. The lower limit is inclusive and the upper limit exclusive. The Nether defaults to a ceiling cut at Y=96 so the bedrock roof is omitted; tune that cut to the caves/structures on your server. Other worlds use their normal build-height range. Roofs are otherwise real geometry and occlude what is below them.

The old blocks-per-pixel and image fields remain accepted for configuration compatibility and do not control the new renderer. No raster-font grid or live-world aerial view is used.

Destinations

waypoints:
  village:
    map: overworld
    name: Willow Village
    description: A quiet stop along the northern road
    x: 120.5
    y: 71
    z: -80.5
    yaw: 90
    pitch: 0
    unlocked: false
    discoverable: true
    travel: true
    permission: ''

unlocked is the default for every player. Explicit per-player true/false values override it in unlocks.yml. discoverable unlocks on physical approach within the configured 3D radius, once per second. Unexplored destinations can be pinned and walked to; their fast travel remains locked. Viewing a destination through the atlas does not discover it. Personal terrain pins grant guidance only, never fast travel.

permission is an additional gate: the player needs it even if the destination is public or saved as unlocked. A discovery cannot override a missing permission. travel: false allows navigation without fast travel. Set discoverable: false for quest-only unlocks. If you administratively lock a discoverable destination while the player stands next to it, proximity discovery will unlock it again; disable discovery for a durable quest lock.

/dim add <id> <map> <name...> records your exact position and facing. New destinations default to locked, discoverable and travel enabled. The map must belong to your current world. Set Y to a safe standing location. Fast travel checks a bounded area within ±16 vertical blocks and the configured horizontal radius, rejecting liquid, fire, lava, dangerous floors and locations outside the world border.

Cross-world guidance

Without a gateway, guidance to another world displays “Enter [world] to continue” until the player enters it. For physical travel, set the current map's gateway to a waypoint in that same world. Guidance will point to that gateway, then automatically resume toward the final destination after a world change. The plugin does not create portals or infer a multi-hop portal graph. Server owners configure the gateway and its actual portal separately.

The supplied green arrows stay at the player's height and interpolate between updates. They do not sample every block's top surface. They tilt toward a higher/lower destination when approaching it; they indicate a bearing rather than computing a walkable route. The supplied destination pin bobs slowly when you are close:

navigation:
  arrow-height: 0.85
  arrow-sway-width: 0.10
  arrow-sway-degrees: 4
  arrow-sway-period-ticks: 80
  elevation-distance: 24
  marker-bob-height: 0.18
  marker-bob-period-ticks: 100
  marker-sway-width: 0.08
  marker-sway-degrees: 3
  marker-sway-period-ticks: 120

arrow-height is the offset above the player's feet. Sway widths are sideways distances in blocks; sway degrees control gentle roll. Arrows keep their center at player height throughout their sway. elevation-distance is the horizontal range where vertical guidance starts to blend in. marker-bob-height is the pin's vertical amplitude. Periods are full cycles in ticks (100 ticks is five seconds at 20 TPS); set widths, degrees or bob height to zero to disable that part of the animation. Models use full block/sky brightness, disabled face shading and element light emission 15 in vanilla 26.2. They do not illuminate surrounding blocks, and shader packs can still apply their own exposure.

Travel settings

Warmup: 3 seconds; cooldown: 10 seconds; combat lock: 10 seconds. Damage cancels warmups. Attacking or being attacked starts the combat lock. Moving more than 0.3 blocks, changing worlds, dying, disconnecting, losing access, or entering a vehicle also cancels pending travel. Target chunks load asynchronously before safe landing checks. The normal Paper teleport event remains available to protection plugins. Cooldowns last for the current server session, including reconnects, and reset on server restart or plugin config reload.

Configure private pin/unlock/arrival sequences under effects; see event effects for titles, sounds, particles, animated items and per-map/per-pin overrides. Set effects.enabled: false to disable them. Admins can preview a named sequence with /dimensions effect <name> [player] after closing the target's atlas.

All numeric limits are bounded in code. The retained blocks-per-pixel value must be 1..256. Invalid map references, gateways, IDs, colors and nonfinite/out-of-world coordinates reject the candidate config before replacing the running atlas. Back up config.yml, unlocks.yml and camera-sessions.yml. Unlock and camera recovery files use atomic replacement where supported and refuse to silently overwrite malformed YAML.

Camera recovery

Opening temporarily moves the player to a stationary input seat near the private display. Both modes interpolate a separate camera lens while panning; native HUD displays follow that lens with matching interpolation. Replacing a terrain region snaps the lens and interface together in the same packet bundle as the texture update. The saved return location and flight state are persisted first. Native transitions use private display shutters, configured by ui.native.transitions.enabled/ticks; default motion lasts six ticks, and closing restores after two additional ticks. Optional screen mode uses a five-tick entrance/four-tick exit shader fade and restores after five ticks. Disconnect, disable and reconnect recovery can restore immediately. If another plugin blocks return, resolve that restriction and use /dim close; the pending record stays in camera-sessions.yml.

Game mode and server inventory contents are preserved. Closing restores camera, inventory and appearance independently, with guarded appearance refreshes two and six ticks later to repair stale client packets. Actual invisibility effects and other plugins' visibility listeners remain respected. Other plugins can observe the temporary location/flight allowance, so test region, anti-cheat, flight and teleport integrations. See rendering and integration.

Resource-pack host

The built-in HTTP endpoint serves only /dimensions.zip and supports GET/HEAD. Its hash is computed from the actual ZIP and sent with the pack offer. Restart to change its host/port. An external URL must serve the same ZIP for that hash to match. The standalone atlas waits for SUCCESSFULLY_LOADED for the current pack; accepting or downloading alone does not open it. If you distribute a merged pack through ItemsAdder, include the current Dimensions base pack, set Dimensions resource-pack.enabled: false, and let ItemsAdder send that pack instead.

Customizing Dimensions

Interface, artwork and typography

plugins/Dimensions/config.yml under ui.layout controls panel placement, order, sizes and visibility. ui.yml supplies art paths, colors, labels and legacy defaults; ui/ holds the PNG artwork. Run /dimensions reload after editing. Invalid layout/YAML/color settings are rejected before the running atlas is closed.

The loader is generic: its title, subtitle and status text are in labels.loading-*; it does not display an invented region name. Map names come from each map file. Use map files to configure real names and pins.

Keep labels short enough for their panels. Text uses the bitmap sheet's character codes 0–255; arbitrary chat-font glyphs and MiniMessage colors are not embedded in map images. Use badge PNGs for rank artwork. The supplied badges/admin.png is available; the prepared default rule assigns it to dimensions.admin. Custom paths remain inside ui/, PNGs are bounded to 1024×1024 and 2 MiB, and assets are cached until reload.

Map pin/mob icons fit a 16×16 logical box without distorting their proportions. Badge images retain their proportions and fit up to 80×16 logical pixels; use native small artwork such as the supplied 48×12 badge for best results. The old large me wordmark is replaced by a compact badge and player name. Replace control PNGs in ui/icons/letters/ to change the A/D/W/S/Q/F artwork; A/D now have separate padded keycaps. Existing quest/event lines remain in config.yml under ui.quests and ui.events and accept placeholders.

Native mode is the default. First-use display setup saves actual viewport width/height, FOV and GUI scale for both atlas fitting and minimap placement; /dim setup reopens it after changes. ui.native.fit: contain preserves the entire interface with possible margins, while cover can crop controls. Optional screen mode scales the HUD uniformly to fit and terrain uniformly to cover the window, with Iris shader packs disabled. Both preserve artwork proportions. At fractional scale, physical pixel widths can differ by one pixel; arbitrary window dimensions do not guarantee an exact integer pixel grid.

Display setup dialog

Edit calibration.title, calibration.instructions, calibration.save-label and calibration.cancel-label in config.yml, then /dim reload. These are plain text. The title supports 64 characters, instructions up to four lines of 300 characters each, and button labels 24 characters. Required inputs and validation stay fixed. Existing players complete the form once even if they used legacy calibration commands; Cancel/Escape leaves the camera untouched and does not mark initial setup complete.

Save/cancel buttons use the dimensions:calibration font and the supplied panels/bg.png artwork. The artwork covers the full 20-pixel-high vanilla button, including its hover outline. Clicks and keyboard controls still work; the artwork itself has no hover animation. Other Minecraft screens keep their own buttons. To change these backgrounds, replace src/main/resources/ui-assets/panels/bg.png, rebuild the pack and send it to players. Changing the server's ui/panels/bg.png changes map panels only. Label edits need /dim reload. Without the pack, or for labels the scoped font cannot fit, plain readable labels are used.

Layout in config.yml

Merge desired overrides into the existing ui section; do not create a second top-level ui key. Positions and sizes are logical pixels in a 1024×640 canvas. The default right panel has one outer border with internal dividers. Quests and events share that panel, leaving the left side clear for terrain and branding.

ui:
  layout:
    preset: right-panel
    right-panel:
      enabled: true
      x: 790
      y: 86
      width: 220
      height: 512
      padding: 10
      section-gap: 8
      sections: [region, destination, quests, events]
    sections:
      region: {enabled: true, title: REGION INFO, height: 72, max-lines: 2}
      destination: {enabled: true, title: DESTINATION, height: 176, max-lines: 4}
      quests: {enabled: true, title: QUESTS, height: 118, max-items: 3, max-lines: 6}
      events: {enabled: true, title: EVENTS, height: 102, max-items: 3, max-lines: 5}
      hover: {enabled: true, height: 110, max-lines: 6}
    header: {enabled: true, x: 384, y: 14, width: 256, height: 46}
    logo: {enabled: true, x: 14, y: 14, width: 150, height: 74}
    footer: {enabled: true, x: -1, y: 604, width: 0, height: 24}
    compass: {enabled: true, x: 14, y: 596, width: 120, height: 32}
    focus: {enabled: true, x: 512, y: 320, player-head: true}
    notice: {enabled: true, x: 512, y: 574}

Reorder right-panel.sections to move content, remove an entry or set its enabled: false to hide it. Supported entries are region, destination, quests, events and optional hover. By default focused-pin details appear inside destination; adding hover gives them a separate section. Keep section heights plus gaps within the panel height minus padding; overflow is clipped. Text and icons retain their proportions, and the logo fits its box without stretching. Footer x: -1 centers it and width: 0 fits its labels. The focus is bounded to X=384–640 and Y=192–448 so cached terrain retains safe coverage.

The compass is a compact horizontal bearing ruler with one prominent cardinal heading and a small pointer. It follows the latest world-space pan direction, initialized from the player's heading. Its default 120×32 panel sits at (14, 596); width is bounded to 64–240 and height to 24–160. Narrow panels keep compact, clipped content. Optional ui.layout.labels overrides matching ui.yml labels such as look, zoom, pin, travel, select and close. For the older separate side cards, set preset: split and use ui.layout.left-x/left-y/right-x/right-y. Reload to apply changes; no client pack rebuild is needed for server-composed map artwork.

Hover information

Set a pin's hover.enabled, hover.title and hover.lines in its map file. Holding the focus over the pin shows its details in the right panel's destination section, or the separate hover section when included in its order. The legacy split preset places the hover card on the left and temporarily replaces quests/events. Use ui.layout.sections.hover.enabled: false to hide hover details; panels.hover remains its legacy default. Hover lines accept built-in player/world/online placeholders and installed PlaceholderAPI expansions; their context is the viewer.

Map icons and badges are rasterized into live map tiles and need no client resource-pack rebuild. 3D item models and textures do require an updated client pack.

Atlas and navigation items

The default atlas is a normal vanilla compass, with its usual size and animated needle. Existing dimensions:atlas models use a compact flat compass silhouette after rebuilding the pack. The supplied green arrow and pin models remain unchanged.

Configure each item independently in plugins/Dimensions/config.yml:

items:
  atlas:
    material: COMPASS
    model-key: ''
    itemsadder-id: ''
  arrow:
    material: PRISMARINE_SHARD
    model-key: dimensions:arrow
    itemsadder-id: dimensions:arrow
  marker:
    material: AMETHYST_SHARD
    model-key: dimensions:marker
    itemsadder-id: dimensions:marker

An empty itemsadder-id skips ItemsAdder for that item. An empty model-key uses the material's vanilla model. A custom model key, such as myserver:travel_book, refers to an item definition in the client resource pack (assets/myserver/items/travel_book.json). That model must be included in the pack players receive.

When an ItemsAdder item is available, Dimensions clones it and preserves its identity, model, textures and other metadata. It only applies the bundled model key to the matching built-in dimensions:arrow, dimensions:marker or dimensions:atlas item. If ItemsAdder or the requested item is unavailable, the configured material and model key provide the fallback. Set itemsadder.enabled: false to disable all ItemsAdder lookups.

Existing itemsadder.arrow / itemsadder.marker identifiers remain supported when their new items.*.itemsadder-id setting is absent. The stock legacy itemsadder.atlas: dimensions:atlas migrates to the vanilla compass; an existing custom atlas identifier is preserved.

Individual pin styles can override their navigation items:

pins:
  example:
    navigation:
      arrow-item: 'ia:myserver:guide_arrow'
      marker-item: 'model:myserver:destination_pin'

Supported overrides are ia:namespace:item for ItemsAdder, model:namespace:key for a modern resource-pack item definition, and material:COMPASS for a vanilla item. A blank override inherits the global item. A model: override uses that kind's configured fallback material. /dimensions reload applies configuration changes; update/reload the resource pack separately when its assets change.

Player names, prefixes and badges

Player visibility still respects /dimensions follow false, world membership, and the viewer's canSee visibility. Names and prefixes support PlaceholderAPI when installed, and %player_name% works without it. Placeholders run for the player being shown. The bitmap UI strips chat formatting; the interface controls its typography and colors.

map-players:
  enabled: true
  max-visible: 64
  name: '%player_name%'
  prefix: ''
  badge: ''
  prefix-rules:
    - permission: dimensions.badge.staff
      prefix: STAFF
      badge: badges/staff.png
    - permission: dimensions.badge.vip
      prefix: VIP
      badge: badges/vip.png

Rules are checked in order; the first matching permission wins. Assign these permissions with your permissions plugin. An omitted prefix or badge inherits its global value. Use a blank permission only for a final rule that should match everyone. Badge paths are relative PNG files under plugins/Dimensions/ui/; absolute paths and parent traversal are rejected. Missing artwork can be omitted or supplied by the server owner.

Optional mob markers

Mob markers are off by default. Turning them on still requires an explicit type allowlist. This system only examines chunks and entity data that are already loaded, so browsing a map never loads terrain or entities for mob markers. Invisible-to-viewer entities, players, armor stands and display entities are excluded. Server vanish integrations should use Bukkit/Paper entity visibility for their hidden mobs.

map-mobs:
  enabled: false
  radius: 64
  max-visible: 24
  max-chunks: 81
  max-entities: 512
  types:
    ZOMBIE:
      name: '%mob_name%'
      icon: icons/mobs/zombie.png
    COW:
      name: Cow
      icon: icons/mobs/cow.png

Type keys are Bukkit entity names; unlisted types are excluded. Each type can also set enabled: false. %mob_name% uses the entity's name and %mob_type% its entity type. Additional PlaceholderAPI expansions use the viewer as their context. Icons are relative PNG files under plugins/Dimensions/ui/.

Results refresh at most once per second per viewer. The scan starts near the map focus and stops at its chunk, entity or marker limit. Radius is capped at 128 blocks, scanned chunks at 289, inspected entities at 2,048, and visible markers at 128. The defaults are intentionally lower. Visibility and entity validity are rechecked when returning cached markers. During a rapid world switch, markers may take up to one second to appear.

Cinematic entrances and event effects

Dimensions can play private visual sequences when a destination is pinned, unlocked, reached on foot, or used for travel. The default arrival uses a short welcome title, emerald arcs and a rising particle sweep. It leaves the player's camera, movement, inventory and invisibility state alone. Effects work with ordinary display entities and particles, including the native/Iris rendering mode.

Set effects.enabled: false to disable the system. Each entry under effects.sequences is a named sequence with enabled and a steps list. Built-in event names are pin, unlock, walk-arrive, travel-depart and travel-arrive. A sequence can contain any combination of title, sound, particles and animated items. All timing values are Minecraft server ticks (20 ticks per second at normal server speed).

effects:
  enabled: true
  max-active-per-player: 2
  max-displays-per-player: 2
  max-particles-per-player-tick: 24
  sequences:
    travel-arrive:
      enabled: true
      steps:
        - type: title
          title: '<#B7F078><destination>'
          subtitle: '<gray>Welcome to <map>'
          duration: 42
          fade-in: 5
          fade-out: 12
        - type: sound
          sound: minecraft:block.amethyst_block.chime
          volume: 0.5
          pitch: 1.2
        - type: particles
          at: 4
          duration: 28
          interval: 4
          pattern: sweep
          particle: DUST
          color: '#8FE553'
          count: 8
          radius: 1.4
          rise: 0.3
          y: 0.15
        - type: item
          at: 4
          duration: 36
          item: model:dimensions:marker
          anchor: player
          y: 1.8
          scale: 0.5
          from-scale: 0.05
          spin: 240
          bob: 0.15
          fade-out: 8

at delays a step. duration sets its lifetime; interval controls particle updates. Steps run on a shared two-tick scheduler, so use even tick values for precise timing. Titles support MiniMessage and the safe text placeholders <destination>, <map> and <player>. Sound names may refer to vanilla or resource-pack sound events; volume and pitch are configurable.

Particle patterns are circle, helix, sweep and burst. radius, rise, count, and size shape them. color and size apply to DUST; other supported particle choices must not require extra block/item data, for example END_ROD. Particle packets go only to the effect's owner.

Positions use anchor: origin (where the sequence started), player (follows the player), or target (the waypoint, projected to within 24 blocks when distant). Optional x, y and z offsets use world axes. An unloaded anchor is skipped; effects never load terrain. Item models remain private to the owner and have no collision or gravity.

Animated custom models and image frames

Item steps accept the same identifiers as navigation: ia:namespace:item, model:namespace:key or material:MATERIAL. The resource pack must contain any custom model. from-scale grows toward scale, spin is total rotation in degrees over the step, bob is vertical motion in blocks, and fade-out shrinks the item during its final ticks. The entity interpolates those changes between server updates.

For an animation with different model frames, provide frames instead of item:

- type: item
  duration: 40
  frame-interval: 4
  frames:
    - model:myserver:portal_0
    - model:myserver:portal_1
    - model:myserver:portal_2
  scale: 0.7
  spin: 0

A GIF file cannot be sent directly to an ItemDisplay. Export its frames into a Minecraft resource-pack animated PNG texture (.png plus .png.mcmeta), referenced by your item model, or create the item-model frame list above. Transparent animated textures on a flat model can provide the same pixel-art animation. The model or ItemsAdder identifier selects that asset; the supplied green arrow and pin remain available without conversion.

Per-map and per-pin choices

Add any named sequence, then select it for an event. Pin overrides take precedence over map overrides. none disables the event at that location.

effects:
  maps:
    desert:
      travel-arrive: desert-arrival
  pins:
    hidden_shrine:
      unlock: shrine-unlocked
      pin: none

Use /dimensions reload after editing configuration. Particle/title/sound/animation timing changes need no resource-pack rebuild. New model or texture assets must be included in the pack separately.

Admins can preview an enabled sequence with /dimensions effect travel-arrive or /dimensions effect travel-arrive PlayerName; console must supply an online player. Close that player's atlas first. Previewing supplies no waypoint, so destination/map placeholders use the sequence's fallback context. The optional minimap pauses while effects are active so its title channel does not overwrite the sequence.

Work limits and cleanup

Defaults allow two active sequences and two displays per player, with at most 24 particles emitted per player per scheduler update. Hard caps are four sequences, four displays, 64 particles per update, 16 steps per sequence and 16 model frames per step. A step starts within 400 ticks and lasts at most 200 ticks. Particle counts are limited to 32 per step and share the player's overall budget.

Starting the same event again replaces its old sequence. Cancelling travel removes its departure sequence; quitting, death, changing worlds and plugin reload remove remaining effects and their displays. Failed or unsupported steps are skipped with a bounded warning. The system does not force a client freeze, camera orbit or repeated player teleports.