Teyvat Cartographia

The world you explore becomes a soft painted map.
Full-screen world map, HUD minimap, cave layers, pins, a Genshin Impact style waypoint in the world and a walking path to it.

✨ Features   |   🎮 Controls   |   🎨 Themes
🧩 Compatibility   |   🐞 Report a bug

📚 Contents

• About
• Screenshots
• Installation
• Features
  • World map · Map colours · Cave layers · Minimap · Pins and tracking · Pin in the world · Walking path · Settings
• Controls
• Themes
• Compatibility with mods
• Performance
• Where data is stored
• Building from source
• Bug reports and ideas
• License and credits

📖 About

Teyvat Cartographia is a client-side Minecraft mod that brings a Genshin Impact inspired world map and minimap to Minecraft. The chunks you load are drawn as a map in the colours of their blocks, with relief shading, water depth and contour lines, while Fog of War covers everything you have not seen yet. Place pins, search for them and for biomes, track them, follow the path and find your way back home.

• Minecraft: 1.21.1 (Java Edition)
• Mod loader: Fabric (Fabric Loader 0.16 or newer with Fabric API) or NeoForge 21.1 (built against 21.1.257): one file for each, the same mod
• Java: 21
• Side: Client only. Servers don't need it, so you can join vanilla and modded servers.
• Languages: English, Russian
• License: MIT

Note: Teyvat Cartographia is a fan-made mod. It is not affiliated with or endorsed by HoYoverse, and it contains no Genshin Impact assets: every texture, icon and the fog are original or CC0 (see credits).

📸 Screenshots

Left: World map with pins and the walking path.
Right: At night the map darkens, lit places keep their colour.

Left: Cave layer with the layer field at the right edge.
Right: The minimap switches to your cave layer.

Left: Pin list sorted by distance.
Right: Map search (Ctrl+F): pins and explored biomes by name.

Left: The walking path goes round the water.
Right: Settings with a live preview of the setting under the mouse.

Left: Right-click menu on the ground: a new pin, or Teleport with cheats.
Right: On a pin: Edit and Track (rounded interface).

Left: Rounded interface (Settings > Map > Interface style).
Right: Round minimap (Settings > Minimap > Minimap shape).

📥 Installation

1. Install a mod loader for Minecraft 1.21.1: Fabric (Fabric Loader 0.16 or newer) with Fabric API, or NeoForge 21.1.
2. Download the file for your loader from Modrinth, CurseForge or the latest GitHub release: teyvatcartographia-v0.5.0+mc1.21.1-fabric.jar or teyvatcartographia-v0.5.0+mc1.21.1-neoforge.jar, and put it into your mods/ folder.
3. Launch the game and press M in a world.
4. Optional: make the minimap round (Settings > Minimap) or the interface rounded (Settings > Map). On Fabric, Mod Menu adds a settings button to the mod list.

