WorldData Core

A fast, shared world data cache for Fabric and NeoForge. WorldData Core reads what Minecraft already holds and gives other mods one safe API for blocks, fluids, biomes, heights, light and water, inside a strict tick budget.
Rohit_1597 | WorldData Core
Create a server, get 25% off your first monthaffiliate logo
Create Server
affiliate banner image

Project details

Field Value
Name WorldData Core
Categories Library, Utility
Loaders Fabric, NeoForge
Game version 1.21.1
Environment Client and server (works on either side or both)
License LGPL-3.0-or-later (API package net.wdc.core.api: MIT)

A fast, shared world data cache for Minecraft 1.21.1 on Fabric and NeoForge.

WorldData Core (WDC) is a library mod. It reads the world data that Minecraft already holds, stores it in a compact cache, and gives every other mod one small API for asking about blocks, fluids, biomes, heights, light and water. Instead of several mods each scanning the same chunks, they ask WDC once and share the answer.

You install it because another mod needs it. WDC adds no blocks, items, mobs or world generation, and it never changes your world.

Why it exists

Mods that react to the world around the player all need the same facts: what block is here, how high is the ground, is there water nearby, how bright is it. Each mod usually walks chunks on its own, so the same work is repeated several times in every tick.

WDC does that work once, inside a bounded slice of the tick, and keeps the result in memory. Any mod can then read it quickly, from any thread, without touching Minecraft's chunk storage itself.

What WorldData Core does

  • Reads, never writes. It asks Minecraft for the chunks the game already holds and copies what it needs: blocks, fluids, biomes, heights, light and water. It never loads or generates chunks and never changes the world.
  • Keeps one compact copy. The copy is built inside a fixed tick budget and kept within fixed memory limits. Chunks that leave memory are written to disk by a background worker.
  • Answers other mods. Mods ask WDC instead of scanning chunks themselves, and several mods asking about the same chunk share the same answer.
  • Follows Minecraft's own data. Blocks, fluids and biomes from other mods work like vanilla ones, because WDC uses registry ids and tags and never a list of known mods.
  • Works on the client and the server. The server is the authority for the chunks it holds. A client reads the chunks the server has sent to it, so a client never claims to know a chunk it was not given.
  • Can speed up two vanilla reads, if you ask it to. An experimental redirect, off by default, answers Level.getBlockState and Level.getFluidState from WDC when it is safe. See the redirect section below.
  • Shows what it costs. F3 lines, an API usage monitor and timed test sessions.

Highlights

  • Complete world reads. Blocks, fluids, biomes, heights, columns, light and water, taken from data Minecraft already holds.
  • Modded content works out of the box. Blocks, fluids and biomes from other mods are handled exactly like vanilla ones, because WDC addresses everything by registry id and tag.
  • Compact storage. A section that is one block or air is a single token. Every other section is bit-packed at the narrowest width that fits. Each chunk also remembers its highest block per column, so height reads never scan.
  • Shared derived layers. Height maps, columns, block indexes and occupancy are built once per chunk version, however many mods ask for them.
  • Pull and push. Read at any time, or subscribe to block changes delivered once per tick as one batch per dimension.
  • Spatial queries. Box, sphere, column and grid queries across chunks.
  • Strict limits. A tick budget and fixed capacity limits keep the cache from growing or running without bound.
  • Hot sections and pins. Sections that are read constantly are kept in a faster form inside a small memory budget, and operators can pin sections by hand.
  • Built-in diagnostics. F3 lines, an API usage monitor, and timed test sessions that write MSPT reports.
  • Fabric and NeoForge. One mod, same behaviour on both loaders, on the client, on a dedicated server, or both.

How it works

Minecraft (source of truth)
   |  chunk load, block change, tick
   v
WDC ingest (server thread, strict tick budget)
   v
Compact cache: chunk -> section -> palette + packed block indexes, plus heights, columns, biome
   |                                      |
   v  PULL: ask at any time               v  PUSH: one batch per dimension at the end of the tick
