Proximity Detection vs. Target Acquisition
Bedrock splits entity detection into two distinct jobs: firing an entity event when something enters a radius, and selecting an active combat or AI target. If you want a custom landmine to explode when a player walks over it, or a shy creature to curl into a shell when a monster approaches, you want an event trigger. That is the job of `minecraft:entity_sensor`.
If you want your mob to chase, look at, or attack the detected entity, a sensor alone is not enough because events do not automatically set the mob's internal attack target (unless the event filter forces a target context that an AI goal can read, which is fragile). For combat and chasing, use AI target goals alongside `minecraft:follow_range`. Many advanced mobs use both: a target goal to pick an enemy, and an entity sensor to switch combat phases when the enemy gets too close.
Using minecraft:entity_sensor
The `minecraft:entity_sensor` component scans a spherical or box-shaped volume around the entity and fires an event when its conditions are met. In modern format versions (1.20.80 and newer), this component uses a `subsensors` array, allowing a single entity to run multiple independent proximity scans with different ranges, cooldowns, and filters.
Each subsensor evaluates entities within its `range` (defined as `[horizontal, vertical]` in blocks). You can require a minimum and maximum count of matching entities before the event fires. By default, the filter evaluates against the candidate entity inside the radius (`subject: "other"`), so a check for `is_family` tests the approaching entity, not the sensor owner.
| Field | What it does | Notes |
|---|---|---|
| find_players_only | Restricts all subsensors to only scan player entities. | Boolean. Set to true whenever you only care about players; it significantly reduces server lag. |
| relative_range | Adds the entity's own collision box size to the subsensor range. | Boolean. Defaults to true. Set to false if you want exact center-to-center block distances. |
| range | Two-number array [horizontal, vertical] defining the detection radius in blocks. | Lives inside each object in the subsensors array. |
| cooldown | Time in seconds between scans for that specific subsensor. | Float. Avoid 0.0 on common mobs; a 0.5 or 1.0 second delay is rarely noticeable to players. |
| minimum_count / maximum_count | How many matching entities must be inside the radius for the event to fire. | Integers. Useful for pack mentality or crowding mechanics. |
{
"format_version": "1.21.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:spore_mine",
"is_spawnable": true,
"is_summonable": true
},
"component_groups": {
"wiki:detonating": {
"minecraft:explode": {
"fuse_length": 1.5,
"fuse_lit": true,
"power": 3.0,
"causes_fire": false,
"breaks_blocks": false
}
}
},
"components": {
"minecraft:health": {
"value": 5,
"max": 5
},
"minecraft:physics": {},
"minecraft:entity_sensor": {
"find_players_only": false,
"relative_range": false,
"subsensors": [
{
"range": [3.5, 2.0],
"minimum_count": 1,
"cooldown": 1.0,
"event": "wiki:trigger_mine",
"event_filters": {
"all_of": [
{
"test": "is_family",
"subject": "other",
"value": "player"
},
{
"test": "is_game_rule",
"domain": "dodaylightcycle",
"value": true
}
]
}
}
]
}
},
"events": {
"wiki:trigger_mine": {
"add": {
"component_groups": [
"wiki:detonating"
]
}
}
}
}
}Detecting Targets for Combat and AI
When your goal is to make a custom mob aggro onto another entity, use `minecraft:behavior.nearest_attackable_target`. This AI goal continuously scans for valid targets and assigns the winner as the entity's current target, which movement and attack behaviors (like `minecraft:behavior.melee_attack` or `minecraft:behavior.ranged_attack`) require in order to run.
The maximum distance at which this behavior can detect an entity is governed by the `minecraft:follow_range` attribute component, or overridden per-type using `within_radius` inside the goal's `entity_types` list. Keep in mind that `must_see: true` requires an unobstructed line of sight between the mob's head and the target.
{
"format_version": "1.21.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:guard_golem",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:type_family": {
"family": ["golem", "mob"]
},
"minecraft:follow_range": {
"value": 24,
"max": 24
},
"minecraft:behavior.nearest_attackable_target": {
"priority": 2,
"must_see": true,
"reselect_targets": true,
"scan_interval": 10,
"entity_types": [
{
"filters": {
"test": "is_family",
"subject": "other",
"value": "monster"
},
"max_dist": 20
}
]
}
}
}
}Checking Nearby Entities in Molang
Sometimes you only need to know if another entity is nearby for an animation controller, particle effect, or environment sensor without setting up a full `entity_sensor` component. While Molang cannot iterate over arbitrary nearby entities directly from a query without a target, it can read whether the entity currently has a valid combat target using `query.has_target`.
If you combine `minecraft:behavior.nearest_attackable_target` (or `minecraft:behavior.look_at_entity`) with an animation controller, you can query properties of the targeted entity in Molang by switching the context or checking target distance. For arbitrary counts of non-targeted entities, stick to `minecraft:entity_sensor` and have its event set an entity property (`minecraft: property` in the description) that Molang can read via `query.property`.
Performance and Filtering Best Practices
Entity detection is one of the easiest ways to accidentally ruin world tick performance. Every active `minecraft:entity_sensor` with `find_players_only: false` has to check the bounding boxes of surrounding entities—including item drops, XP orbs, arrows, and armor stands—before running your `event_filters`.
Always set `find_players_only: true` if your mechanic only interacts with players. If you must scan for other mobs, keep the `range` under 16 blocks, set `cooldown` to at least 0.5 seconds, and remove the `minecraft:entity_sensor` component via component groups when the mob is in a state that no longer needs it (such as after the trap has already triggered).
Which versions this applies to
Applies to Bedrock Edition 1.20.80+ for the subsensors array syntax in minecraft:entity_sensor. Earlier format versions placed sensor fields directly on the component root. No experimental toggles are required.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| [Entities][error]-wiki:spore_mine | minecraft:entity_sensor: failed to parse subsensors | You used the old 1.16–1.20.70 flat syntax (putting sensor_range and event directly inside minecraft:entity_sensor) in a file with format_version 1.20.80 or higher, or you passed a single number to range instead of a [horizontal, vertical] two-element array. | Move range, event, and event_filters inside a subsensors array, and ensure range is formatted as [X, Y], such as [5.0, 3.0]. |
| The entity sensor fires its event every single tick or repeatedly spams component groups while the player stands near the mob. | minecraft:entity_sensor does not stop scanning after firing once. As long as the player remains inside the radius, the sensor will fire the event again every time its cooldown expires. | Place minecraft:entity_sensor inside an 'idle' or 'armed' component group, and have the triggered event remove that component group so the sensor shuts off after firing. |
| minecraft:behavior.nearest_attackable_target ignores entities beyond 16 blocks even though max_dist is set to 32. | The mob's hard detection ceiling is capped by the minecraft:follow_range component, which defaults to 16 blocks if omitted. | Add the minecraft:follow_range component to your entity's components list and set both value and max to at least your highest max_dist. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.