← All mods Expansions · Space & Worlds

NEROMAPS

Chart · Share · Explore

A fast minimap that is on from the first minute, a world map of everywhere you have been, and waypoints you share only with the people you choose.

Beta v0.1.0-beta.1
NeroMaps logo

NeroLink App — Beta Explore the Neroland ecosystem

📱 NeroLink App Beta — your Neroland world on your phone. Check energy, alerts and machines live, claim quest rewards and search your storage without logging in. Join the beta at nerolandmc.net →

🌌 Explore the Neroland ecosystem. See how NeroMaps fits together with the rest of the Nero mods — every mod, wiki and changelog in one place. View the ecosystem at nerolandmc.net → · NeroMaps on the website


NeroMaps is the minimap and world map of the Neroland ecosystem. The minimap and the full-screen map are drawn on your own client from chunks you have already loaded, so they work on any server and cost it no terrain traffic. Waypoints follow you to the NeroLink app, where the same map opens in 2D or as a 3D terrain view you can orbit. Atlases, wall maps and signposts put the map into the world as things you craft, copy and hang up. When other Nero mods are installed, their stations, colonies, ruins and companions appear as map layers.

Built on Neroland Core, the only mod it requires. Every other Nero mod is optional.

(Beta — 0.1.0-beta.1, the first feature release.)


What it adds

  1. Minimap, on by default. Square or round, in any corner or a free position, with adjustable size, zoom, opacity and border, north-locked or rotating. Four map styles (Day / Night, Biome, Height-shaded and Flat) plus a high-contrast style, optional grid and chunk borders, and a cave mode that shows a slice at your height (servers can turn it off). Readouts for coordinates, facing, biome, dimension, in-game time and light level are each switched on or off separately. Works on any server, even one without NeroMaps.
  2. World map. Pan and zoom across everything you have explored, switch dimension, search your waypoints, click to create or edit one, measure a distance, or let the map follow you. Every dimension has its own map.
  3. Waypoints. A name, colour, icon and optional in-world beam with a distance label, kept in sets per dimension and stored on the server so they reach the app too. Death waypoints are automatic, keep the last three and can be turned off. Temporary waypoints vanish when you log out. Look through a spyglass and press the waypoint key to mark a distant point, and carry a Waypoint Compass that locks onto your waypoints and death points one by one.
  4. Sharing by consent only. Share a waypoint, your explored map or your live position with named players. They must accept, and either side can revoke at any time, effective immediately. Live position has no "everyone" option.
  5. Fog of war. You see terrain you have explored, terrain shared with you and terrain from an atlas you have merged. Unsurveyed ground stays dark. Fog of war is an access rule, enforced by the server on the app and on shared maps, not a visual effect.
  6. Atlases and the Cartography Desk. An Atlas is a physical copy of an explored map: using one merges its area into your own. Copy, merge and label atlases at the Cartography Desk, which also prints wall maps and crafts signposts. An atlas carries map coverage only, never who made it.
  7. Wall Map, Map Table, Signpost and Trail Marker. A Wall Map tiles into arrays up to 8 × 8 and updates as the terrain changes; each viewer sees only the part they have explored. A Map Table shows its own surroundings, 32, 64 or 128 blocks across, on a table top. A Signpost is a public waypoint with a label and icon that anyone nearby sees on their map. A Trail Marker is a small coloured stake for caves and long trips. None of them stores an owner.
  8. Presets and customisation. A settings screen with a live preview and named presets (Compact, Explorer, Builder, Cinematic and Off), which you can import and export as text. Every layer is toggled separately for the minimap and the world map. Two colour-blind-safe marker palettes, keylines and solid label plates, reduce motion, and nothing shown by colour alone.

Default keys: M world map, Y toggle minimap, = and - zoom, U new waypoint here. All rebindable.

  • 🗺️ 2D map. Pan, zoom, layers, waypoints, search and follow-me. Add, edit and delete waypoints, and answer or end shares, from your phone.
  • 🏔️ 3D view. Orbit, tilt and pinch-zoom over terrain with height shading, translucent water, markers and waypoint beams.
  • 📐 What the 3D view is. The server sends a surface height map and your phone renders it, which costs the server very little. It is a surface model: overhangs, building interiors and caves are not shown in 0.1.0.
  • 🔒 Same rules as in game. The app receives only terrain inside your own fog of war, your own waypoints, and the position of players who have a live, mutual share with you.

