RufusMap - WorldMap & Minimap

RufusMap WorldMap & Minimap MOD - For Minecraft 1.21.1 / NeoForge

RufusMap combines a square or round minimap, a persistent world map, textured terrain, automatic cave layers, waypoints, server-managed claims and chunk loading. Optional integrations connect it to FTB Teams and Waystones. Its mapping and claiming systems work independently of Xaero's Minimap, JourneyMap and FTB Chunks.

The current interface uses a Frutiger Aero-inspired blue/cyan palette, glass-style panels, lime highlights, custom icon buttons and Minecraft's active font. This beta adds depth layers and changes intended to reduce map-rendering overhead. It remains under development; compatibility and performance depend on the modpack and environment.

Highlights since the original alpha

• Square or round minimap, player direction arrow, compass and configurable block textures.
• Custom glass-style interface, compact toolbars and waypoint tooltips.
• Terrain colors derived from block-model textures, transparency and biome tint, with texture detail at close zoom.
• Automatic or manual cave layers in 16-block slices, including negative Y levels.
• Dedicated vanilla mob icons, generic fallbacks and configurable radar icon limits.
• Chunk-load queues, nearby block-change refreshes, background map-tile reads and reduced-detail rendering while panning or zooming.

Requirements

Integration versions exercised during earlier development (not revalidated for this beta): FTB Teams 2101.1.11, FTB Library 2101.1.37, Architectury 13.0.11, Waystones 21.1.46 and Balm 21.0.66. Other versions need their own compatibility checks.

Controls

Gameplay keybindings can be changed in Minecraft's Controls menu. Inside the world-map screen, Page Up and Page Down are also handled directly. The minimap toggle starts unbound. Settings are also available from the NeoForge Mods screen.

Mapping and terrain textures

RufusMap records terrain from chunks the client has actually received. Unknown terrain remains dark. Maps are stored per world/server identity and dimension. With RufusMap on the server, its persistent world identity separates worlds hosted at the same address. Client-only mapping uses the server address as its fallback identity.

Newly loaded chunks enter a deduplicated update queue. Nearby block changes also enqueue updates. By default, continuous rescanning covers the 3x3 chunk area around the player; block-change refreshes accept a slightly wider nearby area. Distant cached terrain may stay unchanged until loaded or scanned again. Updates are incremental and depend on the queue and client workload, rather than having a guaranteed instant refresh time.

Terrain colors use the top face of the block model where available, transparency-weighted sampling, biome tint and elevation shading. Water receives its biome color. Unreadable or special models fall back to a particle sprite or map color.

With Block textures enabled, close views add 16x16 texture detail derived from the active resource pack. World-map detail begins at a scale of 4 pixels per block; world-map zoom ranges from 25% to 3200%. Minimap detail is available at its closer texture zoom levels. Older color-only tiles gain block IDs when rescanned. Texture detail uses the block's default-state model, so it does not reproduce every orientation, variant or custom block-entity renderer.

Colors, heights and block IDs are stored in compressed tiles under `<instance>/rufusmap/<world-hash>/`, with a `blocks.json` palette. Rendering requests disk tiles on a background thread, with an in-memory tile cache capped at 12,288 entries. The world map temporarily uses coarser sampling during panning or zooming, then repaints at full detail. The minimap reuses its image when its tracked inputs have not changed. These are implementation choices, not measured FPS guarantees.

1## Cave layers

Cave mapping uses **16-block vertical slices**, such as Y -16 to -1 or Y 0 to 15. Within a slice, the scanner skips a solid ceiling when possible and finds a floor below the opening. Solid columns appear darker, and columns without a floor in that slice remain dark. This is a sliced map, not a complete 3D cave reconstruction.

Cave layers has three modes:

• Off: automatic selection stays on the surface.
• Auto: follows the player's slice when a run of at least three solid, occluding blocks is found above their head. Leaves are excluded. The map returns to the surface when the roof is no longer detected.
• Always: follows the player's cave slice even without a detected roof.

Page Up, Page Down and the right-side world-map buttons select layers manually. The automatic-layer button restores following behavior. A manual choice overrides the automatic mode until reset. Auto mode keeps the normal terrain view in the Nether and other ceiling dimensions; their normal view scans below the roof.

Cave layers are available in singleplayer and client-only mode. On a dedicated server running RufusMap, they require `allowCaveMap=true`. New cave data uses `s<Y>` directories, separate from the older cave-cache layout.

