ShadowsOverWestgate/sow-tools
7
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 38 Activity

Template usage

Browse Source
This commit is contained in:
archvillainette
2026-04-10 15:26:27 +02:00
parent 9300033e95
commit ae58c4ae71
7 changed files with 492 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/topdata/PORTRAIT_METADATA_CONTRACT.md
+21 -12
View File
@@ -2,7 +2,7 @@
## Objective
Define the canonical behavior for portrait metadata embedded in topdata rows, enabling cross-dataset portrait injection into the portraits.2da table.
Define the canonical behavior for portrait metadata embedded in topdata rows, enabling explicit opt-in portrait injection into the portraits.2da table.
---
@@ -46,7 +46,13 @@ Field names are case-insensitive with hyphen/underscore normalization:
### Identity Matching
Portrait entries are matched by `resref`. When any row in any dataset carries `meta.portrait.resref`:
Portrait entries are matched by `resref`. Injection is only enabled when all of the following are true:
1. The row carries `meta.portrait.resref`
2. The row comes from a JSON module under `topdata/data/<dataset>/modules`
3. The dataset is one of `appearance`, `genericdoors`, or `placeables`
When those conditions are met:
1. If a portraits.2da row with matching `BaseResRef` already exists → merge into that row
2. If no matching row exists → create a new row with auto-generated identity `portraits:auto:<resref>`
@@ -91,14 +97,15 @@ For example: `portraits:auto:nw2book1_`
## Cross-Dataset Injection
Any dataset may contribute portrait metadata. The build pipeline:
Only module-authored rows from `appearance`, `genericdoors`, and `placeables` may contribute portrait metadata. The build pipeline:
1. Collects all datasets
2. Runs `mergePortraitMetadata()` after dataset collection
3. Injects portrait rows into the portraits.2da dataset
4. Updates lock data if new auto-generated rows were created
5. Prunes stale `portraits:auto:*` lock entries when no active auto-injected portrait row remains
This enables non-portrait datasets (e.g., placeables, genericdoors) to define portrait associations without modifying the portraits dataset directly.
This enables supported non-portrait datasets to define portrait associations without modifying the portraits dataset directly, while making the behavior explicit and removable with the originating module.
---
@@ -107,8 +114,9 @@ This enables non-portrait datasets (e.g., placeables, genericdoors) to define po
1. `resref` is required — missing resref produces a parse error
2. Unknown metadata fields in `meta.portrait` produce a parse error
3. Unknown top-level keys in `meta` produce a parse error (allowed keys: `family`, `wiki`, `portrait`)
4. Conflicting portrait field values from different contributors produce a build error
5. Portrait metadata is excluded from emitted 2DA output — it exists only at authoring/build time
4. Base rows do not inject portraits, even if they carry `meta.portrait`
5. Conflicting portrait field values from different contributors produce a build error
6. Portrait metadata is excluded from emitted 2DA output — it exists only at authoring/build time
---
@@ -117,9 +125,10 @@ This enables non-portrait datasets (e.g., placeables, genericdoors) to define po
Implementation is correct only if all of the following are true:
1. Portrait metadata is parsed from `meta.portrait` with case-insensitive field names
2. Rows with portrait metadata inject into portraits.2da by `resref` matching
3. Auto-generated rows receive `portraits:auto:<resref>` lock keys
4. First-contributor-wins precedence is enforced per column
5. Conflicting values produce build errors with clear diagnostic messages
6. Portrait metadata does not leak into emitted 2DA column output
7. Lock data is persisted when new auto-generated rows are created
2. Only module-authored rows from `appearance`, `genericdoors`, and `placeables` inject into portraits.2da by `resref` matching
3. Base rows do not trigger portrait injection
4. Auto-generated rows receive `portraits:auto:<resref>` lock keys
5. First-contributor-wins precedence is enforced per column
6. Conflicting values produce build errors with clear diagnostic messages
7. Portrait metadata does not leak into emitted 2DA column output
8. Lock data is persisted when new auto-generated rows are created and stale auto-generated keys are pruned