Layers from other Nero mods

Layers appear only when their mod is installed, and each one shows only what you are entitled to see: your own things, places you belong to, or world features you have discovered. No layer lists another player's base.

  • 🌌 Nerospace: your stations and launch pads, landed rockets and terraformed regions near you, and a star chart of worlds you have visited.
  • 🏘️ NeroColonies: the border, buildings and outposts of colonies you belong to.
  • 🏛️ NeroRuins: ruins you have discovered, with the vaults you claimed.
  • 🐾 NeroCompanion / NeroCreatures: your companions, their home Bays and your own creatures.
  • 🛡️ NeroSecurity: your installations, their devices and field boundaries.
  • ⚡ NeroPower: your reactors and beam links, unowned machines near you, and scorch zones as a hazard overlay.
  • 🎪 NeroEvents: live event areas and war zones, with a storm badge beside the dimension name.
  • 🚚 NeroLogistics / NeroEconomy / NeroFactions: nearby drone ports and train stations, your own shops, and faction outposts while you are near them, with your standing as a badge.
  • 🪧 NeroMaps itself: signposts and trail markers near you.

A mod that is not installed leaves no empty entry in the layer panel. Mod authors can add layers through Neroland Core's map API without depending on NeroMaps.

Performance and server control

  • ⚙️ Light on the client. Chunk scanning runs off the render thread, and drawing the minimap is one textured quad plus one batched pass for markers. The on-disk map cache has a size cap.
  • 🖥️ Light on the server. The server never loads or generates a chunk for the map. Terrain capture for the app and wall maps works only on chunks that are already loaded, inside a small per-tick budget that backs off when the server is behind, and can be switched off.
  • 📋 Server policy. Operators set the waypoint limit per player, death waypoints, cave mode, fog of war or a public map, and server capture. Policy is synced at login, a client cannot enable what it forbids, and the settings screen says why a control is locked.

Privacy (POPIA / GDPR)

Where you are is personal data, and NeroMaps treats it as the most sensitive thing it touches. Your position is never written to disk: no trails, no position history, no last-seen location. A server stores, under your player UUID, only your waypoints and last three death points, which chunks you have explored, your sharing lists and your privacy toggles. Map tiles, atlases, wall maps and signposts hold terrain and no identity. Nobody learns where you are, have been or have built without your consent or the server's stated policy; if an operator makes the map public, players are told when they join. Display settings and presets stay on your own computer. Get a copy of your data with /neromaps export; erase everything with Neroland Core's /neroland data eraseme, which also removes you from every other player's sharing lists and clears your NeroMaps data alongside every other Neroland mod.

Telemetry notice: NeroMaps contains opt-out, anonymous crash reporting via Sentry (EU servers) — on by default. A report carries only the stack trace of an error in NeroMaps code, the mod/game/loader/Java versions and the list of loaded mod ids — never IPs, usernames, UUIDs, positions, world data, chat or waypoint names. Opt out any time by setting telemetryEnabled=false in config/neromaps.properties. Full details: PRIVACY.md.

Why it fits the ecosystem

  • 🧩 Built on Neroland Core — one config framework, Core's map API for layers, and Core's shared per-player erasure hook. NeroMaps ships in its own creative tab.
  • 📱 NeroLink module — the 2D map and 3D view in the companion app, with optional notifications (off by default) that never contain coordinates or names.
  • 🤝 Interoperates, never hard-depends — every sibling layer is optional and reaches the map through Neroland Core. NeroMaps works in full on Core alone.
  • 🧱 Cross-loader — NeoForge, Forge and Fabric on Minecraft 1.21.1 to 1.21.11 and 26.1.2, 26.2 and 26.3.

