builtin/game/register.lua

   1 -- Minetest: builtin/misc_register.lua
   2
   3 --
   4 -- Make raw registration functions inaccessible to anyone except this file
   5 --
   6
   7 local register_item_raw = core.register_item_raw
   8 core.register_item_raw = nil
   9
  10 local unregister_item_raw = core.unregister_item_raw
  11 core.unregister_item_raw = nil
  12
  13 local register_alias_raw = core.register_alias_raw
  14 core.register_alias_raw = nil
  15
  16 --
  17 -- Item / entity / ABM / LBM registration functions
  18 --
  19
  20 core.registered_abms = {}
  21 core.registered_lbms = {}
  22 core.registered_entities = {}
  23 core.registered_items = {}
  24 core.registered_nodes = {}
  25 core.registered_craftitems = {}
  26 core.registered_tools = {}
  27 core.registered_aliases = {}
  28
  29 -- For tables that are indexed by item name:
  30 -- If table[X] does not exist, default to table[core.registered_aliases[X]]
  31 local alias_metatable = {
  32         __index = function(t, name)
  33                 return rawget(t, core.registered_aliases[name])
  34         end
  35 }
  36 setmetatable(core.registered_items, alias_metatable)
  37 setmetatable(core.registered_nodes, alias_metatable)
  38 setmetatable(core.registered_craftitems, alias_metatable)
  39 setmetatable(core.registered_tools, alias_metatable)
  40
  41 -- These item names may not be used because they would interfere
  42 -- with legacy itemstrings
  43 local forbidden_item_names = {
  44         MaterialItem = true,
  45         MaterialItem2 = true,
  46         MaterialItem3 = true,
  47         NodeItem = true,
  48         node = true,
  49         CraftItem = true,
  50         craft = true,
  51         MBOItem = true,
  52         ToolItem = true,
  53         tool = true,
  54 }
  55
  56 local function check_modname_prefix(name)
  57         if name:sub(1,1) == ":" then
  58                 -- If the name starts with a colon, we can skip the modname prefix
  59                 -- mechanism.
  60                 return name:sub(2)
  61         else
  62                 -- Enforce that the name starts with the correct mod name.
  63                 local expected_prefix = core.get_current_modname() .. ":"
  64                 if name:sub(1, #expected_prefix) ~= expected_prefix then
  65                         error("Name " .. name .. " does not follow naming conventions: " ..
  66                                 "\"" .. expected_prefix .. "\" or \":\" prefix required")
  67                 end
  68
  69                 -- Enforce that the name only contains letters, numbers and underscores.
  70                 local subname = name:sub(#expected_prefix+1)
  71                 if subname:find("[^%w_]") then
  72                         error("Name " .. name .. " does not follow naming conventions: " ..
  73                                 "contains unallowed characters")
  74                 end
  75
  76                 return name
  77         end
  78 end
  79
  80 function core.register_abm(spec)
  81         -- Add to core.registered_abms
  82         assert(type(spec.action) == "function", "Required field 'action' of type function")
  83         core.registered_abms[#core.registered_abms + 1] = spec
  84         spec.mod_origin = core.get_current_modname() or "??"
  85 end
  86
  87 function core.register_lbm(spec)
  88         -- Add to core.registered_lbms
  89         check_modname_prefix(spec.name)
  90         assert(type(spec.action) == "function", "Required field 'action' of type function")
  91         core.registered_lbms[#core.registered_lbms + 1] = spec
  92         spec.mod_origin = core.get_current_modname() or "??"
  93 end
  94
  95 function core.register_entity(name, prototype)
  96         -- Check name
  97         if name == nil then
  98                 error("Unable to register entity: Name is nil")
  99         end
 100         name = check_modname_prefix(tostring(name))
 101
 102         prototype.name = name
 103         prototype.__index = prototype  -- so that it can be used as a metatable
 104
 105         -- Add to core.registered_entities
 106         core.registered_entities[name] = prototype
 107         prototype.mod_origin = core.get_current_modname() or "??"
 108 end
 109
 110 function core.register_item(name, itemdef)
 111         -- Check name
 112         if name == nil then
 113                 error("Unable to register item: Name is nil")
 114         end
 115         name = check_modname_prefix(tostring(name))
 116         if forbidden_item_names[name] then
 117                 error("Unable to register item: Name is forbidden: " .. name)
 118         end
 119         itemdef.name = name
 120
 121         -- default short_description to first line of description
 122         itemdef.short_description = itemdef.short_description or
 123                 (itemdef.description or ""):gsub("\n.*","")
 124
 125         -- Apply defaults and add to registered_* table
 126         if itemdef.type == "node" then
 127                 -- Use the nodebox as selection box if it's not set manually
 128                 if itemdef.drawtype == "nodebox" and not itemdef.selection_box then
 129                         itemdef.selection_box = itemdef.node_box
 130                 elseif itemdef.drawtype == "fencelike" and not itemdef.selection_box then
 131                         itemdef.selection_box = {
 132                                 type = "fixed",
 133                                 fixed = {-1/8, -1/2, -1/8, 1/8, 1/2, 1/8},
 134                         }
 135                 end
 136                 if itemdef.light_source and itemdef.light_source > core.LIGHT_MAX then
 137                         itemdef.light_source = core.LIGHT_MAX
 138                         core.log("warning", "Node 'light_source' value exceeds maximum," ..
 139                                 " limiting to maximum: " ..name)
 140                 end
 141                 setmetatable(itemdef, {__index = core.nodedef_default})
 142                 core.registered_nodes[itemdef.name] = itemdef
 143         elseif itemdef.type == "craft" then
 144                 setmetatable(itemdef, {__index = core.craftitemdef_default})
 145                 core.registered_craftitems[itemdef.name] = itemdef
 146         elseif itemdef.type == "tool" then
 147                 setmetatable(itemdef, {__index = core.tooldef_default})
 148                 core.registered_tools[itemdef.name] = itemdef
 149         elseif itemdef.type == "none" then
 150                 setmetatable(itemdef, {__index = core.noneitemdef_default})
 151         else
 152                 error("Unable to register item: Type is invalid: " .. dump(itemdef))
 153         end
 154
 155         -- Flowing liquid uses param2
 156         if itemdef.type == "node" and itemdef.liquidtype == "flowing" then
 157                 itemdef.paramtype2 = "flowingliquid"
 158         end
 159
 160         -- BEGIN Legacy stuff
 161         if itemdef.cookresult_itemstring ~= nil and itemdef.cookresult_itemstring ~= "" then
 162                 core.register_craft({
 163                         type="cooking",
 164                         output=itemdef.cookresult_itemstring,
 165                         recipe=itemdef.name,
 166                         cooktime=itemdef.furnace_cooktime
 167                 })
 168         end
 169         if itemdef.furnace_burntime ~= nil and itemdef.furnace_burntime >= 0 then
 170                 core.register_craft({
 171                         type="fuel",
 172                         recipe=itemdef.name,
 173                         burntime=itemdef.furnace_burntime
 174                 })
 175         end
 176         -- END Legacy stuff
 177
 178         itemdef.mod_origin = core.get_current_modname() or "??"
 179
 180         -- Disable all further modifications
 181         getmetatable(itemdef).__newindex = {}
 182
 183         --core.log("Registering item: " .. itemdef.name)
 184         core.registered_items[itemdef.name] = itemdef
 185         core.registered_aliases[itemdef.name] = nil
 186         register_item_raw(itemdef)
 187 end
 188
 189 function core.unregister_item(name)
 190         if not core.registered_items[name] then
 191                 core.log("warning", "Not unregistering item " ..name..
 192                         " because it doesn't exist.")
 193                 return
 194         end
 195         -- Erase from registered_* table
 196         local type = core.registered_items[name].type
 197         if type == "node" then
 198                 core.registered_nodes[name] = nil
 199         elseif type == "craft" then
 200                 core.registered_craftitems[name] = nil
 201         elseif type == "tool" then
 202                 core.registered_tools[name] = nil
 203         end
 204         core.registered_items[name] = nil
 205
 206
 207         unregister_item_raw(name)
 208 end
 209
 210 function core.register_node(name, nodedef)
 211         nodedef.type = "node"
 212         core.register_item(name, nodedef)
 213 end
 214
 215 function core.register_craftitem(name, craftitemdef)
 216         craftitemdef.type = "craft"
 217
 218         -- BEGIN Legacy stuff
 219         if craftitemdef.inventory_image == nil and craftitemdef.image ~= nil then
 220                 craftitemdef.inventory_image = craftitemdef.image
 221         end
 222         -- END Legacy stuff
 223
 224         core.register_item(name, craftitemdef)
 225 end
 226
 227 function core.register_tool(name, tooldef)
 228         tooldef.type = "tool"
 229         tooldef.stack_max = 1
 230
 231         -- BEGIN Legacy stuff
 232         if tooldef.inventory_image == nil and tooldef.image ~= nil then
 233                 tooldef.inventory_image = tooldef.image
 234         end
 235         if tooldef.tool_capabilities == nil and
 236            (tooldef.full_punch_interval ~= nil or
 237             tooldef.basetime ~= nil or
 238             tooldef.dt_weight ~= nil or
 239             tooldef.dt_crackiness ~= nil or
 240             tooldef.dt_crumbliness ~= nil or
 241             tooldef.dt_cuttability ~= nil or
 242             tooldef.basedurability ~= nil or
 243             tooldef.dd_weight ~= nil or
 244             tooldef.dd_crackiness ~= nil or
 245             tooldef.dd_crumbliness ~= nil or
 246             tooldef.dd_cuttability ~= nil) then
 247                 tooldef.tool_capabilities = {
 248                         full_punch_interval = tooldef.full_punch_interval,
 249                         basetime = tooldef.basetime,
 250                         dt_weight = tooldef.dt_weight,
 251                         dt_crackiness = tooldef.dt_crackiness,
 252                         dt_crumbliness = tooldef.dt_crumbliness,
 253                         dt_cuttability = tooldef.dt_cuttability,
 254                         basedurability = tooldef.basedurability,
 255                         dd_weight = tooldef.dd_weight,
 256                         dd_crackiness = tooldef.dd_crackiness,
 257                         dd_crumbliness = tooldef.dd_crumbliness,
 258                         dd_cuttability = tooldef.dd_cuttability,
 259                 }
 260         end
 261         -- END Legacy stuff
 262
 263         -- This isn't just legacy, but more of a convenience feature
 264         local toolcaps = tooldef.tool_capabilities
 265         if toolcaps and toolcaps.punch_attack_uses == nil then
 266                 for _, cap in pairs(toolcaps.groupcaps or {}) do
 267                         local level = (cap.maxlevel or 0) - 1
 268                         if (cap.uses or 0) ~= 0 and level >= 0 then
 269                                 toolcaps.punch_attack_uses = cap.uses * (3 ^ level)
 270                                 break
 271                         end
 272                 end
 273         end
 274
 275         core.register_item(name, tooldef)
 276 end
 277
 278 function core.register_alias(name, convert_to)
 279         if forbidden_item_names[name] then
 280                 error("Unable to register alias: Name is forbidden: " .. name)
 281         end
 282         if core.registered_items[name] ~= nil then
 283                 core.log("warning", "Not registering alias, item with same name" ..
 284                         " is already defined: " .. name .. " -> " .. convert_to)
 285         else
 286                 --core.log("Registering alias: " .. name .. " -> " .. convert_to)
 287                 core.registered_aliases[name] = convert_to
 288                 register_alias_raw(name, convert_to)
 289         end
 290 end
 291
 292 function core.register_alias_force(name, convert_to)
 293         if forbidden_item_names[name] then
 294                 error("Unable to register alias: Name is forbidden: " .. name)
 295         end
 296         if core.registered_items[name] ~= nil then
 297                 core.unregister_item(name)
 298                 core.log("info", "Removed item " ..name..
 299                         " while attempting to force add an alias")
 300         end
 301         --core.log("Registering alias: " .. name .. " -> " .. convert_to)
 302         core.registered_aliases[name] = convert_to
 303         register_alias_raw(name, convert_to)
 304 end
 305
 306 function core.on_craft(itemstack, player, old_craft_list, craft_inv)
 307         for _, func in ipairs(core.registered_on_crafts) do
 308                 itemstack = func(itemstack, player, old_craft_list, craft_inv) or itemstack
 309         end
 310         return itemstack
 311 end
 312
 313 function core.craft_predict(itemstack, player, old_craft_list, craft_inv)
 314         for _, func in ipairs(core.registered_craft_predicts) do
 315                 itemstack = func(itemstack, player, old_craft_list, craft_inv) or itemstack
 316         end
 317         return itemstack
 318 end
 319
 320 -- Alias the forbidden item names to "" so they can't be
 321 -- created via itemstrings (e.g. /give)
 322 for name in pairs(forbidden_item_names) do
 323         core.registered_aliases[name] = ""
 324         register_alias_raw(name, "")
 325 end
 326
 327
 328 -- Obsolete:
 329 -- Aliases for core.register_alias (how ironic...)
 330 -- core.alias_node = core.register_alias
 331 -- core.alias_tool = core.register_alias
 332 -- core.alias_craftitem = core.register_alias
 333
 334 --
 335 -- Built-in node definitions. Also defined in C.
 336 --
 337
 338 core.register_item(":unknown", {
 339         type = "none",
 340         description = "Unknown Item",
 341         inventory_image = "unknown_item.png",
 342         on_place = core.item_place,
 343         on_secondary_use = core.item_secondary_use,
 344         on_drop = core.item_drop,
 345         groups = {not_in_creative_inventory=1},
 346         diggable = true,
 347 })
 348
 349 core.register_node(":air", {
 350         description = "Air",
 351         inventory_image = "air.png",
 352         wield_image = "air.png",
 353         drawtype = "airlike",
 354         paramtype = "light",
 355         sunlight_propagates = true,
 356         walkable = false,
 357         pointable = false,
 358         diggable = false,
 359         buildable_to = true,
 360         floodable = true,
 361         air_equivalent = true,
 362         drop = "",
 363         groups = {not_in_creative_inventory=1},
 364 })
 365
 366 core.register_node(":ignore", {
 367         description = "Ignore",
 368         inventory_image = "ignore.png",
 369         wield_image = "ignore.png",
 370         drawtype = "airlike",
 371         paramtype = "none",
 372         sunlight_propagates = false,
 373         walkable = false,
 374         pointable = false,
 375         diggable = false,
 376         buildable_to = true, -- A way to remove accidentally placed ignores
 377         air_equivalent = true,
 378         drop = "",
 379         groups = {not_in_creative_inventory=1},
 380         on_place = function(itemstack, placer, pointed_thing)
 381                 core.chat_send_player(
 382                                 placer:get_player_name(),
 383                                 core.colorize("#FF0000",
 384                                 "You can't place 'ignore' nodes!"))
 385                 return ""
 386         end,
 387 })
 388
 389 -- The hand (bare definition)
 390 core.register_item(":", {
 391         type = "none",
 392         wield_image = "wieldhand.png",
 393         groups = {not_in_creative_inventory=1},
 394 })
 395
 396
 397 function core.override_item(name, redefinition)
 398         if redefinition.name ~= nil then
 399                 error("Attempt to redefine name of "..name.." to "..dump(redefinition.name), 2)
 400         end
 401         if redefinition.type ~= nil then
 402                 error("Attempt to redefine type of "..name.." to "..dump(redefinition.type), 2)
 403         end
 404         local item = core.registered_items[name]
 405         if not item then
 406                 error("Attempt to override non-existent item "..name, 2)
 407         end
 408         for k, v in pairs(redefinition) do
 409                 rawset(item, k, v)
 410         end
 411         register_item_raw(item)
 412 end
 413
 414
 415 core.callback_origins = {}
 416
 417 function core.run_callbacks(callbacks, mode, ...)
 418         assert(type(callbacks) == "table")
 419         local cb_len = #callbacks
 420         if cb_len == 0 then
 421                 if mode == 2 or mode == 3 then
 422                         return true
 423                 elseif mode == 4 or mode == 5 then
 424                         return false
 425                 end
 426         end
 427         local ret = nil
 428         for i = 1, cb_len do
 429                 local origin = core.callback_origins[callbacks[i]]
 430                 if origin then
 431                         core.set_last_run_mod(origin.mod)
 432                 end
 433                 local cb_ret = callbacks[i](...)
 434
 435                 if mode == 0 and i == 1 then
 436                         ret = cb_ret
 437                 elseif mode == 1 and i == cb_len then
 438                         ret = cb_ret
 439                 elseif mode == 2 then
 440                         if not cb_ret or i == 1 then
 441                                 ret = cb_ret
 442                         end
 443                 elseif mode == 3 then
 444                         if cb_ret then
 445                                 return cb_ret
 446                         end
 447                         ret = cb_ret
 448                 elseif mode == 4 then
 449                         if (cb_ret and not ret) or i == 1 then
 450                                 ret = cb_ret
 451                         end
 452                 elseif mode == 5 and cb_ret then
 453                         return cb_ret
 454                 end
 455         end
 456         return ret
 457 end
 458
 459 function core.run_priv_callbacks(name, priv, caller, method)
 460         local def = core.registered_privileges[priv]
 461         if not def or not def["on_" .. method] or
 462                         not def["on_" .. method](name, caller) then
 463                 for _, func in ipairs(core["registered_on_priv_" .. method]) do
 464                         if not func(name, caller, priv) then
 465                                 break
 466                         end
 467                 end
 468         end
 469 end
 470
 471 --
 472 -- Callback registration
 473 --
 474
 475 local function make_registration()
 476         local t = {}
 477         local registerfunc = function(func)
 478                 t[#t + 1] = func
 479                 core.callback_origins[func] = {
 480                         mod = core.get_current_modname() or "??",
 481                         name = debug.getinfo(1, "n").name or "??"
 482                 }
 483                 --local origin = core.callback_origins[func]
 484                 --print(origin.name .. ": " .. origin.mod .. " registering cbk " .. tostring(func))
 485         end
 486         return t, registerfunc
 487 end
 488
 489 local function make_registration_reverse()
 490         local t = {}
 491         local registerfunc = function(func)
 492                 table.insert(t, 1, func)
 493                 core.callback_origins[func] = {
 494                         mod = core.get_current_modname() or "??",
 495                         name = debug.getinfo(1, "n").name or "??"
 496                 }
 497                 --local origin = core.callback_origins[func]
 498                 --print(origin.name .. ": " .. origin.mod .. " registering cbk " .. tostring(func))
 499         end
 500         return t, registerfunc
 501 end
 502
 503 local function make_registration_wrap(reg_fn_name, clear_fn_name)
 504         local list = {}
 505
 506         local orig_reg_fn = core[reg_fn_name]
 507         core[reg_fn_name] = function(def)
 508                 local retval = orig_reg_fn(def)
 509                 if retval ~= nil then
 510                         if def.name ~= nil then
 511                                 list[def.name] = def
 512                         else
 513                                 list[retval] = def
 514                         end
 515                 end
 516                 return retval
 517         end
 518
 519         local orig_clear_fn = core[clear_fn_name]
 520         core[clear_fn_name] = function()
 521                 for k in pairs(list) do
 522                         list[k] = nil
 523                 end
 524                 return orig_clear_fn()
 525         end
 526
 527         return list
 528 end
 529
 530 local function make_wrap_deregistration(reg_fn, clear_fn, list)
 531         local unregister = function (key)
 532                 if type(key) ~= "string" then
 533                         error("key is not a string", 2)
 534                 end
 535                 if not list[key] then
 536                         error("Attempt to unregister non-existent element - '" .. key .. "'", 2)
 537                 end
 538                 local temporary_list = table.copy(list)
 539                 clear_fn()
 540                 for k,v in pairs(temporary_list) do
 541                         if key ~= k then
 542                                 reg_fn(v)
 543                         end
 544                 end
 545         end
 546         return unregister
 547 end
 548
 549 core.registered_on_player_hpchanges = { modifiers = { }, loggers = { } }
 550
 551 function core.registered_on_player_hpchange(player, hp_change, reason)
 552         local last
 553         for i = #core.registered_on_player_hpchanges.modifiers, 1, -1 do
 554                 local func = core.registered_on_player_hpchanges.modifiers[i]
 555                 hp_change, last = func(player, hp_change, reason)
 556                 if type(hp_change) ~= "number" then
 557                         local debuginfo = debug.getinfo(func)
 558                         error("The register_on_hp_changes function has to return a number at " ..
 559                                 debuginfo.short_src .. " line " .. debuginfo.linedefined)
 560                 end
 561                 if last then
 562                         break
 563                 end
 564         end
 565         for i, func in ipairs(core.registered_on_player_hpchanges.loggers) do
 566                 func(player, hp_change, reason)
 567         end
 568         return hp_change
 569 end
 570
 571 function core.register_on_player_hpchange(func, modifier)
 572         if modifier then
 573                 core.registered_on_player_hpchanges.modifiers[#core.registered_on_player_hpchanges.modifiers + 1] = func
 574         else
 575                 core.registered_on_player_hpchanges.loggers[#core.registered_on_player_hpchanges.loggers + 1] = func
 576         end
 577         core.callback_origins[func] = {
 578                 mod = core.get_current_modname() or "??",
 579                 name = debug.getinfo(1, "n").name or "??"
 580         }
 581 end
 582
 583 core.registered_biomes      = make_registration_wrap("register_biome",      "clear_registered_biomes")
 584 core.registered_ores        = make_registration_wrap("register_ore",        "clear_registered_ores")
 585 core.registered_decorations = make_registration_wrap("register_decoration", "clear_registered_decorations")
 586
 587 core.unregister_biome = make_wrap_deregistration(core.register_biome,
 588                 core.clear_registered_biomes, core.registered_biomes)
 589
 590 core.registered_on_chat_messages, core.register_on_chat_message = make_registration()
 591 core.registered_on_chatcommands, core.register_on_chatcommand = make_registration()
 592 core.registered_globalsteps, core.register_globalstep = make_registration()
 593 core.registered_playerevents, core.register_playerevent = make_registration()
 594 core.registered_on_mods_loaded, core.register_on_mods_loaded = make_registration()
 595 core.registered_on_shutdown, core.register_on_shutdown = make_registration()
 596 core.registered_on_punchnodes, core.register_on_punchnode = make_registration()
 597 core.registered_on_placenodes, core.register_on_placenode = make_registration()
 598 core.registered_on_dignodes, core.register_on_dignode = make_registration()
 599 core.registered_on_generateds, core.register_on_generated = make_registration()
 600 core.registered_on_newplayers, core.register_on_newplayer = make_registration()
 601 core.registered_on_dieplayers, core.register_on_dieplayer = make_registration()
 602 core.registered_on_respawnplayers, core.register_on_respawnplayer = make_registration()
 603 core.registered_on_prejoinplayers, core.register_on_prejoinplayer = make_registration()
 604 core.registered_on_joinplayers, core.register_on_joinplayer = make_registration()
 605 core.registered_on_leaveplayers, core.register_on_leaveplayer = make_registration()
 606 core.registered_on_player_receive_fields, core.register_on_player_receive_fields = make_registration_reverse()
 607 core.registered_on_cheats, core.register_on_cheat = make_registration()
 608 core.registered_on_crafts, core.register_on_craft = make_registration()
 609 core.registered_craft_predicts, core.register_craft_predict = make_registration()
 610 core.registered_on_protection_violation, core.register_on_protection_violation = make_registration()
 611 core.registered_on_item_eats, core.register_on_item_eat = make_registration()
 612 core.registered_on_punchplayers, core.register_on_punchplayer = make_registration()
 613 core.registered_on_priv_grant, core.register_on_priv_grant = make_registration()
 614 core.registered_on_priv_revoke, core.register_on_priv_revoke = make_registration()
 615 core.registered_on_authplayers, core.register_on_authplayer = make_registration()
 616 core.registered_can_bypass_userlimit, core.register_can_bypass_userlimit = make_registration()
 617 core.registered_on_modchannel_message, core.register_on_modchannel_message = make_registration()
 618 core.registered_on_player_inventory_actions, core.register_on_player_inventory_action = make_registration()
 619 core.registered_allow_player_inventory_actions, core.register_allow_player_inventory_action = make_registration()
 620
 621 --
 622 -- Compatibility for on_mapgen_init()
 623 --
 624
 625 core.register_on_mapgen_init = function(func) func(core.get_mapgen_params()) end