Config

The config is divided into five sections: general, advanced, cache, obfuscation, and proximity. Each will be explained in detail below. The current config version is 5 and should only be changed if you have a specific reason to do so.

general

name	description	default value
checkForUpdates	Check for updates on server startup and whenever a player with the orebfuscator.admin permission joins	true
updateOnBlockDamage	Treat block damage (when a player is digging/breaking a block) as a block update	true
bypassNotification	Notify players when they are bypassing obfuscation	true
ignoreSpectator	Prevent spectators from revealing proximity-obfuscated blocks if they get too close. Useful if all players have spectator access.	false
updateRadius	Radius of neighboring blocks to deobfuscate once a block is updated (broken, exploded, burned, etc.)	2

advanced

❗ Since version 5.2.2 — contains advanced settings for tuning performance and how system resources are used. Proceed with caution.

name	description	default value
verbose	Enable more verbose logging for diagnostic purposes	false

obfuscation

The obfuscation subsection controls how chunk obfuscation work is scheduled and limited. You can change how many worker threads are used, set a per-chunk timeout (in ms) to abort slow obfuscations, and cap how many milliseconds per server tick the obfuscation dispatcher may consume.

name	description	default value
threads	Number of threads used for obfuscation. -1 means use the full processor count.	-1
timeout	Chunk obfuscation timeout in milliseconds; obfuscation of a chunk is cancelled if this is exceeded.	10000
maxMillisecondsPerTick	Maximum milliseconds per server tick that the obfuscation dispatcher may use (see FAQ).	10

proximity

The proximity subsection controls how proximity deobfuscation (player-centric updates) is distributed across threads and how often players are checked. It includes thread count, bucket sizing to group players per thread, and polling intervals used to decide when players need updates.

name	description	default value
threads	Number of threads used for proximity deobfuscation. -1 means use {processor count} / 2.	-1
defaultBucketSize	Target number of players handled by a single proximity thread (used to balance load).	50
threadCheckInterval	How often (in ms) a proximity thread checks whether its players need updates due to position/rotation changes.	50
playerCheckInterval	How often (in ms) each player receives a proximity update regardless of movement/rotation changes.	5000

cache

The cache stores already obfuscated chunks to improve performance. It has two levels:

1. Memory cache (level one) — fast, in-memory storage with size and time limits.
2. Disk cache (level two) — slower but persistent storage for chunks evicted from memory.

When a chunk is requested, the system first checks the memory cache, then the disk cache, and finally obfuscates the chunk if it is not found in either. Newly obfuscated chunks are then stored in the memory cache.

name	description	default value
enabled	Whether the cache should be used	true

memoryCache

The memory cache is the first-level cache. It provides the fastest access speed but is limited by a maximum size and expiration time. A chunk will be evicted if it exceeds the expiration time or if the cache is full, in which case the least recently accessed chunk is removed.

name	description	default value
maximumSize	Maximum number of chunks in memory cache	32768
expireAfterAccess	Time (in ms) before a chunk in memory expires	60000 (60s in ms)

diskCache

The disk cache is the second-level cache. It stores chunks evicted from memory so they can be reused without re-obfuscation. While slower than memory, it persists between requests. Region files may stay open (up to maximumOpenFiles) to avoid repeatedly reading headers, but the actual files on disk are deleted if they haven’t been accessed within the configured deleteFilesAfterAccess time.

name	description	default value
enabled	Whether the disk (level two) cache should be used	true
directory	Directory where the cache is saved after being flushed from memory. Path is relative to your worlds directory	'orebfuscator_cache/'
maximumOpenFiles	Maximum number of region files (file descriptors) that may remain open at the same time to avoid re-reading headers	256
deleteFilesAfterAccess	Minimum time (in ms) after a region file on disk was last accessed before it is deleted	172800000‬ (2d in ms)
maximumTaskQueueSize	Maximum number of concurrently queued disk cache tasks	32768

obfuscation config section

This section contains arbitrarily named obfuscation config sections (e.g. obfuscation-overworld, obfuscation-nether, etc.). Each section can be assigned to multiple worlds, but a world may only have one obfuscation config at a time. An obfuscation section defines which blocks should be obfuscated, which replacement materials (via randomBlocks sections) can be used, and which worlds to apply the configuration to.

name	description	default value
enabled	Enable or disable this obfuscation config	true
minY	Lowest block height to obfuscate	-2032 (technical possible minimum)
maxY	Highest block height to obfuscate	2031 (technical possible maximum)
worlds	List of world matchers to apply this config to
layerObfuscation	When enabled, uses one replacement block type per Y layer per chunk (see FAQ)	false
hiddenBlocks	Set of blocks or block tags to obfuscate
randomBlocks	List of randomBlocks sections used to replace obfuscated blocks

world matchers

❗ Since version 5.2.0 (before this would have been a list of plain world names)

Worlds can be matched in multiple ways:

type	description	example
plain	Matches a single world by exact name	world_the_end
simple glob	Matches multiple worlds using a glob pattern. Currently only * wildcards are supported.	world*end
regex pattern	Matches multiple worlds using a regular expression. Must be defined as regex(<pattern>).	regex(world.+end)

