TerraLense

What is TerraLense?
TerraLense brings a fully functional minimap to ordinary vanilla Minecraft clients.
Players do not need Fabric, Forge, JourneyMap, Xaero's Minimap, or any client-side minimap mod.
The minimap is rendered server-side and displayed through a generated resource pack. Players simply join the server, accept the resource pack, and the minimap appears automatically.
TerraLense is designed for Minecraft servers that want a modern minimap experience while keeping their players on the vanilla client.

✨ Features

• Terrain Rendering — Render terrain using 21 material categories across the Overworld, Nether and End.
• Height Shading — Adds shading based on terrain height to make hills, cliffs and coastlines easier to recognize.
• Rotating Map — Follow the direction the player is looking or lock the map to north-up.
• Waypoints — Create, remove and manage personal waypoints with SQLite persistence.
• 64 Waypoints Per Player — Each player can store up to 64 waypoints.
• Death Marker — Automatically mark the player's last death location so they can find their way back.
• Player Radar — Display nearby players while respecting vanish, spectator mode, tab-list hiding and permissions.
• Large Map — Open a larger map using /tl map or by double-tapping the swap-hands key.
• Per-Player Settings — Players can customize zoom, orientation, visibility and horizontal position.
• Marker API — Allows other plugins to add their own markers to the TerraLense map.
• Async Rendering — Rendering is handled asynchronously without scanning worlds from asynchronous threads.

️ How It Works
TerraLense uses a generated resource pack to display the minimap on a vanilla Minecraft client.
The server generates the required map assets and serves the resource pack through a lightweight built-in HTTP server.
TerraLense automatically:

• Generates the resource pack
• Calculates the SHA-1 hash
• Serves the pack through its built-in HTTP server
• Handles the resource-pack configuration

You don't need to manually host the resource pack.
Already using your own server resource pack?
TerraLense provides an auto mode that can stand down when another resource pack is already being used. You can also merge the generated TerraLense assets into your own pack and use external mode.

⚙️ Installation

1. Download the latest TerraLense JAR.
2. Place the JAR inside your server's plugins/ folder.
3. Start the server.
4. TerraLense will automatically generate its configuration, resource pack and pack server.
5. If players connect remotely, configure resource-pack.self-host.public-address with your public IP address or hostname.
6. Make sure the configured HTTP port is reachable from the Internet.
7. Run /tl reload.
8. Players reconnect and accept the resource pack.
9. The minimap is ready.

Testing locally?
If you're testing everything on localhost, the automatic setup is usually enough.

Commands
The main command is:
/terralense
Aliases:
/tl
/minimap

• /tl toggle — Show or hide the minimap.
• /tl zoom <1-16> — Change the map zoom level.
• /tl mode <north|player> — Change map orientation.
• /tl position <left|right|center> — Adjust the horizontal map position.
• /tl map [zoom] — Open the large map.
• /tl waypoint <add|remove|list|tp> [name] — Manage waypoints.
• /tl death [clear] — Show or clear your latest death location.
• /tl status — Display version, rendering, cache and resource-pack information.
• /tl debug [on|off|reset] — Enable or disable diagnostic information.
• /tl reload — Reload the TerraLense configuration.

All commands support tab completion.

Permissions

• terralense.use — Use TerraLense. Default: true
• terralense.toggle — Toggle the minimap. Default: true
• terralense.waypoint — Manage waypoints. Default: true
• terralense.waypoint.teleport — Teleport to waypoints. Default: op
• terralense.radar — Use the player radar. Default: true
• terralense.admin — Access administrative commands including reload, debug and status. Default: op

Normal gameplay does not require operator permissions.

Performance
TerraLense is designed with server performance in mind.

• Terrain data is obtained through ChunkSnapshot.
• World access is never performed asynchronously.
• Chunks are not loaded solely to render the map.
• Players cannot force world generation simply by moving around with the minimap.
• Turning in place can reuse cached terrain instead of sampling the world again.
• Render queues and caches are bounded.
• Thread pools are bounded.
• There is no thread created for every player.

Use:
/tl status
to view rendering timings, queue depth, cache hit rate and dropped-frame information.

Requirements

• Paper 26.2 or newer
• Java 25
• One reachable TCP port for the resource-pack HTTP server
• Default HTTP port: 8123

Folia is currently not supported.

⚠️ Important: Resource Pack
A resource pack is required because vanilla Minecraft does not provide a normal server-side API for placing arbitrary custom graphics directly onto the player's HUD.
TerraLense therefore uses a generated resource pack to display the minimap.
Players who decline the resource pack will still be allowed to join the server, but they will not see the minimap.

⚠️ Known Limitations
We prefer to list the limitations clearly so you know exactly what to expect.

• HTTP access is required — Vanilla clients need to download the resource pack through HTTP.
• The built-in pack server is unauthenticated — Vanilla clients cannot provide authentication credentials when downloading resource packs.
• Only the required pack endpoint is exposed — The built-in server handles GET and HEAD requests for the resource pack.
• Automatic pack merging is not supported — If you already have your own resource pack, merge the TerraLense assets manually and use external mode.
• Folia is not supported.
• HUD positioning is limited — Vanilla clients do not provide the server with screen size or GUI scale information, so the minimap cannot be freely pinned to an exact screen corner.
• Default HUD placement — TerraLense uses the boss bar by default. You can use hud.anchor: action-bar to move it above the hotbar.
• BungeeCord resource-pack limitation — BungeeCord does not forward the required resource-pack packets from backend servers, so players connecting through BungeeCord will not receive the minimap correctly.
• Velocity works — Velocity can be used with TerraLense.
• Surface view only — Cave mode and full 3D mapping are not currently available.
• Biome colouring — Not implemented yet.
• Arrow rotation — Rotation uses 16 discrete directions because the font-based rendering system cannot rotate textures continuously at runtime.
• Declining the resource pack — Players who decline the pack are not kicked, but they will not see the minimap.

Developer API
TerraLense provides a marker API that allows other plugins to integrate directly with the minimap.
This can be used to display custom locations, objectives, events or other plugin-specific information on the map.
More API documentation will be provided as the API develops.

️ Troubleshooting
If the minimap is not appearing, start with:
/tl status
The status command provides information about:

• TerraLense version
• Server version
• Resource-pack state
• Rendering performance
• Cache status
• Render queue
• Dropped frames

When requesting support, please include your:

• /tl status output
• Minecraft server version
• Paper version
• Relevant console errors

This makes it much easier to identify the problem.

Planned / Future Features
TerraLense is actively being developed.
Some features planned for future releases include:

• Biome colouring
• Cave view
• Additional marker functionality
• Further HUD customization
• Additional integrations for other plugins

Feature requests and suggestions are welcome.

Support
Having an issue or a feature request?
Please post in the discussion thread or open an issue on GitHub.
When reporting a problem, please include /tl status output and your server version.

License
TerraLense is released under the MIT License.
TerraLense does not use code, assets or resource-pack files from other minimap projects.
All TerraLense pack textures are generated at runtime.