late/API.md

Introduction

LATE is a library for managing lasting effects, not instant effects.

Targets: Targets of effects. For now, players and mobs can be targets of effects.

Impacts: An elementary impact on target. Different effects can result in the same impact. In that case, their parameters and intensities are properly mixed to result in a single impact.

Effects: Combination of impacts, conditions and target. Many effects at once can be affected to a target, with different conditions (duration, area, equipment).

Conditions are only for stopping effect. LATE does not automatically start effects where condition are fulfilled. This would be far too difficult to continuously check for every possibility. Effect creation has to be triggered explicitely. Some helpers exist to start effects automatically on certain events.

Effects management

Active effects are represented by Effect objects. Effect objects are created by calling late.new_effect method. Effects can also be automatically affected when using some items and blocks. In that case, they are defined in item or node definition.

Effect phases

Effects have a cycle of life involving four phases:

raise

Effect starts in this phase.
It stops after raise seconds or if effect conditions are no longer fulfilled.
Intensity of effect grows from 0 to 1 during this phase.

still

Once raise phase is completed, effects enters the still phase.
Intensity is full and the phases lasts until one of the conditions stops being fulfilled.

fall

When conditions are no longer fulfilled, effect enters fall phase.
This phase lasts fall seconds (if 0, effects gets to end phase instantly).

end

This is the terminal phase.
Effect will be deleted in next step.

Effect definition table

Effect definition table may contain following fields:

• id Identifier. If given, should be unique for a target. If not given, an internal id is given.
• impacts Impacts effect has (pair of impact name / impact parameters);
• raise Time (in seconds) it takes to raise to full intensity (default 0: immediate);
• fall Time (in seconds) it takes to fall, after end to no intensity (default 0: immediate);
• duration Duration (in seconds) the effect lasts (default: always);
• distance For effect associated to nodes, distance of action;
• stop_on_death If true, the effect stops at player death;
• hud Hud defition (see Hud definition table section);

All fields are optional but an effect without impacts would do nothing.

Hud definition table

Hud definition table (hud field of effect definition) may contain following fields:

• icon Texture used to display effect in hud;
• color Color of the hud background;
• label Text to be displayed;
• duration Set to false to hide duration (default true);

Example of effect definition

-- Run fast and make high jumps for 20 seconds
{
    impacts = { jump=3, speed=10 },
    fall = 2,
    duration = 20,
	hud = { color="yellow", label ="Jump fast!" },
}

Of course, jump and speed impacts have to be defined (they are included in base impacts).

How to affect effects?

With custom code

To affect a target with an effect, create a new effect using late.new_effect, giving the target and the effect definition. Think about adding a duration or stop_on_death clause in effect definition to avoid permanent effect (unless expected).

Example :

-- Stuck player "toto" for 5 seconds
local player = minetest.get_player_by_name("toto")
if player then
    late.new_effect(player, { duration=5, impacts = { speed=0 } })
end

Using items

Items can have effects on players or mobs when:

• Equiped (in hand or in armor equipment): cloth, amulets, rings;
• Used (effect on self): potion, food;
• Used (on someone or something): magic wand, special weapon;

Effect when equiped

To create an item that have an effect when equiped, add to the item definition a field named effect_equip containing the effect definition.

Example:

-- Jump boots
minetest.register_tool("mymod:jump_boots", {
    description = "Jump boots",
	inventory_image = "mymod_boots.png",
    effect_equip = { impacts = { jump=3 } },
})

To make boots wearable as boots armor, refer to 3D Armor mod API.

Effect when used

To create an item that have an effect when used:

• Put the effect definition in item definition field effect_use (for use on self) or effect_use_on (for use on players or mobs);
• Add a call to late.on_use_tool_callback in item on_use;
• Add an end condition to avoid creating permanent effect : a duration clause or stop_on_death=true clause;

Example:

-- Poison potion
minetest.register_tool("mymod:poison", {
    description = "Poison potion",
	inventory_image = "mymod_potion.png",
    effect_use = { impacts = { damage={ 1, 2 } }, stop_on_death=true },
    on_use = late.on_use_tool_callback,
})

Placing nodes

Effects can be triggered by the proximity of a specific node.

To create a node with effect:

• Add the node in effect_trigger group (effect_trigger=1 in groups table);
• Add an effect_near field in the node definition with a distancefield;

Example:

-- Darkness 20 nodes around dark stone
minetest.register_node("mymod:dark_stone", {
	description = "Dark stone",
	tiles = {"default_stone.png"},
    groups = { cracky = 3, stone = 1, effect_trigger = 1 },
    effect_near = { impacts = { daylight=0 }, distance = 20 },
})

Methods

get_effect_by_id

function late.get_effect_by_id(target, id)

Retrieves an effect affecting a target by it's id.

target: Target of the effect.
id: Identifier of the effect to retrieve.

Returns the Effect object if found, nil otherwise.

on_use_tool_callback

function late.on_use_tool_callback(itemstack, user, pointed_thing)

Standard on_use tool callback to be added to tools with effects (see above).

Effect object

Effect object represent a temporary (or permanent) effect on a target (player or mob).

Public methods

new

function Effect:new(target, definition)

Public API :

function late.new_effect(target, definition)

Creates a new effect on a target.

target: Target to be affected by the effect.
definition: Effect defintion table.

Returns an Effect object if creation succeded, nil otherwise.

Possible cause of failure :

• Target is not suitable (neither a player nor a mob);
• definition.id (optional) field contains a value that is already in use for the target (check first with late.get_effect_by_id if you are using ids);