block and block tags

❗ Since version 5.5.5 both individual blocks and block tags are supported in all config sections.

A block is specified by its block resource location, e.g. minecraft:stone or minecraft:chest.

A block tag is also a resource location, but it refers to a set of blocks defined by Minecraft or datapacks. Tags let you include multiple blocks at once without listing each individually. Tags must be written in the form: tag(<tag-resource-location>).

For example tag(minecraft:anvil) will expand to all anvil variants:

• minecraft:anvil
• minecraft:chipped_anvil
• minecraft:damaged_anvil

Using block tags makes it easier to configure Orebfuscator consistently without needing to keep track of every variant of a block.

randomBlocks section

The randomBlocks sections can be arbitrarily named (e.g. section-global, section-stone, etc.). Each consists of a height limit and a list of weighted entries.

The entries can be either:

• blocks (e.g. minecraft:stone)
• block tags (e.g. tag(minecraft:anvil))

When a block tag is used, its given weight will be shared equally among all blocks inside the tag. For example tag(minecraft:anvil) expands to three blocks (anvil, chipped_anvil, damaged_anvil), each will receive weight (15 / 3) = 5 if the whole tag had a weight of 15. This prevents tags from being disproportionately more likely to appear compared to single blocks.

Blocks and tags can be mixed in the same section. If the same block appears multiple times (directly or via multiple tags), all weights for that block are added together. For example:

minecraft:damaged_anvil: 2
tag(minecraft:anvil): 15

results in the block minecraft:damaged_anvil having total weight 7 (2 direct + (15 / 3) = 5 from tag).

The height limit can be used to fill certain parts of a world with different replacement materials based on their Y level (e.g. using deepslate ores below y=0). The resulting weighted set is used to randomly select replacement blocks. If multiple sections target the same height range, they are merged.

randomBlocks:
  section-air:
    minY: -2032
    maxY: 2031
    blocks:
      minecraft:cave_air: 5
  section-anvil:
    minY: 5
    maxY: 2031
    blocks:
      tag(minecraft:anvil): 15
  section-stone:
    minY: -5
    maxY: 2031
    blocks:
      minecraft:stone: 15
  section-deepslate:
    minY: -2032
    maxY: 5
    blocks:
      minecraft:deepslate: 15

This example would create three different sections internally:

• section 1:
  • from y=-2032 to y=-5
  • blocks: cave_air=5(25%), deepslate=15(75%)
• section 2:
  • from y=-5 to y=5
  • blocks: cave_air=5(~14.3%), deepslate=15(~42.9%), stone=15(~42.9%)
• section 3:
  • from y=5 to y=2031
  • blocks: cave_air=5(~14.3%), stone=15(~42.9%), anvil=5(~14.3%), chipped_anvil=5(~14.3%), damaged_anvil=5(~14.3%)

Section 1 for example will only get used as replacement material for blocks between y -2032 and -5. The total weight of the section is 20 = 5(cave_air) + 15(deepslate) which results in cave_air having a 25% (5 / 20) chance to get selected and deepslate having a 75% (15 / 20) chance.

proximity config section

This section contains arbitrarily named proximity config sections (e.g. proximity-overworld, proximity-nether, etc.). Each section can be assigned to multiple worlds, but a world may only have one proximity config at a time. A proximity config defines which blocks should be proximity-hidden, which replacement materials should be used (via randomBlocks sections), which worlds it applies to, the visibility distance, and any additional checks such as frustum culling or ray casting.

❗ Since version 5.2.2 the useBlockBelow mode replaces hidden blocks with the next valid block found below them. This makes hidden blocks blend in more naturally with the environment.

name	description	default value
enabled	Enable or disable this proximity config	true
minY	Lowest Y level to proximity-hide blocks	-2032 (technical possible minimum)
maxY	Highest Y level to proximity-hide blocks	2031 (technical possible maximum)
worlds	List of world matchers to apply this config to
distance	Maximum distance from a player at which a hidden block will be deobfuscated	24
frustumCulling	See What is frustum culling?
↳ enabled	Enable or disable frustum culling	true
↳ minDistance	Minimum distance at which frustum culling applies (closer blocks ignore it)	3
↳ fov	Camera FOV used for the view frustum	80
rayCastCheck	See What is ray cast checking?
↳ enabled	Enable or disable ray cast checking (will impact performance)	false
↳ onlyCheckCenter	Check only the block center (faster but less accurate)	false
useBlockBelow	Enable the “use block below” replacement mode	true
hiddenBlocks	Set of blocks or block tags to hide
randomBlocks	List of randomBlocks sections to replace proximity-hidden blocks

proximity block options

Each block type can override default constraints such as the Y range or whether useBlockBelow applies.

name	description	default value
minY	Lowest Y level to proximity-hide this block	-2032 (technical possible minimum)
maxY	Highest Y level to proximity-hide this block	2031 (technical possible maximum)
useBlockBelow	Enable the useBlockBelow replacement mode for this block	true

Example:

hiddenBlocks:
  chest: {}
  trapped_chest: {
    minY: 64
    maxY: 2031
  }

In this example, chest is always hidden (default Y range), while trapped_chest is only hidden above Y=64.