ZoyLuo Map — Fabric Minimap & World Map for Minecraft 1.21.3

简体中文 · Modrinth · GitHub Releases · Issues · MIT License

ZoyLuo Map is an early-alpha, client-side Fabric minimap and full-screen world map for Minecraft Java Edition 1.21.3. It stores explored terrain, waypoints, profiles, and settings on your device, and adds filtered live entity radar, automatic cave views, and per-server Fair Play controls without requiring server installation by design.

0.1.1 Alpha: This is a public preview, not a verified stable release. Automated source and artifact checks pass, but Windows/macOS, multiplayer, Sodium/Iris, dedicated-server behavior, permission-server teleport, the complete bilingual visual matrix, and large-scale performance still require real-world verification.

Quick facts

Item	Requirement or status
Minecraft	Java Edition 1.21.3 only
Loader	Fabric Loader >=0.18.4
Required dependency	Fabric API >=0.114.1+1.21.3 for Minecraft 1.21.3
Java	>=21
Side	Client-only by design; server installation is not required
Optional integration	Mod Menu >=12.0.1 <13.0.0
Languages	English and Simplified Chinese through Minecraft's native language setting
Release channel	Alpha / early preview
License	MIT

Features in 0.1.1 Alpha

Minimap and world map

• Circular or square HUD minimap, six screen positions, cardinal directions, configurable frame size, and independent content zoom.
• Full-screen map with pan, cursor-centered wheel zoom, a right-side zoom rail, and a visible-diameter limit of 10,000 blocks.
• Cached browsing across the Overworld, Nether, and End, with per-dimension viewport and layer state.
• Automatic nearby cave views in the Overworld and height-based Nether slices using only chunk data already received by the client.

Coordinates and waypoints

• Press B to open a list-first Coordinates & Waypoints manager without creating a marker.
• Save the current position or enter finite custom X/Y/Z coordinates in a known dimension.
• Search, filter, sort, favorite, group, recolor, edit, show/hide, batch-organize, and delete saved waypoints.
• Use named color swatches, icons, searchable groups, one-step undo, and a retained latest death point.
• Optional same-dimension teleport submits one vanilla /tp command only when the live command tree permits it; it never bypasses server permissions or force-loads a destination.

Tracked-entity radar

• Shows client-tracked living entities within the configured range.
• Uses the same compact directional triangle for the local player and other players; other players remain blue, while non-player living entities retain compact category-colored markers.
• Supports searchable category and EntityType selection, including registered living types added by other Mods.
• Item drops, arrows, minecarts, boats, offline positions, health, ownership details, and movement history are excluded.

Fair Play

• Fair Play is stored per server and can be enabled when server rules restrict radar, cave views, or teleport assistance.
• It hides other players, living-entity radar, cave/Nether slices, and coordinate teleport while retaining the surface map, local waypoints, and your own position.
• ZoyLuo Map does not infer a world seed, force-load chunks, or render chunks the client has not received.

Local-first data

• Map data is separated by a privacy-preserving server identity, player UUID, profile, and dimension.
• The same account on the same installation can recover its own saved map and waypoints after reconnecting.
• There is no telemetry, analytics, cloud sync, map upload, server-address upload, or player movement history.
• Work queues, caches, scans, and disk use have explicit implementation bounds. Large-scale FPS, GPU, memory, and disk targets have not yet been benchmark-verified.

Gallery

Installation

Requirements

• Minecraft Java Edition 1.21.3
• Fabric Loader 0.18.4 or newer
• Fabric API 0.114.1+1.21.3 or newer for Minecraft 1.21.3
• Java 21 or newer
• Optional: Mod Menu 12.x

Steps

1. Install Fabric Loader for Minecraft 1.21.3.
2. Install the matching Fabric API release.
3. Download the ZoyLuo Map 0.1.1 Alpha JAR from Modrinth or GitHub Releases.
4. Place both JARs in the client's mods folder.
5. Start Minecraft and use M, Left Alt/Option + M, or B.

The server does not need to install ZoyLuo Map by design. Back up .minecraft/config/minecraft_map before upgrading or downgrading an Alpha build; pre-1.0 data compatibility is not yet a stable public contract.

Default controls

All seven actions are globally rebindable in ZoyLuo Map settings. Exact duplicate bindings are rejected; possible conflicts with Minecraft or another Mod are warned without silently replacing the user's choice.

