@optolith/entity-descriptions 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.4.8](https://github.com/Optolith/entity-descriptions/compare/v0.4.7...v0.4.8) (2026-03-15)
+
+
+### Bug Fixes
+
+* render style and advanced special ability values ([d7a2a99](https://github.com/Optolith/entity-descriptions/commit/d7a2a99188976ea626e917da0085726cb02f7e26))
+
 ## [0.4.7](https://github.com/Optolith/entity-descriptions/compare/v0.4.6...v0.4.7) (2026-03-15)
 
 

package/lib/entities/activatable.d.ts

@@ -1,7 +1,10 @@
-import type { ActivatableIdentifier, AdvantageDisadvantagePrerequisites, AdventurePointsValue, ApplicableCombatTechniques, Aspect_ID, CombatSpecialAbilityUsageType, DaggerRitualCost, EnchantmentCost, Errata, GeneralPrerequisites, MagicalSignCost, Penalty, PropertyDeclaration, PublicationRefs, RatedIdentifier, SelectOptions, SpecialRule, Volume } from "optolith-database-schema/gen";
+import type { ActivatableIdentifier, AdvancedSpecialAbility, AdvantageDisadvantagePrerequisites, AdventurePointsValue, ApplicableCombatTechniques, Aspect_ID, CombatSpecialAbilityUsageType, DaggerRitualCost, EnchantmentCost, Errata, GeneralPrerequisites, MagicalSignCost, Penalty, PropertyDeclaration, PublicationRefs, RatedIdentifier, SelectOptions, SpecialRule, Volume } from "optolith-database-schema/gen";
+import { Case } from "tsondb/schema/gen";
 import type { GetAllInstances, GetInstanceById } from "../helpers/getTypes.js";
 import type { GetAllResolvedNewSkillApplications, GetAllResolvedSelectOptions, GetAllResolvedSkillUses } from "../index.js";
-import type { GetResolvedSelectOptionById } from "./partial/prerequisites/single/activatable.js";
+import { type GetResolvedSelectOptionById } from "./partial/prerequisites/single/activatable.js";
+type AdvancedSpecialAbilityKind = "AdvancedSkillSpecialAbility" | "AdvancedCombatSpecialAbility" | "AdvancedMagicalSpecialAbility" | "AdvancedKarmaSpecialAbility";
+type AdvancedIdentifierSpecialAbility = string | Case<AdvancedSpecialAbilityKind, string>;
 /**
  * The base fields for a special ability entity in the database.
  */
@@ -10,6 +13,7 @@ export type BaseActivatable = {
     maximum?: number;
     select_options?: SelectOptions;
     usage_type?: CombatSpecialAbilityUsageType;
+    advanced?: AdvancedSpecialAbility<AdvancedIdentifierSpecialAbility>[];
     penalty?: Penalty;
     combat_techniques?: ApplicableCombatTechniques;
     volume?: Volume;
@@ -43,10 +47,11 @@ export type BaseActivatableTranslation = {
  * Get a JSON representation of the rules text for a special ability.
  */
 export declare const getActivatableEntityDescription: import("../creator.js").EntityDescriptionCreator<"Advantage" | "Disadvantage" | "AdvancedCombatSpecialAbility" | "AdvancedKarmaSpecialAbility" | "AdvancedMagicalSpecialAbility" | "AdvancedSkillSpecialAbility" | "AncestorGlyph" | "ArcaneOrbEnchantment" | "AttireEnchantment" | "Beutelzauber" | "BlessedTradition" | "BowlEnchantment" | "BrawlingSpecialAbility" | "CauldronEnchantment" | "CeremonialItemSpecialAbility" | "ChronicleEnchantment" | "CombatSpecialAbility" | "CombatStyleSpecialAbility" | "CommandSpecialAbility" | "DaggerRitual" | "FamiliarSpecialAbility" | "FatePointSexSpecialAbility" | "FatePointSpecialAbility" | "FoolsHatEnchantment" | "GeneralSpecialAbility" | "Haubenzauber" | "InstrumentEnchantment" | "KarmaSpecialAbility" | "Krallenkettenzauber" | "Kristallkugelzauber" | "LiturgicalStyleSpecialAbility" | "LycantropicGift" | "MagicalSign" | "MagicalSpecialAbility" | "MagicalTradition" | "MagicStyleSpecialAbility" | "OrbEnchantment" | "PactGift" | "ProtectiveWardingCircleSpecialAbility" | "RingEnchantment" | "Sermon" | "SexSpecialAbility" | "SickleRitual" | "SikaryanDrainSpecialAbility" | "SkillStyleSpecialAbility" | "SpellSwordEnchantment" | "StaffEnchantment" | "ToyEnchantment" | "Trinkhornzauber" | "VampiricGift" | "Vision" | "WandEnchantment" | "WeaponEnchantment", {
-    getInstanceById: GetInstanceById<"Publication" | "Subject" | ActivatableIdentifier["kind"] | RatedIdentifier["kind"] | "TradeSecret" | "Aspect" | "Property" | "Race" | "Culture" | "State" | "Enhancement" | "PactCategory" | "PactDomain" | "SocialStatus" | "Weapon">;
+    getInstanceById: GetInstanceById<"Publication" | "Subject" | ActivatableIdentifier["kind"] | RatedIdentifier["kind"] | "TradeSecret" | "Aspect" | "Property" | "Race" | "Culture" | "State" | "Enhancement" | "PactCategory" | "PactDomain" | "SocialStatus" | "Weapon" | "Patron">;
     getAllInstances: GetAllInstances<"Script">;
     getResolvedSelectOptionById: GetResolvedSelectOptionById;
     getAllResolvedSelectOptions: GetAllResolvedSelectOptions;
     getAllResolvedNewSkillApplications: GetAllResolvedNewSkillApplications;
     getAllResolvedSkillUses: GetAllResolvedSkillUses;
 }, import("../index.js").EntityDescription>;
+export {};

package/lib/entities/activatable.js

@@ -1,3 +1,6 @@
+import { isNotEmpty } from "@elyukai/utils/array/nonEmpty";
+import { count } from "@elyukai/utils/array/reductions";
+import { deepEqual } from "@elyukai/utils/equality";
 import { on } from "@elyukai/utils/function";
 import { isNotNullish } from "@elyukai/utils/nullable";
 import { numAsc } from "@optolith/helpers/compare";
@@ -7,14 +10,24 @@ import { romanize } from "@optolith/helpers/roman";
 import { assertExhaustive } from "@optolith/helpers/typeSafety";
 import { Case, fromUniformCase } from "tsondb/schema/gen";
 import { createEntityDescriptionCreator } from "../creator.js";
+import { renderActivatableNameComponents } from "./partial/activatableNameChunks.js";
 import { renderAdventurePointsValue } from "./partial/adventurePointsValue.js";
 import { renderResponsiveMap } from "./partial/map.js";
 import { additionFormatter } from "./partial/mathOperation.js";
 import { printAdvantageDisadvantagePrerequisites, printGeneralPrerequisites, } from "./partial/prerequisites/index.js";
+import { printActivatableName, } from "./partial/prerequisites/single/activatable.js";
 import { parensIf } from "./partial/rated/activatable/parensIf.js";
 import { getResponsiveText, getResponsiveTextOptional, ResponsiveTextSize, } from "./partial/responsiveText.js";
 import { formatTimeSpan } from "./partial/units/timeSpan.js";
 import { MISSING_VALUE } from "./partial/unknown.js";
+const isStyleSpecialAbilityKind = (value) => value === "SkillStyleSpecialAbility" ||
+    value === "CombatStyleSpecialAbility" ||
+    value === "MagicStyleSpecialAbility" ||
+    value === "LiturgicalStyleSpecialAbility";
+const isAdvancedSpecialAbilityKind = (value) => value === "AdvancedSkillSpecialAbility" ||
+    value === "AdvancedCombatSpecialAbility" ||
+    value === "AdvancedMagicalSpecialAbility" ||
+    value === "AdvancedKarmaSpecialAbility";
 const renderPropertyValue = (getInstanceById, translate, translateMap, propertyDecl) => {
     switch (propertyDecl.kind) {
         case "DependingOnSelection":
@@ -460,6 +473,155 @@ const renderCost = (translate, translateMap, localeJoin, localeCompare, getAllRe
             return assertExhaustive(cost);
     }
 };
+const renderAdvancedLabel = (translate, entityName) => {
+    switch (entityName) {
+        case "SkillStyleSpecialAbility":
+            return translate("Advanced Skill Special Abilities");
+        case "CombatStyleSpecialAbility":
+            return translate("Advanced Combat Special Abilities");
+        case "MagicStyleSpecialAbility":
+            return translate("Advanced Magical Special Abilities");
+        case "LiturgicalStyleSpecialAbility":
+            return translate("Advanced Karma Special Abilities");
+        default:
+            return assertExhaustive(entityName);
+    }
+};
+const normalizeId = (entityName, id) => {
+    if (typeof id === "string") {
+        switch (entityName) {
+            case "SkillStyleSpecialAbility":
+                return Case("AdvancedSkillSpecialAbility", id);
+            case "CombatStyleSpecialAbility":
+                return Case("AdvancedCombatSpecialAbility", id);
+            case "MagicStyleSpecialAbility":
+                return Case("AdvancedMagicalSpecialAbility", id);
+            case "LiturgicalStyleSpecialAbility":
+                return Case("AdvancedKarmaSpecialAbility", id);
+            default:
+                return assertExhaustive(entityName);
+        }
+    }
+    else {
+        return id;
+    }
+};
+const renderAdvancedSpecialAbilityName = (translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, id, option) => {
+    const normalizedId = normalizeId(entityName, id);
+    return `^[${mapNullable(printActivatableName(getInstanceById, translate, normalizedId, option, undefined, getResolvedSelectOptionById, false), name => renderActivatableNameComponents(translateMap, name, false)) ?? MISSING_VALUE}](entity: "${normalizedId.kind}", instance: "${fromUniformCase(normalizedId)}", style: "normal")`;
+};
+const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceById, getResolvedSelectOptionById, entityName, advanced) => {
+    if (advanced.every(entry => entry.kind === "OneOf") &&
+        isNotEmpty(advanced) &&
+        advanced.every(entry => entry.OneOf.options.length === 3)) {
+        const optionsInAllEntries = advanced[0].OneOf.options.filter(option => advanced.every(otherEntry => otherEntry.OneOf.options.some(otherOption => deepEqual(option, otherOption))));
+        if (optionsInAllEntries.length === 2) {
+            const uniqueOptions = advanced
+                .map(entry => entry.OneOf.options.find(option => optionsInAllEntries.every(commonOption => !deepEqual(option, commonOption))))
+                .filter(isNotNullish); // should not do anything, just for type narrowing
+            if (uniqueOptions.length === advanced.length) {
+                const [first, second] = optionsInAllEntries.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option));
+                return [
+                    ...uniqueOptions.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option)),
+                    translate("one or two of these special abilities can alternatively be replaced by advanced special abilities {$first} and/or {$second}", { first, second }),
+                ].join(", ");
+            }
+        }
+    }
+    const derivedFromExternalOptionEntriesToGenerate = count(advanced, entry => entry.kind === "DeriveFromExternalOption" &&
+        entry.DeriveFromExternalOption.display_option === undefined);
+    return [
+        ...advanced.map((entry) => {
+            switch (entry.kind) {
+                case "General":
+                    return renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.General);
+                case "RestrictOptions":
+                    return renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.RestrictOptions.id, entry.RestrictOptions.option);
+                case "OneOf": {
+                    if (entry.OneOf.display_option !== undefined) {
+                        switch (entry.OneOf.display_option.kind) {
+                            case "Hide":
+                                return undefined;
+                            case "ReplaceWith":
+                                return (translateMap(entry.OneOf.display_option.ReplaceWith.translations)?.replacement ??
+                                    MISSING_VALUE);
+                            default:
+                                return assertExhaustive(entry.OneOf.display_option);
+                        }
+                    }
+                    return localeJoin(entry.OneOf.options.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option)), "disjunction");
+                }
+                case "DeriveFromExternalOption":
+                    if (entry.DeriveFromExternalOption.display_option !== undefined) {
+                        switch (entry.DeriveFromExternalOption.display_option.kind) {
+                            case "Hide":
+                                return undefined;
+                            case "ReplaceWith":
+                                return (translateMap(entry.DeriveFromExternalOption.display_option.ReplaceWith.translations)?.replacement ?? MISSING_VALUE);
+                            default:
+                                return assertExhaustive(entry.DeriveFromExternalOption.display_option);
+                        }
+                    }
+                    return undefined;
+                default:
+                    return assertExhaustive(entry);
+            }
+        }),
+        derivedFromExternalOptionEntriesToGenerate === 0
+            ? undefined
+            : translate(".input {$count :number} {{{$count} more by primary patron}}", {
+                count: derivedFromExternalOptionEntriesToGenerate,
+            }),
+    ]
+        .filter(isNotNullish)
+        .join(", ");
+};
+const renderDeriveFromExternalOptionTable = (translate, translateMap, localeCompare, getInstanceById, getResolvedSelectOptionById, entityName, advanced) => {
+    if (!isStyleSpecialAbilityKind(entityName)) {
+        return undefined;
+    }
+    const derivedFromExternalOptionEntriesToGenerate = advanced.filter((entry) => entry.kind === "DeriveFromExternalOption" &&
+        entry.DeriveFromExternalOption.display_option === undefined);
+    if (derivedFromExternalOptionEntriesToGenerate.length === 0) {
+        return undefined;
+    }
+    const rows = Map.groupBy(derivedFromExternalOptionEntriesToGenerate.flatMap(entry => entry.DeriveFromExternalOption.map.map((option) => [
+        option.from_option,
+        option.to_advanced,
+    ])), row => row[0])
+        .entries()
+        .map(([option, list]) => [
+        translateMap(getInstanceById("Patron", option)?.translations)?.name ?? MISSING_VALUE,
+        list
+            .map(([, toAdvanced]) => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, toAdvanced))
+            .toSorted(localeCompare)
+            .join(", "),
+    ])
+        .toArray()
+        .toSorted(on(row => row[0], localeCompare));
+    return {
+        type: "table",
+        header: [translate("Patron"), renderAdvancedLabel(translate, entityName)],
+        rows,
+    };
+};
+const renderTrailingAdvancedPrerequisitesNote = (translate, entityName) => {
+    if (isAdvancedSpecialAbilityKind(entityName)) {
+        switch (entityName) {
+            case "AdvancedCombatSpecialAbility":
+                return translate("corresponding combat style special ability");
+            case "AdvancedKarmaSpecialAbility":
+                return translate("corresponding liturgical style special ability");
+            case "AdvancedMagicalSpecialAbility":
+                return translate("corresponding magic style special ability");
+            case "AdvancedSkillSpecialAbility":
+                return translate("corresponding skill style special ability");
+            default:
+                return assertExhaustive(entityName);
+        }
+    }
+    return undefined;
+};
 /**
  * Get a JSON representation of the rules text for a special ability.
  */
