Update README.md

This commit is contained in:
rubenwardy 2018-04-04 18:02:43 +01:00
parent 72cc346c35
commit d82972b448
3 changed files with 170 additions and 163 deletions

169
README.md Normal file

@ -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 -- Backwards compat
awards.on[tname] = tdef.on awards.on[tname] = tdef.on
awards['register_on_' .. tname] = tdef.register awards['register_on_' .. tname] = tdef.register
return tdef
end end
function awards.increment_item_counter(data, field, itemname, count) function awards.increment_item_counter(data, field, itemname, count)

163
readme.md

@ -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