yl_api_nodestages #

Purpose #

This mod is a library which brings various nodestage-related functions.

Download #

Get it from https://gitea.your-land.de/your-land/yl_api_nodestages

Installation #

1. Copy the "yl_api_nodestages" folder to your mod directory.
2. Enable the mod in your world.mt file.

Configuration #

yl_api_nodestages.debug = false

Set to true to enable debug mode

yl_api_nodestages.run_lbm = true

Set to true to enable the timer restart lbm, set to false to disable it

Usage #

This mod can be used in singleplayer and multiplayer. It comes with no direct content but exposes functions you can use in your mod.

Data structure #

One stage consists of at least the stage_name, next_stages and duration.

local stage = {
    {
        stage_name = "modname:nodename", -- required, string, nodename to attach this stage to, must not exist previously
        next_stages = "modname:same_or_other_nodename", -- required, string or table (see below), if missing last stage is assumed
        --    OR 
        next_stages = { -- required if not last stage, table format
            {
                "modname:same_or_other_nodename", -- required, string, target nodename must exist
                50,  -- optional, number, chance for the node to switch to this target, defaults to 1
                { can_set = mymod.optional_can_set_function, more_functions = ... }, -- optional, table, callback table of known keys and function values
                { param1 = 90, param2 = 107, ... } -- optional, table, metadata table of known keys and whatever values they want
            },
            { "modname:same_or_other_nodename"}, -- as above, but without any optional fields
            { "other_modname:their_nodename"} -- as above, but targets a node from different mod
        },
        duration = 120, -- required, number, fixed duration of stage in seconds, if missing last stage is assumed
        tiles = {"modname_nodename_texturename.png", ... }, -- required, table, table of tiles
        description = "Node description", -- required, string, node description
        -- Optional "Node definition" aka "Used by minetest.register_node"
        node_definition = {
            drawtype = "normal",
            ...
        },
        overwrite = false, -- optional, boolean, false breaks during registration if the node has on_timer or on_construct. true overwrites regardless
        restart = true, -- optional, boolean, true restarts the nodetimer via lbm, false does not
        _previous = {}, -- DO NOT USE, this holds the history to be accessed by delete_stage only
        _version = 1, -- DO NOT USE, this holds the version of the datastructure, will increase when datastructure changes
    }
}

A list of {stage} sit in a table stages:

local stages = {
    {stage},
    {stage},
    ...
}

Modmakers #

Use the following public functions related to nodestages.

yl_api_nodestages.get_stage(modname, nodename)

Gets a table with the values of the stage attached to the given modname:nodename. Returns true, {stage} or false, errormessage if an error occurred.

yl_api_nodestages.create_stagenode(stage)

Creates the node without attaching the stage. Returns true if the node was successfully created. Returns false, "errormessage" if not.

yl_api_nodestages.add_stage(stage)

Attaches a stage to an existing node. Returns true if the stage was successfully attached. Only successful if the stage does not yet exist. Returns false, "errormessage" if not.

yl_api_nodestages.overwrite_stage(stage)

Attaches a stage to an existing node. Returns true if the stage was successfully attached, regardless whether the stage already exist. Returns false, "errormessage" if not.

yl_api_nodestages.rollback_stage(modname, nodename)

Rolls a stage of an existing node back to the stage before the last overwrite. Returns true if the stage was successfully rolled back. Returns false, "errormessage" if not.

yl_api_nodestages.delete_stage(modname, nodename)

Deletes the stage (including cached previous stages) from an existing node. Returns true if the stage was successfully removed. Returns false, "errormessage" if not.

yl_api_nodestages.register_stage(stage)

Registers a single stage, calls create_stage and add_stage. Returns true if the stage was successfully registered. Returns false, "errormessage" if not.

yl_api_nodestages.register_stages(stages)

Registers all given stages, calls create_stage and add_stage. Returns true, good, bad, total, {} if all stages were registered successfully. Returns false, good, bad, total, {reasons} if at least one stage was not successfully registered.

yl_api_nodestages.validate_all_stages()

Validates all stages currently attached to any node. Returns true, good, bad, total, {} if all stages were validated successfully. Returns false, good, bad, total, {reasons} if at least one stage was not successfully validated.

Limitations #

• No randomized duration except by registering the same stage as a next_stage again
• Core nodes cannot have stages, examples are air and ignore
• Unclear: About 1 Million active stages may cause Server::ActiveObjectMgr::addActiveObjectRaw(): no free id available

Alternatives #

• Implement nodetimers, ABMs or LBMs

Supported versions #

If you use yl_api_nodestages, but something is wrong, please file a bug. PRs also welcome.

There is no reason to believe it doesn't work anywhere, but you never know.

Allied projects #

• yl_canned_food

Uninstall #

Remove it from your mod folder or deactivate it in your world.mt

Mods that depend on it will cease to work, if the mod is removed without proper replacement.

License #

See LICENSE.md

• Code MIT Developername
• Screenshot CC0 Styxcolor

Thank you #

• Original canned_food author: https://github.com/h-v-smacker
• AspireMint
• Styxcolor