forked from mtcontrib/awards
Update README.md
This commit is contained in:
rubenwardy
parent
72cc346c35
commit
d82972b448
169
README.md
Normal file
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
|
||||
1
api.lua
1
api.lua
@ -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)
|
||||
|
||||
163
readme.md
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
|
||||
Loading…
Reference in New Issue
Block a user