Ores tagged as ores whose top face is covered by an occluding block are rendered using an approximate host-rock appearance. Exposed ore can remain visible. This is a display rule, not a server-side anti-x-ray system.

Minimap, world map and radar

The minimap supports square and round shapes, optional rotation, adjustable size, corner, opacity and zoom. It shows player direction, compass information, coordinates, biome, dimension, waypoints and the nearest HUD waypoint's distance. Claim overlays are displayed on the world map, not the minimap.

The world map includes claims, loaded-claim highlights, waypoint labels and hover details, teammate markers, dimension selection, chunk coordinates and zoom readouts. The optional grid shows chunk boundaries with stronger lines every 512 blocks. The Overworld spawn marker appears when the player is in that dimension. Personal waypoints can also appear as projected markers over the game view.

Entity radar uses dedicated icons for supported vanilla mobs and players, with generic hostile/passive fallbacks. World-map entity icons appear from 50% zoom in the player's current dimension. Only living entities available to the client are considered; invisible entities and spectators are excluded. Radar does not apply a separate cave-slice Y filter.

The default mob limit is 24 per icon category, with 8, 16, 24, 48 and unlimited settings. Nearby entities receive priority, and players are exempt. Modded entities sharing a fallback icon also share its cap. Servers running RufusMap can disable radar. Icon PNGs can be replaced through a resource pack.

Waypoints

Waypoints support names, coordinates, hex colors, categories and diamond, flag or cross icons. Minimap, world map and in-world visibility can be controlled independently. Temporary waypoints last for the current session. Deaths create separate red waypoints.

Use the manager to search by name, category or dimension, edit personal waypoints, delete waypoints and copy team locations. In the editor, a blank share-recipient field shares with your team; entering an online player name sends a personal copy to that player. Team waypoint deletion affects the team's shared entry. Shared entries can be copied and edited locally; editing a shared entry in place is not supported.

Claims and protection

Claims are owned by the server, persisted in the world's `data/rufusmap.dat`, and synchronized with clients. Claim changes are checked against ownership and permissions on the server. Operators with permission level 2 can manage other claims.

Implemented protections include block breaking and placement, multi-block placement, common block/item/entity interactions, farmland trampling, player attacks on non-player entities, PvP in protected chunks, explosion effects, mob-griefing checks and piston movement across ownership boundaries. Vanilla flowing fluids cannot enter a claim from a different territory.

Claim settings allow public visitor access, PvP and FTB Teams allies. Change these settings while standing in a claim owned by your current team. Visitor access is a combined build/interaction permission in this beta. Team members can manage the team's claims and shared waypoints. Allies with enabled access can use the territory but cannot manage its ownership.

Third-party machines, fake players, custom weapons, fire propagation, block transfer mechanics and custom griefing behavior need individual modpack validation. This release does not claim comprehensive protection against every mechanism in every mod.

Chunk loading

Force-loaded claims are highlighted on the world map. RufusMap uses its own NeoForge ticket controller and does not remove other mods' loading tickets. A loaded chunk must already be claimed.

The server configuration controls team limits and offline loading. By default, loaded claims are active while a member of their owning team is online. Status is reconciled every five seconds. With offline loading enabled, selected chunks can stay active while their owners are offline. Tickets are rebuilt from saved claims after a restart, with a reconciliation delay of up to five seconds.

Teams and shared exploration

FTB Teams supplies membership, party management and ally relationships through its own commands and interface. RufusMap uses the FTB team ID for ownership, shared limits, teammate markers and shared waypoints. Without FTB Teams, each player has personal ownership.

Teammate locations are synchronized only when enabled by the server. Spectators and invisible teammates are omitted. Live terrain sharing is opt-in in client settings and also requires server permission. In this beta, it distributes nearby surface-tile colors and heights to currently online teammates who enable sharing. Cave slices and block-ID texture data are not included in the outgoing terrain-sharing payload. It does not provide a historical server-wide map archive or bulk map merge. Already received exploration remains in a player's local cache after leaving a team.

## Waystones

The server periodically sends the Waystones available in the player's activated collection. Invalid Waystones are omitted. The map lists names, coordinates and dimensions and updates the list during synchronization.

Travel from the map requires standing within four blocks of an activated Waystone in the same dimension as the source. RufusMap passes the source and destination through Waystones' default teleport context and normal teleport API. Waystones retains control over costs, requirements and dimension rules. This beta does not support starting map travel using Warp Stones, Warp Scrolls, or the inventory teleport button.

## Configuration

