Class NewChunksHelper

java.lang.Object
dev.boze.api.utility.NewChunksHelper

public final class NewChunksHelper extends Object
Read-only access to the chunks classified by the client's NewChunks module.

Threading: call these methods from the client thread only, for example from an EventTick handler. getAge(int, int), getDetail(int, int) and the marks passed to forEachMarked(int, int, int, NewChunksHelper.MarkedChunkConsumer) do not allocate. A radius covering more chunks than there are marks allocates a small iterator per call.

Collection: the NewChunks module must be enabled, which you can check with ModuleManager.getClientModule("NewChunks").getState(). While it is off, getAge(int, int) and getDetail(int, int) return null and forEachMarked(int, int, int, NewChunksHelper.MarkedChunkConsumer) reports nothing, the same as for a chunk that has no mark. Classification happens when the server sends a chunk, so chunks already loaded when the module is enabled stay unclassified until the server sends them again. The module's render settings have no effect on collection.

Lifetime: marks are kept in memory only and nothing is saved, so they cover what was seen since the module was enabled in the current world. Only the current world and dimension are reported. Marks are dropped when the module is disabled, by the newchunks clear command, on joining a server and on a dimension change, so returning to a dimension starts empty. Chunks that arrive during a dimension change can be lost with the old marks and stay unclassified. Within a world, marks outlive chunk unloading, and a chunk keeps its first classification.

Detection: marks are heuristics over chunk data as the server sends it, mostly block palette ordering, so NewChunksHelper.ChunkAge.NEW and NewChunksHelper.ChunkAge.OLD are likely, not certain. A server that rewrites or regenerates chunk data can change the results.

  • Overworld: NEW when the first non-empty section's palette starts with air, or when at least 51% of non-empty sections have a fresh-looking palette.
  • Nether: NEW only when the first non-empty section's palette starts with air.
  • End: NEW only when a non-empty section's biome palette starts with plains.
  • Anything else received is OLD, so OLD means "no evidence of being new". This includes chunks with only air, such as the void between End islands, which makes the End's OLD marks weak evidence of earlier visits.
  • NewChunksHelper.ChunkAge.OLD also covers NewChunksHelper.ChunkDetail.LEGACY and NewChunksHelper.ChunkDetail.UPDATING, and a chunk that looks updating is never NEW. With DetectUpdating off, nothing is reported as NewChunksHelper.ChunkDetail.UPDATING and those chunks are judged by the other rules. With a DetectLegacy setting off, that dimension reports no NewChunksHelper.ChunkDetail.LEGACY.

A received chunk stays unclassified only if its data fails to parse, or if outside the End it looks new while legacy detection also calls it legacy. The second case is most likely in the Nether, where the default DetectLegacy calls a chunk legacy when its lowest eight sections contain none of the post-1.16 blocks it looks for. Turning off the matching DetectLegacy setting makes such a chunk NEW. How often this happens depends on the terrain and has not been measured. The End requires the same biome evidence for NEW with or without its setting.

  • Method Details

    • getAge

      public static NewChunksHelper.ChunkAge getAge(int chunkX, int chunkZ)
      Gets the age of a chunk in the current world and dimension.
      Parameters:
      chunkX - The chunk X coordinate
      chunkZ - The chunk Z coordinate
      Returns:
      The age, or null if the chunk is unclassified or NewChunks is off
    • getDetail

      public static NewChunksHelper.ChunkDetail getDetail(int chunkX, int chunkZ)
      Gets the detailed classification of a chunk in the current world and dimension.
      Parameters:
      chunkX - The chunk X coordinate
      chunkZ - The chunk Z coordinate
      Returns:
      The detail, or null if the chunk is unclassified or NewChunks is off
    • forEachMarked

      public static void forEachMarked(int centerChunkX, int centerChunkZ, int radius, NewChunksHelper.MarkedChunkConsumer consumer)
      Reports every classified chunk within a square radius, in the current world and dimension.

      The order is unspecified. The scan blocks incoming chunk classification while it runs, so keep the consumer short, and do not toggle NewChunks from it.

      Parameters:
      centerChunkX - The chunk X coordinate of the center
      centerChunkZ - The chunk Z coordinate of the center
      radius - The radius in chunks, where 0 covers only the center chunk. A negative radius reports nothing
      consumer - Receives each classified chunk