API Explosions

Explosions

Lua API / Explosions

ctx.world:createExplosion(options) creates an explosion from any mutable world action context. It supports a short vanilla-style call and independent control over block destruction, entity damage, knockback, drops, fire, sound, and particles. The method is unavailable in queries and client display callbacks.

On this page

• Create an explosion
• Options
• Position and source defaults
• Result
• Block and entity callbacks
• Limits and errors

Create an explosion

strength is the only required field. Omitted effects use non-flaming vanilla defaults:

local result = ctx.world:createExplosion { strength = 4 }

The position defaults to the callback origin. A fully selected explosion can look like this:

local result = ctx.world:createExplosion {
    position = { x = 12.5, y = 64, z = -8.5 },
    strength = 3.5,
    source = ctx.entity,
    fire = false,
    blocks = "destroy",
    entities = true,
    knockback = true,
    drops = true,
    dropChance = 0.3,
    sound = true,
    particles = true,
    includeAffectedBlocks = false
}

Options

Field	Type	Default / behavior
strength	number 0.1–16	Required. Vanilla explosions commonly use 1–6.
position	{ x, y, z }	Exact current entity position in entity-owned callbacks; callback block center otherwise.
source	live entity handle or false	Current entity in entity-owned callbacks; no source otherwise. false clears an automatic entity source.
fire	boolean	false; attempts to ignite supported affected air after block effects.
blocks	"destroy" or "none"	"destroy"; "none" preserves blocks while they still shield entities.
entities	boolean	true; enables entity damage.
knockback	boolean	true; enables radial velocity independently from damage.
drops	boolean	true; runs normal drop logic for destroyed blocks.
dropChance	number 0–1	0.3; passed to block drop logic when drops are enabled.
sound	boolean	true; plays the vanilla explosion sound.
particles	boolean	true; creates vanilla explosion and smoke particles.
includeAffectedBlocks	boolean	false; includes a bounded coordinate list in the result.

drops and dropChance have no effect when blocks = "none". Block destruction callbacks still run when blocks are destroyed with drops disabled. Damage and knockback are independent, so an explosion can damage without moving entities or create a non-damaging shockwave.

Position and source defaults

position accepts an ordinary coordinate table, betamoon.positions:integer(...), or betamoon.positions:float(...). Coordinates must be finite and within -30000000 through 30000000. The center Y may be outside the normal build range so an explosion can intersect the world boundary.

Entity AI, lifecycle, interaction, damage, sensor, pickup, projectile, and tick contexts default to the current entity's exact position and use that entity as source. The source is excluded from the affected-entity search and is passed to block resistance and damage attribution.

Block, item, and tile callbacks default to the callback block center and have no source. Pass a player, projectile, or another live same-world entity explicitly when attribution and source exclusion matter. Lua table fields cannot distinguish an omitted field from nil; use source = false to clear an automatic entity source.

local result = ctx.world:createExplosion {
    position = ctx.player:getPosition(),
    strength = 2,
    source = ctx.player,
    blocks = "none"
}

Result

The method finishes the selected effects before returning a detached snapshot:

Field	Meaning
position	Exact { x, y, z } center.
strength	Applied strength.
blocksAffected	Unique ray-reached positions, including air.
blocksDestroyed	Blocks successfully replaced with air.
entitiesDamaged	Entities whose damage handler accepted the hit.
entitiesKnockedBack	Entities given a non-zero impulse.
firesPlaced	Fire blocks successfully placed.
affectedBlocks	Coordinate list when includeAffectedBlocks = true; otherwise nil.
affectedBlocksTruncated	Whether the requested coordinate list was cut to its 4096-entry limit.

entitiesDamaged reports accepted hits, which does not always equal health lost because armor and native invulnerability remain active. A result table contains snapshots only; editing it never changes the world.

Block and entity callbacks

A block destroyed by this method runs its normal onExploded callback after removal. That callback receives ctx.explosion with the center, strength, resolved options, and optional source. Native Minecraft explosions do not provide this field.

A BetaMoon entity hit by this method receives cause = "explosion" in onBeforeDamage and onAfterDamage. Both callbacks receive the same ctx.explosion snapshot. attacker and directSource refer to the selected native source when available.

Callbacks may create chained explosions. Read request fields from ctx.explosion; the final counts are available only from the completed call's result.

Limits and errors

The method requires a live mutable callback and an authoritative singleplayer world. Invalid fields and values raise an error instead of being ignored. A source must be alive and in the same world.

Each explosion is limited to strength 16, 32768 calculated positions, and 1024 entity candidates. An affected-position result contains at most 4096 coordinates and reports truncation. Chained explosions are limited to eight nested calls. Workload and recursion failures stop that explosion; scripts should not use large repeated blasts every tick.

See Configurable Explosion for a non-destructive concussive mode and a destructive mode using the same item callback.