From d7c2257c1fdfe145e0d88ce083ef11ab064b8a5f Mon Sep 17 00:00:00 2001
From: Wuzzy <Wuzzy@disroot.org>
Date: Tue, 7 Jun 2022 16:11:10 +0200
Subject: [PATCH] Update rp_achievements documentation

---
 mods/rp_achievements/API.md | 63 ++++++++++++++++++++++++++++++-------
 1 file changed, 51 insertions(+), 12 deletions(-)

diff --git a/mods/rp_achievements/API.md b/mods/rp_achievements/API.md
index 26d6a68..8128cd0 100644
--- a/mods/rp_achievements/API.md
+++ b/mods/rp_achievements/API.md
@@ -3,9 +3,18 @@
 ## Introduction
 
 Each achievement must have an unique `name` which is the internal identifier.
-Achievements can get triggered manually with `achievements.trigger_achievement`,
-or automatically. Achievements get awarded when they have been triggered
-enough, as specified by `times` in the achievements definition.
+There are two types of achievements:
+
+Trigger achievements and subcondition achievements.
+
+Trigger achievements count the number of times they are triggered.
+They are completed when the threshold of triggers has been met (`times`
+parameter). Trigger achievements can be triggered automatically
+or manually.
+
+Subcondition achievements have a list of subconditions that must all
+be triggered to complete the achievement. These achievements can
+only be triggered manually.
 
 ## Functions
 
@@ -17,13 +26,23 @@ Registers an achievement.
 * `def`: Achievement definition. This is a table:
     * `title`: Title, as shown to the player (default: same as `name`)
     * `description`: Short (!) description that tells the player what to do to get the achievement
-    * `times`: How many times to trigger this achievement before awarding it (default: 1)
-    * `dignode`: Trigger achievement when this node has been dug
-    * `placenode`: Trigger achievement when this node has been placed
-    * `craftitem`: Trigger achievement when this item has been crafted (needs to match
       crafting output identifier as provided to the `rp_crafting` mod)
     * `icon`: Optional icon (texture name)
     * `item_icon`: Optional icon (texture name)
+    * Additional fields depending on the type (see below)
+
+If neither `icon` nor `item_icon` are present, this mod will pick an icon automatically
+by using the item icon of `dignode`, `placenode` or `craftitem`. If those fields
+are not present, or use groups, a generic trophy icon will be used instead.
+
+#### Trigger achievements
+
+For trigger achievements, use these additional fields for `def`:
+
+* `times`: How many times to trigger this achievement before awarding it (default: 1)
+* `dignode`: Trigger achievement when this node has been dug
+* `placenode`: Trigger achievement when this node has been placed
+* `craftitem`: Trigger achievement when this item has been crafted
 
 Both `dignode` and `placenode` support the `group:<groupname>` syntax to check
 for digging/placing a node in a given group instead.
@@ -32,17 +51,37 @@ If neither `dignode`, `placenode`, nor `craftitem` are present, the achievement
 will not be triggered automatically. You can always trigger an achievement
 manually with `achievements.trigger_achievement`.
 
-If neither `icon` nor `item_icon` are present, this mod will pick an icon automatically
-by using the item icon of `dignode`, `placenode` or `craftitem`. If those fields
-are not present, or use groups, a generic trophy icon will be used instead.
+A trigger achievement must be triggered `times` times to be completed.
 
-Note: Any item specified in `def` *must* have been registered before registering
+Note: Any item specified here **must** have been registered *before* registering
 the achievement.
 
+#### Subcondition achievements
+
+For subconditoin achievements, use this additional field for `def`:
+
+* `subconditions`: List of subcondition identifiers (as strings). Put all
+  the required subconditions here. NOT translatable!
+* `subconditions_readable`: Optional. List of subcondition names as shown
+  to the player. The table keys must correspond with the keys in
+  `subconditions`. If this field is missing, the GUI will use the IDs
+  instead.
+
+Use `achievements.trigger_subcondition` to mark a subcondition as complete.
+
 ### `achievements.trigger_achievement(player, name, times)`
 
 Manually trigger an achievement once or multiple times.
 
-* `name`: Achievement identifier
 * `player`: Player to trigger the achievement for
+* `name`: Achievement identifier
 * `times`: How many times to trigger the achievement (default: 1)
+
+### `achievements.trigger_subcondition(player, name, subcondition)`
+
+Mark a subcondition of an achievement as completed.
+
+* `player`: Player to trigger the achievement subcondition for
+* `name`: Achievement identifier
+* `subcondition`: Identifier of subcondition to mark as complete
+