From a25ec1727ac7d1d9d673e4eec5e9dde4eb9e9d65 Mon Sep 17 00:00:00 2001
From: Asriel Camora <asriel@camora.dev>
Date: Thu, 15 Aug 2024 15:01:58 -0700
Subject: [PATCH] Add relations docs

---
 README.md |  1 +
 Usage.md  | 50 +++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8695b81..1acf010 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@ The schema includes the following:
 - Comment support on any schema object
 - Maps out-of-the-box to a very simple object mapping
 - JSON schema for the schema itself, providing IDE completion and error-checking
+- Relations to group similarly sized arrays together
 
 This repository hosts the schema files for each game version. Each change produces a new release of every known game version's schema and removes the old release.
 Due to the structure of this repository, any change to a given game version is meant to supercede all others.
diff --git a/Usage.md b/Usage.md
index 722b25a..7195bc4 100644
--- a/Usage.md
+++ b/Usage.md
@@ -285,4 +285,52 @@ Yes, the `case` dictionary may contain an *array*. This means that each case can
 The `AdditionalData` column in `Item` does a lot of heavy lifting. We can assume during game execution that the use of the field is heavily based on context,
 but for research and data exploration, having the ability to define the exact sheet is useful. Here, we can see that when `FilterGroup` is `14`,
 we can link to any of `HousingExterior`, `HousingInterior`, `HousingYardObject`, `HousingFurniture`, `HousingPreset`, or finally `HousingUnitedExterior`.
-This works because the value for `AdditionalData` are distinct ranges, even when `FilterGroup` is `14`, thus allowing the definition here to behave like a multi link.
\ No newline at end of file
+This works because the value for `AdditionalData` are distinct ranges, even when `FilterGroup` is `14`, thus allowing the definition here to behave like a multi link.
+
+## Relations
+Relations are used to group different arrays together of the same size. They are supported on every sheet and in every array declaration with more than one field.
+
+To best explain relations, here's an example with `ItemFood`:
+```yml
+name: ItemFood
+fields:
+  - name: Max
+    type: array
+    count: 3
+  - name: MaxHQ
+    type: array
+    count: 3
+  - name: EXPBonusPercent
+  - name: BaseParam
+    type: array
+    count: 3
+    fields:
+      - type: link
+        targets: [BaseParam]
+  - name: Value
+    type: array
+    count: 3
+  - name: ValueHQ
+    type: array
+    count: 3
+  - name: IsRelative
+    type: array
+    count: 3
+```
+Here, `ItemFood` contains several arrays of size 3. Each index has one `BaseParam` and its accompanying `Max`, `MaxHQ`, `Value`, `ValueHQ`, and `IsRelative` values.
+These should all be related to one another, but they're instead spread out across 6 different arrays. This is a perfect example of the downsides of
+[Structs of Arrays](https://en.wikipedia.org/wiki/AoS_and_SoA), since our data is best formatted using Arrays of Structs.
+
+Using relations, we can circumvent this issue by explicitly grouping these 6 arrays together into one array with 3 structs.
+To do so, we can add the following to the end of the schema file:
+```yml
+relations:
+  Params:
+    - BaseParam
+    - IsRelative
+    - Value
+    - Max
+    - ValueHQ
+    - MaxHQ
+```
+Now, instead of accessing each array individually, `Params` is the only available field, where every element of `Params` contains all the related columns.
\ No newline at end of file