Dimensions: Installation and compatibility

Dimensions 1.0.0

A terrain atlas for Minecraft servers, with custom pins, player heads, discoveries, fast travel and animated route markers. Maps and pins have separate config files. Players do not need a client mod or a MineSkin key.

Requirements

Other Minecraft versions, Spigot and Folia are not supported by this release. Do not list untested versions as compatible. ItemsAdder also needs its own dependencies.

Install

1. Put Dimensions-1.0.0.jar and PacketEvents in plugins/. Remove any older Dimensions JAR so only one copy loads.
2. Start the server. Dimensions creates config.yml, ui.yml and a file in maps/ for each loaded world. New installs use real world names and have no demo pins.
3. Set resource-pack.url to a URL your players can reach. 127.0.0.1 works only on the server computer. Use the built-in host or serve dimensions-pack.zip over HTTPS. Restart after changing the host or port.
4. If ItemsAdder already serves your pack, use the merge instructions instead of sending two competing packs.
5. Choose the display mode and minimap rules below. Edit the map files and run /dim reload.
6. Accept the pack and run /dim. First use asks for the game's viewport width, height, FOV and GUI scale. /dim setup repeats this after a window or settings change.

To add a pin, stand at its location and run /dim add market <map-id> Market Square. Edit its appearance, description, unlock and travel settings in maps/<map-id>.yml. See map setup.

Display mode and minimap

display:
  mode: native
  allow-player-override: false
minimap:
  enabled: false
  default-enabled: true
  allow-player-toggle: false

• Native: places real map tiles in front of a private camera. Use this with Iris shader packs. Players must calibrate their view. Shader lighting can change its appearance.
• Screen: fits the atlas using the resource pack's core shader. It does not work with an active Iris shader pack. Iris installed with shaders switched off is fine. See Iris compatibility.
• Minimap: a separate top-down GUI overlay. It works with either atlas mode and uses no custom shader. It pauses during the atlas, setup and other plugins' titles.

minimap.enabled: false disables it for everyone. When enabled, default-enabled sets its state. Players can change it only when allow-player-toggle: true and they have dimensions.minimap.toggle. They still need dimensions.use and dimensions.minimap to see it.

The server's display.mode applies to everyone unless allow-player-override: true and the player has dimensions.display. Both override permissions default to false, including for OPs. Turning overrides off ignores saved choices; it does not erase them. /dim reload applies the policy.

For calibration, copy F3 → Display while using the window you play in. A 1920×1080 monitor does not mean a windowed game has a 1920×1080 viewport. Use the numeric GUI scale from Video Settings, not Auto. The server cannot read these settings for you. A wrong height can cut off the minimap's top border.

Controls

Controls follow the player's key bindings. The atlas uses movement/look controls, not a free mouse cursor. Personal pins and routes are private. Fast travel checks unlocks, permissions and a safe landing place.

Files and customization

• config.yml: display policy, layout, rendering, minimap, navigation and effects.
• maps/<id>.yml: each map's name, world, view settings and pins.
• ui.yml and ui/: labels, colors, PNG icons, panels and badges.
• player-settings.yml: player choices and calibration.
• unlocks.yml: saved discoveries. Keep waypoint IDs stable.
• camera-sessions.yml: interrupted camera returns. Do not delete it to resolve a stuck return; use /dim close and check teleport restrictions.

Back up these files before upgrading. Use /dim reload, not a third-party plugin hot-loader. Host/port changes need a restart; packaged artwork changes need a rebuilt client pack.

Documentation

• Configuration
• Maps, pins and migration
• Artwork, layout, heads and mobs
• Commands and permissions
• Effects and cinematic travel
• ItemsAdder
• Rendering and Iris
• Test results and remaining limits

Native mode preserves proportions but cannot promise fullscreen fitting for every FOV and window. contain shows the whole interface with possible margins; cover crops edges. Terrain uses Minecraft's map colors. The minimap shows sampled surface colors, not the atlas's textured 3D view. Neither feature is free of client rendering cost. Check FPS with the shader pack and player count you plan to support.

Iris, screen sizing and PacketEvents

Use display.mode: native when players use Iris shader packs. It needs no custom Iris pack or MineSkin key. Shader lighting and post-processing can still change its appearance. display.mode: screen does not work with an active Iris shader pack; having Iris installed with shader packs off is fine.

The owner chooses display.mode in config.yml. /dim display native|screen requires display.allow-player-override: true and dimensions.display. The permission defaults false, including for operators. Saved player modes are ignored while overrides are locked. Run /dim reload to apply owner changes. Old ui.screen-space is read only when display.mode is absent.

The separate GUI minimap works with Iris packs and either atlas mode. minimap.enabled: false disables it for everyone. When enabled, minimap.default-enabled sets the state for players who cannot choose or have no saved choice. /dim minimap on|off requires minimap.allow-player-toggle: true and dimensions.minimap.toggle (default false, including operators). Players also need dimensions.use and dimensions.minimap to see it. No permission bypasses the owner switches.

