Configuration

General Notes

• Distances are measured in blocks unless a setting says otherwise.
• Minecraft normally runs at 20 ticks per second, so a one tick interval is approximately 50 milliseconds or 0.05 seconds.

Shared Configurations

The following configuration options are shared across multiple checks. The word "entity" is used as a catch-all for players, normal entities, and tile entities in this section.

1. Targets within the relevant always-show-radius are shown without a raycast.
2. Targets beyond raycast-radius are treated as hidden.
3. Targets between those distances are checked using raycasting.
4. A target becomes hidden once the ray passes through the configured number of occluding blocks.

max-occluding-count: 3

• max-occluding-count: 1 hides a target behind one blocking block.
• max-occluding-count: 3 allows two blocking blocks, then hides the target at the third.
• max-occluding-count: 0 effectively hides any target that is outside the always-visible radius and requires a raycast.

It can take up to {the player's ping in ms} + 100ms for a player to be shown an entity once they are supposed to be able to, so max-occluding-count provides a buffer, showing entities pre-emptively shortly before the player would actually be able to see the entity. Lower values hide players more aggressively. Higher values reveal entities earlier as they approach corners, gaps, and thin walls. This buffer helps offset network delay and the time needed to process visibility changes.

Valid values range from 0 through 127. Invalid values produce a warning and fall back to 3.

Very high values substantially weaken RaycastedAntiESP's efficacy.

always-show-radius: 8

Always shows players entities the configured distance, without checking line of sight.

The default radius of 8 blocks helps prevent close-range combat problems. Nearby entities remain visible even when a wall edge, partial block, network delay, or raycasting approximation would otherwise hide them.

Invalid values fall back to 8.

Raising this value reduces visual weirdness but weakens RaycastedAntiESP's efficacy.

raycast-radius: {128/92/64} - Defaults correspond to players, entities, and tile entities respectively.

Sets the farthest distance at which the plugin performs raycasts.

Entities beyond this distance are treated as hidden. Skipping the raycast does not make them visible.

The default values match Minecraft’s normal entity-tracking range. Raising it will have no effect unless the server also tracks and sends entities over a greater distance.

Lowering it reduces raycast work, but it also delays the point at which distant entities may become visible.

hide-on-spawn-distance: 24

Controls how the plugin handles newly spawned or newly tracked players before the visibility engine has produced a result.

When an entity spawns at or beyond this distance, the plugin withholds the spawn packet until it confirms visibility. This prevents players with a cheat client from ever learning about the entity. Only entities beyond a certain point are hidden on spawn since it can take up to {the player's ping in ms} + 100ms for an entity which was hidden on spawn but supposed to be visible to be made visible, so close entities need to be immediately shown to the player. Since entities typically spawn beyond 24 blocks from a player and tile entities are usually sent to players all the way at the edge of their view distance, this is unlikely to cause issues.

visible-recheck-interval-ticks: {5/-1} - Defaults to 5 for players and entities, -1 for tile entities.

Sets how often the plugin checks an already visible entity again.

Hidden entities are always checked every tick so they can become visible as soon as possible. This setting controls the opposite transition: whether a visible entity may become hidden after moving behind cover.

The default value of 5 checks visible entities about four times per second.

Larger values reduce processing work and visual flickering due to entities which alternate between being visible and hidden, but visible entities remain exposed for longer after moving out of sight.

A value of -1 disables visible rechecks. Once any mechanism has revealed an entity to a viewer, that entity remains visible to that viewer. This reduces the utility of RaycastedAntiESP for players and entities since they are able to move, but tile entities default to a visible-recheck-interval-ticks of -1 since once you've seen a tile entity once, you know it is there and there is limited point in hiding it again.

keep-client-entity-when-hidden: false - Does not apply to tile entities.

Controls whether a hidden entity remains registered as an entity on the client.

When set to false, the plugin removes the client-side entity while it is hidden.

When set to true, the client retains the entity but if the entity has been marked as hidden, future packets for that entity will be intercepted. This will cause the entity to appear as a "ghost", with its position not updated. As this only occurs when the player can't see the entity, it shouldn't cause many issues.

This reduces bandwidth used by RaycastedAntiESP.

Config Version

config-version: '2.0'

Marks the schema version of the configuration file.

This value exists for configuration compatibility and migration. It should never be changed by hand.

Checks

Player Checks

checks:
    player:
        enabled: true
        hide-sounds-when-hidden: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 128
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: 5
        keep-client-entity-when-hidden: false
        only-check-sneaking: false

The checks.player section controls whether other players are hidden when the viewer lacks line of sight.

enabled

Enables player anti-ESP checks.

When enabled, the plugin can withhold hidden players and their related packets from a viewer. When disabled, players remain visible through normal server packet handling.

hide-sounds-when-hidden

Suppresses sounds associated with a player while that player is hidden.

This is not yet implemented.

only-check-sneaking: false

Limits player concealment to players who are sneaking.

When enabled, non-sneaking players bypass player anti-esp checks. This matches vanilla, where you can see player name-tags behind walls if they are not sneaking.

Note that sneaking state is determined by whether the player is pressing their sneak key (usually shift), not whether they are visually crouching. This means that standing under a slab does not count as sneaking, but pressing shift while underwater or midair does. This is the same way Minecraft defines player name-tag visibility.

Entity Checks

checks:
    entity:
        enabled: true
        hide-sounds-when-hidden: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 92
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: 5
        keep-client-entity-when-hidden: false
        excluded-types:
            - minecraft:arrow
            - minecraft:spectral_arrow
            - minecraft:fireball
            - minecraft:dragon_fireball
            - minecraft:small_fireball
            - minecraft:firework_rocket
            - minecraft:wither_skull
            - minecraft:breeze_wind_charge
            - minecraft:wind_charge
            - minecraft:ender_pearl
            - minecraft:evoker_fangs
            - minecraft:shulker_bullet
            - minecraft:area_effect_cloud
            - minecraft:lingering_potion
            - minecraft:splash_potion
            - minecraft:potion
            - minecraft:lightning_bolt
            - minecraft:ender_dragon
            - minecraft:wither
            - minecraft:warden
            - minecraft:block_display
            - minecraft:text_display
            - minecraft:item_display
            - minecraft:interaction
            - minecraft:mannequin

The checks.entity section controls anti-ESP checks for non-player entities.

enabled: true

Enables concealment for non-player entities.

When disabled, ordinary entities bypass the entity visibility system.

hide-sounds-when-hidden

Suppresses sounds caused by entities while the source entity is hidden.

This stops a viewer from locating a concealed mob or other entity through sounds attached to that entity. General positional sound filtering remains controlled by checks.sound-effects.

This is not yet implemented.

excluded-types

Lists entity types that bypass anti-ESP checks and remain visible.

Entries use optionally-namespaced Minecraft entity identifiers. These are the same identifiers accepted by /summon.

For example:

excluded-types:
    - minecraft:falling_block
    - minecraft:armor_stand

The shipped list exempts several kinds of entities:

• Fast projectiles, because delayed visibility may leave too little time to react.
• Potions and area-effect clouds, because they can harm players even when their source is hidden.
• Lightning, because it is brief and is normally expected to be visible without direct line of sight to the block being struck.
• The Ender Dragon, Wither, and Warden, because they are large so a single-point raycast does not accurately check visibility, and are dangerous boss-type mobs.
• Display, interaction, and mannequin entities often used by custom-mechanic plugins.

The former minecraft:potion entity (1.21.4) was split into minecraft:splash_potion and minecraft:lingering_potion in newer versions (1.21.5+). You should remove the identifier(s) not supported by your server version.

Add an entity type if its concealment breaks gameplay or another plugin.

Tile Entity Checks

checks:
    tile-entity:
        enabled: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 64
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: -1

The checks.tile-entity section controls concealment of tile entities, also called block entities.

Tile entities include chests, furnaces, hoppers, beacons, signs, spawners, and other blocks that carry extra state or data.

enabled: true

Enables tile entity anti-esp checks.

When enabled, the plugin can withhold concealed block-entity information from the viewer.

Sound-effect Checks

checks:
    sound-effects:
        enabled: true
        max-occluding-count: 3
        always-play-radius: 8
        raycast-radius: 48

These configuration options are not yet implemented, and are part of a planned future check.

Chunk-section Checks

checks:
    chunk-section:
        enabled: false
        max-occluding-count: 6
        always-show-radius-chunks: 2
        visible-recheck-interval-ticks: -1

A chunk section is a 16 × 16 × 16 block part of a chunk column. This system will operate at a much coarser level than entity or tile-entity checks.

It is not yet implemented, but a WIP preview of it can be seen here.

Engine

engine:
    mode: async
    async:
        processing-threads: 1
    netty:

The engine section selects where and how the plugin performs anti-ESP processing.

mode

Supported values are:

• async
• netty - Not implemented yet. The legacy value simple is also accepted and maps to async.

async

The asynchronous engine runs visibility processing on one or more dedicated worker threads.

This is the shipped default. It moves raycast work away from the main server thread but also avoids running the full workload directly on network threads.

async.processing-threads: 1

Sets the number of worker threads used by the asynchronous engine.

The default is 1. The value must be at least 1; lower values stop configuration loading.

One processing thread is intended to be sufficient for hundreds of players under ordinary conditions. More threads do not guarantee better performance. Additional workers add scheduling and coordination costs, and the workload may not scale evenly across them.

Increase this value only after profiling shows that the asynchronous worker is saturated or that visibility work is consistently falling behind. Profiling has suggested that a single async thread may be sufficient for up to 1000 players.

netty

The netty node is currently a placeholder.

There are no user-configurable options under engine.netty at present.

Block Processor

block-processor: mode: packetevents track-all-blocks: false packetevents: tile-entity-exempted-ids: tile-entity-force-included-ids:

The block processor builds and maintains the block view used by raycasts.

mode: packetevents

Selects the block-processing implementation.

The only currently supported value is packetevents.

track-all-blocks

Controls how broadly the PacketEvents processor tracks block states.

When set to false, the processor uses the narrower tracking path intended for blocks relevant to normal anti-esp operation.

When set to true, it tracks all blocks. This permits the use of tile-entity-force-included-ids, but increases memory use and packet-processing work. It was implemented to be used for chunk-section checks, which are not yet implemented, so this should currently never be set to true.

tile-entity-force-included-ids must remain empty while this setting is false. The plugin rejects configurations that break this rule.

packetevents.tile-entity-exempted-ids

Lists numeric PacketEvents block-state IDs that should be exempted from tile-entity handling.

Use this when a tile entity must remain visible.

These values are numeric protocol or block-state IDs. They are not namespaced Minecraft identifiers, and they change between server versions.

Use the following console command to print the current server’s block-ID mapping:

/raycastedantiesp print-block-ids

The command writes a large list of block IDs and names to the console. Search the server log for the block name, then add the matching ID.

For example:

block-processor:
    packetevents:
        tile-entity-exempted-ids:
            - 9779

Do not copy IDs blindly from another Minecraft version. The same number may refer to a different block.

This was implemented to exclude beacons from anti-esp checks, as they are expected to always be visible.

packetevents.tile-entity-force-included-ids

This feature is not yet implemented, but is envisioned as an anti-xray style feature where ores can be added to the list to be checked.

Debugging

debug:
    info-level: 5
    info-exempted-classes:
    warn-level: 5
    warn-exempted-classes:
    error-level: 5
    error-exempted-classes:
    particles: false
    timings: false

The debug section controls logging thresholds and diagnostic tools.

Logging levels range from 0 through 10.

Each log sent by RaycastedAntiESP is assigned a level, with levels closer to 1 marking important messages and levels closer to 10 marking unimportant or frequently sent messages. A larger level permits more verbose messages. Lower levels suppress lower-priority diagnostic output. The shipped value of 5 is the normal operating threshold. Increasing the log level should only be done when debugging.

info-level, warn-level, and error-level

These settings control the logging threshold for each severity:

• info-level controls informational messages.
• warn-level controls warning messages.
• error-level controls error messages.

All three default to 5.

Lowering a threshold reduces output for that severity. Raising it exposes more detailed diagnostic messages.

info-exempted-classes, warn-exempted-classes, and error-exempted-classes

These lists block selected source classes from sending logs with the corresponding severity.

Entries may use a simple class name:

info-exempted-classes:
    - AsyncEngine

They may also use a fully qualified class name:

info-exempted-classes:
    - games.cubi.raycastedantiesp.core.engine.AsyncEngine

Each severity has its own exemption list. Adding a class to info-exempted-classes does not exempt its warning or error messages.

particles: false

Shows particles along raycast paths.

The raycaster can mark sampled positions and occluding blocks, which helps diagnose unexpected visibility results.

This option is intended for controlled testing and debugging. It will cause server lag if enabled.

Keep it disabled during normal operation.

timings: false

Enables collection of internal timing data.

Use this while profiling anti-esp work or comparing the cost of configuration changes.

Timing collection adds measurement overhead of approximately 5%. Keep it disabled unless the data is needed. It should be used to gather information when tweaking performance-affecting config options.

Updates

updates:
    check-release: true
    check-beta: true
    check-alpha: true
    notify-in-game: true

The updates section controls which release channels the plugin checks and where it reports available updates.

check-release: true

Checks for stable release builds.

check-beta: true

Checks for beta builds.

Disable this when the server should receive notices only for stable releases.

check-alpha: true

Checks for alpha builds.

Alpha builds are the least stable channel. Note that since v2 builds are currently all in alpha, for now this should be left enabled. Once beta or stable builds are being released, you may want to disable alpha version notifications to stay on more stable versions.

When all three channel settings are disabled, the plugin has no enabled update channel and does not perform a useful update check.

notify-in-game: true

Controls whether authorised players receive update notifications in game.

When set to true, the plugin reports updates to the console and to players with the permission raycastedantiesp.updatecheck, which is granted to server operators.

When set to false, it reports updates only to the console.

This setting does not enable update checking by itself. At least one of check-release, check-beta, or check-alpha must also be enabled.

Current Default Configuration

The following is the current default configuration.

config-version: '2.0'
checks:
    player:
        enabled: true
        hide-sounds-when-hidden: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 128
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: 5  # -1 disables visible rechecks. When set to -1, once an entity is shown by any mechanism, it will be permanently visible.
        keep-client-entity-when-hidden: false
        only-check-sneaking: false
    entity:
        enabled: true
        hide-sounds-when-hidden: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 92
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: 5 # -1 disables visible rechecks. When set to -1, once an entity is shown by any mechanism, it will be permanently visible.
        keep-client-entity-when-hidden: false
        excluded-types:
            # Projectiles move very quickly, giving limited time for the raycast engine to process them. This could cause the player not to have enough time to dodge the projectile, so they are always visible by default.
            - minecraft:arrow
            - minecraft:spectral_arrow
            - minecraft:fireball
            - minecraft:dragon_fireball
            - minecraft:small_fireball
            - minecraft:firework_rocket
            - minecraft:wither_skull
            - minecraft:breeze_wind_charge
            - minecraft:wind_charge
            - minecraft:ender_pearl
            - minecraft:evoker_fangs
            - minecraft:shulker_bullet

            # Potions and area effect clouds can damage players even if not visible. A reasonable always-show-radius mitigates these issues, so exempting these entities is not necessary.
            # If your server relies on potion pvp where knowing the exact number of potions someone else has used is an unfair advantage, you may want to un-exempt these entities.
            - minecraft:area_effect_cloud
            - minecraft:lingering_potion
            - minecraft:splash_potion
            - minecraft:potion # Note: the "potion" entity was removed in 1.21.5 and replaced with "splash_potion" and "lingering_potion". If you are on 1.21.4, you can comment out the above two entry. If you are on 1.21.5+ you should instead comment out this entry.

            # Lightning is short-lived and expected to be visible to people who cannot see the block being struck.
            - minecraft:lightning_bolt

            - minecraft:ender_dragon
            - minecraft:wither
            - minecraft:warden

            # These entities are not seen in normal gameplay, and are usually part of custom mechanics.
            # If you un-exempt these entities, it is likely that other plugins (such as hologram or NPC plugins) will break.
            - minecraft:block_display
            - minecraft:text_display
            - minecraft:item_display
            - minecraft:interaction
            - minecraft:mannequin
            # Falling blocks are often used in custom mechanics, especially by plugins made before display entities were added to the game.
            # Therefore, exempting them can make sense. However, falling blocks also occur in regular gameplay,
            # and can provide insight about players which are not visible.
            # Therefore, falling blocks are not exempted by default.
            #- minecraft:falling_block

            # You can add more excluded types using the name for the entity which would be used by the /summon <entity> command, adding "- <entity>" to the list above.
    tile-entity:
        enabled: true
        max-occluding-count: 3
        always-show-radius: 8
        raycast-radius: 64
        hide-on-spawn-distance: 24
        visible-recheck-interval-ticks: -1  # -1 disables visible rechecks. When set to -1, once an entity is shown by any mechanism, it will be permanently visible.
    sound-effects:
        enabled: true
        max-occluding-count: 3
        always-play-radius: 8
        raycast-radius: 48
    chunk-section:
        enabled: false
        max-occluding-count: 6
        always-show-radius-chunks: 2
        visible-recheck-interval-ticks: -1
engine:
    mode: async
    async:
        processing-threads: 1 # 1 thread is sufficient for hundreds of players, I do not recommend increasing this value blindly.
    netty:
block-processor:
    mode: packetevents
    track-all-blocks: false
    packetevents:
        tile-entity-exempted-ids:
            #- 9779 - Beacon ID on 1.21.11. To see what the beacon ID is for your server version, run the command "/antiesp print-block-ids". This will dump a massive list of all the block ID to block name mappings in the console. Search your logs for "beacon" (or whatever other tile entity you'd like to exempt) and add the associated ID here
        tile-entity-force-included-ids:
debug:
    info-level: 5
    info-exempted-classes:
    warn-level: 5
    warn-exempted-classes:
    error-level: 5
    error-exempted-classes:
    particles: false
    timings: false
updates:
    check-release: true
    check-beta: true
    check-alpha: true
    notify-in-game: true # When false, update checks only notify the console. When true, players with the correct permission are notified.