Map Art Optimizer 0.1.0

Displays explored surface terrain from Xaero's World Map on maps placed in vanilla item frames. Client-side only; no server installation required.

Supported Versions

• Minecraft Java Edition 26.1.2

• Fabric Loader 0.19.3 or later

• Fabric API 0.155.3+26.1.2

• Xaero's World Map 1.41.3 (required; this exact version is mandatory)

• Java 25

Xaero's World Map must be installed separately. This project does not include any Minecraft or Xaero program files.

Installation and Usage

1. Place map-art-optimizer-0.1.0.jar in the mods folder of your game instance and restart the game.

2. Join a server, press M to open Xaero's World Map, and make sure the correct world, dimension, and map instance are selected.

3. Look at a map placed in an item frame and enter one of the following binding commands:

/xmapframe bind <map center X> <map center Z>
/xmapframe corner <northwest corner X> <northwest corner Z>

The zoom level is read from the vanilla map itself. For example, a map covering 512×512 blocks with a center at (192,192) has a northwest corner at (-64,-64). You can bind it using:

/xmapframe bind 192 192

Alternatively, hold the map in your hand, stand inside the area actually depicted by that map, and enter:

/xmapframe here

The here command infers the map boundaries from the vanilla map grid at the player's current position. If the player is outside the area depicted by the map, the binding will be incorrect. In that case, use bind or corner to overwrite it. When binding by center coordinates, enter the map's center coordinates, not the item frame's position.

1. Look at the item frame and wait for high-resolution tiles to load progressively. Reading a large historical map for the first time may take longer. Areas without available Xaero terrain data retain the vanilla map rendering.

2. Enter /xmapframe status to view the high-resolution coverage percentage and diagnostic information for the currently targeted map.

Additional Commands

/xmapframe help       Display help
/xmapframe unbind     Unbind the currently targeted or held map
/xmapframe refresh    Reload high-resolution tiles
/xmapframe off        Temporarily disable the overlay
/xmapframe on         Re-enable the overlay

All item frames displaying maps with the same map ID in the current world share the same binding. Multiple maps with different IDs can be bound to adjacent areas to create a connected map wall.

Bindings are stored only in config/xaero-map-frames.json within the current game instance. They are isolated by Xaero world, dimension, and multiworld map instance. After renaming the mod, keep this configuration filename unchanged to preserve existing bindings. The command prefix remains /xmapframe.

Current Behavior and Limitations

• One block per pixel: High-resolution terrain uses one pixel per block. Level 0 maps cover 128×128 blocks, Level 1 covers 256×256, Level 2 covers 512×512, Level 3 covers 1024×1024, and Level 4 covers 2048×2048. Level 0 maps primarily benefit from improved colors. They already have one pixel per block, so additional internal block texture details cannot be created.

• Item frame rendering only: Only the map background inside item frames is replaced. Vanilla rotation, glowing effects, icons, markers, and label text are preserved. Maps held in the player's hand continue to display their original vanilla content.

• No Xaero waypoint or label integration: Xaero waypoints, place names, and fonts are not imported. Vanilla marker labels have not been redesigned.

• Current Xaero surface map only: When switching to another dimension or map instance, you must configure bindings for that instance separately.

• Local exploration data required: High-resolution coverage depends on Xaero exploration data stored on the local machine. Areas explored by other players but not synchronized to your local data will not automatically become high-resolution. The server does not receive the high-resolution pixels.

• Daytime surface colors: The mod uses daytime surface colors. Xaero's nighttime brightness, screen filters, interface overlays, and custom shader effects are not fully reproduced.

• Updates follow local Xaero data: High-resolution coverage changes as local Xaero data changes, including for maps that have already been locked in vanilla. This version does not preserve historical snapshots of locked maps.

• Bounded resource usage: The mod uses a bounded CPU tile cache and a high-resolution texture budget. Large map walls may temporarily fall back to vanilla rendering and reload progressively. This version has not been optimized for displaying hundreds of large maps simultaneously.

• First prototype release: Compilation, structural checks, and logic checks have been completed. See the delivery notes for details. This does not imply that visual rendering has been tested in a graphical client or on your server.

Building from Source

The standard build requires Gradle 9.6.0, JDK 25, and Fabric Loom. Obtain the Xaero 1.41.3 JAR separately and place it at:

libs/xaeroworldmap-fabric-26.1.2-1.41.3.jar

Alternatively, specify its location using -PxaeroJar=<absolute path>.

This workspace also includes build-local.ps1, which can reuse existing Minecraft/Fabric development caches for the same versions to perform an offline build. Minecraft 26.1.2 is no longer obfuscated, and all injections use official class names. The offline build path therefore does not require remapping.

.\build-local.ps1 `
  -DependencyCache 'E:\Gradle\.gradle' `
  -JavaHome 'E:\graalvm-jdk-25_windows-x64_bin\graalvm-jdk-25.0.4+7.1' `
  -XaeroJar '<path to your Xaero World Map 1.41.3 JAR>'

The build artifacts are generated in build/libs. The build script only reads existing dependency caches. Temporary build files are written to the project's own .local-build and build directories.

After an offline build, run verify-local.ps1 -JavaHome <JDK25 directory> -XaeroJar <Xaero 1.41.3 JAR> to test binding persistence, failure protection, and the actual Xaero pixel and historical cache formats. This verification does not launch the game.

In this computer's restricted execution environment, the JDK may occasionally report AccessDeniedException while closing ZipFS after compilation has completed. The build is performed using an external javac process, and the final JAR is additionally validated through structural inspection and actual class loading.