Platform	Default	Action
Windows / macOS	M	Open or close the full-screen map
Windows	Left Alt + M	Open or close map settings
macOS	Left Option + M	Open or close map settings
Windows / macOS	B	Open or close Coordinates & Waypoints
Windows / macOS	Up / Down	Zoom minimap content in / out within 0.25..16
Windows / macOS	Left / Right	Enlarge / shrink the minimap frame within 64..256 pixels

How to use the shortcuts

1. Open the full-screen map: press M during gameplay. Press M again or Esc to close it. On the map, use the mouse wheel to zoom, hold the left mouse button and drag to pan, right-click a location for map actions, and press Home to return to the player.
2. Open map settings: hold Left Alt and press M on Windows, or hold Left Option and press M on macOS. The modifier chord takes priority over plain M, so it opens settings without also opening the full-screen map.
3. Manage coordinates and waypoints: press B to open Coordinates & Waypoints. Press B again or Esc to close it.
4. Adjust the minimap: while playing with no menu open, tap Up or Down to change map zoom, and tap Left or Right to change the minimap frame size. Each fresh press applies one bounded step; release and press again for another step.
5. Change a binding: open Map Settings → Controls, choose Modify, press the new key or chord, then use Apply or Done to save. Default restores only that action's default binding.

Map shortcuts are temporarily disabled while a text field is focused or a new shortcut is being captured. Exact duplicate bindings are rejected; possible conflicts with Minecraft or another Mod are warned without silently replacing the user's binding.

Data, privacy, and server rules

• Player-facing settings and waypoints are stored locally under .minecraft/config/minecraft_map.
• Raw server addresses are not used as filenames; a locally salted cryptographic digest identifies server data.
• Waypoints are not shared with other players or devices and are not automatically synchronized.
• Cave views use chunk data that the Minecraft client has already received. They may reveal underground spaces inside those received chunks even if the player has not personally visited every space.
• Coordinate teleport is disabled across dimensions, under Fair Play, while disconnected, with invalid coordinates, or when the live vanilla command tree does not expose an executable /tp route.
• If a server's rules disallow radar or cave mapping, enable Fair Play before playing there.

FAQ

Is ZoyLuo Map client-side?

Yes. It is designed as a client-only Fabric Mod, and the server does not need to install it. Dedicated-server smoke remains unverified for this Alpha.

Which Minecraft version does it support?

The current Alpha targets Minecraft Java Edition 1.21.3 only, with Fabric Loader and Fabric API.

Is Fabric API required? Is Mod Menu required?

Fabric API is required. Mod Menu is optional and only adds an integration entry.

Does it reveal chunks the client has not received?

No. ZoyLuo Map does not infer the world seed, force-load chunks, or display chunks the client has not received. Cave slices may still reveal underground spaces inside already-received chunk data that the player has not personally visited.

What does the entity radar show?

It shows client-tracked living entities only, subject to the configured range and EntityType filters. Item drops, arrows, minecarts, boats, offline positions, health, names, and movement history are excluded.

Can it teleport without permission?

No. Teleport is limited to the current dimension, requires Fair Play to be off and an executable vanilla /tp route in the live command tree, and submits at most one command attempt.

Does it upload maps or player data?

No. The Mod has no telemetry, analytics, cloud sync, map upload, server-address upload, or player movement history.

Are waypoints shared with other players or devices?

No. Waypoints remain local to the current installation and are not automatically shared or synchronized.

Is it compatible with Sodium, Iris, Windows, macOS, or Linux?

Compatibility has not yet been verified for this Alpha. Windows and macOS are target platforms; Sodium and Iris are desired integrations; Linux is currently unsupported and unverified.

Is 0.1.1 a stable release?

No. Version 0.1.1 is an Alpha preview. The documented 1.0.0 compatibility, UI, server, and performance gates remain incomplete.

Build and verification

./gradlew clean check releaseBundle

The build targets Java 21 and creates the remapped JAR, sources JAR, and SHA256SUMS.txt under build/libs/. Automated checks cover localization parity, core data rules, bounded pipeline behavior, coordinate-layout geometry, teleport safety, and release-artifact contents. They do not replace the real-world compatibility and interaction checks listed above.

Approved dependency versions and licenses are recorded in Third-Party Notices. See the Changelog for version details.

Support and license

Report reproducible bugs through GitHub Issues with the Minecraft version, Fabric Loader/Fabric API versions, relevant Mod list, steps, logs, and whether Fair Play was enabled. Remove server addresses and personal data before attaching files.

ZoyLuo Map is licensed under the MIT License. It is an independent community project and is not affiliated with or endorsed by Mojang Studios or Microsoft.