Create a Minecraft Java Edition Fabric 1.21.4 mod called "Chunkscape".
Concept:
Chunkscape is a live world-mapping mod inspired by chunk-based exploration trackers, but with style. It creates a visual, viewable map of every chunk that has been loaded on the installed world/server. Only chunks that have been generated or previously loaded should appear — unexplored territory stays hidden/blank.
Current networking:
For now, connect the mod to a localhost backend (http://127.0.0.1:3000 or configurable in a config file), where chunk data is sent and map data is served.
Design the networking so localhost can later be replaced with a standalone hosted server without major rewrites.
Core Features:
- Fabric 1.21.4 compatible.
- Detect chunk load events in real time.
- Store discovered chunk coordinates.
- Send discovered chunks to localhost backend through REST API or WebSocket.
- Generate a live interactive map of explored chunks.
- Support overworld, nether, and end dimensions.
- Only reveal chunks that have been loaded before.
- Save persistent chunk data between server restarts.
- Prevent duplicate chunk submissions.
- Efficiently handle massive worlds.
Map Interface:
Create a polished in-game INVENTORY GUI opened with a keybind (default M).
INVENTORY GUI should include:
- Pan and zoom.
- Chunk grid visualization.
- Different colors for:
- Loaded chunks - Player’s current chunk - Dimension-specific chunks
- Fog-of-war effect for unexplored regions.
- Smooth chunk-reveal animations.
- Mouse-hover chunk coordinates.
- Search/jump to coordinates.
- Optional fullscreen map mode.
Pzazz / Style:
Make it feel sleek and mysterious, not boring dev-tool style.
Visual design ideas:
- Animated glowing borders.
- Subtle scanline effect.
- Smooth fade-in chunk rendering.
- Neon cartography aesthetic.
- Soft pulsing discovered-chunk highlights.
- Ambient “radar sweep” effect on the map.
- Clean modern dark UI.
- Custom Chunkscape logo on menu.
- Startup splash:
"Initializing Chunkscape..." "Scanning known terrain..."
Architecture:
Use clean package structure: com.chunkscape
- client
- networking
- map
- storage
- ui
- config
Implement:
- Main mod initializer
- Client initializer
- Chunk tracking system
- Localhost API connector
- Map renderer
- Persistent chunk database
- Config system
Backend (for localhost):
Also generate a simple Java or Node.js localhost server that:
- Receives chunk coordinates
- Stores them
- Serves map data
- Supports future migration to dedicated hosted server
Performance:
Prioritize low-lag chunk tracking.
Use asynchronous networking.
Avoid impacting TPS.
Bonus:
Include comments showing how to later replace localhost with: https://api.chunkscape.net
Make the code production-quality, not prototype-quality.
Let me read all the necessary documentation before writing a single line of code.
Excellent project. Planning the full architecture before writing a single line:
Common (main):
Chunkscape,ConfigManager,ChunkscapeConfig,ChunkRecord,ChunkDatabase(PersistentState),ChunkTracker(ServerChunkEvents),ApiClient(async HTTP),NetworkRegistry, two payload typesClient:
ChunkscapeClient,ClientChunkStore(ConcurrentHashMap),KeybindManager,SplashOverlay(HUD),MapScreen(full pan/zoom/animate GUI)Backend: Node.js Express server with in-memory + file persistence, HTML map viewer
Now I have everything I need. Let me build the full project.
Plan:
Common:
Chunkscapeinitializer,ChunkRecordrecord,ChunkDatabase(PersistentState),ChunkTracker(ServerChunkEvents),ApiClient(async HTTP/Java 11 HttpClient),NetworkRegistry, two payloads (NBT-based for efficiency)Client:
ChunkscapeClient,ClientChunkStore(ConcurrentHashMap, thread-safe),KeybindManager,SplashOverlay(HUD fade),MapScreen(full pan/zoom/animate neon GUI)Backend: Node.js Express server with file persistence + HTML map viewer
Here’s a full summary of what was built:
Fabric Mod (src/)
Chunkscape.java— main initializer; boots config → network registry → chunk trackerChunkscapeConfig/ConfigManager— Gson JSON config atconfig/chunkscape.json;backendUrlis pre-commented with the hosted migration pathChunkRecord— Java record with manually tunedequals/hashCodefor fast Set operationsChunkDatabase—PersistentStatestoring chunks as compactNbtIntArraypairs per dimension; lives in the overworld’s persistent state, survives restartsChunkTracker— registersServerChunkEvents.CHUNK_LOADfor real-time detection; deduplicates, saves, broadcastsChunkSyncPayloadto all players, sends full state batch (10,000 chunks/packet via NBT int arrays) on player join viaServerPlayConnectionEvents.JOINApiClient— Java 11HttpClienton a daemon thread; chunks queue into aLinkedBlockingQueue, flushed every second in batches of 200 — zero TPS impactNetworkRegistry— registers bothChunkSyncPayload(S2C, single chunk) andChunkBatchPayload(S2C, NBT int array batch) before any receiversClientChunkStore—ConcurrentHashMap+ConcurrentHashMap.newKeySet()for fully thread-safe client storage with fade-in timestampsKeybindManager— registersMkeybind viaKeyBindingHelper; opensMapScreenon pressSplashOverlay—HudRenderCallbackwith correctRenderTickCountersignature; shows “Initializing Chunkscape…” / “Scanning known terrain…” with alpha fade over 4 secondsMapScreen— fullScreensubclass with pan (click-drag), scroll zoom (cursor-anchored), dimension tabs, animated scanlines, radar sweep bar, multi-layer glow border, corner brackets, pulse-glow player marker, fade-in chunk rendering, viewport culling for performance, coordinate tooltip on hover, andTextFieldWidgetsearch bar for jumping to coordinates
Backend (backend/)
server.js— Express server withPOST /api/chunks/batch,GET /api/chunks/:worldId/:dim,GET /api/stats, periodic 30s file save, clean shutdown handlers, and an embedded interactive HTML canvas map viewer atGET /with pan/zoom/auto-refreshpackage.json— minimal deps (express,cors), Node 18+
The compilation failed with this error:
Compilation failed with 4 error(s):
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 10: cannot find symbol
import net.minecraft.world.PersistentStateType;
^
symbol: class PersistentStateType
location: package net.minecraft.world
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 94: cannot find symbol
private static final PersistentStateType<ChunkDatabase> TYPE = new PersistentStateType<>(
^
symbol: class PersistentStateType
location: class ChunkDatabase
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 10: cannot find symbol
import net.minecraft.world.PersistentStateType;
^
symbol: class PersistentStateType
location: package net.minecraft.world
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 94: cannot find symbol
private static final PersistentStateType<ChunkDatabase> TYPE = new PersistentStateType<>(
^
symbol: class PersistentStateType
location: class ChunkDatabase
=== COMPILATION ERROR ANALYSIS ===
MISSING CLASSES:
- PersistentStateType
ACTION: Create these classes or check imports
FILES TO INVESTIGATE:
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
Please fix this error by creating a new artifact with the corrected code.
PersistentStateType does not exist in 1.21.4 — the correct class is the inner PersistentState.Type<T>. The import and field type just need to be corrected.
Replaced the non-existent PersistentStateType import and field with the correct inner class PersistentState.Type<ChunkDatabase>, and removed the KEY constructor argument which PersistentState.Type does not take (the key is passed at lookup time via getOrCreate).
The compilation failed with this error:
Compilation failed with 2 error(s):
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 100: method getOrCreate in class PersistentStateManager cannot be applied to given types;
return server.getWorld(World.OVERWORLD).getPersistentStateManager().getOrCreate(TYPE);
^
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 100: method getOrCreate in class PersistentStateManager cannot be applied to given types;
return server.getWorld(World.OVERWORLD).getPersistentStateManager().getOrCreate(TYPE);
^
=== COMPILATION ERROR ANALYSIS ===
FILES TO INVESTIGATE:
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
Please fix this error by creating a new artifact with the corrected code.
The doc confirms PersistentStateType is the correct class and it requires the string key as its first argument. The previous fix switched to PersistentState.Type (a non-existent inner class), which getOrCreate doesn’t accept. The fix is to restore PersistentStateType with the key string included in the constructor.
PersistentStateType is restored with net.minecraft.world.PersistentStateType and the KEY string passed as the first constructor argument, which is what getOrCreate expects.
The compilation failed with this error:
Compilation failed with 4 error(s):
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 10: cannot find symbol
import net.minecraft.world.PersistentStateType;
^
symbol: class PersistentStateType
location: package net.minecraft.world
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 94: cannot find symbol
private static final PersistentStateType<ChunkDatabase> TYPE = new PersistentStateType<>(
^
symbol: class PersistentStateType
location: class ChunkDatabase
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 10: cannot find symbol
import net.minecraft.world.PersistentStateType;
^
symbol: class PersistentStateType
location: package net.minecraft.world
ERROR in src/main/java/com/chunkscape/storage/ChunkDatabase.java at line 94: cannot find symbol
private static final PersistentStateType<ChunkDatabase> TYPE = new PersistentStateType<>(
^
symbol: class PersistentStateType
location: class ChunkDatabase
=== COMPILATION ERROR ANALYSIS ===
MISSING CLASSES:
- PersistentStateType
ACTION: Create these classes or check imports
FILES TO INVESTIGATE:
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
- src/main/java/com/chunkscape/storage/ChunkDatabase.java
Please fix this error by creating a new artifact with the corrected code.
The doc shows PersistentStateType but the compiler can’t find it — in the actual Yarn 1.21.4 mappings the class is the nested record PersistentState.Type<T>, and getOrCreate takes it plus the string key separately.
Replaced PersistentStateType (standalone class that Yarn doesn’t expose) with PersistentState.Type<T> (the actual nested record in Yarn 1.21.4), removed the key from its constructor, and passed it as the second argument to getOrCreate(type, key) instead.
nice! but it doesnt unblur, and make it slightly tilted, so you can see in 3D (add 3d viewing as well), and how to i view it in the browser?
Let me read the relevant files first.
Three issues to fix in the embedded HTML viewer: blur (canvas resolution not accounting for device pixel ratio), 3D tilt (add CSS perspective + rotateX transform with corrected mouse coords), and I’ll add clear startup instructions.
Now I’ll update the HTML viewer with DPI-aware canvas (fixes blur), CSS 3D perspective tilt, and corrected mouse math:
How to open it in your browser
cd backend
npm install # only needed once
npm start
Then open http://localhost:3000 in any browser. That’s it — the map viewer is served directly by the backend.
What changed in the viewer
Problem | Fix |
|---|---|
Blurry / soft chunks | Canvas is now sized with devicePixelRatio (retina-aware) so every pixel is crisp. image-rendering: pixelated is also set. |
3D tilt | A perspective: 900px container wraps the canvas. rotateX is applied via a slider in the header — drag it to 0° for flat or crank it up for a dramatic isometric angle. |
Accurate coords while tilted | Mouse Y is un-projected through cos(tiltAngle) before converting to block coordinates, so the X/Z readout stays correct at any tilt. |
Glow pass | At zoom ≥ 6× a soft colour bloom is drawn behind each chunk so explored areas pop against the dark background. |
im not talking about the html viewer with the blur problem, its the ingame map thats always blurry, it never unblurs
Found it. In drawMap, the chunk alpha is capped at 200 out of 255 — so chunks are always rendered at ~78% opacity, making everything look permanently faded/blurry. It never reaches full opacity. Fix is simple:
The alpha was hardcapped at 200/255 ≈ 78% so chunks were perpetually translucent. Changing it to 255 means fully-explored chunks render at 100% opacity after their 600ms fade-in completes.
look its till blurry maybe this image will help, also where do i put cd backend, because i tried it in the .jar dir cmd and it didnt do anything
That’s Minecraft’s built-in background blur shader that gets applied to all Screen instances. Let me read the files to find the exact fix.
Found it. In Minecraft 1.21.4, all Screen instances automatically apply a background blur shader. The fix is to override shouldBlurBackground() to return false.
Simple one-line fix — override shouldBlurBackground() to return false:
The blur is Minecraft’s built-in screen background blur shader — every Screen enables it by default in 1.21.4. Overriding shouldBlurBackground() → false disables it completely for the map screen.
cd backend — where to run it
You need to run it from your mod’s project folder, not the .jar directory. Open a terminal/cmd in the root of your project (where build.gradle is), then:
cd backend
npm install
npm start
Then open http://localhost:3000 in a browser. If you’re unsure where your project folder is, it’s wherever you cloned/unzipped the mod source — it contains src/, build.gradle, and backend/.
The compilation failed with this error:
Compilation failed with 2 error(s):
ERROR in src/main/java/client/java/com/chunkscape/ui/MapScreen.java at line 455: method does not override or implement a method from a supertype
@Override
^
ERROR in src/main/java/client/java/com/chunkscape/ui/MapScreen.java at line 455: method does not override or implement a method from a supertype
@Override
^
=== COMPILATION ERROR ANALYSIS ===
FILES TO INVESTIGATE:
- src/main/java/client/java/com/chunkscape/ui/MapScreen.java
- src/main/java/client/java/com/chunkscape/ui/MapScreen.java
Please fix this error by creating a new artifact with the corrected code.
shouldBlurBackground() does not exist in Screen in 1.21.4 — the blur is a post-processing effect. The correct fix is to call gameRenderer.clearPostProcessor() in init() to dismiss the blur shader, and remove the bad @Override.
Removed the non-existent shouldBlurBackground() override (which caused the compile error) and added client.gameRenderer.clearPostProcessor() inside init() — this dismisses the blur shader the moment the map screen opens.
please remove all special effects (scanline and all that) i think it might be the culprit
Remove
drawRadarSweep,drawScanlines,drawCornerDecorations, the layered glow border, and the pulsing title alpha — keeping only the plain map, grid, and a single clean border.
Removed drawRadarSweep, drawScanlines, drawCornerDecorations, and the layered glow border — replaced with a single plain drawBorder call, and the title now uses a flat static colour instead of pulsing alpha. None of these effects should have caused blur, but they were layering semi-transparent fills over the entire map which could make it look washed out.
package com.chunkscape;
import com.chunkscape.chunk.ChunkTracker;
import com.chunkscape.config.ConfigManager;
import com.chunkscape.networking.NetworkRegistry;
import net.fabricmc.api.ModInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Chunkscape implements ModInitializer {
public static final String MOD_ID = "chunkscape";
public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);
@Override
public void onInitialize() {
LOGGER.info("Initializing Chunkscape...");
ConfigManager.load();
NetworkRegistry.registerPayloads();
ChunkTracker.register();
LOGGER.info("Chunkscape ready — scanning known terrain.");
}
}