WDC.requests().chunk(...)                 WDC.changes().subscribe(...)

Minecraft stays the source of truth. WDC reads from the most accurate side available:

  • A dedicated server reads its own loaded chunks.
  • Singleplayer and LAN hosts read from the integrated server, so there is one cache that every thread can read.
  • A client on a remote server reads the chunks that server sent it.

WDC adds no networking of its own, and it never loads or generates a chunk to answer a question. Every answer says how trustworthy it is:

State Meaning
LIVE Minecraft holds the chunk and the cache is current.
STALE Minecraft no longer holds the chunk. The last known data is kept and may be old.
PENDING The chunk is loaded in Minecraft but not ingested yet. The read is queued.
UNAVAILABLE Nothing is known about the chunk.

Performance expectations

WorldData Core does not automatically speed up your whole pack. Most gains appear when other mods, or script mods that can call Java APIs, use its API instead of scanning the world the slow way. Installing it on its own is not free TPS.

For a quick test of the optional vanilla redirect:

  1. Install WorldData Core.
  2. In game, run /worlddata redirect on. It needs operator permission, so in singleplayer cheats must be on.
  3. This sends two vanilla reads, getBlockState and getFluidState, through Core when its data is available.
  4. Compare how the game feels, MSPT and Spark with the redirect off and on. /worlddata session start writes a report you can compare.

The redirect is off by default. It can improve some block and fluid reads, and the gain is small. It will not fix lag from pipes, machines, entities or other heavy mods. Use /worlddata redirect off to turn it off again.

For API usage details, see /worlddata monitor and /worlddata session, explained under Diagnostics below.

For players and server owners

Installation. Put the jar for your loader in the mods folder, together with the mods that require it. On Fabric, Fabric API is also required. WDC works on the client, on a dedicated server, or on both.

Performance. WDC spends tick time only on asking Minecraft for chunk data, building its cache and answering other mods. The defaults are conservative:

Setting Default
Share of the remaining tick used for ingestion 10%
Fixed allowance when the tick is already late 4 ms
Hard ceiling per tick 16 ms
LIVE chunks kept in memory 4096
STALE chunks kept per dimension 1024

Chunks that leave memory are written to config/worlddata_core/<world>/<dimension>/, and disk work never runs on the server thread. Everything above can be changed in config/worlddata_core/worlddata_core.json.

See what it costs. The F3 screen shows WDC Mem, WDC CPU, WDC Budget and WDC Redirect, so the cost of the mod is always visible.

Commands. All commands start with /worlddata. Information commands are available to everyone by default and changing commands need operator level 2. Both levels are configurable.

Command Purpose
stats, help, performance, capacity show, budget, pins Status, cost, limits and hot memory use.
budget share|fixed|max|reset, capacity reset, performance reset Adjust or restore limits at runtime.
pin, unpin, overlay Manage hot sections and show them in the world.
monitor ... API usage monitor.
session start [seconds], session stop, session status Timed test session with a report file.
redirect [on|off|reset] Experimental hot-read redirect.
dump ..., gc Debug dumps and a JVM garbage collection request.

For mod developers

The public API lives in net.wdc.core.api and is licensed under MIT. The entry class is WDC.

import net.wdc.core.api.WDC;
import net.wdc.core.api.request.*;

WDCChunkResult chunk = WDC.requests().chunk("minecraft:overworld", chunkX, chunkZ);
if (chunk.isUsable()) {                                   // LIVE or STALE
    String blockId = chunk.blockAt(x, y, z).blockId();    // "minecraft:stone" or "mymod:ruby_ore"
    int surface    = chunk.heightmap().topY(x & 15, z & 15);
    int ores       = chunk.countBlocksByTag("c:ores");    // every mod that added to the tag
    var logs       = chunk.findBlocksByTag("minecraft:logs");
}
var around = WDC.spatial().summarizeSphere("minecraft:overworld", x, y, z, 24);
var light  = WDC.light().read("minecraft:overworld", x, y, z);   // the result says why when empty
Entry point Purpose
WDC.requests() Chunk reads (chunk, peek, availability).
WDC.blocks() State id, block name, property and tag lookups.
WDC.spatial() Box, sphere, column and grid queries.
WDC.light() Sky and block light.
WDC.world() Raw time, weather and moon values.
WDC.changes() Push feed and dirty-chunk hooks.
WDC.capabilities() Feature flags, so a mod can check what is available.
WDC.extensions() Registry for optional data providers.

