Numeric Ranges
Many components need a random number chosen between two bounds, such as how many seconds a timer should wait or how many items a loot pool should drop. Bedrock accepts a numeric range in three different shapes depending on which subsystem is reading the file, though the object and two-element array forms are the most common.
If a field accepts a range, passing a single flat number usually works too, locking the value to that exact constant every time. When using the object format, always make sure the minimum is less than or equal to the maximum, or the parser will reject the component during world load.
| Format | Example | Where it is commonly used |
|---|---|---|
| Two-number array | [2.5, 6.0] | Entity components like minecraft:timer and behaviour AI goals. |
| Min/Max object | {"min": 1, "max": 3} | Loot table functions (such as set_count) and feature rules. |
| Range Min/Max object | {"range_min": 2, "range_max": 5} | Specific entity components like minecraft:Angry and spawn rules. |
{
"format_version": "1.20.80",
"minecraft:entity": {
"description": {
"identifier": "wiki:custom_sheep"
},
"components": {
"minecraft:timer": {
"looping": true,
"time": [5.0, 10.0],
"time_down_event": {
"event": "wiki:baa_loudly"
}
},
"minecraft:ageable": {
"duration": 1200.0
}
}
}
}Item Descriptors
Whenever a component checks what an entity is holding, what repairs a custom tool, or what item heals a mob, it uses an Item Descriptor. At its simplest, an item descriptor can just be a plain string containing the item identifier, such as "minecraft:apple".
When you need to match a whole group of items by tag, or you need to match a legacy data value or Molang expression, you expand the string into a JSON object. Inside an item descriptor object, you use either the "item" key for a specific identifier or the "tags" key to query item tags.
{
"format_version": "1.20.80",
"minecraft:item": {
"description": {
"identifier": "wiki:ruby_pickaxe"
},
"components": {
"minecraft:max_stack_size": 1,
"minecraft:durability": {
"max_durability": 850
},
"minecraft:repairable": {
"repair_items": [
{
"items": [
"wiki:ruby",
{
"tags": "q.any_tag('minecraft:is_minecart')"
}
],
"repair_amount": "q.max_durability * 0.25"
}
]
}
}
}
}Block Descriptors
Block Descriptors work very much like item descriptors, allowing components to target a single block by name, a block in a specific state, or an entire class of blocks sharing a tag. You will write block descriptors inside custom digger items, entity navigation rules, and entity block sensor components.
Like item descriptors, a plain string such as "minecraft:stone" is valid shorthand when you do not care about block states. If you need to match a specific state or a tag, use an object containing "name" and "states", or a "tags" query string.
| Field | What it does | Notes |
|---|---|---|
| name | Matches an exact block identifier. | Example: "minecraft:oak_log". Cannot be combined with tags in the same object. |
| states | Key-value map of block states that must match. | Paired with "name" to filter specific orientations or growth stages. |
| tags | Molang query checking for block tags. | Uses query.any_tag() or query.all_tags() with single-quoted tag names. |
{
"format_version": "1.20.80",
"minecraft:item": {
"description": {
"identifier": "wiki:heavy_shovel"
},
"components": {
"minecraft:digger": {
"use_efficiency": true,
"destroy_speeds": [
{
"block": "minecraft:dirt",
"speed": 8
},
{
"block": {
"tags": "q.any_tag('sand', 'gravel')"
},
"speed": 6
}
]
}
}
}
}Event Triggers
In entity files, components do not directly add or remove other components when something happens. Instead, they fire an Event Trigger construct, which points to a named section inside the entity's "events" block. A trigger always bundles three concepts together: the name of the event to run, who should run it, and an optional filter condition.
The "target" field defaults to "self", meaning the entity that owns the component fires the event on itself. In interactions or damage sensors, you can set the target to "other" so the event runs on the player or attacker instead, provided that other entity actually has an event with that name defined in its own JSON.
| Field | What it does | Notes |
|---|---|---|
| event | Identifier of the event in the events block. | Required. If the event does not exist on the target, nothing happens. |
| target | Entity subject that receives the event. | Defaults to "self". Common alternatives are "other", "holder", and "parent". |
| filters | Entity filter object or group that gates the trigger. | Optional. The event only fires if this filter evaluates to true. |
{
"format_version": "1.20.80",
"minecraft:entity": {
"description": {
"identifier": "wiki:guard_golem"
},
"components": {
"minecraft:Environment_sensor": {
"triggers": [
{
"event": "wiki:melt_in_water",
"target": "self",
"filters": {
"test": "in_water",
"subject": "self",
"value": true
}
}
]
}
},
"events": {
"wiki:melt_in_water": {
"add": {
"component_groups": [
"wiki:melting_state"
]
}
}
}
}
}Molang String Versus Number Fields
Another shared pattern across animations, particle effects, and modern item or block components is the Molang-enabled value field. Where older schemas only accepted a hardcoded float or integer, newer fields accept either a raw JSON number or a quoted string containing a Molang expression.
When you just need a constant value, write it as a normal JSON number without quotes so the engine does not waste time parsing it as an expression. Only wrap the value in quotes when you need math operators, variables, or queries like "q.life_time * 20.0".
Which versions this applies to
Applies to all modern Bedrock versions (1.16.0 through 1.21+). No experimental toggles are required for these shared constructs in entity, item, block, or loot files.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| Content Log shows: "Failed to parse block descriptor: tag query string is invalid" | You used escaped double quotes inside a "tags" query string, or you wrote a raw tag name instead of wrapping it in a Molang function. | Always wrap tag names in single quotes inside query.any_tag() or query.all_tags(), for example: "q.any_tag('wood', 'log')". |
| Entity timer or loot table crashes or always picks the minimum value. | You used the {"min": 1, "max": 5} object inside an entity component that expects a two-element array [1, 5], or you set the minimum higher than the maximum. | Switch to the [min, max] array syntax for entity timers and AI goals, and reserve the {"min", "max"} object for loot table functions. |
| Event trigger does nothing when triggered, with no error in the Content Log. | The "target" on the trigger is set to "other" (such as the player interacting with a mob), so the game looks for the custom event inside player.json instead of your custom entity. | Change "target" to "self" inside the trigger object so your entity runs its own event, and use "subject": "other" inside the "filters" block if you still need to test the player. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.