Iris explains that arbitrary resource-pack core shaders cannot generally be merged with shader-pack programs, and recommends a fallback without custom shaders. Switching an override from a text shader to an entity shader does not establish compatibility with every Iris pack. Ordinary textures and bitmap fonts do not require such an override. See Iris's compatibility guidance.

What the server can read

Checked against the local Minecraft Java 26.2 client and PacketEvents 2.14.0 on 22 October 2026:

• Client Information reports language, chunk view distance, chat settings, skin parts, main hand, text filtering, server listing preference and particle status. It has no resolution, FOV or GUI-scale field. View distance means chunks, not screen dimensions. See the PacketEvents wrapper source.
• Paper's getClientOption/PlayerClientOptionsChangeEvent expose those transmitted preferences; they do not add local window measurements. The exact-version Paper 26.2 ClientOption definitions confirm that distinction. This establishes the absence of a direct standard packet/API, rather than proving that every possible indirect calibration experiment is impossible.
• The vanilla minecraft:brand payload contains a brand string. It is not a screen-settings query. A custom channel only adds information if client code implements the response.
• Window resizing and GUI scaling update local rendering and screen layout without a corresponding vanilla resize packet. Dialog responses contain configured values and user inputs, not automatic viewport measurements.
• Tick-end and chunk-batch feedback also contain no viewport dimensions. The latter reports a processing-rate estimate.

Local development checks inspected the 26.2 client packet codecs and resize handling, including ClientInformation.write, Options.buildPlayerInformation, Minecraft.framebufferSizeChanged, Minecraft.resizeGui and BrandPayload.write. Those inspection files are development evidence and are not included in the release bundle.

Automatic fitting and freezing

Automatic drawing does not require sending the screen size to the server. In the inspected 26.2 client, assets/minecraft/shaders/include/globals.glsl exposes ScreenSize, and projection.glsl exposes ProjMat. A compatible overlay shader can use these locally to position graphics. Server-side interaction coordinates still need to agree with that layout.

Tick freeze changes simulation state; it does not query the screen or read GPU data. The actual 26.2 ticking-state handler sets tick rate and the frozen flag only. Mojang's tick documentation also distinguishes freezing gameplay from stopping player movement.

Deliberately making a shader slow could theoretically create a timing signal. That is an experimental side channel, not a supported exact sizing API: it introduces delay and is affected by hardware, scheduling and network timing. No reliable zero-delay calibration mechanism was verified. GPU readback normally requires host-side API calls and synchronization; see Khronos's synchronization documentation. Dimensions prepares terrain before showing it and does not stall the client to measure its screen.

ItemsAdder

Test stack: Paper 26.2 build 134, Java 25, PacketEvents 2.14.0, ItemsAdder 4.0.18 and the current ProtocolLib 5.5.0 development build. Your ItemsAdder JAR is commercial and is copied only into the ignored local test server. Distributable ZIPs contain our content, not ItemsAdder.

Import

1. Install ItemsAdder and its required ProtocolLib build. PacketEvents remains a separate Dimensions dependency.
2. Extract dimensions-itemsadder.zip into plugins/ItemsAdder/, so the path is plugins/ItemsAdder/contents/dimensions/configs/items.yml.
3. Run /iareload, then /iazip. Check console for missing models/textures.
4. Registered IDs are dimensions:atlas, dimensions:arrow, dimensions:marker.

The content uses ItemsAdder's documented full folder structure: resourcepack/assets/dimensions/. Modern items/*.json definitions and the bitmap font are included as well as model/textures. Do not mix a second folder structure into this namespace.

Choose a distribution mode

Prepared test server: Dimensions hosts the small original pack at http://127.0.0.1:8127/dimensions.zip. ItemsAdder auto-application is disabled in this disposable server to avoid sending two conflicting packs. ItemsAdder still registers and supplies the three items. Dimensions preserves their IA identity and applies its stable modern model key.

Production merged pack: set Dimensions resource-pack.enabled: false; leave itemsadder.enabled: true; use ItemsAdder hosting for the generated merged pack. Check that the generated ZIP includes assets/dimensions/font/pixels.json, assets/dimensions/font/minimap.json, their referenced textures, and the three model definitions. The optional minimap needs its custom font even when the atlas uses native map frames. Run /iazip after changes and let your players accept the new pack. This is the recommended mode when your server already has an ItemsAdder pack.

Without ItemsAdder: keep itemsadder.enabled: false (or omit the plugin). Dimensions uses standard Bukkit ItemStacks with modern item_model keys. The same base resource pack supplies their geometry.

Items are looked up when needed through the public CustomStack.getInstance/getItemStack API. No stale IA item instances are cached across /iareload. If content is not available yet, the plugin falls back to its own model-backed ItemStacks. /dim give adds the plugin's atlas interaction tag; /iaget dimensions:atlas alone supplies the cosmetic item but does not add that tag.

See the official first-install guide and content folder structure.

Resource-pack distribution and merging

Dimensions 1.0.0 supports Paper and Minecraft Java 26.2 only, Java 25 and PacketEvents 2.14.0. A pack manager does not extend that version support. Install a version of your chosen manager that supports the same server and client.