Two ways to get data. Pull reads answer from the cache at any time, including changes Minecraft has already reported this tick. The push feed delivers one coalesced batch per dimension at the end of each tick, so several edits to one block arrive as a single change:

WDCSubscription subscription = WDC.changes().subscribe(WDCChangeFilter.all(), batch -> {
    if (batch.reset() || batch.truncated()) return;   // detail was dropped: pull again instead
    batch.chunks().forEach(chunk -> chunk.blockChanges().forEach(change -> {
        // change.oldBlockId() -> change.newBlockId() at change.x(), change.y(), change.z()
    }));
});

Mods that do not want to call subscribe themselves can declare a worlddata_core:changes entrypoint in their Fabric or NeoForge metadata.

Things to know

  • A mid-tick pull is best effort. For logic that must be exact at the same instant, read Minecraft directly.
  • Edits that bypass normal block updates, such as bulk editing tools, are not seen until you call markChunkDirty or markBlockDirty.
  • State ids are internal and valid for one session only. Persist the block id and its properties instead.
  • A waterlogged block answers as the block for block reads and as water for fluid reads, as in vanilla.
  • Heights are built once per chunk and kept up to date on every block change, so a height read is one array lookup. They answer the Y of the top block, which is one lower than Minecraft's Level.getHeight. WORLD_SURFACE answers the highest block that is not air, so plants count; MOTION_BLOCKING answers the highest block that blocks motion or holds a fluid, so plants are skipped and water counts; OCEAN_FLOOR answers the highest block that blocks motion, so fluids and plants are skipped; MOTION_BLOCKING_NO_LEAVES is MOTION_BLOCKING without leaves.
  • Point reads return the exact state at a position, including minecraft:air, minecraft:cave_air, minecraft:void_air and any other state Minecraft calls air. isPresent, block searches, counts, height maps, columns and the block index count real blocks only, and a position outside the stored height range answers NULL_ID.
  • Light is read live from the thread that owns the level. Other threads receive a server snapshot kept in RAM only, built inside the tick budget as chunks load and refreshed around block changes, and WDC.light().read(...) explains an empty answer with PENDING, UNLOADED, NO_WORLD or UNAVAILABLE.

Hot sections and pins

A section that is read often and rarely changes can be kept as a plain array of tokens so that a read skips the palette. WDC counts reads per section and promotes and demotes sections automatically. Operators can also pin sections with /worlddata pin. The budget is small and fixed (192 sections, about 3 MB, by default), pins are never evicted, and a new pin is refused with a message when the budget is full. /worlddata overlay shows hot sections in the world: yellow for normal, green for hot.

Experimental hot-read redirect

Off by default. /worlddata redirect on lasts until the game or server restarts. To make it the default, set hot.redirectReads to true in the configuration.

What it does today. When it is on, vanilla Level.getBlockState and Level.getFluidState are answered from WDC when it is safe to do so. WDC answers only when all of these hold:

  • the chunk is LIVE,
  • the caller is on the thread that owns the level,
  • no block change is waiting in the queue, and
  • the position is inside the height range WDC stored for the chunk.

Air, cave air and void air are stored as separate states and are served like any other block, so open sky, caves and structures answer the same as in vanilla. A position above or below the stored range goes to vanilla, which answers void air there. In every other case vanilla answers. A waterlogged block answers as the block for block reads and as water for fluid reads. Writes, world generation and the light engine are never affected, and WDC's own reads of those two methods always go to vanilla.

Redirect commands. All of them need operator level 2 by default.

