Component structure and fields
At its core, `minecraft:timer` counts down in real-time seconds (derived from game ticks) and fires an event block when the countdown hits zero. You can place it directly in the base `components` block if the timer should run for the entity's entire lifetime, or inside a `component_groups` entry if you only want the countdown active during a specific state.
Duration is configured in one of three mutually exclusive ways: a fixed range (`time` as a two-number array), a single fixed number (`time` as a float), or a weighted list of choices (`random_time_choices`). You must pick one method depending on whether you want predictable intervals or organic variation.
| Field | What it does | Notes |
|---|---|---|
| looping | Boolean controlling whether the timer restarts automatically after firing. | Defaults to true. Set to false for one-shot delays like despawning. |
| randomInterval | Boolean deciding if `time` is treated as a [min, max] range or a single float. | Defaults to true. Set to false when passing a single number to `time`. |
| time | Either a float (e.g., 5.0) or a two-float array (e.g., [3.0, 8.0]) in seconds. | Type must match what `randomInterval` expects. |
| random_time_choices | Array of objects containing `weight` and `value` keys for discrete durations. | Overrides `time`. Useful when you want specific intervals rather than a smooth range. |
| time_down_event | Event definition object containing `event`, `target`, and optional `filters`. | Fires on the entity when the countdown reaches zero. |
Fixed and ranged intervals
The most common setup uses the `time` property alongside `randomInterval`. By default, `randomInterval` is `true`, which means the engine expects `time` to be an array of two numbers representing the minimum and maximum seconds to wait. Each time the timer starts or loops, it picks a new random duration within that window.
If you need an exact, predictable countdown—such as a bomb that always detonates after four seconds—you must explicitly set `randomInterval` to `false` and pass a single float or integer to `time`. Leaving `randomInterval` at its default while passing a single number is one of the most frequent causes of broken timers.
{
"format_version": "1.20.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:bomb_dummy",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:physics": {},
"minecraft:timer": {
"looping": false,
"randomInterval": false,
"time": 4.0,
"time_down_event": {
"event": "wiki:detonate",
"target": "self"
}
}
},
"events": {
"wiki:detonate": {
"add": {
"component_groups": [
"wiki:exploding"
]
}
}
},
"component_groups": {
"wiki:exploding": {
"minecraft:explode": {
"fuse_length": 0.0,
"power": 3.0
}
}
}
}
}Weighted time choices
Sometimes a continuous range feels too unpredictable, but a single fixed time feels robotic. The `random_time_choices` array solves this by letting you define specific time values (in seconds) and assign a probability weight to each.
When the timer starts, it sums all weights and rolls a choice. In the example below, the entity has a 75% chance to wait 2 seconds and a 25% chance to wait 10 seconds, never picking any number in between. When using `random_time_choices`, omit the `time` property entirely.
{
"format_version": "1.20.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:flickering_wisp",
"is_spawnable": false,
"is_summonable": true
},
"components": {
"minecraft:timer": {
"looping": true,
"random_time_choices": [
{
"weight": 75,
"value": 2.0
},
{
"weight": 25,
"value": 10.0
}
],
"time_down_event": {
"event": "wiki:pulse",
"target": "self"
}
}
},
"events": {
"wiki:pulse": {}
}
}
}Chaining states and resetting timers
An entity can only have one instance of `minecraft:timer` active at any given moment. Because of this limitation, you cannot run two independent countdowns side by side in the same component list. However, you can chain multiple timers together by placing different configurations of `minecraft:timer` inside separate component groups.
When an event removes one component group and adds another containing a new `minecraft:timer`, the countdown resets to the new group's duration. This pattern is how you build state machines—for example, a turret that spends 5 seconds in a 'cooling down' group, then switches to a 'ready to fire' group.
{
"format_version": "1.20.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:state_cycler",
"is_spawnable": true,
"is_summonable": true
},
"components": {
"minecraft:physics": {}
},
"component_groups": {
"wiki:phase_one": {
"minecraft:scale": {
"value": 1.0
},
"minecraft:timer": {
"looping": false,
"randomInterval": false,
"time": 3.0,
"time_down_event": {
"event": "wiki:to_phase_two",
"target": "self"
}
}
},
"wiki:phase_two": {
"minecraft:scale": {
"value": 2.0
},
"minecraft:timer": {
"looping": false,
"randomInterval": false,
"time": 1.5,
"time_down_event": {
"event": "wiki:to_phase_one",
"target": "self"
}
}
}
},
"events": {
"minecraft:entity_spawned": {
"add": {
"component_groups": [
"wiki:phase_one"
]
}
},
"wiki:to_phase_two": {
"remove": {
"component_groups": [
"wiki:phase_one"
]
},
"add": {
"component_groups": [
"wiki:phase_two"
]
}
},
"wiki:to_phase_one": {
"remove": {
"component_groups": [
"wiki:phase_two"
]
},
"add": {
"component_groups": [
"wiki:phase_one"
]
}
}
}
}
}Persistence, chunk unloading, and alternatives
Timers only tick while the entity is in a loaded, ticking area. If a player walks away and the chunk unloads, the entity is frozen in place and its timer pauses until the chunk is loaded again. Furthermore, the remaining time on a `minecraft:timer` is saved with the entity's data when the world closes, so a 60-second timer interrupted at 30 seconds will resume with 30 seconds left on reload.
If you discover you need two independent timers running simultaneously on the same entity, `minecraft:timer` alone will not work. Instead, keep your primary state machine on `minecraft:timer` and offload secondary periodic checks to `minecraft:environment_sensor` (using the `hourly_clock_time` or `clock_time` filters) or `minecraft:behavior.Timer_flag_1` style AI goals if applicable, or handle tick-level scheduling via the `@minecraft/server` Script API.
Which versions this applies to
Available in all modern Bedrock versions (format_version 1.8.0 through 1.21.0+). Stable; no experimental toggles are required.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| Timer fires immediately on spawn or throws a Content Log error about `time` not being an array. | You passed a single number like `"time": 5.0` without setting `"randomInterval": false`. Because `randomInterval` defaults to `true`, the parser expects a `[min, max]` array. | Either add `"randomInterval": false` to the component, or change `"time"` to an array like `[5.0, 5.0]`. |
| Adding a component group with a new timer does not seem to run both timers. | Bedrock entities can only hold one instance of any given component type at a time. Adding a group with `minecraft:timer` overwrites the existing `minecraft:timer` in the base components or other active groups. | Design your events as sequential steps where one timer hands off to the next, or move one of the recurring tasks into a Script API `system.runInterval` loop. |
| A non-looping timer (`"looping": false`) refuses to run a second time when you re-add its component group. | If the component group containing the finished timer was never removed, `add` on that same group is ignored by the engine because the entity already has the group. | Always `remove` the component group containing the one-shot timer inside the event it fires, so that adding the group later forces a fresh instance of the component. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.