• Client preferences: `<instance>/config/rufusmap-client.json`.
• Server rules: `<world>/serverconfig/rufusmap-server.toml`.
• Personal waypoints: `<instance>/rufusmap/<world-hash>/waypoints.json`.
• Exports: `<instance>/rufusmap-exports/`.

There is a global limit of 2,048 RufusMap claims per world and a maximum of 128 shared waypoints per team in this beta. Changing claim limits does not automatically delete existing claims. Team colors are generated consistently from team IDs, rather than copied from FTB Teams' selected display color.

Operator waypoint teleport requires both permission level 2 and allowOperatorTeleport=true. It uses a surface destination in the selected dimension, independently of Waystones travel. It is not a survival fast-travel feature.

Commands

• rufusmap — brief help.
• /rufusmap claim — claim the chunk you stand in.
• rufusmap unclaim — remove that claim if permitted.
• rufusmap load — enable loading for that claim.
• rufusmap unload — disable loading for that claim.
• rufusmap admin clear <chunkX> <chunkZ> — operator-only removal in the executing player's current dimension.
• ftbteams — FTB Teams' own party-management interface, when installed.

Current implementation limits

• Special models, block entities, state-dependent textures and highly transparent blocks can use approximations or flat-color fallbacks. Animated textures use a fixed frame.
• Cave maps show a floor per column within a 16-block slice, not every overlapping tunnel. Automatic detection can also identify thick building roofs as underground cover.
• Radar is based on client-visible living entities and is not restricted to the selected cave layer.
• The night view is a darker palette; it does not calculate lighting or spawn safety.
• PNG export saves the current terrain texture without labels or claim overlays. It does not stitch the entire explored world.
• Claim access combines building and interaction. Fine-grained per-block permissions and per-rank management are not implemented.
• Existing FTB Chunks claims and JourneyMap/Xaero map data are not imported. Protection settings are independent of FTB Chunks.
• Terrain sharing sends surface colors and heights, not a full historical map or detailed block-texture archive.
• No browser/web map, route finding, timed chunk-loading expiry or fully translated interface is included. Keybinding translations include English and Brazilian Portuguese.
• This beta still needs broader multiplayer, modpack, resource-pack and performance validation before being described as stable or feature-equivalent to mature mapping mods.

Build and development tests

Use JDK 21, then run:

```powershell
.\gradlew.bat build

The result is written under `build/libs/`. Normal development launches:

powershell
.\gradlew.bat runClient
.\gradlew.bat runServer

`build` executes the JUnit tests. The bundled JUnit Platform standalone JAR is used only by tests and is not included in the mod. Its license notices are embedded inside that test JAR.

The `-Psmoke` development profile uses separate `run-server` and `run-client` folders, an isolated localhost-only server on port 25574, and automated checks enabled by `rufusmap.selftest`. The server's test profile is offline solely for local development. Do not reuse its `server.properties` for a public server.

powershell
.\gradlew.bat runServer -Psmoke
.\gradlew.bat runClient -Psmoke

The automated client records screenshots and closes itself. The smoke setup can place test Waystones and edit the disposable test world. To stop the smoke server gracefully, create an empty `run-server/rufusmap-stop-test` file; delete it before starting another test. These actions are disabled unless the smoke system property is explicitly set.

### Validation of the latest 0.6.5-beta build

The latest supplied source ZIP compiled successfully with JDK 21 and NeoForge 21.1.256. Both included JUnit tests passed, with no skipped tests. They cover core coordinate/claim rules and persistent world identity; they do not verify the new cave renderer, UI or frame-rate performance.

The smoke-test profile is available, but it was not run for this latest beta compilation. Earlier client/server smoke tests must not be presented as runtime validation of this build. The newly compiled JAR has not been launched through PrismLauncher in this compilation session.

## Project structure

text
src/main/java/dev/rufusmap/          Mod entry point, models, networking, saved data and server rules
src/main/java/dev/rufusmap/client/   Terrain/texture caches, cave layers, minimap, radar and custom screens
src/main/java/dev/rufusmap/mixin/    Fluid boundary protection and client terrain-update hooks
src/main/resources/                NeoForge metadata, key translations, UI sprites, entity icons and logo
src/test/java/                     Core regression tests
gradle/wrapper/                     Gradle wrapper
```

RufusMap is independent of, and is not endorsed by, the authors of Xaero's Minimap, JourneyMap, FTB Chunks, FTB Teams or Waystones.

 
RufusMap Team