player_monoids/init.lua

local modpath = minetest.get_modpath(minetest.get_current_modname()) .. "/"

player_monoids = {}

local mon_meta = {}
mon_meta.__index = mon_meta

local nop = function() end

-- A monoid object is a table with the following fields:
--   def: The monoid definition.
--   player_map: A map from player names to their branch maps. Branch maps
--     contain branches, and each branch holds an 'effects' table.
--   value_cache: A map from player names to the cached value for the monoid.
--   next_id: The next unique ID to assign an effect.

--[[
In def, you can optionally define:

  - apply(new_value, player)
  - on_change(old_value, new_value, player, branch)
  - listen_to_all_changes (bool)
  - on_branch_created(monoid, player, branch_name)
  - on_branch_deleted(monoid, player, branch_name)

These hooks allow you to respond to monoid changes, branch creation, and branch deletion.
]]

local function monoid(def)
    local mon = {}

    -- Clone the definition to avoid mutating the original
    local actual_def = {}
    for k, v in pairs(def) do
        actual_def[k] = v
    end

    if not actual_def.apply then
        actual_def.apply = nop
    end
    if not actual_def.on_change then
        actual_def.on_change = nop
    end
    if not actual_def.on_branch_created then
        actual_def.on_branch_created = nop
    end
    if not actual_def.on_branch_deleted then
        actual_def.on_branch_deleted = nop
    end
    if actual_def.listen_to_all_changes == nil then
        actual_def.listen_to_all_changes = false
    end

    mon.def = actual_def

    mon.player_map = {}  -- p_name -> { active_branch="main", branches={ branch_name={ effects={}, value=...} } }
    mon.value_cache = {} -- p_name -> numeric or table
    mon.next_id = 1

    setmetatable(mon, mon_meta)

    -- Clear out data when player leaves
    minetest.register_on_leaveplayer(function(player)
        local p_name = player:get_player_name()
        mon.player_map[p_name] = nil
        mon.value_cache[p_name] = nil
    end)

    -- Initialize branches for the monoid
    function mon:init_branches(player_name)
        self.player_map[player_name] = {
            active_branch = "main",
            branches = {
                main = {
                    effects = {},
                    value = def.identity
                }
            }
        }
    end

    return mon
end

player_monoids.make_monoid = monoid

local function init_player_branches_if_missing(self, p_name)
    if not self.player_map[p_name] then
        self:init_branches(p_name)
    end
end

-- Create or return existing branch. If a new one is created, fire on_branch_created.
local function get_or_create_branch_data(self, p_name, branch_name)
    local branches = self.player_map[p_name].branches
    local existing_branch = branches[branch_name]

    if not existing_branch then
        branches[branch_name] = {
            effects = {},
            value = self.def.identity
        }

        existing_branch = branches[branch_name]

        local player = minetest.get_player_by_name(p_name)
        if player then
            self.def.on_branch_created(self, player, branch_name)
        end
    end

    return existing_branch
end

-- decide if to call on_change for this change based on listen_to_all_changes
function mon_meta:call_on_change(old_value, new_value, player, branch_name)
    local p_name = player:get_player_name()
    if self.def.listen_to_all_changes or (self.player_map[p_name].active_branch == branch_name) then
        self.def.on_change(old_value, new_value, player, self:get_branch(branch_name))
    end
end