Command What it does
/worlddata redirect Shows ON or OFF, the configured default, and how many reads were served from WDC and how many fell back to vanilla, split into getBlockState and getFluidState.
/worlddata redirect on Turns the redirect on for this run. The counters start again and the totals of the last run are printed.
/worlddata redirect off Turns it off right away. Vanilla answers every read again.
/worlddata redirect reset Clears the counters without changing ON or OFF.

The F3 screen shows WDC Redirect: ON served=... fallback=.... The counters are read counts, not time saved. To judge the redirect, run /worlddata session start with it off and again with it on, in the same place and doing the same thing, and use Spark for a per-mod breakdown.

What players should not expect

  • A higher TPS or FPS from installing WorldData Core by itself. Nothing gets faster until a mod uses its API or you turn the redirect on.
  • A cure for lag from pipes, machines, entities, redstone, chunk generation or other heavy mods. WDC does not touch them.
  • A big change from the redirect. It can improve some block and fluid reads, and many mods read blocks in ways it does not see.
  • Anything visible. It adds no blocks, items, mobs, world generation, weather or shaders. The only visible parts are F3 lines, commands and a debug overlay.
  • Memory to be free. WDC keeps its own copy of loaded chunk data, so it uses some RAM on top of Minecraft's.
  • A repair tool. It does not load, generate or fix chunks, and it never changes your world.

What mod authors should not expect

  • Exact-instant truth. Pull reads include changes Minecraft already reported this tick, but a mid-tick pull is best effort. Logic that must be exact at the same instant should read Minecraft directly.
  • Notice of every edit. Edits that bypass normal block updates, such as bulk editing tools, are not seen until markChunkDirty or markBlockDirty is called. With the redirect on, other mods can read the old block until then.
  • Data for every chunk. WDC never loads chunks. An unloaded, pending or not yet read chunk answers with a reason instead of data. A position above or below the stored height has no state (NULL_ID) and does not answer void air.
  • Air in scans. Point reads return the state at the position, including minecraft:air, minecraft:cave_air, minecraft:void_air and any other state Minecraft calls air. isPresent, block searches, counts, height maps, columns, the block index and occupancy count real blocks only.
  • Stable ids. State ids are valid for one session. Persist block ids and properties.
  • A write API. There is none. WDC cannot place, remove or change blocks.
  • The redirect to be a contract. It is an internal, experimental optimization and it is off by default. Do not depend on it, and do not assume Level.getBlockState became cheap.
  • Every thread to be served. Reads from a thread that does not own the level always go to vanilla.

Risks, delays and duplication

WDC is built to be safe, but a cache sits between a mod and the game, so these are worth knowing. Some of them are only possible in theory. They are listed so that nothing is a surprise.

  • Stale answers. Answers come from a cache. A change that WDC was not told about can be read as the old block until it is noticed. WDC re-reads chunks around players over time, and the redirect does not answer while a known change is still queued, but it cannot see an edit that bypasses normal block updates.
  • Delays. New chunks are read inside the tick budget, so a chunk can be PENDING for a few ticks after it loads. Changes made off the owning thread wait in a queue until the next drain. The push feed delivers once per tick. In those windows vanilla answers, or the API says why it has no data.
  • Duplicated data. WDC keeps its own compact copy of loaded chunk data next to Minecraft's. That costs RAM, bounded by the capacity.* limits and shown on the F3 screen. Two copies of the same data can also disagree for a short time, as described under stale answers.
  • Duplicated work. If a mod keeps scanning chunks itself and also calls WDC, the work is done twice. WDC cannot stop a mod from doing that.
  • Duplicating items or blocks. Not possible through WDC. It is read-only and never touches inventories, entities, block entities or world saves. The only way an old block could be used is a mod that acts on a stale answer, which is one reason the redirect is off by default.
  • Double counting. Redirect counters count reads, not unique blocks. The same position read a thousand times counts a thousand times.
  • Redirect overhead. A fallback costs a little more than vanilla alone, and a served read is not always faster. If your pack reads blocks mostly through other paths you may see no change, or a very small slowdown.
  • Mod conflicts. The redirect and the block change hook are mixins. Another mod that rewrites the same methods can fail at launch or give inconsistent results. Remove one of the two mods.
  • Wrong side or wrong thread. On a client connected to a remote server, WDC knows only the chunks the server has sent. Reads from threads that do not own the level are never redirected.
  • Disk. Chunk data that leaves memory is written under config/worlddata_core/. It is a cache that WDC can rebuild from the loaded world.
  • Crashes and restarts. The cache lives in memory. After a crash or restart it is rebuilt from the loaded world, and anything not yet written is lost without affecting the world.
  • Exact decisions. Do not use cached data to decide permissions, prices or anything else that must be exact.

