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