@@ -526,18 +688,24 @@ export const getActivatableEntityDescription = createEntityDescriptionCreator(({
                         label: translate("Range"),
                         value: range,
                     })),
+                    mapNullable(baseEntry.advanced, advanced => isStyleSpecialAbilityKind(entityName)
+                        ? {
+                            label: renderAdvancedLabel(translate, entityName),
+                            value: renderAdvancedValue(translate, translateMap, locale.join, getInstanceById, getResolvedSelectOptionById, entityName, advanced),
+                        }
+                        : undefined),
                     mapNullable(baseEntry.penalty, penalty => ({
                         label: translate("Penalty"),
                         value: renderPenaltyValue(getInstanceById, translate, translateMap, translation.name, penalty),
                     })),
-                    mapNullable(entry.prerequisites, prerequisites => ({
+                    mapNullable(entry.prerequisites ?? (isAdvancedSpecialAbilityKind(entityName) ? [] : undefined), prerequisites => ({
                         label: translate("Prerequisites"),
                         value: wrappedId.kind === "Advantage" || wrappedId.kind === "Disadvantage"
                             ? printAdvantageDisadvantagePrerequisites(getInstanceById, getResolvedSelectOptionById, locale, prerequisites, translation.name, wrappedId.kind)
                             : printGeneralPrerequisites(getInstanceById, getResolvedSelectOptionById, locale, prerequisites, mapNullable(baseEntry.levels, levels => ({
                                 id: wrappedId,
                                 levels,
-                            }))),
+                            })), renderTrailingAdvancedPrerequisitesNote(translate, entityName)),
                     })),
                     mapNullable(baseEntry.combat_techniques, combatTechniques => ({
                         label: translate("Combat Techniques"),
@@ -573,6 +741,7 @@ export const getActivatableEntityDescription = createEntityDescriptionCreator(({
                     }),
                 ],
             },
+            renderDeriveFromExternalOptionTable(translate, translateMap, locale.compare, getInstanceById, getResolvedSelectOptionById, entityName, baseEntry.advanced ?? []),
         ],
         errata: translation.errata,
         references: entry.src,

package/lib/entities/partial/prerequisites/index.d.ts

@@ -20,7 +20,7 @@ export declare const printPlainGeneralPrerequisites: (getInstanceById: GetInstan
 export declare const printGeneralPrerequisites: (getInstanceById: GetInstanceById<"Race" | "Culture" | "PactCategory" | "PactDomain" | "SocialStatus" | "State" | ActivatableIdentifier["kind"] | RatedIdentifier["kind"] | "Property" | "Aspect" | "Enhancement">, getResolvedSelectOptionById: GetResolvedSelectOptionById, locale: LocaleEnvironment, value: GeneralPrerequisites, printPreviousLevelPrerequisites?: {
     id: SpecialAbilityIdentifier;
     levels: number;
-}) => string;
+}, trailingText?: string) => string;
 /**
  * Print profession prerequisites as a string.
  */