Diagnostics

API usage monitor. /worlddata monitor on records which mods call the WDC API, which calls they make and how often, and flags callers that repeat the same request and could cache it. It is off until an operator turns it on and costs one flag check per call while off.

Test sessions. /worlddata session start 300 records five minutes of server tick time (minimum, average, maximum, ticks over 50 ms), the redirect counts for that window, and the mods that called the API. When the time is up WDC writes a plain text report to config/worlddata_core/sessions/. Run one session with the redirect off and one with it on to compare them. Test sessions can be disabled in the configuration for production servers.

Requirements and compatibility

   
Minecraft 1.21.1
Fabric Fabric Loader 0.19.2 or newer, Fabric API
NeoForge 21.1.x
Java 21
Side Client, dedicated server, or both

WDC reads data Minecraft knows, so blocks, fluids and biomes from other mods need no special support. It is written to cope with mods that replace Minecraft's chunk palette storage, such as Lithium. The optional redirect uses a mixin on Level; if another mod conflicts with it at launch, remove one of the two mods.

Frequently asked questions

Do I need to install it? Only if another mod lists WorldData Core as a dependency. It does nothing visible on its own.

Will it slow down my game or server? WDC runs inside a fixed tick budget (10% of the remaining tick, 4 ms when late, never more than 16 ms) and its memory is capped. The F3 screen and /worlddata performance show what it uses.

Does it change or load chunks? No. It is read-only. If Minecraft does not hold a chunk, WDC reports UNAVAILABLE instead of loading it.

Does it work with modded blocks and fluids? Yes. Anything Minecraft's registries know about is handled through its registry id and tags.

Does it work in singleplayer, on a LAN host and on a dedicated server? Yes. A client on a remote server reads the chunks the server sent it.

Will it improve my TPS? Not by itself. Installing it only helps once mods use its API. The optional redirect can improve some block and fluid reads and the gain is small. See Performance expectations.

Is the redirect safe to enable? It is experimental and off by default. It answers only when the chunk is LIVE, nothing is waiting in the queue and the position is inside the stored range. In every other case vanilla answers. /worlddata redirect off turns it off immediately. See Risks, delays and duplication.

Can it duplicate items or blocks? No. It is read-only and never touches inventories, entities, block entities or saves. Where are its files? Configuration is in config/worlddata_core/worlddata_core.json. Spilled chunk data, monitor reports and session reports are in folders next to it.

What WorldData Core does not do

  • It does not load or generate chunks.
  • It does not change the world.
  • It does not render anything beyond its F3 lines and debug overlay: no fog, clouds, weather visuals, particles or shaders.
  • It does not simulate weather, temperature, humidity or wind. It exposes raw Minecraft values.
  • It does not track entities or block entities.

Test Results

WorldData Core — API Speed vs Vanilla

Source: WorldData Core Test mod harness (2026-11-16)
Settings: 100,000 ops · 3.0 ms time budget per server tick · 64 thrash workers · seed 333


Time to finish 100,000 ops

Arm Time Approx ops/s
WorldData Core 17.9 s ~5,600
Minecraft 202.0 s ~495

Core finished the same op count about 11× sooner.


API speed (p50 / p99)