function mon_meta:add_change(player, value, id, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local branch = branch_name or "main"
    local p_branch_data = get_or_create_branch_data(self, p_name, branch)

    local p_effects = p_branch_data.effects

    local actual_id = id or self.next_id
    if not id then
        self.next_id = actual_id + 1
    end

    local old_total = p_branch_data.value
    p_effects[actual_id] = value

    local new_total = self.def.fold(p_effects)
    p_branch_data.value = new_total

    if self.player_map[p_name].active_branch == branch then
        self.def.apply(new_total, player)
    end

    self:call_on_change(old_total, new_total, player, branch)
    return actual_id
end

function mon_meta:del_change(player, id, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local branch = branch_name or "main"
    local p_branch_data = get_or_create_branch_data(self, p_name, branch)
    if not p_branch_data then return end

    local p_effects = p_branch_data.effects
    local old_total = p_branch_data.value

    p_effects[id] = nil
    local new_total = self.def.fold(p_effects)
    p_branch_data.value = new_total

    if self.player_map[p_name].active_branch == branch then
        self.def.apply(new_total, player)
    end

    self:call_on_change(old_total, new_total, player, branch)
end

function mon_meta:reset_branch(player, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local branch = branch_name or "main"
    local bdata = self.player_map[p_name].branches[branch]
    if not bdata then
        return -- Branch doesn't exist, nothing to reset
    end

    local old_total = bdata.value

    -- Clear effects and recalc
    bdata.effects = {}
    local new_total = self.def.fold({})
    bdata.value = new_total

    -- Update active branch
    local active_branch = self.player_map[p_name].active_branch or "main"
    local active_branch_data = self.player_map[p_name].branches[active_branch]

    local active_branch = self.player_map[p_name].active_branch or "main"
    local active_branch_data = self.player_map[p_name].branches[active_branch]
    self.value_cache[p_name] = active_branch_data.value
    self.def.apply(active_branch_data.value, player)

    -- Fire on_change for the branch being reset
    self:call_on_change(old_total, new_total, player, branch)
end

-- new method: create a branch for a player, but do NOT check it out
function mon_meta:new_branch(player, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    get_or_create_branch_data(self, p_name, branch_name)

    return self:get_branch(branch_name)
end

function mon_meta:get_branch(branch_name)
    if not branch_name then
        return false
    end

    local monoid = self
    return {
        add_change = function(_, player, value, id)
            return monoid:add_change(player, value, id, branch_name)
        end,
        del_change = function(_, player, id)
            return monoid:del_change(player, id, branch_name)
        end,
        value = function(_, player)
            return monoid:value(player, branch_name)
        end,
        reset = function(_, player)
            return monoid:reset_branch(player, branch_name)
        end,
        get_name = function(_)
            return branch_name
        end,
        delete = function(_, player)
            local p_name = player:get_player_name()
            init_player_branches_if_missing(monoid, p_name)

            local player_data = monoid.player_map[p_name]
            if not player_data then
                return
            end

            local existing_branch = player_data.branches[branch_name]
            if not existing_branch or branch_name == "main" then
                return
            end

            -- If it's the active branch, switch to main
            if player_data.active_branch == branch_name then
                player_data.active_branch = "main"
                local new_main_total = monoid:value(player, "main")
                monoid.value_cache[p_name] = new_main_total

                monoid.def.apply(new_main_total, player)
            end

            -- Remove the branch
            player_data.branches[branch_name] = nil

            monoid.def.on_branch_deleted(monoid, player, branch_name)
        end,
    }
end

function mon_meta:get_active_branch(player)
    local p_name = player:get_player_name()
    local active = self.player_map[p_name] and self.player_map[p_name].active_branch or "main"
    return self:get_branch(active)
end

function mon_meta:get_branches(player)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local branch_map = self.player_map[p_name].branches or {}
    local result = {}
    for b_name, _ in pairs(branch_map) do
        result[b_name] = self:get_branch(b_name)
    end
    return result
end

function mon_meta:delete_branch(player, branch_name)
    local b = self:get_branch(branch_name)

    if not b then
        return false
    end

    b:delete(player)
end

minetest.register_on_joinplayer(function(player)
    for _, monoid_instance in pairs(player_monoids) do
        if type(monoid_instance) == "table" and monoid_instance.init_branches then
            monoid_instance:init_branches(player:get_player_name())
        end
    end
end)

function mon_meta:value(player, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local chosen_branch = branch_name or self.player_map[p_name].active_branch or "main"
    local p_data = self.player_map[p_name]
    local bdata = p_data.branches[chosen_branch]
    if not bdata then
        return self.def.identity
    end

    local calculated_value = self.def.fold(bdata.effects)
    return calculated_value
end

function mon_meta:checkout_branch(player, branch_name)
    local p_name = player:get_player_name()
    init_player_branches_if_missing(self, p_name)

    local old_total = self.value_cache[p_name] or self.def.identity
    local checkout_branch = self:new_branch(player, branch_name)

    self.player_map[p_name].active_branch = branch_name
    local new_total = self:value(player)
    self.value_cache[p_name] = new_total

    self:call_on_change(old_total, new_total, player, branch_name)
    self.def.apply(new_total, player)

    return checkout_branch
end

-- Finally, load the additional files

dofile(modpath .. "standard_monoids.lua")
dofile(modpath .. "test.lua")