package/lib/entities/partial/prerequisites/index.js

@@ -78,7 +78,7 @@ const printPrerequisiteForLevel = (printPrerequisite, locale, value) => printPre
 /**
  * Print prerequisites for levels as a string.
  */
-const printPrerequisitesForLevels = (printPrerequisite, locale, value, printPreviousLevelPrerequisites) => {
+const printPrerequisitesForLevels = (printPrerequisite, locale, value, printPreviousLevelPrerequisites, trailingText) => {
     const previousLevelPrerequisites = printPreviousLevelPrerequisites === undefined
         ? []
         : Array.from({ length: printPreviousLevelPrerequisites.levels - 1 }, (_, i) => ({
@@ -89,6 +89,9 @@ const printPrerequisitesForLevels = (printPrerequisite, locale, value, printPrev
             },
         }));
     const groupedByLevel = Map.groupBy([...value, ...previousLevelPrerequisites], prerequisite => prerequisite.level);
+    if (trailingText !== undefined && !groupedByLevel.has(1)) {
+        groupedByLevel.set(1, []);
+    }
     const hasBasePrerequisites = groupedByLevel.has(1);
     const sortedByLevel = groupedByLevel
         .entries()
@@ -104,14 +107,24 @@ const printPrerequisitesForLevels = (printPrerequisite, locale, value, printPrev
                 })}: ${locale.translate("none")}`,
             ]),
         ...sortedByLevel.map(([levelNumber, prerequisites]) => {
-            const prerequisitesString = joinPrerequisiteParts(locale.translate, locale.translateMap, locale.compare, prerequisites
-                .map(element => mapNullable(printPrerequisiteForLevel(printPrerequisite, locale, element), part => ({
-                type: element.prerequisite.kind === "Single"
-                    ? element.prerequisite.Single.kind
-                    : element.prerequisite.kind,
-                part,
-            })))
-                .filter(isNotNullish));
+            const prerequisitesString = joinPrerequisiteParts(locale.translate, locale.translateMap, locale.compare, [
+                ...prerequisites
+                    .map(element => mapNullable(printPrerequisiteForLevel(printPrerequisite, locale, element), part => ({
+                    type: element.prerequisite.kind === "Single"
+                        ? element.prerequisite.Single.kind
+                        : element.prerequisite.kind,
+                    part,
+                })))
+                    .filter(isNotNullish),
+                ...(levelNumber === 1 && trailingText !== undefined
+                    ? [
+                        {
+                            type: "trailing",
+                            part: { value: trailingText, sentenceType: undefined, isMeta: false },
+                        },
+                    ]
+                    : []),
+            ]);
             return hasOnlyBasePrerequisites
                 ? prerequisitesString
                 : `${locale.translate("Level {$level}", {
@@ -136,7 +149,7 @@ export const printPlainGeneralPrerequisites = (getInstanceById, getResolvedSelec
 /**
  * Print general prerequisites as a string.
  */
-export const printGeneralPrerequisites = (getInstanceById, getResolvedSelectOptionById, locale, value, printPreviousLevelPrerequisites) => printPrerequisitesForLevels(prerequisite => printGeneralPrerequisiteGroup(getInstanceById, getResolvedSelectOptionById, locale, prerequisite), locale, value, printPreviousLevelPrerequisites === undefined
+export const printGeneralPrerequisites = (getInstanceById, getResolvedSelectOptionById, locale, value, printPreviousLevelPrerequisites, trailingText) => printPrerequisitesForLevels(prerequisite => printGeneralPrerequisiteGroup(getInstanceById, getResolvedSelectOptionById, locale, prerequisite), locale, value, printPreviousLevelPrerequisites === undefined
     ? undefined
     : {
         levels: printPreviousLevelPrerequisites.levels,
@@ -148,7 +161,7 @@ export const printGeneralPrerequisites = (getInstanceById, getResolvedSelectOpti
                 level,
             },
         }),
-    });
+    }, trailingText);
 /**
  * Print profession prerequisites as a string.
  */

package/lib/entities/partial/unknown.d.ts

@@ -5,4 +5,4 @@ export declare const MISSING_VALUE = "###MISSING###";
 /**
  * String to display when a translation that should be present produces an error.
  */
-export declare const UNHANDLED_VALUE = "###UNHANDLED_ERROR###";
+export declare const UNHANDLED_VALUE = "###UNHANDLEDERROR###";

package/lib/entities/partial/unknown.js

@@ -5,4 +5,4 @@ export const MISSING_VALUE = "###MISSING###";
 /**
  * String to display when a translation that should be present produces an error.
  */
-export const UNHANDLED_VALUE = "###UNHANDLED_ERROR###";
+export const UNHANDLED_VALUE = "###UNHANDLEDERROR###";