Dimensions: Commands and maps

Commands and integration

/dim, /atlas and /dimensions are aliases. Player commands need dimensions.use, except help and admin commands.

dimensions.use, dimensions.travel, dimensions.follow and dimensions.minimap default to true. dimensions.admin defaults to OP. dimensions.display, dimensions.minimap.toggle and dimensions.bypass-lock default to false, including for operators. Grant these explicitly when needed; the first two also require the matching owner setting above. Destination-specific permission gates still apply to bypass holders. Player names for unlock commands must be online; UUIDs work offline and avoid guessing names/identities.

Bare dimensions from console shows help. Use dimensions open PlayerName to request an online player's atlas; that player still needs dimensions.use and the normal pack/state checks apply. Follow visibility persists in player-settings.yml, respects vanish/visibility checks and affects player-head markers only. Each player's pin and walking guidance stay private.

First atlas or minimap use prompts for game viewport width/height, FOV and numeric GUI scale. Save validates all four values and persists the atlas fit, minimap placement and setup completion together in player-settings.yml, then resumes the requested action. Existing users with legacy calibration values are prompted once; their preferences remain intact. Cancel or Escape leaves first-use setup incomplete and does not enter the map camera. Use /dim setup after resizing or changing FOV/GUI scale; bare /dim calibrate and /dim minimap calibrate also open the form.

The owner sets display.mode: native or screen in config.yml. Native is the default and uses ordinary map frames for Iris compatibility. /dim display is available only with the owner setting and permission listed above; saved choices are ignored while locked. The legacy /dimensions calibrate 70 16:9 command changes FOV/aspect only; a decimal aspect such as 1.777778 is also accepted. It does not replace first-use setup. contain fitting keeps the complete canvas visible with possible margins; cover can crop controls. Calibration does not force client settings.

Optional display screen fits the HUD uniformly inside the window and scales terrain uniformly to cover it using the shader in the base pack. Screen mode does not work with an active Iris shader pack. Iris installed with shader packs off is fine. Allowed display choices persist in player-settings.yml. An atlas requested during a standalone-pack download opens after the client confirms that the current pack loaded successfully.

minimap.enabled: false disables the minimap for everyone, even with a saved on setting. Set it true to enable the feature. minimap.default-enabled supplies the state when the player cannot choose or has no saved choice. /dim minimap on|off needs both minimap.allow-player-toggle: true and dimensions.minimap.toggle; it cannot bypass the master switch. Players also need dimensions.use and dimensions.minimap. An allowed /dim minimap on requests setup if needed. F3's Display size supplies viewport pixels; use Options for FOV and Video Settings for the explicit numeric GUI scale, not monitor dimensions or Auto. Supported resulting GUI dimensions are 320–4096 pixels wide and 180–1000 high; scales that Minecraft would reduce for the entered viewport are rejected. The legacy /dimensions minimap calibrate 1920 1080 3 updates minimap placement only and does not complete first-use setup. This top-down preview uses custom resource-pack fonts in the title channel and pauses for setup, the atlas, effects and other titles.

/dim reload applies these owner settings and closes active atlas views. Permissions cannot bypass owner locks. Old configs use ui.screen-space only while display.mode is absent; set the new key when updating. Help and tab completion show only the override commands available to that player.

Fresh installations create empty maps from currently loaded worlds, using their actual names and spawn positions. /dimensions map create adds a map later; /dimensions add requires a player standing at the destination. Migration keeps IDs and unlocks and reports its backup location. See map files and custom pins for syntax, and UI/items/players/mobs customization for appearance settings.

The mouse menu has 45 destinations per page, world arrows at the corners and page buttons around the close button. Left click guides; right click travels. Inventory movement and drags are blocked only for this plugin's own menus.

Quest commands

Run the following from your quest plugin's console action (replace placeholders using your quest system):

dimensions unlock PlayerName astral
dimensions lock PlayerName ember

No command configured in the atlas executes as console on a player's behalf. There are no arbitrary command templates in the config.

Java integration

Declare softdepend: [Dimensions] or depend: [Dimensions] in your plugin, and add the built Dimensions JAR as a compile-only dependency. Use the public methods on Paper's main thread:

DimensionsPlugin dimensions = (DimensionsPlugin) Bukkit.getPluginManager().getPlugin("Dimensions");
dimensions.setUnlocked(player.getUniqueId(), "astral", true); // can throw IOException
dimensions.openAtlas(player);
boolean started = dimensions.guideTo(player, "astral");

data() exposes the configured map/waypoint records for read access. guideTo preserves permission and loaded-world checks while allowing unexplored destinations. Fast travel additionally enforces unlocks. Changing an online player's effective unlock from false to true plays the configured unlock effect; offline changes only save the unlock. The plugin uses no economy dependency; unlocking can be awarded by your existing quests, ranks or economy system through these commands/API methods. See event effects for sequence configuration and previewing.

Map files and custom pins

