Configuration File

Lithium makes use of the Java properties format for its configuration file. If the configuration file does not exist during game start-up, a blank file with a comment to this page will be created.

This configuration file defines overrides for options in Lithium, and as such, a blank file is perfectly normal! It simply means that you'd like to use all the default values.

Each category below includes a list of options which can be changed by the user. Due to the nature of the mod, configuration options require a game restart to take effect.

Editing the configuration file

All configuration options in Lithium are simple key-value pairs. In other words, you first specify the option's name, followed by the desired value, like so:

mixin.ai.pathing=false
mixin.gen.biome_noise_cache=false

The remarks after the # are comments and exist for your own book-keeping. As such, you don't need to include them, but you might want to include a note as to why you're modifying a default value.

Configuration options

Entity AI

mixin.ai.goal

(boolean, default: true)

If true, a faster implementation of the goal selector for entity AI will be used. This will generally provide a decent improvement to server tick rates in nearly all cases and is generally safe to enable.

mixin.ai.nearby_entity_tracking

(boolean, default: true)

If true, a number of AI goals which query for nearby entities in the world every tick will be changed to use an event-based system for tracking nearby entities. In other words, instead of entities constantly polling to see if other entities are nearby, they will instead be notified only occasionally when such an entity enters their range. This significantly reduces the amount of CPU overhead added by these goals and should be safe to enable.

mixin.ai.pathing

(boolean, default: true)

If true, a faster code path will be used for determining what kind of path-finding node type is associated with a given block. Additionally, a faster chunk cache will be used for accessing blocks while evaluating paths.

mixin.ai.poi

(boolean, default: true)

If true, a secondary lookup table will be used for points of interests used by Villagers and other complex mob AIs. When one of these entities goes to lookup nearby points of interests, they will then be able to scan all points in a chunk in one operation rather than needing to scan each sub-chunk individually. This can greatly reduce the amount of overhead incurred by these tasks.

mixin.ai.raid

(boolean, default: true)

If true, raid logic will be optimized to avoid expensive logic and network updates, which might help with certain raid farms.

mixin.ai.task

(boolean, default: true)

If true, the complex AI brain system used by Villagers and some other entities will be optimized through replacing the streams-based code with more traditional iteration. This can reduce a huge amount of CPU and memory allocation overhead, speeding up the game when entities using this system are present in the world.

Shapes

Optimizations for collision detection and resolution.

mixin.specialized_shapes

(boolean, default: true)

If true, specialized implementations will be used for certain classes of shapes (such as full block or empty shapes) in collision detection and resolution. This can greatly reduce the overhead involved in testing entities for collision detection against blocks in the world, as most block interactions will involve simple shapes.

mixin.shapes.blockstate_cache

(boolean, default: true)

If true, the property cache attached to every block state will be extended to contain additional properties which are commonly used in checking whether or not a given block can support another Redstone component. This can provide a small speed up when many Redstone block updates are occurring.

mixin.shapes.precompute_shape_arrays

(boolean, default: true)

If true, vertex arrays for some shape types will be cached in order to prevent unnecessary allocations.

mixin.shape_merging

(boolean, default: true)

If true, an optimized algorithm will be used for merging and comparing block shapes. This can greatly speed up many common operations in the game.

use_fast_world_border_checks

(boolean, default: true)

If true, the algorithm for checking whether or not an entity is within the world border will be replaced with a much faster axis-aligned bounding box check. Even if the world border has not been changed or entities are not near it, this patch will improve performance.

Entities and Mobs

Optimizations for entity ticking.

mixin.entity.data_tracker.use_arrays

(boolean, default: true)

If true, an optimized map implementation will be used for entity data tracking which avoids integer boxing and a map lookup by using a simple array.

mixin.entity.data_tracker.no_locks

(boolean, default: true)

If true, unnecessary locking code will be removed from the data tracker used for entities. This code used to have a purpose in older versions of the game, but has since become irrelevant. This could, however unlikely, cause issues if mods are installed which try to access the data tracker on the wrong thread.

mixin.entity.block_cache

(boolean, default: true)

If true, living entities will cache which block is at their feet to improve performance in situations where it is repeatedly checked, such as when entities are heavily crowded and colliding with many blocks.

mixin.entity.collisions

(boolean, default: true)

If true, a number of optimizations will be applied to entity collision detection and resolution in order to speed up some common operations. This can greatly reduce the amount of time entity ticking takes in a server.

mixin.entity.stream_entity_collisions_lazily

(boolean, default: true)

If true, blocks will be scanned first instead of entities when determining which shapes an entity is colliding against. This provides a small speed-up as most entities will almost always be colliding with a block before another entity, allowing the expensive entity retrieval to be skipped.

World Generation

Optimizations for world generation and population.

mixin.fast_noise_interpolation

(boolean, default: true)

If true, the chunk generator will be optimized to avoid sampling noise levels for interpolation in y-coordinates where the value range produces a constant value. This can greatly speed up world generation in the Overworld through eliminating many unnecessary and expensive samples.

mixin.gen.biome_noise_cache

(boolean, default: true)

If true, an optimized cache will be used for storing noise data used in biome sampling. This can greatly reduce the amount of time spent generating or searching for biomes.

mixin.gen.chunk_region

(boolean, default: true)

If true, an optimized chunk cache will be used for world population features which avoids array indirection and complex logic.