Requirements & compatibility

  • Requires Neroland Core 1.19.0 or newer — install it alongside NeroMaps (it loads first).
  • Minecraft 1.21.1, 1.21.4, 1.21.5, 1.21.8 (also 1.21.7), 1.21.10 (also 1.21.9), 1.21.11, 26.1.2, 26.2 and 26.3, on NeoForge, Forge and Fabric (Fabric also needs Fabric API).
  • Optional: NeroLink for the app, and any other Nero mod for its layers. NeroMaps is complete without them.
  • Maps never gate gameplay: nothing in another Nero mod needs NeroMaps to be reachable.
  • Modpacks are allowed and encouraged — any platform, no need to ask. Use the official files and credit NeroMaps by Neroland with links to this page and the GitHub repository. Full terms: LICENSE.
  • 📖 Wiki — getting started, every setting and preset, waypoints, sharing and privacy, server policy, layers, commands and config.
  • 💬 Discord — chat, help, and sneak peeks.
  • 🐞 Issues — bug reports and feature requests.
  • 🗒️ Changelog
  • 🔥 Also on CurseForge

Created by Neroland. The project logo was made with the help of AI image tools; in-game art is generated by the project's own tooling and refined by hand.

Latest release

v0.1.0-beta.1

The first feature release. Requires Neroland Core 1.19.0 or newer (the map layer API); Core 1.19.0 must be released before this version can be installed. Built for Minecraft 1.21.1, 1.21.4, 1.21.5, 1.21.8, 1.21.10, 1.21.11, 26.1.2, 26.2 and 26.3 on Fabric, NeoForge and Forge.

Changed

  • Neroland Core requirement raised from 1.17.6 to 1.19.0 (accepts any Core from 1.19.0 below 2.0).