Vanilla column = closest harness call (not always an identical operation).

Point reads

WorldData Core API ≈ Vanilla Core p50 Core p99 Vanilla p50 Vanilla p99
stateIdAt Level.getBlockState 200 ns 1.6 µs 928 ns 3.5 µs
blockAt Level.getBlockState 304 ns 2.2 µs 928 ns 3.5 µs
waterAt getBlockState + fluid 400 ns 7.4 µs 1.3 µs 5.9 µs
isSubmerged getBlockState + fluid 400 ns 9.7 µs 1.3 µs 5.9 µs
matchesAt getBlockState + tags 304 ns 2.9 µs 2.7 µs 17.4 µs
materialAt getBlockState + tags 304 ns 4.4 µs 2.7 µs 17.4 µs
hasBlock getBlockState + tags 1.3 µs 10.8 µs 2.7 µs 17.4 µs
isPresent — 400 ns 3.5 µs — —
biome Level.getBiome 100 ns 1.2 µs 5.4 µs 19.5 µs
heightmap().topY Level.getHeight 608 ns 17.4 µs 672 ns 4.4 µs
column() height ×2 + surface 800 ns 9.7 µs 2.0 µs 8.7 µs
occupancy() hasOnlyAir 496 ns 9.7 µs 800 ns 6.9 µs
requests().chunk(load=false) Level.hasChunk 200 ns 10.8 µs 608 ns 3.7 µs
requests().peek — 400 ns 8.7 µs — —
requests().availability — 800 ns 19.5 µs — —

Scans / spatial

WorldData Core API ≈ Vanilla Core p50 Core p99 Vanilla p50 Vanilla p99
countBlocks chunk getBlockState scan 2.7 µs 14.8 µs 1.51 ms 3.01 ms
visitBlocks chunk getBlockState scan 15.9 µs 38.9 µs 1.51 ms 3.01 ms
findBlocks chunk getBlockState scan 29.7 µs 344 µs 1.51 ms 3.01 ms
spatial().summarizeBox box scan 8.7 µs 63.5 µs 21.5 µs 110.6 µs
spatial().summarizeSphere window scan 9.7 µs 69.6 µs 139.3 µs 278.5 µs
spatial().visitBox box scan 5.4 µs 69.6 µs 21.5 µs 110.6 µs
spatial().visitSphere — 5.4 µs 69.6 µs — —
spatial().visitColumn column scan 2.4 µs 21.5 µs 2.9 µs 17.4 µs
spatial().sampleGrid grid height scan 9.7 µs 77.8 µs 5.9 µs 29.7 µs

Filter helpers (Core)

WorldData Core API Core p50 Core p99
hasBlockByTag 3.2 µs 25.6 µs
hasBlockByName 3.7 µs 19.5 µs
hasBlockByStateId 7.4 µs 47.1 µs
countBlocksByTag 4.4 µs 43.0 µs
countBlocksByName 4.4 µs 25.6 µs
countBlocksByStateId 13.8 µs 69.6 µs
findBlocksByTag 14.8 µs 623 µs
findBlocksByName 14.8 µs 377 µs
findBlocksByStateId 21.5 µs 410 µs
blocks().stateIdsOfTag 2.4 µs 623 µs
blocks().stateIdsOfBlock 2.9 µs 13.8 µs
world().snapshot 2.0 µs 15.9 µs

Note

These speed figures were measured with WorldData Core Test, a separate test mod built only to benchmark WorldData Core APIs. That test mod is not included in this release yet — it will be published after a little more polish.

Source

https://github.com/RohitVoxel/WorldData-Core

Report Issues here

https://github.com/RohitVoxel/WorldData-Core/issues

Example mod

https://github.com/RohitVoxel/WorldData-Core-Facade

License

The public API (net.wdc.core.api) is licensed under MIT. Everything else is licensed under LGPL-3.0-or-later.

WorldData Core Team

profile avatar
  • 2
    Projects
  • 301
    Downloads

More from Rohit_1597