start

function Effect:start()

Starts an effect or restart it.

If conditions are not fulfilled, it will fall in fall phase again during next step. So start/restart should be called only if condition are fulfilled again.

restart

function Effect:restart()

Same as start.

stop

function Effect:stop()

Stops an effect. Actually set it in fall phase, regardless of conditions.

change_intensity

function Effect:change_intensity(intensity)

Change intensity of effect.

intensity: New intensity (between 0.0 and 1.0)

Developed for internal purpose but safe to use as public method.

set_conditions(conditions)

function Effect:set_conditions(conditions)

Sets or overrides condition(s) of an effect. conditions Key / value table of conditions.

Developed for internal purpose but safe to use as public method.

Internal use methods (unsafe)

add_impact

function Effect:add_impact(type_name, params)

Add a new impact to the effect.

type_name: Impact type name
params: Params for that impact (refer to the corresponding impact type definition)

remove_impact

function Effect:remove_impact(type_name)

Remove an impact from effect.

type_name: Impact type name

step

function Effect:step(dtime)

Performs a step calculation of effect. dtime: Time since last step.

Conditions registration

register_condition_type

function late.register_condition_type(name, definition)

Registers a condition type. Conditions are checked each step to determine if the effect should last or stop. Registering new condition types allows to extend the available types of conditions.

name: Name of the condition type.
definition: Definition table of the condition type.

Condition definition table

definition table may contain following fields:

• check (optional) = function(data, target, effect) A function called to check is a condition is fulfilled. Should return true if condition still fulfilled, false otherwise. This function is not called at each step, only when engine needs it. Function parameters:
  • data: condition data (value of this condition field in effect definition)
  • target: target affected,
  • effect: Effect object instance.
• step (optional) = function(data, target, effect) A function called at each step. Could be useful to prepare condition checking. Same parameters as check function.

Impacts registration

register_impact_type

function late.register_impact_type(target_types, name, definition)

Registers an impact type.

target_types: Target type or table of target types that can be affected by that impact type
name: Name of the impact type
definition: Definition table of the impact type

Impact definition table

definition table may contain following fields:

• varsInternal variables needed by the impact (variables will instantiated for each target) (optional);
• reset (optional) = function(impact) Function called when impact stops to reset normal target state (optional);
• update (optional) = function(impact) Function called when impact changes to apply impact on target;
• step (optional) = function(impact, dtime) Function called every global step (optional);

Impact instance table

impactargument passed to reset, update and step functions is a table representing the impact instance concerned. Table fields are :

• target Player or mob ObjectRef affected by the impact;
• type Impact type name;
• vars Table of impact variables (copied from impact type definition) indexed by their name;
• params Table of per effect params and intensity;
• changed True if impact changed since last step;

Except variables in vars, nothing should be changed by the functions.

Impact Helpers

In following helpers, valint stands for a pair of value / intensity.

Each effect corresponding to an impact gives one or more parameters to the impact and an effect intensity.

The impact is responsible of computing a single values from these parameters and intensity. LATE provides helpers to perform common combination operations.

get_valints

function late.get_valints(params, index)

Returns extacts value/intensity pairs from impact params table.

Impact params table contains params given by effects definition, plus an intensity field reflecting the corresponding effect intensity.

params: the impact.params field
index: index of the params field to be extracted

append_valints

function late.append_valints(valints, extravalints)

Appends a values and intensities list to another. Usefull to add extra values in further computation.

valints: List where extra valints will be append
extravalints: Extra valints to append

multiply_valints

function late.multiply_valints(valints)

Returns the result of a multiplication of values with intensities

valints: Value/Intensity list;

sum_valints

function late.sum_valints(valints)

Returns the result of a sum of values with intensities

valints: Value/Intensity list

superpose_valints

function late.superpose_valints(valints, base_value)

Returns a ratio superposition (like if each ratio was a greyscale value and intensities where alpha chanel). valints Value/Intensity list of ratios (values should go from 0 to 1)
base_value Base ratio value on which valints are superposed

superpose_color_valints

function late.superpose_color_valints(valints, background_color)

Returns a color superposition with alpha channel and intensity (actually, intensity is considered as a factor on alpha channel) valints Value/Intensity list of colors
background_color Background color (default none)

mix_color_valints

function late.mix_color_valints(valints)

Mix colors with intensity. Returns {r,g,b,a} table representing the resulting color.

valints List of colorstrings (value=) and intensities

color_to_table

function late.color_to_table(colorspec)

Converts a colorspec to a {r,g,b,a} table. Returns the conversion result.

colorspec Can be a standard color name, a 32 bit integer or a table

color_to_rgb_texture

function late.color_to_rgb_texture(colorspec)

Converts a colorspec to a "#RRGGBB" string ready to use in textures.

colorspec Can be a standard color name, a 32 bit integer or a table

Full example of impact type creation

-- Impact on player speed
-- Params :
-- 1: Speed multiplier [0..infinite]. Default: 1

late.register_impact_type('player', 'speed', {
	-- Reset function basically resets target speed to default value
	reset = function(impact)
			minetest.set_physics_override(impact.target, {speed = 1.0})
		end,
	-- Main function actually coding the impact		
	update = function(impact)
			minetest.set_physics_override(impact.target, {
				speed = late.multiply_valints(
					late.get_valints(impact.params, 1))
			})
		end,
})

More internal stuff

get_storage_for_target

late.get_storage_for_target(target)

Retrieves or create the effects_api storage for a target.

target: Target

Returns storage associated with the target or nil if target not suitable.