From ec131fe7cbb66127b4a28100f7169d7f63957586 Mon Sep 17 00:00:00 2001
From: Yair Morgenstern <yairm210@hotmail.com>
Date: Sat, 9 Mar 2024 21:54:56 +0200
Subject: [PATCH] Added documentation and schemas for events

---
 .../5-Miscellaneous-JSON-files.md             | 19 +++++++++++
 docs/Modders/Type-checking.md                 |  7 ++++
 docs/Modders/schemas/events.json              | 32 +++++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 docs/Modders/schemas/events.json

diff --git a/docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md b/docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md
index ead79091b8..6ddea1b357 100644
--- a/docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md
+++ b/docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md
@@ -114,6 +114,25 @@ The code below is an example of a valid "turns" definition and it specifies that
 ]
 ```
 
+## Events.json
+
+Events allow users to choose between options of triggers to activate.
+
+| Attribute | Type                 | Default  | Notes                                                     |
+|-----------|----------------------|----------|-----------------------------------------------------------|
+| name      | String               | Required | Used for triggering via "Triggers a [event] event" unique |
+| text      | String               | None     | Flavor text displayed to user                             |
+| choices   | List of EventChoices |          | User can choose to trigger one of the viable choices      |
+
+Event choices are comprised of:
+
+| Attribute        | Type                        | Default    | Notes                                                         |
+|------------------|-----------------------------|------------|---------------------------------------------------------------|
+| text             | String                      | Required   | Displayed to user. Should be an action name - "Do X"          |
+| triggeredUniques | List of trigger uniques     | Required   | The triggers that this choice activates upon being chosen     |
+| conditions       | List of conditional uniques | Empty list | If any conditional is not met, this option becomes unpickable |
+
+
 ## ModOptions.json
 
 <!-- [Link to original](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons/Civ%20V%20-%20Gods%20&%20Kings/ModOptions.json) -->
diff --git a/docs/Modders/Type-checking.md b/docs/Modders/Type-checking.md
index 85c3d3ed4a..f94b965e83 100644
--- a/docs/Modders/Type-checking.md
+++ b/docs/Modders/Type-checking.md
@@ -66,6 +66,13 @@ Tada! Now Android Studio will recognize all Buildings.json files as belonging to
             ],
             "url": "https://raw.githubusercontent.com/yairm210/Unciv/master/docs/Modders/schemas/tileResources.json"
         }
+        ,
+        {
+            "fileMatch": [
+              "*/Events.json"
+            ],
+            "url": "https://raw.githubusercontent.com/yairm210/Unciv/master/docs/Modders/schemas/events.json"
+        }
     ]
 ```
 
diff --git a/docs/Modders/schemas/events.json b/docs/Modders/schemas/events.json
new file mode 100644
index 0000000000..d1351f22cd
--- /dev/null
+++ b/docs/Modders/schemas/events.json
@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "type": "array",
+  "items": {
+      "type": "object",
+      "properties": {
+          "name": { "type": "string" },
+          "text": { "type": "string" },
+          "choices": {
+              "type": "array",
+              "items": {
+                  "properties": {
+                      "text": { "type": "string" },
+                      "triggeredUniques": {
+                          "$ref": "https://raw.githubusercontent.com/yairm210/Unciv/master/docs/Modders/schemas/uniques.json",
+                          "minItems": 1
+                      },
+                      "conditions": {
+                          "$ref": "https://raw.githubusercontent.com/yairm210/Unciv/master/docs/Modders/schemas/uniques.json"
+                      }
+                  },
+                  "required": ["text", "triggeredUniques"],
+                  "additionalProperties": false
+              }
+          }
+      },
+      "required": [
+          "name", "text"
+      ],
+      "additionalProperties": false
+  }
+}