liblevelup is a mod for collecting statistics on what node drops players have acquired throughout their time on your server. It's intended to be used to add a sense of progression to the game, giving some sort of bonus to players based on the amount of experience they've had mining different materials, but does not itself do anything but count.
liblevelup has now been streamlined and improved. Now, it counts minerals drops, farm crop drops, sapling drops, and farm seed drops. These are all detected automatically; liblevelup attempts to adapt to the set of mods that are currently running, and no hard-coded drops are included. It's all dynamic. Originally, liblevelup included an sfinv page, but that has now been broken off into its own mod. If you want to restore that functionality, please install
minestats_sfinv. Other graphical interfaces can be installed as well, such as
minestats_hud, which displays a player's stats to them via the HUD instead of the inventory menu.
Things mined not by players directly are not counted. These things include, for example, leaf decay, falling node mishap, attached node drops, and TNT explosions. They are not attributed to any player, as no player mined them. If for some reason you want those stats as a player, you need to mine your own leaves instead of letting leaf decay do all the work for you; you only get credit for stats you actually *earn*. This isn't likely to change anytime soon; the Minetest API barely allows me to capture player names when actually digging through subtle hackery; it doesn't allow me to capture coordinates at all, nor is there a get_nearest_player() method even if I did have coordinates.
History:
Originally, this functionality was coded as part of a mod called Minequest, where it allowed players to become more proficient at using items in certain ways. I though the feature might be useful to other mods, so I generalised it, broke it off into a separate mod, and called it "minestats". While minestats was complete, I eventually hit a dead end with Minequest and had to discontinue it before release. Given its name and its lack of context, I felt like minestats sort of just became a stats display mod, which is never what it was intended to be. It was supposed to actually influence game play. In an attempt to turn that around, I've rebranded it as "liblevelup", a more-fitting name. That breaks dependencies though, so with dependencies already broken, I took the opportunity to reorganise the API a bit better. The old API will be included in the mod for at least two years after its deprecation, as is my standard when deprecating API features in this mod, but you'll also need to edit the dependency list of any older mods you have that use this to depend on liblevelup instead of minestats.
The API tables are as follows:
- liblevelup.register:
This table contains callback-registration functions used to alter liblevelup's behaviour or request event notifications from libelvelup. Registration functions should be called during mod-loading time. After mod-loading time has ended, the entire registration table becomes unavailable at some point between mod-loading time and game time.
Code: Select all
liblevelup.register.is_countable(function(node_string, drop_string, drop_possibilities))
liblevelup is extendible! It does its best to determine what nodes and drops should be counted, but by registering a function here, you can help it out a bit and make it count even more node/drop combos. When going through the list of available nodes and their drops, liblevelup will call your function passing three arguments. The first two are the node and one item of one of its potential drops. Your function should return true if you want that node/drop combo counted. The third argument is a table of potential drops that node can drop in their full form. Each item is itself a table, containing the items that the node could drop together in a single dig. All possible drop combinations are included. Both the node string and drop string are in item string format. Usually, the node will simply be a node name, but in the case of coloured nodes, it'll also contain a palette index. Don't just assume this string is a valid node name and attempt to look it up in the minetest.registered_nodes table; the string may have more data and not be in the table in that form. The drop string will frequently contain non-name data, such as an item count, but can also include tool wear and metadata.
Only one is_countable function can be registered per mod, so put all your checking logic in a single function or call other functions from within the function you register. If you try to register a second is_countable function from the same mod, it'll override the first.
Code: Select all
liblevelup.register.levelup_function(function(player, level))
When a player levels up, functions registered with this function will be called and passed a player object and an integer, with the integer being the player's new level. Levels start at zero, so the first level-up will be at level one.
Code: Select all
liblevelup.register.startup_function(function())
Some mods need to run code near the beginning of the game, but need access to the liblevelup API, including liblevelup.meta.drops_list(). They can use this function to register their own function that will be called once liblevelup has become ready. Please note two things about this function though. First, these functions are only called once, soon after load time. Registering a function later is pointless, and this function actually disappears from the API once it's too late to use it. Second, because of the way this is implemented, each mod may only register up to one startup function. As all these functions are called in succession, you might as well put everything you need run in one registered function anyway.
Code: Select all
liblevelup.register.update_function(function(player))
Functions registered with this function should take a player object as an argument and will be called every time a player's stats are updated. This could, for example, be used to set up a self-updating stats page for players in their inventory menu. Like the last function, only one function per mod is allowed; again, as these functions are all run in succession, you might as well put all your code to be registered in a single function.
- liblevelup.unregister:
If you want to override the functionality of another mod, it can be helpful to remove that mod's callback registrations, either to replace them with others or simply prevent them from activating. The following functions take a mod's name and removes the function they registered of the relevant type, if such a function was registered. For this to be effective, you'll need to depend on the mod (or soft depend on it) in order to make sure your unregistration comes after the other mod's registration. Otherwise, the other mod will sometimes register after you try to unregister. At this time, is-countable registrations cannot be unregistered. The other unregistration functions are self-explanatory:
Code: Select all
liblevelup.unregister.is_countable(mod_name)
liblevelup.unregister.levelup_function(mod_name)
liblevelup.unregister.update_function(mod_name)
- liblevelup.get:
These functions query the stats database.
Code: Select all
liblevelup.get.drop_stat(player_name, drop_name)
This function returns the number of a given item the player has gotten from node drops. For example, call this function passing the name "default:coal_lump", not "default:stone_with_coal".
Code: Select all
liblevelup.get.player_level(player_name)
Given a player name, this function returns that player's current level. Levels are obviously determined based on mining/farming experience. Levels start from level zero.
Code: Select all
liblevelup.get.next_level_at(player_name, material)
Given a player name and a material name, this function returns how many more of the material the player would need to mine/harvest in order to level up. Levelling occurs on a per-material curve, so the less of a material you've already harvested, the more harvesting that material counts toward your next level. That means there are two main strategies for increasing your level: harvest a lot of material or harvest many types of materials.
Code: Select all
liblevelup.get.player_material_level(player_name, material)
This function returns a per-material level related to how much of the material the player has harvested. Using this levelling function is usually not preferred, and liblevelup.get.player_level() is usually the better option. Use liblevelup.get.player_material_level() instead if for some reason you need separate levels for separate materials, such as if you want to add a feature that depends on a player's proficiency with a given material.
Code: Select all
liblevelup.get.pair_stat(player_name, node_name, drop_name)
This function returns the number of a given item, such as coal or cotton, a player has mined from the given node, such as coal ore or a specific cotton growing stage. This function is quantity-sensitive, so passing "farming:cotton" will tell how many times a given player has gotten a single cotton drop from the cotton plant stage, while passing "farming:cotton 2" will instead tell how many times the player received the possible double drop.
- liblevelup.meta:
These functions query information about the environment liblevelup is running in, but don't touch the database in any way.
Code: Select all
liblevelup.meta.is_counted(node_name, drop_name)
Returns a boolean, indicating whether the given node/drop combination is considered to be countable by liblevelup.
This function, if called during load time, will return an empty table, as liblevelup is still waiting for all mods to have their chance to register nodes, recipes, and items. Once the game begins though, it'll return a table of all nodes and items counted by this mod. Each table entry is itself a table, containing three elements. "node" contains the name of the node that drops this item. "drop" is the drop that gets counted; it could be plural, like "farming:wheat 2". Confusingly, the outer table is is indexed from one instead of from zero, but that makes it easier to work with in many of Lua's functions. The keys denote the alphabetical order of the nodes, then drops.
Like the previous function, this one returns an empty table when called during load time. Otherwise, it returns a table of all detected countable drop items. The keys are simply integers denoting the alphabetical order of the drops, and the values are the item strings of each drop. Again, these are indexed from one. For example, if default is installed, "default:coal_lump" will be in this table, not "default:stone_with_coal".
Code license: GNU LGPL 2.1+
Resource license: no images or sounds are included!
Mod dependencies: None!
Download: <
https://notabug.org/y.st./liblevelup/archive/master.zip>
Repository: <
https://notabug.org/y.st./liblevelup>