Choose one system to build and send your complete server pack. The standalone Dimensions pack is included as dimensions-pack.zip; the JAR contains the same pack. Preserve the dimensions item-model and font identifiers when merging. Do not obfuscate or rename those identifiers without updating every reference. Keep a readable, unprotected source ZIP if the terrain renderer needs your custom blocks.

Standalone pack

No content plugin is required. Dimensions creates plugins/Dimensions/dimensions-pack.zip from its bundled pack. With resource-pack.enabled: true, configure its host, port and resource-pack.url so players can download the exact ZIP. The default 127.0.0.1 URL works only on the server computer; remote players need a reachable address or HTTPS hosting. Restart after host or port changes. Keep itemsadder.enabled: false when not using ItemsAdder.

An externally hosted URL must serve the same unmodified ZIP because Dimensions supplies its SHA-1. The atlas waits for successful loading of its own pack. Players can retry with /dim pack, or use /dim menu as the inventory fallback without a pack.

ItemsAdder

This release includes an ItemsAdder content import and public CustomStack item lookups. See ITEMSADDER.md for the full instructions. Extract dimensions-itemsadder.zip into plugins/ItemsAdder/, then rebuild the merged pack with your installed ItemsAdder version. The content path should be plugins/ItemsAdder/contents/dimensions/configs/items.yml.

For merged distribution, set Dimensions resource-pack.enabled: false and leave itemsadder.enabled: true. Let ItemsAdder build and send the merged pack. PacketEvents is still required independently; ItemsAdder also needs its own dependencies. The checked stack used ItemsAdder 4.0.18 and the ProtocolLib 5.5.0 development build.

Nexo

Nexo's documented external-pack importer accepts a ZIP or unpacked folder in plugins/Nexo/pack/external_packs/. Copy dimensions-pack.zip there, rebuild and send your Nexo pack using the commands and hosting configured for your installed version. In Dimensions, set resource-pack.enabled: false and itemsadder.enabled: false.

Keep the Dimensions namespace and its model/font paths stable. Nexo's obfuscation can rename models and namespaces; do not apply that renaming to assets referenced by Dimensions. Check the final pack's fonts, item definitions, models, textures and core shaders for conflicts.

This is a manual resource-pack merge workflow, not a Nexo item API integration. Dimensions does not resolve Nexo item IDs. To choose other navigation artwork, use a modern model:namespace:item definition from the final pack, or a vanilla material: override.

Official reference: Nexo resource-pack structure, import and obfuscation.

CraftEngine

CraftEngine organizes content in plugins/CraftEngine/resources/<pack>/, with pack.yml, configuration/ and a vanilla-format resourcepack/ folder. On a current compatible CraftEngine build, /ce resource create dimensions creates that structure; choose another unique folder name if it already exists. Merge the contents of dimensions-pack.zip under that pack's resourcepack/ directory, retaining the existing assets/dimensions/ namespace.

Set Dimensions resource-pack.enabled: false and itemsadder.enabled: false. Use /ce reload all with CraftEngine's default build workflow to generate, upload and send the merged pack. Custom workflows must include the corresponding generation, hosting and send steps. A config-only reload does not rebuild texture/model files.

CraftEngine explicitly does not merge conflicting shaders automatically. Check its generated pack before enabling Dimensions screen mode. Native mode is the default and the appropriate choice when another pack owns the same core shaders or players use active Iris packs.

This is a manual asset merge, not a CraftEngine item API integration. Dimensions does not resolve CraftEngine item IDs; configure modern model:namespace:item definitions or vanilla material: overrides instead. This workflow has not been tested live with a CraftEngine server.

Official references: CraftEngine project structure and reload workflow, file conflicts and shader limitation.

Custom terrain textures

Pack distribution and server-side terrain rendering are separate. To render readable custom block models/textures from a Nexo, CraftEngine or other pack, list its unprotected ZIP in renderer.resource-packs in the Dimensions config. Relative paths start at plugins/Dimensions/; later packs take priority. ItemsAdder's standard generated ZIP can be imported automatically when renderer.use-itemsadder-pack: true.

Run /dim reload after the generated assets change. Unsupported client-mod renderers, block-entity visuals, animated terrain textures and exact biome tinting are not reproduced by this renderer. A successful merge does not establish compatibility with every custom block or shader pack.

Iris and preflight checks

Use display.mode: native with active Iris shader packs and complete /dim setup for the actual game viewport, FOV and numeric GUI scale. Shader lighting can change the result. Screen mode uses a core-shader override and does not support active Iris shader packs; Iris installed with shader packs switched off is fine. The optional minimap uses custom fonts instead of that screen-fitting shader.

Before opening the server to players, accept the generated pack and check /dim, /dim give, pinning, travel and the minimap if enabled. Confirm the final ZIP retains assets/dimensions/font/pixels.json, minimap.json, calibration.json, their textures and the navigation item definitions. Recheck after changing pack protection, shaders or hosting. Nexo and CraftEngine directions are documented manual workflows, not claims of live-tested native integrations.