Each map can live in its own plugins/Dimensions/maps/<id>.yml file. On a fresh installation, Dimensions creates one map for each currently loaded world, using that world's actual name and spawn position. The files start with no pins. It does not create worlds, invent region names or add fictional destinations.

The first initialization is recorded in maps/.initialized. Worlds loaded later can be added explicitly. Existing PNG previews in maps/ are not map definitions; only direct .yml files are read. Map files are ordered by filename after any legacy maps.

Quick setup

1. Load the desired world with your server's normal world-management system.
2. Run /dimensions map create town world as an administrator or from console. In game, omitting the world uses your physical world: /dimensions map create town.
3. Stand at a safe destination and run /dimensions add market town Market Square. This saves the pin into maps/town.yml.
4. Edit the map file for its name, appearance, lock and navigation settings. Run /dimensions reload to validate and apply it.

/dimensions help lists these commands. They require dimensions.admin (default OP). A newly added pin is discoverable and initially locked; set unlocked: true for a public destination. Pinning an unexplored destination permits walking guidance but does not unlock fast travel.

File format

Save the following as plugins/Dimensions/maps/town.yml, replacing the world and coordinates with your own:

id: town
world: world
name: Town
subtitle: ''
color: '#95D655'
center-x: 0
center-z: 0
gateway: ''

## Optional overrides. Omitted values use the global renderer settings.
renderer:
  style: clear
  yaw: 25
  elevation: 60
  blocks-across: 112
  texture-softening: 1
  shadow-strength: 0.20
  brightness: 1.08
  small-plants: false
  # Optional underground cutaway, lower inclusive / upper exclusive:
  # render-min-y: -64
  # render-max-y: 128

pins:
  market:
    name: Market Square
    description: Shops and trading
    x: 120.5
    y: 71
    z: -80.5
    yaw: 90
    pitch: 0
    unlocked: false
    discoverable: true
    travel: true
    permission: ''
    icon: icons/poi/building.png
    hover:
      enabled: true
      title: Market Square
      lines:
        - Shops and trading
        - Walk here to discover this destination
    navigation:
      arrow-item: ''
      marker-item: ''

The filename must match id. Map IDs and pin IDs accept 1–48 lowercase letters, digits, _ and -. Pin IDs are global across every map because they are the keys used by saved unlocks. Keep an existing ID when changing a destination's display name or location. Duplicate map/pin IDs, malformed YAML and invalid references reject the candidate before it replaces the active atlas.

Pins inherit the world from their containing map file; do not add a different map value under a pin. gateway, when used, must name a pin in the same map. It provides a configured cross-world bearing target, not an automatically created portal.

The clear renderer style reduces small ground-texture noise and uses softer relief. texture-softening is an integer number of extra prefiltered texture levels (0–2); shadow-strength is bounded to 0–0.6, and brightness to 0.5–1.5. detailed selects the original fixed preset with stronger texture detail and small plants, ignoring the clear style's tuning values. Per-map renderer.* values override the global values; legacy top-level render-min-y and render-max-y remain accepted. Use the rendering guide for geometry, palette and shader limits.

Pin appearance

icon is a PNG path relative to plugins/Dimensions/ui/. The supplied icons/navigation/pin.png, icons/poi/building.png, icons/poi/quest.png, icons/poi/flag.png, icons/poi/event_scroll.png and icons/poi/book.png are available. Place your own PNG at a safe relative path such as ui/icons/custom/station.png, then set icon: icons/custom/station.png. Absolute paths and parent-directory traversal are rejected. Small pixel artwork should be supplied at its intended native proportions.

hover.enabled controls the pin's information panel. When omitted, the title defaults to the pin name and the text defaults to its description. hover.lines accepts up to 12 lines of 256 characters, although short lines fit the panel best.

Empty navigation overrides use the global arrow/marker items. To change only this destination, set navigation.arrow-item or navigation.marker-item to one of these forms:

See item customization for global item settings. These fields choose appearance; they do not execute commands or change who can see a personal pin.

Migrate an existing config

Legacy config.yml sections worlds and waypoints still work. They may coexist with map files when IDs do not overlap. To move them into per-map files, run:

dimensions maps migrate

The command validates the complete result, creates a timestamped backup under plugins/Dimensions/backups/, writes each map through a temporary file and atomic replacement where supported, then clears only the migrated worlds/waypoints sections from config.yml. Existing IDs, names, coordinates, styles, renderer overrides and unrelated global settings are retained. unlocks.yml is untouched. Legacy pins pointing at an already managed map are moved into that map's file, with its previous file included in the backup. A second migration with nothing left is harmless.

Ordinary write failures trigger restoration from the saved original contents. A filesystem cannot atomically replace several unrelated files at once: after a machine interruption during migration, stop the server and use the reported backup to restore config.yml and any backed-up map files, removing only the newly created map files from that migration before retrying. Keep the backup until the migrated server has been checked. YAML is reserialized during migration, so comments may not be retained; the backup preserves the original file bytes.

Fresh installations do not need migration. Back up the map files together with config.yml, unlocks.yml, player-settings.yml and camera-sessions.yml.