diff options
| -rw-r--r-- | README.md | 169 | ||||
| -rw-r--r-- | api.lua | 1 | ||||
| -rw-r--r-- | readme.md | 163 |
3 files changed, 170 insertions, 163 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..938a4ef --- /dev/null +++ b/README.md @@ -0,0 +1,169 @@ +# Awards + +Adds achievements to Minetest (plus a very good API). + +by [rubenwardy](https://rubenwardy.com), +with thanks to Wuzzy, kaeza, and MrIbby. + +Majority of awards are back ported from Calinou's old fork in Carbone, under same license. + +# API + +## Registering Achievements + +```lua +awards.register_achievement(name, { + description = "The title of the award", + + -- Optional: + + sound = {}, -- SimpleSoundSpec or false to play no sound + -- if not provided, uses default sound + image = "icon_image.png", -- uses default icon otherwise + background = "background_image.png", -- uses default background otherwise + + trigger = { -- is only unlocked by direct calls to awards.unlock() otherwise + type = "trigger_type", + -- see specific docs on the trigger to see what else goes here + } +}) +``` + +## Registering Trigger Types + +```lua +local trigger = awards.register_trigger(name, { + type = "", -- type of trigger, defaults to custom + + progress = "%2/%2" + auto_description = { "Mine: @2", "Mine: @1×@2" }, + + on_register = function(self, def) end + + -- "counted_key" only, when no key is given (ie: a total) + auto_description_total = { "Mine @1 block.", "Mine @1 blocks." }, + + -- "counted_key" only, get key for particular award - return nil for a total + get_key = function(self, def) + return minetest.registered_aliases[def.trigger.node] or def.trigger.node + end +}) +``` + +Types: + +* "custom" requires you handle the calling of awards.unlock() yourself. You also + need to implement on_register() yourself. +* "counted" stores a single counter for each player which is incremented by calling + trigger:notify(player). Good for homogenous actions like number of chat messages, + joins, and the like. +* "counted_key" stores a table of counters each indexed by a key. There is also + a total field (`__total`) which stores the sum of all counters. A counter is + incremented by calling trigger:notify(player, key). This is good for things like + placing nodes or crafting items, where the key will be the item or node name. + + +## Helper Functions + +* awards.register_on_unlock(func(name, def)) + * name is the player name + * def is the award def. + * return true to cancel HUD + +* awards.unlock(name, award) + * gives an award to a player + * name is the player name + +# Included in the Mod + +The API, above, allows you to register awards +and triggers (things that look for events and unlock awards, they need +to be registered in order to get details from award_def.trigger). + +However, all awards and triggers are separate from the API. +They can be found in init.lua and triggers.lua + +## Triggers + +Callbacks (register a function to be run) + +"dig", "place", "craft", "death", "chat", "join" or "eat" +* dig type: Dig a node. + * node: the dug node type. If nil, all dug nodes are counted +* place type: Place a node. + * node: the placed node type. If nil, all placed nodes are counted +* eat type: Eat an item. + * item: the eaten item type. If nil, all eaten items are counted +* craft type: Craft something. + * item: the crafted item type. If nil, all crafted items are counted +* death type: Die. +* chat type: Write a chat message. +* join type: Join the server. +* (for all types) target - how many times to dig/place/craft/etc. +* See Triggers + +### dig + + trigger = { + type = "dig", + node = "default:dirt", + target = 50 + } + +### place + + trigger = { + type = "place", + node = "default:dirt", + target = 50 + } + +### death + + trigger = { + type = "death", + target = 5 + } + +### chat + + trigger = { + type = "chat", + target = 100 + } + +### join + + trigger = { + type = "join", + target = 100 + } + +### eat + + trigger = { + type = "eat", + item = "default:apple", + target = 100 + } + +## Callbacks relating to triggers + +* awards.register_on_dig(func(player, data)) + * data is player data (see below) + * return award name or null +* awards.register_on_place(func(player, data)) + * data is player data (see below) + * return award name or null +* awards.register_on_eat(func(player, data)) + * data is player data (see below) + * return award name or null +* awards.register_on_death(func(player, data)) + * data is player data (see below) + * return award name or null +* awards.register_on_chat(func(player, data)) + * data is player data (see below) + * return award name or null +* awards.register_on_join(func(player, data) + * data is player data (see below) + * return award name or null @@ -174,6 +174,7 @@ function awards.register_trigger(tname, tdef) -- Backwards compat awards.on[tname] = tdef.on awards['register_on_' .. tname] = tdef.register + return tdef end function awards.increment_item_counter(data, field, itemname, count) diff --git a/readme.md b/readme.md deleted file mode 100644 index 6fbfee4..0000000 --- a/readme.md +++ /dev/null @@ -1,163 +0,0 @@ -# Awards - -by [rubenwardy](https://rubenwardy.com), with lots of awesome contributions -from Wuzzy, kaeza, MrIbby, and Traxie21. - -This mod adds achievements to Minetest. - -Majority of awards are back ported from Calinou's -old fork in Carbone, under same license. - - -# Basic API - -* awards.register_achievement(name, def) - * name - * desciption - * sound [optional] - set a custom sound (SimpleSoundSpec) or `false` to play no sound. - If not specified, a default sound is played - * image [optional] - texture name, eg: award_one.png - * background [optional] - texture name, eg: award_one.png - * trigger [optional] [table] - * type - "dig", "place", "craft", "death", "chat", "join" or "eat" - * dig type: Dig a node. - * node: the dug node type. If nil, all dug nodes are counted - * place type: Place a node. - * node: the placed node type. If nil, all placed nodes are counted - * eat type: Eat an item. - * item: the eaten item type. If nil, all eaten items are counted - * craft type: Craft something. - * item: the crafted item type. If nil, all crafted items are counted - * death type: Die. - * chat type: Write a chat message. - * join type: Join the server. - * (for all types) target - how many times to dig/place/craft/etc. - * See Triggers - * secret [optional] - if true, then player needs to unlock to find out what it is. - * on_unlock [optional] - func(name, def) - * name is player name - * return true to cancel register_on_unlock callbacks and HUD -* awards.register_trigger(name, func(awardname, def)) - * Note: awards.on[name] is automatically created for triggers -* awards.run_trigger_callbacks(player, data, trigger, table_func(entry)) - * Goes through and checks all triggers registered to a trigger type, - unlocking the award if conditions are met. - * data is the player's award data, ie: awards.player(player_name) - * trigger is the name of the trigger type. Ie: awards.on[trigger] - * table_func is called if the trigger is a table - simply return an - award name to unlock it - * See triggers.lua for examples -* awards.increment_item_counter(data, field, itemname) - * add to an item's statistic count - * for example, (data, "place", "default:stone") will add 1 to the number of - times default:stone has been placed. - * data is the player's award data, ie: awards.player(player_name) - * returns true on success, false on failure (eg: cannot get modname and item from itemname) -* awards.register_on_unlock(func(name, def)) - * name is the player name - * def is the award def. - * return true to cancel HUD -* awards.unlock(name, award) - * gives an award to a player - * name is the player name - -# Included in the Mod - -The API, above, allows you to register awards -and triggers (things that look for events and unlock awards, they need -to be registered in order to get details from award_def.trigger). - -However, all awards and triggers are separate from the API. -They can be found in init.lua and triggers.lua - -## Triggers - -Callbacks (register a function to be run) - -### dig - - trigger = { - type = "dig", - node = "default:dirt", - target = 50 - } - -### place - - trigger = { - type = "place", - node = "default:dirt", - target = 50 - } - -### death - - trigger = { - type = "death", - target = 5 - } - -### chat - - trigger = { - type = "chat", - target = 100 - } - -### join - - trigger = { - type = "join", - target = 100 - } - -### eat - - trigger = { - type = "eat", - item = "default:apple", - target = 100 - } - -## Callbacks relating to triggers - -* awards.register_on_dig(func(player, data)) - * data is player data (see below) - * return award name or null -* awards.register_on_place(func(player, data)) - * data is player data (see below) - * return award name or null -* awards.register_on_eat(func(player, data)) - * data is player data (see below) - * return award name or null -* awards.register_on_death(func(player, data)) - * data is player data (see below) - * return award name or null -* awards.register_on_chat(func(player, data)) - * data is player data (see below) - * return award name or null -* awards.register_on_join(func(player, data) - * data is player data (see below) - * return award name or null - - -# Player Data - -A list of data referenced/hashed by the player's name. -* player name - * name [string] - * count [table] - dig counter - * modname [table] - * itemname [int] - * place [table] - place counter - * modname [table] - * itemname [int] - * craft [table] - craft counter - * modname [table] - * itemname [int] - * eat [table] - eat counter - * modname [table] - * itemname [int] - * deaths - * chats - * joins |