juanchi/mods/explosions

Explosions

Explosions API mod for Minetest.

Description

This mod adds a common API to generate ray-traced explosions in Minetest. Ray-traced explosion are more realistic than what is currently used to simulate explosions. It allows different nodes to have different blast resistances, and will allow nodes with high blast resistance to absorb blasts, protecting weaker nodes or entities behind them. This mod only exposes one function `explosions.explode' which is used to create explosions of various strengths and shapes.

The computation-intensive parts of the mod has been optimized to allow for larger explosions and more faster world updating.

Requires Minetest 5.1.0 or later.

Documentation

explosions.explode(pos, explosion_def)

Create an explosion at position.

• pos position where the explosion should start from
• explosion_def contains the properties of the explosion

Explosion definition properties

strength

Each explosion has a strength which determines how much damage it will do, both to entities and to the environment. A higher strength value will lead to more powerful explosions.

shape

A shape is an array of normalized vectors. Each vector define the direction of each ray in the explosion. When creating custom shapes it is important that enough rays are specified so the explosion does not create artifacts (like flying nodes in the environment).

If unspecified the shape becomes a sphere which is generated by the mod and contains an appropriate number of rays. These spheres will only be generated once for each different radius of the explosions.

radius

Rays need to die at some point. This is specified by the radius property which define the maximum distance each ray will go. Entities or nodes past this radius will not be affected by the explosion. If unspecified it becomes the cube root of strength.

Blast resistance

This mod also adds a new group for nodes, blast_resistance which is used to define how resistant different materials are to explosions. When a node does not have a defined blast resistance, the mod will calculate it from other nodes groups (like cracky/crumbly, dig_immediate and level). The algorithm used for that is quite arbitrary and not described here (look at source-code if interested).

Following is a table which lists the calculated blast resistance for some materials in the default game:

Node type	Blast resistance
Diamond	1000
Obsidian	500
Iron block	500
Gold block	200
Lava	100
Stone	100
Planks	75
Dirt/Sand	50
Water	50
Leaves	12.5

Node blast callbacks

Each node type can define callback functions which get called when the node get hit by a ray. The callback functions get specified from minetest.register_node among the other callback functions.

The callbacks are called after the entire explosion has been traced, but before the environment is updated. If code in the callback updates nodes in the environment in any way, those changes must be be wrapped in a call to minetest.after, otherwise the changes will not have any effect. If the callback returns true, the node will be removed, otherwise it will stay.

on_blast_break(pos, strength, dir)

Gets called when a ray hits the node and has enough strength to go through it. The default behavior for this is to remove the node from the map. Nodes can be made indestructible (while still having low blast resistance) by defining this to an empty function.

• pos position of the node
• strength strength of the ray which hit the node
• dir direction of the ray which hit the node

on_blast_shock(pos, strength, dir)

Gets called when a ray hits the node but does not have enough strength to go through it. The default behavior is to make the node fly away with a velocity proportional to the strength of the ray which hit it. Possible applications of this callback could be to make stone turn into cobblestone, or wood catch fire.

• pos position of the node
• strength strength of the ray which hit the node
• dir direction of the ray which hit the node

Credits

This API mod was created by Elias Åström. It is released under the LGPL license, see the license file for more information.