Atlas

Make your server more stable and faster.

Core Optimization Points

Chunk Cache and Level Index

Atlas maintains a bounded loaded-chunk index for each dimension.

Cached data includes:

• Block counts per chunk
• Block tag counts per chunk
• Block entity positions per chunk
• Optional non-air block position index

Reusable query examples:

• Whether a loaded chunk contains a specific block
• How many blocks of a specific type exist in a chunk
• Whether a chunk contains blocks matching a specific tag
• Which known block entities exist in a chunk

Atlas does not globally cache getBlockState results. This avoids stale cache problems after world state changes and reduces the risk of conflicts with other mods that modify block states.

Dirty Chunk Queue

Atlas does not rebuild chunk caches immediately in most event callbacks. Instead, affected chunks are marked as dirty and rebuilt later with a per-tick budget.

This helps reduce short spikes caused by:

• Large bursts of chunk loading
• Many block changes in the same area
• Multi-block placement events
• Fluid placing blocks
• Crop growth and tool-based block state changes

If the same chunk changes multiple times before being processed, it remains queued only once and is rebuilt once.

Bounded Memory Usage

Atlas applies explicit limits to both chunk caches and dirty queues.

Default values:

• cache.maxIndexedChunksPerLevel = 1024
• cache.maxDirtyQueueChunksPerLevel = 8192
• cache.indexNonAirPositions = false

The non-air block position index is disabled by default because modern modpacks are often memory-constrained, and storing every non-air block position can add significant extra memory usage.

Entity Query Snapshots

Atlas builds reusable server-side entity query snapshots to reduce repeated entity list scans across entities, AI, and modules.

Snapshot data includes:

• Players bucketed by chunk
• Living entities bucketed by chunk
• Living entities bucketed by entity type
• Nearest-player cache for relevant chunks
• Snapshot statistics

Supported queries include:

• Nearby player queries
• Nearby living entity queries
• Nearby entity queries by entity type
• Nearest player lookup within a range

Snapshot building is split across ticks instead of scanning all entities at once. The number of entities processed per dimension per tick is configurable.

AI Query Optimization

Atlas connects entity query snapshots to selected AI query paths.

Currently covered:

• NearestAttackableTargetGoal
• Player target lookup through the NearestAttackableTargetGoal<Player/ServerPlayer> branch
• PlayerSensor
• NearestLivingEntitySensor

These paths prefer a fresh Atlas entity snapshot when available. If no snapshot exists, the snapshot is too old, or the feature is disabled, Atlas automatically falls back to vanilla logic.

Atlas still keeps vanilla final filtering semantics:

• Target selection still passes through TargetingConditions.test
• Player Sensor filtering still passes through Sensor.isEntityTargetable
• Attackable-player filtering still passes through Sensor.isEntityAttackable
• Nearby visible entities still use vanilla NearestVisibleLivingEntities

This means Atlas mainly reduces candidate entity scanning cost. It does not loosen or change AI target validation rules.

Configuration

Cache

cache.enableLevelIndex = true
cache.maxIndexedChunksPerLevel = 1024
cache.indexNonAirPositions = false
cache.maxDirtyChunkRebuildsPerTick = 4
cache.maxDirtyQueueChunksPerLevel = 8192

Recommendations:

• Increase cache.maxDirtyChunkRebuildsPerTick if dirty chunks take too long to settle.
• Lower cache.maxIndexedChunksPerLevel if the modpack is memory-constrained.
• Keep cache.indexNonAirPositions = false unless exact non-air block positions are explicitly needed.

Entity Query Snapshots

entityQuery.enableSnapshots = true
entityQuery.snapshotIntervalTicks = 5
entityQuery.maxSnapshotEntitiesPerLevel = 8192
entityQuery.snapshotEntitiesPerTick = 1024
entityQuery.idleRetainTicks = 200

Details:

• entityQuery.snapshotIntervalTicks controls the snapshot refresh interval.
• entityQuery.maxSnapshotEntitiesPerLevel limits how many living entities can be included per dimension.
• entityQuery.snapshotEntitiesPerTick controls how many entities are processed per tick during split snapshot building.
• entityQuery.idleRetainTicks controls how long the snapshot system remains active after a one-shot query.

Recommendations:

• Lower entityQuery.snapshotIntervalTicks if AI query results need to be fresher.
• Increase entityQuery.maxSnapshotEntitiesPerLevel if the server has many mobs.
• Lower entityQuery.snapshotEntitiesPerTick if snapshot building causes tick-time spikes.

AI Query Optimization

aiQueries.enableTargetGoalQueries = true
aiQueries.enableSensorQueries = true
aiQueries.maxSnapshotAgeTicks = 10

Details:

• aiQueries.enableTargetGoalQueries controls whether NearestAttackableTargetGoal uses snapshot-backed queries.
• aiQueries.enableSensorQueries controls whether selected vanilla Sensors use snapshot-backed queries.
• aiQueries.maxSnapshotAgeTicks controls the maximum snapshot age accepted by AI mixins. Older snapshots fall back to vanilla logic.

If entity target selection behaves incorrectly, disable aiQueries.enableTargetGoalQueries first. If Brain or Sensor behavior behaves incorrectly, disable aiQueries.enableSensorQueries first.