8acddab74f
When applying bonemeal to eg. farm crops, these have a chance to grow in response to the application of bone meal. When a node can be bonemealed, the applied bone meal item should always be spent after using it, regardless of the results. Currently this does not work correctly, if the result of bonemealing has no effect on the node, the used bone meal item is not spent. This commit fixes the behavior of the bone meal item to always be taken when used on a node that defines a `_mcl_on_bonemealing()` callback. The nodes that implement the callback imay use the handler's return value only to signal if the bonemealing was succesful, not to signal if it was at all possible. For this reason, some nodes need to be made more strictly conforming to the API. * Always take the used bone meal item (if user is not in creative mode), regardless of whether the bonemealed node's handler returned `true`. * Make dispensers spawn particles after succesful bonemealing. * Trivial comment fix. * Ripe cocoa pod cannot be bonemealed. * Update API.md to describe the stricter API semantics.
2.6 KiB
Bone meal API
Bonemealing callbacks and particle functions.
_mcl_on_bonemealing(pointed_thing, placer)
The bone meal API provides a callback definition that nodes can use to register a handler that is executed when a bone meal item is used on it.
Nodes that wish to use the bone meal API should in their node registration
define a callback handler named _mcl_on_bonemealing.
Note that by registering the callback handler, the node declares that bone
meal can be used on it and as a result, when the user is not in creative
mode, the used bone meal is spent and taken from the itemstack passed to
the on_place() handler of the bone meal item used.
It is for all intents and purposes up to the callback defined in the node to decide how to handle the specific effect that bone meal has on that node.
The _mcl_on_bonemealing callback handler is a
function(pointed_thing, placer)
Its arguments are:
pointed_thing: exact pointing location (see Minetest API), where the bone meal is appliedplacer: ObjectRef of the player who aplied the bone meal, can be nil!
The return value of the handler function indicates if the bonemealing had
its intended effect. If true, 'bone meal particles' are spawned at the
position of the bonemealed node.
The on_place code in the bone meal item will spawn bone meal particles and
decrease the bone meal itemstack if the handler returned true and the
placer is not in creative mode.
mcl_bone_meal.add_bone_meal_particle(pos, def)
Spawns standard or custom bone meal particles.
pos: position, is ignored if you define def.minpos and def.maxposdef: (optional) particle definition; see minetest.add_particlespawner() for more details.
Legacy API
The bone meal API also provides a legacy compatibility function. This function is not meant to be continued and callers should migrate to the newer bonemealing API.
mcl_bone_meal.register_on_bone_meal_apply(function(pointed_thing, placer))
Called when the bone meal is applied anywhere.
pointed_thing: exact pointing location (see Minetest API), where the bone meal is appliedplacer: ObjectRef of the player who aplied the bone meal, can be nil! This function is deprecated and will be removed at some time in the future.
mcl_dye.add_bone_meal_particle(pos, def)
mcl_dye.register_on_bone_meal_apply(function(pointed_thing, user))
These shims in mcl_dye that point to corresponding legacy compatibility functions in mcl_bone_meal remain for legacy callers that have not yet been updated to the new API. These shims will be removed at some time in the future.