mixin.gen.fast_layer_sampling

(boolean, default: true)

If true, biome layer sampling will optimized to avoid sampling adjacent locations or layers unless absolutely necessary.

mixin.gen.voronoi_biomes

(boolean, default: true)

If true, voronoi sampling for biomes will be optimized to avoid object allocations and to use cheaper bit-banging instead of the expensive modulo operations. This can greatly improve the speed at which topical biomes are calculated.

mixin.gen.fast_multi_source_biomes

(boolean, default: true)

If true, a number of optimizations will be applied to world generation layers which sample from multiple biome layers. Primarily, this involves eliminating stream-heavy code. This can greatly speed up world generation in dimensions like the Nether.

Chunk

Optimizations for chunks and block data containers.

mixin.chunk.palette

(boolean, default: true)

If true, the vanilla hash palette (which maps a small range of integers from chunk data into blocks) will be replaced with an optimized variant.

mixin.chunk.serialization

(boolean, default: true)

If true, an optimized method for compacting a chunk's palette upon serialization will be used. This is greatly faster the vanilla implementation and should be safe to use, providing a boost when the server is saving many chunks.

mixin.chunk.no_locking

(boolean, default: false)

⚠️ This option is experimental and only intended for profiling.

If true, checks which see if a chunk is being concurrently modified will be removed. This may slightly improve performance in some situations, but comes with the dangerous side effect that these kinds of threading issues will not be detected and could go on to create serious problems. This option does not make it valid to access chunks from multiple threads, and if the vanilla game or another mod attempts to do so, it will create problems.

Disabled by default until further testing in vanilla is performed and alternatives are looked into.

World

mixin.world.tick_scheduler

(boolean, default: true)

If true, the tick scheduler will be replaced with an optimized variant which allows for significantly reduced CPU usage with many scheduled ticks and much faster checking of in-progress ticks. In real world terms, this means that the tick settling which occurs right after generating chunks will take much less time, and redstone ticking will be slightly faster. Additionally, scheduled ticks will be stored in a secondary index which allows chunk saving to quickly grab ticks within a region instead of needing to iterate over all scheduled ticks in the world.

mixin.world.chunk_access

(boolean, default: true)

If true, the server's chunk manager will have patches applied to it in order to reduce the amount of time it takes to fetch a chunk from the world. This will greatly speed up many operations in the game that need to read or modify blocks in the world, whether the chunk is in the cache or not.

mixin.world.chunk_inline_block_access

(boolean, default: true)

If true, accessing blocks through a chunk will be optimized to reduce the instruction count. This can provide a modest speed-up when accessing blocks in the world.

mixin.chunk_task_system

(boolean, default: true)

If true, an optimized task submission system will be used for scheduling jobs pertaining to chunks. This can provide a massive speed-up when many light updates or block updates are being scheduled.

mixin.chunk_tickets

(boolean, default: true)

If true, an optimized algorithm for removing obsolete chunk tickets will be used during world ticking.

mixin.chunk_ticking

(boolean, default: true)

If true, scanning for players in nearby chunks during mob spawning ticks will be optimized to remove stream-heavy code.

mixin.explosions

(boolean, default: true)

If true, explosions (which includes TNT) will be patched to reduce their impact on server tick rates. This patch does a number of things to achieve these gains:

• The set responsible for de-duplicating the collection of touched block positions (HashSet<BlockPos>) is replaced with a long integer set. Using integer encoding for the block positions provides a massive speedup and prevents us from needing to allocate a block position for every step we make along each ray, eliminating essentially all the memory allocations of this function.
• While stepping along a cast ray, we check to see whether or not we are still in the same block and re-use the result from the previous step to determine how much resistance will be applied.
• Chunks are cached locally and the block and fluid lookup steps are combined to reduce data retrieval overhead.

mixin.mob_spawning

(boolean, default: true)

If true, optimized collection types will be used for mob spawning lists in order to speed up comparison operations that are performed very frequently every tick.

mixin.math.fast_util

(boolean, default: true)

If true, some math utility classes will be patched with various optimizations in order to reduce the general overhead in operations such as switching/rotating axis's or shifting block positions. This does not make any optimizations to trigonometric functions or the like of them!

Blocks

mixin.block.flatten_states

(boolean, default: true)

If true, block states will be extended to store their contained fluid in order to speed up many fluid-checking operations.

mixin.block.piston_shapes

(boolean, default: true)

If true, pistons will be modified to cache their various block shapes for all extended and rotated positions. This can greatly reduce their overhead during block updates through eliminating repeated shape merging operations.

Other

General optimizations which apply to some miscellaneous sections of the game.

mixin.collections.entity_filtering

(boolean, default: true)

If true, the expensive check to see if a TypeFilterableList can be filtered by a specific class will only be made when a new list for that type needs to be created.

mixin.alloc.chunk_random

(boolean, default: true)

If true, random block ticking will be optimized to no longer use block position allocations, thereby reducing the object allocation rate.

mixin.alloc.enum_values

(boolean, default: true)

If true, a number of locations in the game will be patched to not call Enum#values() in hot code. Each one of these calls would othewrise clone the backing array in order to protect against writers, which in turn would create large allocations that slow the game down.

mixin.tag

(boolean, default: true)

If true, a specialized implementation which uses linear array scanning will be used for tags with very few elements, speeding up some checks.