The Fabric file also runs on NeoForge through Sinytra Connector with Forgified Fabric API (Connector Extras adds its settings button to NeoForge's mod list), but on NeoForge the NeoForge file is the better choice.

✨ Features

World map

• Cartography from real world data. Loaded client chunks are sampled (surface height, block map colour, water depth, biome tint, block light) and shaded on background threads into 256 x 256 block regions. Nothing is loaded or generated just for the map. Regions are cached in memory and on disk, so the map grows as you explore and survives restarts.
• Fog of War over unexplored land, painted regions with relief shading and contour lines. The map darkens at night, while torches, lava and other lights keep their colour. The Nether (smoke and embers) and The End (a starry void) have a fog of their own, soft wisps and glowing motes like the fog of the Genshin Impact map.
• Biome name labels, biome under the cursor, player and cursor coordinates, explored chunk counter, zoom slider (1/32 to 32, the zoom shown beside its thumb), optional chunk grid. Pins show at every zoom; at 1/16 and 1/32 the biome names and the grid step aside.
• Search in the pin list (or Ctrl+F): pins of every dimension by name, and the explored biomes by name. A click flies the map to the result, switching the dimension if needed. A biome goes to its nearest explored place, and each further click to the next one ("Place 2 of 5"); the spot is marked with a few rings.
• Off-screen indicators for the player (green) and the tracked pin (gold).
• Separate maps per world or server and per dimension. The compass opens the list of mapped dimensions: Overworld, The Nether, The End, then modded dimensions in alphabetical order. The Nether is mapped below its roof.
• Its own mouse pointer in the theme's colours on the map and in the settings: a hand over what you can click, a text cursor in text fields, a move cross while you drag the map, arrows on the sliders. It is a system cursor, so it never lags behind the mouse.

Map colours

• Every block is drawn in the colour of its texture, like Xaero's Minimap: the average of the texture on its top, with the biome tint of grass, leaves and water, blended smoothly from one biome to the next. This works for the blocks of any mod and in every dimension, and follows your resource packs.
• Blocks that tint themselves in the world (lily pads, stems, redstone, leaf litter, the leaves and grass of mods with a palette of their own) take the colour they have at their place.
• Plants colour their spot on the map. The arrow next to Settings > Map > Plants opens the list of every plant of the game and your mods, with a search field and a switch for each: at first all of them show; switch off the ones you do not want (flowers, if meadows look too busy). A solid plant switched off shows the ground under it.
• Terrain detail (flat colours, shaded slopes, or slopes with contour lines), Deep water shading and Clear shallow water (the ground seen through shallow water) in Settings > Map > Colours.
• View cone and glow under the player arrow can be switched off (Settings > Map).

Cave layers

• In the Overworld, once you are underground (at least 4 blocks of natural ground in a row above your head: stone, dirt, sand, gravel, ores; the floors and roof of a house do not count), the caves within 32 blocks of you are mapped in layers 16 blocks high: floor in block colours, water, lava and ores marked, shafts darker.
• The minimap and the world map switch to the layer you are in.
• The layer field at the right edge of the world map works like the Genshin Impact map: the large button is the surface, a click opens the cave layers in height order around it (at most 5, scrolled with the wheel or the small arrows), a click on the large button goes back to the surface, and another click closes the field.
• Pins made on a cave layer belong to it; pins of other layers are fainter with a small arrow up or down. Cave layers can be switched off in Settings > Map.

Minimap

• Square or round (Settings > Minimap > Minimap shape), with "N" on the rim (and a fainter E, S and W while it turns with the view), the player arrow and view cone, pins, the walking path and the tracked pin held on the rim when it is far.
• North up or rotating with the view; size (never larger than your screen holds), corner, offsets, opacity, zoom and update rate (30 redraws a second while you move by default). An inner padding between the frame and the map, and how wide and how strong its edge fades. In a bottom corner the lines go over it, mirrored.
• Coordinates, biome (long names wrap onto two lines), a clock (game time, your computer's time marked "IRL", or both side by side; 24-hour, 12-hour or 12-hour with AM/PM) and a day counter under it, with their own spacing, text size (Auto: a step smaller than the interface, always sharp) and background opacity.

Pins and tracking

• Three kinds of pins:
  • Custom, for every player: demon, quest, star, meat, flower, pickaxe and hook (the name of each shows when you point at its tile);
  • Interactive, for every player too: sign, party and structure;
  • System: automatic points from real data, the world spawn and your last death location.
• Rename, retype, delete; up to 300 pins per world, a pin list sorted by distance, saved per world and dimension.
• A right click on the world map opens a small menu: New pin on empty ground, Edit and Track on a pin. Operators (permission level 2, or cheats in singleplayer) also get Teleport on the ground, in any dimension the map shows, unexplored ground too.
• Track a pin or an automatic point. Its beam, path and pointers are golden, like the path stars of Genshin Impact. Tracking an automatic point ends on arrival.
• Distances are in blocks everywhere and in 3D: from your feet to the floor of the point.
• Export and import from the pin list: save every pin of the world to a .json file, add the pins of such a file (or of another world's markers.json); repeats are skipped.
• Import from Xaero's Minimap (its waypoints also show on Xaero's World Map): the waypoints of the current world are found on their own, or pick any waypoint file of a Xaero world. Settings > Compatibility > Xaero's Minimap sets the pin type they get and whether hidden waypoints and death points come too.

Pin in the world

• The tracked pin is shown in the 3D world (from the In the world step of its kind) like a Genshin Impact waypoint for a minute after you start tracking or press the pulse key: constant size, visible through terrain, the distance in blocks under it.
• Off screen it slides along an ellipse around the centre, above the hotbar and around the minimap.
• A golden beam of light rises from the target at any distance (hidden behind terrain, drawn after the clouds), fading out softly towards its top and growing with the distance, so a far pin's beam still stands tall; it fades in over a second when the pin comes onto the screen and out when it goes to the edge. Closer than 10 blocks the pin fades out. A white arrow shows a target well above or below you.
• The pulse key sends a thin diamond closing in on the pin in one second, and the glyph flashes when it arrives.

Walking path

• Searched once when you start tracking (and by the pulse key when you are more than 8 blocks off the line), never while you walk.
• A precise path over the loaded terrain (128 blocks around you) follows a coarse path over the explored map (up to 1024 blocks). It goes round lava, tree trunks, walls and mountains, takes steps of up to 2 blocks and shallow water straight on, swims across narrow water (up to 16 blocks) and leads out of the water when you are swimming. The Route setting chooses the way: By land it walks round wider water, By water it goes by boat straight over, and By air it is a straight line to the pin whatever lies between, for elytra and aircraft.
• The world map and the minimap draw it as a golden dash-dot line, grey through unexplored land and in the colour of the sea over water, with a sea icon where each longer crossing begins, without the part you have already walked. By air the line is near white (dark grey over unexplored land) with a cloud on it ahead of you. In the world, golden sparkles follow the path, within 64 blocks of the camera.

Settings

• The gear on the map holds quick switches: the three pin kinds, the path to the target, plants, biome names, chunk grid.
• The full settings screen (also from the mod list: NeoForge's, or Mod Menu's on Fabric) has a tab for each part: Map (appearance; what the map shows: plants, caves; colours; the world map), Minimap (display, size and position, look, extra information), Pins (display and path to the target for each kind), System (performance) and Compatibility (The Nether and End fogs, and the supported mods in the game: see Compatibility with mods).
• Live preview: point at a setting and the card beside the list shows it, with what it does. The map around you as it will look, the minimap at its real size and where it sits, the three terrain detail modes, the cave layers with their buttons to click, each pin kind on the world map, the minimap and in the world, the mapping speed and memory, the mods' fogs and samples. It changes as you move a slider. Without room for the card (GUI 4 on a 1080p screen) the setting under the mouse shows its description as a tooltip instead.
• A setting with parts is one slider in steps: each pin kind goes Off, Map, Both maps, In the world (the marker over a tracked pin), Everywhere (its beam too); its path Off, Map, Both maps, Everywhere (the stars); the clock Off, Game, Real, Both.
• Every list (the settings, plants, pins, overlapping pins on the map) glides as it scrolls, with no steps, and its rows dissolve softly at the top and bottom edges.
• Reset to defaults and a shortcut to key binds. Stored in config/teyvatcartographia-client.json (the teyvatcartographia-client.toml of 0.4 and earlier is taken over once).

🎮 Controls

🎨 Themes

Three choices, each on its own (Settings > Map > Appearance, and the shape in Settings > Minimap):

• Theme: colours, icons and the Fog of War. Default (default) is built in and always available; a resource pack may add more, and the list shows only themes whose pack is enabled. Other themes fall back to its assets.
• Minimap shape: Square (the default) or Round.
• Interface style: Rectangular (the default), flat panels, buttons and tiles with square corners, or Rounded, with circles, capsules and rounded corners.

So the minimap can be round while the menus stay rectangular, or the other way round, with any theme.

A custom theme comes as a resource pack: put it into resourcepacks/, enable it in the game, and its theme appears in the setting.

Making your own theme

Every theme follows the same layout, assets/teyvatcartographia/themes/<id>/:

• theme.json (required): { "name": "..." }: a translation key (teyvatcartographia.theme.<id>) or plain text. Makes the theme selectable.
• colors.json (optional): Colours as "key": "#AARRGGBB" or "#RRGGBB". Keys are the colour fields of render/Theme.java; themes/default/colors.json lists them all. Missing keys keep the built-in defaults.
• icons/64/<name>.png (optional, 64 x 64): Icons. Missing ones (or the whole folder) fall back to the default icons.
• fog.png (optional): Seamless background for unexplored space (256 x 256 in default), repeated every 512 GUI units whatever its resolution. A fog.json beside it may set "repeat" (GUI units). Falls back to the default fog.
• fog/<namespace>/<path>.png, .json (optional): A fog of one dimension (in default: fog/aether/the_aether.png a sea of clouds, fog/minecraft/the_nether.png smoke and embers, fog/minecraft/the_end.png a starry void, fog/the_sift/the_sift.png a pearly haze), also on the minimap. The .json may say { "island_shadow": true } (the land casts a shadow on it) and "repeat".
• dimensions/<namespace>/<path>.json (optional): Map colours of one dimension's blocks, { "blocks": { "<block id>": "#AARRGGBB" } } (for example dimensions/aether/the_aether.json). They replace the texture colours of those blocks; a theme's file replaces the default one of that dimension.
• cursors/<name>.png, cursors/hotspots.json (optional, 64 x 64): The mouse pointers of the menus (white, tinted with the cursor colours) and the pixel of each that clicks. Fall back to the default ones.

A theme does not set any shapes: the minimap shape and the interface style are the player's settings. Colour keys are named by their role, not their shape: icon_button_* is a round or a square button, info_box_* a capsule or a rectangle. Resource packs are merged, so a pack can change a few keys of any theme or add a new theme. Changes apply when the theme is picked, or on F3+T.

🧩 Compatibility with mods

Teyvat Cartographia draws the blocks of any mod in the colours of their textures and lists modded dimensions on the world map, so most mods work without anything special. A few get more: with one of them in the game, Settings > Compatibility has a part for it.

The Nether and The End have fogs of their own too (each can be switched off in Compatibility > Minecraft); a resource pack theme can add a fog for any other dimension (see Themes). Players with other minimaps keep them: this mod changes nothing in the world and needs nothing from the server.

⚡ Performance

The mod is meant to cost at most 2 to 3% FPS:

• Every HUD element is drawn into a cached texture and redrawn only when what it shows changes; a still minimap costs about one textured quad per frame, and a moving one is redrawn at most at its update rate.
• Per-frame paths do not allocate memory. Chunk reading and shading run on worker threads; the path searches run on the main thread in slices of at most 1 ms per tick, and only while the path is shown.
• A chunk whose data did not change triggers no texture upload, no disk write and no minimap refresh. Biome tints are sampled on a 4 x 4 block grid and interpolated.
• The first search in a world reads the explored map once on a background thread (about 1 second per 1000 map regions) and keeps a small biome index; later searches only read what was explored since.
• On the world map, the fog is one quad, and the grid, the path and the labels are each drawn in a single call. Far out the map is drawn from small copies of the regions, so even zoom 1/32 costs only a few textures.

💾 Where data is stored

• Settings: config/teyvatcartographia-client.json
• Map regions: teyvatcartographia/<world>/<dimension>/r.<x>.<z>.png + .dat (heights and metadata) + .lod.png (64 x 64 thumbnail for far zoom) + index.txt + format.txt (the map format; a map of an older format is deleted and mapped again)
• Cave layers: teyvatcartographia/<world>/<dimension>/caves/b<layer>/
• Biome index for the search: teyvatcartographia/<world>/<dimension>/biomes.idx
• Pins and the tracked target: teyvatcartographia/<world>/markers.json
• Exported pins (default folder): teyvatcartographia/exports/

<world> is sp_<save folder> in singleplayer and mp_<server address> on servers.

🛠️ Building from source

Requirements: JDK 21 (Gradle's toolchain support will use or download one), internet on the first build.

./gradlew build

On Windows: gradlew.bat build. The project follows the layout of MultiLoader-Template: the shared code is in common/ (compiled against the game alone, with the unit tests), the loaders' own parts in fabric/ and neoforge/, the shared build rules in buildSrc/. One code base builds both files: fabric/build/libs/teyvatcartographia-v<version>+mc1.21.1-fabric.jar and neoforge/build/libs/teyvatcartographia-v<version>+mc1.21.1-neoforge.jar. ./gradlew :fabric:runClient or ./gradlew :neoforge:runClient starts a development client with the mod.

🐞 Bug reports and ideas

Found a bug, a crash or have an idea? Open an issue on GitHub and pick the matching form. A few tips that help a lot:

1. Make sure you are on the latest version and look through the existing issues first.
2. If you play with other mods, try to reproduce the problem with Teyvat Cartographia alone.
3. Attach logs/latest.log (and the crash report from crash-reports/ after a crash) as a link to a GitHub Gist or a paste site, plus a screenshot if the problem is visual.

Release notes for every version are in CHANGELOG.md.

📜 License and credits

Teyvat Cartographia is released under the MIT License. Source code: github.com/Tapacywka/teyvat-cartographia.

• All textures and the player arrow are original; every pin gets a thin dark outline and is scaled to the same visual weight.
• All other icons (the pins, the automatic points and the interface icons) come from Game Icon Pack by Nieobie, released under CC0 1.0. Thank you!
• All text uses the vanilla Minecraft font. No Genshin Impact assets are included.