Added

  • Compliance:

    • /neromaps export: everything NeroMaps holds about you (your record, shares others gave you, offers you made) is sent to your own game, which saves it as JSON under neromaps/exports/ only when you click Save on the chat line that announces it (an export the server sends unasked writes nothing; the ten newest files are kept). Nothing is written on the server; once a minute.
    • Erasure now also resyncs the erased player if online (empty waypoints, shares and positions), ends in-flight tile answers and layer state for everyone who shared with them, forgets their link and rate state, and tells the app (a new record id), all in the same tick. Core's ErasureConformance passes; retention runs through the same eraser from Core's sweep.
    • Each player record carries a random record id (no identity) that changes when the record is erased.
    • Tests: Core's erasure conformance, a two-player export, a simulated world folder scanned for a session position and an erased player's identity before, during and after a session, a source log sweep and a runtime INFO+ log capture, and telemetry checks.
  • NeroLink link module neromaps, schema 1: sections dimensions, tiles, palette, waypoints, layers, position, shares; actions waypoint_add, waypoint_edit, waypoint_delete, share_offer, share_accept, share_decline, share_revoke (20 a minute, offline-safe, no teleport or world change); events waypoints, shares, deaths and coarse tiles, with push copy (no names or coordinates) only for share requests and death points.

    • Tiles: a cursor/want-mask protocol over 8 x 8-tile blocks, fog-checked on every read (a hidden tile answers exactly like a missing one), partly visible tiles masked, pages capped at 256 KiB, 8 MiB per player per minute. The server thread only assembles pre-encoded base64 strings that the capture worker prepares.
    • Fog masks are now built region by region (55 times faster than per chunk), so the link can serve LOD 0-4.
    • Just after a server start, the tile index and the palette answer a pending shape with retryMs instead of an error while the on-disk tile etags are learned and the colour table is built: the index lists each visible tile it has not learned yet with the placeholder etag "pending" (never null, so a client keeps what it holds), and the palette answers {"v":"","pending":true,"retryMs":...}.
    • Tests for the layers section: each requester gets only their own entries, a stranger gets nothing, nearby-only layers follow the requester's server-side position and never the requested bounds, and an answer holds at most 1 024 items and stays inside one 256 KiB page.
  • Client map engine:

    • Tile format and codec (schema 1) with round-trip, fuzz and size tests. A corrupt or unknown-schema tile is dropped and recaptured without a log line per tile.
    • Off-thread chunk scans from immutable snapshots, triggered by chunk loads and coalesced block changes, through a bounded queue.
    • Region textures updated a 16 x 16 patch at a time, with at most one upload batch per frame.
    • A disk cache for each server, world and dimension, with a size cap and least-recently-used eviction. It holds terrain only.
  • Block and biome colour tables built by tools/build_colour_table.py from vanilla and Nero block textures. They ship in assets/ and data/ and can be overridden by resource packs. Blocks missing from the table fall back to the vanilla map colour.

  • Minimap, on by default:

    • Square or round, in any corner or at a free position inside a safe-area margin. The default is top-right, below the status effects.
    • Size, zoom, opacity, three border styles, and north-locked or rotating.
    • Day / Night, Biome, Height-shaded, Flat and High-contrast styles, plus grid and chunk-border overlays.
    • Readouts for coordinates, facing, biome, dimension, time and light, each toggled separately.
  • World map screen (M): pan, zoom with level-of-detail tiles, dimension switcher, follow-me and distance measure.

  • Cave mode, a client-only slice that is never written to disk, gated by the caveMode server policy (default allowed). Roofed dimensions get a scan that skips the ceiling.

  • Key mappings: M (world map), Y (toggle minimap), = / - (zoom), U (new waypoint here, or at the spyglass target), plus three unbound actions (toggle waypoint beams, cycle preset, open settings).

  • /neromaps perf: an overlay showing frame cost, queue depth, texture memory and NeroMaps allocations. Also /neromaps perf reset and /neromaps perf dump. On servers without NeroMaps the client-only form is /neromaps-client perf (a client root named neromaps would block the server's subcommands on Fabric).

  • Subtitle, block and item names for the art set.

  • Waypoints, stored on the server in the one player store (neromaps:players, schema 1, read through Neroland Core's corrupt-file recovery): create, edit and delete, sets per dimension, a per-player limit (default 256), the last three death points (players can turn them off), temporary waypoints kept in client memory only, beams and distance labels drawn on the HUD, and a waypoint editor (key U, or right-click the world map).

  • One name filter and 32-character limit for waypoint names, also used for atlas labels and signpost labels (24 characters), with a server deny list (nameDenyList).

  • Spyglass marking: press U while looking through a spyglass to drop a waypoint where you look.

  • Waypoint Compass: locks onto your waypoints and death points in the current dimension, using vanilla's lodestone needle. Crafted from a compass, an empty map and redstone.

  • Server policy in config/neromaps.properties (cave mode, radar categories, players on radar, waypoint teleport, death waypoints, waypoint limit, public map, explore radius, server capture, debug overlays), sent to clients in a hello payload at login, on dimension change and after /neromaps reload, with lock explanations.

  • NeroMaps' own payload channel neromaps:main: every serverbound payload is validated against the sender and rate-limited per player; codec round-trip and hostile-input tests.

  • Server commands: /neromaps waypoint add|list|remove, share, unshare, privacy, policy and reload (operators), and perf (the client overlay, plus server counters for operators).

  • Server terrain capture: dirty marks from block changes and newly explored chunks; snapshots of already-loaded chunks only, within captureBudgetMicros per tick (a quarter while the server is behind, none below captureMinTps) and only while something needs server tiles; one worker scans, encodes, rebuilds the LOD 1-4 pyramid and writes tiles atomically under <world>/data/neromaps/tiles/ with a disk cap, eviction and corrupt-tile recovery.

  • Fog of war: each player's explored chunks (one bit per chunk) gate every server terrain read; a public-map policy with a notice on join.

  • Consent-only sharing of a waypoint, an explored map or a live position with a named player: offer, accept, decline and revoke by a server-issued request id. Live positions are relayed at most once a second, memory only, never while the sharer sneaks, is invisible or spectates; revocation ends everything at once. Shared terrain is masked to the sharer's exploration and kept in client memory only.

  • Map layers from other mods through Neroland Core's map API: bounded per-player queries (on a schedule and on change hints), delta sync, a Layers panel on the world map with world-map and minimap toggles per layer, and icons resolved from assets/neromaps/map/map_icons.json with a generic fallback.

  • Survival cartography:

    • Atlas (blank and filled): records your own explored map of the current dimension, nearest regions first; using a filled atlas merges its coverage into the reader's map; sneak-use re-records. Page Packs (+16 regions each) and a Binding Ring (allows up to eight packs) fit with the atlas in the other hand. An atlas holds coverage only, never an identity.
    • Cartography Desk: copy, merge and label atlases, print a Wall Map of an atlas's area (paper), or make a Signpost (a sign). The desk holds nothing; its slots return to you when you close it.
    • Wall Map: panels join into arrays up to 8 x 8 with connected frames; a printed panel brings its area (32, 64 or 128 blocks per panel). Each viewer sees only their own explored part of the area.
    • Map Table: a flat map of its surroundings in its glass top (32, 64 or 128 blocks across; use to change).
    • Signpost: a public waypoint with a label, symbol and colour; anyone within 128 blocks sees it on their map (layer neromaps:signposts). Sneak-use adds a plate (up to three).
    • Trail Marker: a stake that shows as a dot on the map of anyone within 64 blocks (layer neromaps:trail_markers); use to change its colour.
    • Recipes with recipe-book unlocks, loot tables, minecraft:mineable/pickaxe and neroland:highlight/* tags, and creative tab entries (the tab icon is now the atlas).
    • A NeroQuests chapter, "Charting the World" (seven quests), shipped as inert data.
  • Settings screen: tabs for the minimap, style, readouts, waypoints, presets and accessibility, a live preview that is the real minimap, a tooltip on every control, and locked controls that say which server policy locked them. Open it with its key (unbound by default) or from the world map.

  • Presets: Compact, Explorer (the default look), Builder, Cinematic and Off, plus your own (saved in config/neromaps-presets.json); the cycle-preset key switches them in play; export and import a preset as JSON text through the clipboard (only display settings; every value is checked and clamped).

  • The art set's minimap frames: the square bezel as a nine-slice, the round bezel and its turning tick ring for 64, 96, 128 and 160, minimal and high-contrast variants and the north tab. A missing texture falls back to the drawn frame.

  • Fog edge: a two-step ordered dither and a rim on the explored side of the fog boundary (white edge in high contrast).

  • World map: a search field in the waypoint list, a Go button that centres on a waypoint, click a waypoint marker to edit it, and a Settings button.

  • Accessibility: two colour-blind-safe marker palettes (Okabe-Ito, the default, and Tol bright), named colours in every colour picker, a keyline and solid-plate option, reduce motion, and a night-darkening switch. The waypoint colour picker uses the seven marker colours of the art direction (the dark blue is gone; old waypoints keep it).

  • NeroEvents war zones now carry a side badge (a glyph, not only a colour) on the world map.

  • /neromaps unshare accepts an offline counterparty's handle with or without its leading # (a command word cannot start with one).

  • Map layers of NeroMaps' own: neromaps:signposts (within 128 blocks) and neromaps:trail_markers (within 64).

  • Sibling layers that ship with this release, each in its own mod's next version (all need Core 1.19.0): Nerospace 2.2.1 (stations, launch pads, nearby pads, rockets, terraforming, star-chart badges), NeroPower 0.3.2-beta.1 (power, nearby power, scorch zones), NeroLogistics 0.7.4-beta.1 (drone ports, train stations), NeroColonies 0.8.1-beta.1 (colony border, buildings, outposts), NeroFactions 0.7.1-beta.1 (outposts within 48 blocks, with a standing badge), NeroEconomy 0.5.2-beta.1 (your shops), NeroSecurity 0.7.1-beta.1 (installations, devices, fields), NeroEvents 0.9.1-beta.1 (events, war zones, storm badges), NeroRuins 0.5.2-beta.1 (discovered ruins), NeroCreatures 0.5.1-beta.1 (your creatures), NeroCompanion 0.7.1-beta.1 (companions, home Bays). The wiki's Layers page lists what each shows and to whom.

  • The companion app's maps module (2D map, 3D terrain view, waypoints, shares, map data) ships in the NeroLink app; tile traffic uses the NeroLink bridge's bulk budget, which ships in the NeroLink release after 1.2.2.

  • Wiki: Getting Started, Minimap, World Map, Customising, Waypoints, Sharing and Privacy, Atlases and the Desk, Wall Maps and Signposts, Layers, Server Policy, Performance, Adding a Layer, Commands, Config, Link Module and The 3D Map.

Security

  • Fog of war holds for change signals, not only for terrain: everything a viewer can read about a partly visible tile (its etag, the index changed bits, the cursor, the pending mask, the in-game tile answer and the tiles events) is derived from the masked bytes that viewer receives, so building or block activity in a chunk outside their fog changes nothing they can observe. Rescans that leave a chunk's pixels as they were no longer rewrite the tile.
  • The in-game tile path has a per-player byte budget (8 MiB a minute), at most 64 tiles in flight per player, a cap on tile jobs on the capture worker so capture always keeps room, and a lower request rate (4 a second).
  • Tile and store requests are only served for dimensions the server has, and for tiles inside the world border.
  • A share sender may have at most three offers waiting on one player and can no longer push other players' offers out of a full inbox; a map share from the app must name * or one of the server's dimensions.
  • /neromaps share revoke with nothing to revoke no longer resyncs either player.
  • Signposts can only be edited by players who may build at that spot (not spectators or adventure mode, and spawn protection and protection mods apply).

Cut

  • Survey Kit (first in the cut order): not registered. Its art and lang name stay in the resources, unused.
  • Entity radar: not built. The radar* policy keys are reserved and do nothing yet; no mob, item or player is ever drawn unless a player shares their live position.
  • Map Table holographic relief: the table ships the flat map in its glass top.
  • The wall-map area picker screen: the printed area is the atlas's explored extent, centred, at the span chosen on the desk's Print tab.
  • The atlas reading view (the folio screen): an atlas is used, merged and copied, not browsed.
  • The Radar and Sharing tabs of the settings screen: sharing lives in the world map's waypoint panel and the /neromaps share commands; layers are toggled in the world map's Layers panel.
  • Layers left out for privacy or accuracy: NeroLogistics storage networks, drive bays and rocket flights (no owner is recorded, so any list would map every base); Nerospace meteor sites and cargo routes; NeroCreatures altars; NeroAgriculture farms; other players' NeroEconomy shops by proximity (a shop has an owner).

Seams and deferrals

  • Waypoint beams are drawn on the HUD from a projection of the player's view, not as textured beams in the world.
  • waypointTeleport is a policy key only; no teleport command ships.
  • Link module: the waypoint minimap flag is not stored (always true); position answers need the requester online too; shares carry no since; death points are ids d0-d2 and can be deleted but not edited; a tile larger than one page is never offered (real terrain never is); layers are never locked (there is no per-layer policy yet).
  • The first tile request for a dimension after a server start reads every stored tile's 16-byte header once, on the capture worker.
  • Offers can be made to online players only. Offline counterparts are shown as # plus eight hex digits.
  • The shared-map read path, wall maps, map tables and the desk preview serve tiles of level of detail 0-2; the per-viewer masked-tile cache is not built (masks are rebuilt per request).
  • Server tile eviction is least-recently-read across all levels of detail (not level 0 first).
  • The server policy also travels in NeroMaps' hello payload, which can arrive up to a second after joining.
  • Trail markers change colour by use, not with dye; their in-world cap glow is not tinted per colour yet (the map dot is).
  • The Waypoint Compass needle does not turn on 1.21.1 (no item model definitions before 1.21.4); it shows a static frame there.
  • Map textures use DynamicTexture on every line; their CPU copy counts against the texture budget.
  • Biome colours come from the biome nearest the surface of each 4 x 4 column. World-map hillshade at a chunk edge refreshes when that chunk changes (the minimap also follows its neighbours).
  • NeroEvents war-zone sides reuse the hostile / friendly / neutral badge glyphs; side-specific art comes later.
  • The 3D view in the app is a surface height map: no overhangs, interiors or caves.
  • The NeroQuests chapter is validated by NeroMaps' own copy of NeroQuests' sibling-pack checks until NeroQuests lists NeroMaps among its sibling packs.

Handovers (work for other mods)

  • Nerotech: pollution readings are stored without a dimension, so a pollution layer could draw a reading in the wrong world. Record the dimension with each reading, then add the layer.
  • NeroFactions: a persistent "discovered outposts" layer needs OutpostVisits to store where each visit happened.
  • NeroEconomy: an opt-in "list my shop on maps" flag per shop, then a public listed_shops layer.
  • NeroRuins: an expedition-target layer needs a read-only accessor for the Surveyor's Compass reading (direction and range band only), drawn as a fixed-distance chevron, never a pin.
  • NeroCreatures: a discovered lairs and habitats layer needs a per-player record of discovered sites (new location data, with erasure, export and retention).
  • NeroQuests: add neromaps to the sibling packs its pack test validates.
Full changelog →

Search across every Nero mod wiki.