Document achievements feature

docs/guide/creating-bots.md

@@ -229,6 +229,58 @@ Make a built-in MCC chat bot named AutoTorch and wire it fully into the repo con
 Create a standalone MCC /script bot that follows private messages, uses GetVerbatim(text), and replies only to bot owners. Use the mcc-chatbot-authoring skill.
 ```
 
+## Achievements And Advancements
+
+Chat bots and C# scripts can read the current achievement state and react to updates.
+
+Useful methods:
+
+- `GetAchievements()`
+- `GetUnlockedAchievements()`
+- `GetLockedAchievements()`
+- `OnAchievementUpdate(IReadOnlyList<Achievement> updated, IReadOnlyList<string> removedIds, bool reset)`
+
+Things worth knowing:
+
+- On `1.8` to `1.11.2`, ids use the legacy `achievement.*` format.
+- On `1.12+`, ids use advancement resource ids such as `minecraft:story/root`.
+- Legacy achievements usually have `Title = null` and `Description = null` because the server does not send display metadata in the statistics packet.
+- On newer versions, revoking an advancement may remove it from the current set instead of turning it into a locked entry, so `removedIds` matters.
+
+Example:
+
+```csharp
+//MCCScript 1.0
+
+MCC.LoadBot(new AchievementWatcher());
+
+//MCCScript Extensions
+
+public class AchievementWatcher : ChatBot
+{
+    public override void AfterGameJoined()
+    {
+        Achievement[] known = GetAchievements();
+        LogToConsole($"Known achievements: {known.Length}");
+    }
+
+    public override void OnAchievementUpdate(IReadOnlyList<Achievement> updated, IReadOnlyList<string> removedIds, bool reset)
+    {
+        LogToConsole($"Achievement update: reset={reset}, updated={updated.Count}, removed={removedIds.Count}");
+
+        foreach (Achievement achievement in updated)
+        {
+            string title = achievement.Title ?? achievement.Id;
+            string state = achievement.IsCompleted ? "done" : "todo";
+            LogToConsole($" - {title}: {state}");
+        }
+
+        foreach (string removedId in removedIds)
+            LogToConsole($" - removed: {removedId}");
+    }
+}
+```
+
 ## C# API
 
 The authoritative reference for the C# API is [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs).

docs/guide/usage.md

@@ -219,6 +219,54 @@ In scripts and remote control, no slash is needed to perform the command, eg. `q
 
 </details>
 
+<details>
+<summary><code>achievement</code></summary>
+
+- **Description:**
+
+  Show the achievements or advancements currently known to MCC.
+
+  On Minecraft `1.8` to `1.11.2`, MCC tracks legacy achievements such as `achievement.openInventory`.
+
+  On Minecraft `1.12+`, MCC tracks advancements such as `minecraft:story/root`.
+
+- **Usage:**
+
+  ```
+  /achievement
+  /achievement list
+  /achievement locked
+  /achievement unlocked
+  ```
+
+- **Examples:**
+
+  List everything MCC currently knows:
+
+  ```
+  /achievement
+  ```
+
+  Show only incomplete entries:
+
+  ```
+  /achievement locked
+  ```
+
+  Show only completed entries:
+
+  ```
+  /achievement unlocked
+  ```
+
+- **Notes:**
+
+  The command only shows data the server has already sent to MCC.
+
+  Legacy achievements do not include titles or descriptions in the protocol, so older servers usually show the raw id instead.
+
+</details>
+
 <details>
 <summary><code>bed</code></summary>