coh-content-db 2.0.0-rc.5 → 2.0.0-rc.6

package/README.md

@@ -25,7 +25,7 @@ that can be loaded into the db for consumption by DB consumers such as [Badger](
 
 For an example data package, see the [coh-content-db-homecoming](https://github.com/n15g/coh-content-db-homecoming) project.
 
-### Defining archetypes, map, badges, etc.
+### Defining archetypes, zones, badges, etc.
 
 To define content, create a new instance using the appropriate `Data` interface and provide values for the required fields:
 
@@ -41,13 +41,13 @@ export const TEST_BADGE: BadgeData = {
 }
 ```
 
-Then, create a `ServerGroupData` instance and load your content into the appropriate field.
+Then, create a `ContentBundle` instance and load your content into the appropriate field.
 
 ```typescript
 import { ContentBundle } from './content-bundle'
 import { TEST_BADGE } from './test-badge'
 
-export const TEST_SERVER_GROUP: ContentBundle = {
+export const MY_CONTENT_BUNDLE: ContentBundle = {
     name: 'My Content Bundle',
     badges: [TEST_BADGE],
 }
@@ -57,7 +57,7 @@ export const TEST_SERVER_GROUP: ContentBundle = {
 
 Fields with long text values can typically accept [Markdown](https://www.markdownguide.org/) format. These fields will also be typed with the tag type [MarkdownString](src/main/api/markdown-string.ts).
 
-Within markdown, you can construct a link to a badge or map using the special `badge://` and `map://` protocol indicators that consumer apps can use to provide runtime links or tooltips.
+Within markdown, you can construct a link to a badge or zone using the special `badge://` and `zone://` protocol indicators that consumer apps can use to provide runtime links or tooltips.
 This replaces the custom `[badge:xyz]` format from v1 and data packages will need to update accordingly.
 
 To create a link, use the standard Markdown link format, with the url as following:

package/dist/coh-content-db.d.ts

@@ -31,8 +31,8 @@ interface ArchetypeData {
 declare const ENHANCEMENT_CATEGORY: readonly ["DEFENSE_DEBUFF", "TO_HIT_DEBUFF", "TAUNT", "CONFUSE", "HEALING", "DEFENSE_BUFF", "RESIST_DAMAGE", "INTANGIBILITY", "SLEEP", "SLOW", "HOLD", "STUN", "IMMOBILIZE", "FEAR", "ENDURANCE_MODIFICATION", "ENDURANCE_REDUCTION", "RECHARGE_REDUCTION", "INTERRUPT_DURATION", "ACCURACY", "TO_HIT_BUFF", "DAMAGE", "KNOCKBACK", "RUN_SPEED", "JUMP", "FLY_SPEED", "RANGE"];
 type EnhancementCategory = typeof ENHANCEMENT_CATEGORY[number];
 
-declare const BADGE_PARTIAL_TYPE: readonly ["PLAQUE", "BADGE", "INVENTION", "INVENTION_PLUS_ONE"];
-type BadgePartialType = typeof BADGE_PARTIAL_TYPE[number];
+declare const BADGE_REQUIREMENT_TYPE: readonly ["PLAQUE", "BADGE", "INVENTION", "MISSION", "ARC", "TASK_FORCE", "INVENTION_PLUS_ONE"];
+type BadgeRequirementType = typeof BADGE_REQUIREMENT_TYPE[number];
 
 declare const PLAQUE_TYPE: string[];
 type PlaqueType = typeof PLAQUE_TYPE[number];
@@ -42,19 +42,24 @@ type PlaqueType = typeof PLAQUE_TYPE[number];
  */
 type MarkdownString = string;
 
-interface BadgePartialData {
+interface Link {
+    title: string;
+    href: string;
+}
+
+interface BadgeRequirementData {
     /**
      * Key.
      */
     readonly key: string;
     /**
-     * Type of partial.
+     * Type of requirement.
      */
-    readonly type: BadgePartialType;
+    readonly type: BadgeRequirementType;
     /**
-     * Map the partial is located on.
+     * Zone the requirement is located in.
      */
-    readonly mapKey?: string;
+    readonly zoneKey?: string;
     /**
      * /loc coordinates.
      */
@@ -68,13 +73,21 @@ interface BadgePartialData {
      */
     readonly plaqueInscription?: string;
     /**
-     * The number or letter the partial appears as on Vidiot Maps.
+     * The number or letter the plaque appears as on Vidiot Maps.
      */
     readonly vidiotMapKey?: string;
     /**
-     * The badge required for this partial.
+     * The key of the badge for this requirement.
      */
     readonly badgeKey?: string;
+    /**
+     * Mission name.
+     */
+    readonly missionName?: string;
+    /**
+     * {@link Contact} key for the story arc.
+     */
+    readonly contactKey?: string;
     /**
      * Level of the invention required.
      */
@@ -91,11 +104,10 @@ interface BadgePartialData {
      * Any additional notes.
      */
     readonly notes?: MarkdownString;
-}
-
-interface Link {
-    title: string;
-    href: string;
+    /**
+     * List of external links. Wiki, forums, etc.
+     */
+    readonly links?: Link[];
 }
 
 declare const BADGE_TYPE: readonly ["EXPLORATION", "HISTORY", "ACCOMPLISHMENT", "ACHIEVEMENT", "ACCOLADE", "GLADIATOR", "VETERAN", "PVP", "INVENTION", "DEFEAT", "EVENT", "OUROBOROS", "CONSIGNMENT", "DAY_JOB", "AE"];
@@ -127,7 +139,7 @@ interface BadgeData {
      */
     readonly badgeText?: AlternateData<string>[];
     /**
-     * Description of how to acquire the badge.
+     * Short description of how to acquire the badge. Detailed instructions should go in the notes field.
      */
     readonly acquisition?: MarkdownString;
     /**
@@ -141,19 +153,19 @@ interface BadgeData {
      */
     readonly notes?: MarkdownString;
     /**
-     * List of external links for this Badge. Wiki, forums, etc.
+     * List of external links. Wiki, forums, etc.
      */
     readonly links?: Link[];
     /**
-     * For exploration badges, the key of the {@link GameMapData|GameMap} that this badge is found on.
+     * For exploration badges, the key of the {@link ZoneData|Zone} that this badge is found on.
      */
-    readonly mapKey?: string;
+    readonly zoneKey?: string;
     /**
-     * For exploration badges, the `/loc` coordinates of the badge on the in-game map.
+     * For exploration badges, the `/loc` coordinates of the badge.
      */
     readonly loc?: [number, number, number];
     /**
-     * For badges that appear on a Vidiot Map, the number or letter the badge appears as.
+     * For plaques that appear on a Vidiot Map, the number or letter the badge appears as.
      */
     readonly vidiotMapKey?: string;
     /**
@@ -174,9 +186,16 @@ interface BadgeData {
      */
     readonly effect?: MarkdownString;
     /**
-     * A list of requirements for badges that have partial fulfilment steps, such as visiting plaques for history badges, or collecting other badges for meta-badges like accolades.
+     * Represents the layered requirements for badges with multiple fulfillment steps,
+     * such as visiting plaques for history badges or collecting other badges.
+     *
+     * The outer array represents groups of requirements evaluated with OR logic —
+     * fulfilling any group satisfies the badge.
+     *
+     * Each inner array represents individual requirements evaluated with AND logic —
+     * all conditions in the group must be met.
      */
-    readonly partials?: BadgePartialData[];
+    readonly requirements?: BadgeRequirementData[][];
     /**
      * Some badges are not included in the badge total count... such as Flames of Prometheus, which can be removed by redeeming it for a Notice of the Well.
      */
@@ -198,65 +217,58 @@ interface Change {
     description: MarkdownString;
 }
 
-interface VidiotMapPointOfInterestData {
+interface ContactData {
     /**
-     * The pixel-space position of the PoI on the map graphic.
+     * Unique key used to reference this contact.
      *
-     * Screen-space, pixels from top-left `[0, 0]`.
+     * Keys can only contain lowercase letters, numbers and hyphens (`-`).
      */
-    readonly pos?: [number, number];
+    readonly key: string;
     /**
-     * Freeform notes about the PoI.
+     * The name of this contact.
      */
-    readonly notes?: MarkdownString;
+    readonly name: string;
     /**
-     * If the POI is a zone transfer, the map it transfers to.
+     * The contact's title.
      */
-    readonly mapKey?: string;
+    readonly title?: string;
     /**
-     * If the POI is a badge, the badge.
+     * The zone this character is located in.
      */
-    readonly badgeKey?: string;
+    readonly zoneKey?: string;
     /**
-     * If the POI is a partial for a badge, the partial key.
+     * The `/loc` coordinates of the contact.
      */
-    readonly badgePartialKey?: string;
-}
-
-interface VidiotMapData {
+    readonly loc?: [number, number, number];
     /**
-     * URL of the map image.
+     * The level range this contact will offer missions for.
      */
-    readonly imageUrl: string;
+    readonly levelRange?: [number, number?];
     /**
-     * Name to display for the Vidiot map.
+     * Freeform notes or tips about the contact.
      */
-    readonly name?: string;
+    readonly notes?: MarkdownString;
     /**
-     * List of Points of Interest labelled on the image.
+     * List of external links. Wiki, forums, etc.
      */
-    readonly pointsOfInterest?: VidiotMapPointOfInterestData[];
+    readonly links?: Link[];
 }
 
-interface GameMapData {
+interface ZoneData {
     /**
-     * Unique key used to reference this badge.
+     * Unique key used to reference this zone.
      *
      * Keys can only contain lowercase letters, numbers and hyphens (`-`).
      */
     readonly key: string;
     /**
-     * The name of the map as it appears in-game.
+     * The name of the zone as it appears in-game.
      */
     readonly name: string;
     /**
-     * List of external links for this Map. Wiki, forums, etc.
+     * List of external links. Wiki, forums, etc.
      */
     readonly links?: Link[];
-    /**
-     * List of Vidiot Map assets for this map.
-     */
-    readonly vidiotMaps?: VidiotMapData[];
 }
 
 /**
@@ -276,7 +288,7 @@ interface ContentBundle {
      */
     readonly repository?: string;
     /**
-     * List of external links for this Badge. Wiki, forums, etc.
+     * List of external links. Wiki, forums, etc.
      */
     readonly links?: Link[];
     /**
@@ -289,9 +301,13 @@ interface ContentBundle {
      */
     readonly archetypes?: ArchetypeData[];
     /**
-     * List of game maps supported by this fork.
+     * List of zones supported by this fork.
      */
-    readonly maps?: GameMapData[];
+    readonly zones?: ZoneData[];
+    /**
+     * List of contacts available in this fork.
+     */
+    readonly contacts?: ContactData[];
     /**
      * List of badges available on this fork.
      */
@@ -337,19 +353,19 @@ declare class Archetype {
     constructor(data: ArchetypeData);
 }
 
-declare class BadgePartial {
+declare class BadgeRequirement {
     /**
      * Key.
      */
     readonly key: string;
     /**
-     * Type of partial.
+     * Type of requirement.
      */
-    readonly type: BadgePartialType;
+    readonly type: BadgeRequirementType;
     /**
-     * Map the partial is located on.
+     * Zone the requirement is located in.
      */
-    readonly mapKey?: string;
+    readonly zoneKey?: string;
     /**
      * /loc coordinates.
      */
@@ -363,13 +379,21 @@ declare class BadgePartial {
      */
     readonly plaqueInscription?: string;
     /**
-     * The number or letter the partial appears as on Vidiot Maps.
+     * The number or letter the plaque appears as on Vidiot Maps.
      */
     readonly vidiotMapKey?: string;
     /**
-     * The badge required for this partial.
+     * The key of the badge for this requirement.
      */
     readonly badgeKey?: string;
+    /**
+     * Mission name.
+     */
+    readonly missionName?: string;
+    /**
+     * {@link Contact} key for the story arc.
+     */
+    readonly contactKey?: string;
     /**
      * Level of the invention required.
      */
@@ -386,7 +410,11 @@ declare class BadgePartial {
      * Any additional notes.
      */
     readonly notes?: MarkdownString;
-    constructor(data: BadgePartialData);
+    /**
+     * List of external links. Wiki, forums, etc.
+     */
+    readonly links: Link[];
+    constructor(data: BadgeRequirementData);
 }
 
 declare class Badge {
@@ -414,7 +442,7 @@ declare class Badge {
      */
     readonly badgeText: Alternates<string>;
     /**
-     * Description of how to acquire the badge.
+     * Short description of how to acquire the badge. Detailed instructions will be in the notes field.
      */
     readonly acquisition?: MarkdownString;
     /**
@@ -428,19 +456,19 @@ declare class Badge {
      */
     readonly notes?: MarkdownString;
     /**
-     * List of external links for this Badge. Wiki, forums, etc.
+     * List of external links. Wiki, forums, etc.
      */
-    readonly links?: Link[];
+    readonly links: Link[];
     /**
-     * For exploration badges, the key of the {@link GameMap} that this badge is found on.
+     * For exploration badges, the key of the {@link Zone} that this badge is found on.
      */
-    readonly mapKey?: string;
+    readonly zoneKey?: string;
     /**
-     * For exploration badges, the `/loc` coordinates of the badge on the in-game map.
+     * For exploration badges, the `/loc` coordinates of the badge.
      */
     readonly loc?: [number, number, number];
     /**
-     * For badges that appear on a Vidiot Map, the number or letter the badge appears as.
+     * For plaques that appear on a Vidiot Map, the number or letter the badge appears as.
      */
     readonly vidiotMapKey?: string;
     /**
@@ -461,15 +489,22 @@ declare class Badge {
      */
     readonly effect?: MarkdownString;
     /**
-     * A list of requirements for badges that have partial fulfilment steps, such as visiting plaques for history badges, or collecting other badges for meta-badges like accolades.
+     * Represents the layered requirements for badges with multiple fulfillment steps,
+     * such as visiting plaques for history badges or collecting other badges.
+     *
+     * The outer array represents groups of requirements evaluated with OR logic —
+     * fulfilling any group satisfies the badge.
+     *
+     * Each inner array represents individual requirements evaluated with AND logic —
+     * all conditions in the group must be met.
      */
-    readonly partials?: BadgePartial[];
+    readonly requirements?: BadgeRequirement[][];
     /**
      * Some badges are not included in the badge total count... such as Flames of Prometheus, which can be removed by redeeming it for a Notice of the Well.
      */
     readonly ignoreInTotals: boolean;
-    constructor(data: BadgeData);
-    getPartial(key: string): BadgePartial;
+    constructor(badgeData: BadgeData);
+    getRequirement(key: string): BadgeRequirement;
 }
 
 interface BadgeSearchOptions {
@@ -494,7 +529,7 @@ interface BadgeSearchOptions {
      */
     filter?: {
         type?: BadgeType;
-        mapKey?: string;
+        zoneKey?: string;
         alignment?: Alignment;
     };
     /**
@@ -503,7 +538,7 @@ interface BadgeSearchOptions {
      * Badges are assumed to be in canonical order in the content bundle, and should match the in-game display order.
      */
     sort?: {
-        by?: 'CANONICAL' | 'BADGE_NAME' | 'MAP_NAME';
+        by?: 'CANONICAL' | 'BADGE_NAME' | 'ZONE_NAME';
         dir?: 'ASC' | 'DESC';
     };
     /**
@@ -516,66 +551,22 @@ interface BadgeSearchOptions {
     pageSize?: number;
 }
 
-declare class VidiotMapPointOfInterest {
+declare class Zone {
     /**
-     * The pixel-space position of the PoI on the map graphic.
+     * Unique key used to reference this zone.
      *
-     * Screen-space, pixels from top-left `[0, 0]`.
-     */
-    readonly pos?: [number, number];
-    /**
-     * Freeform notes about the PoI.
-     */
-    readonly notes?: MarkdownString;
-    /**
-     * If the POI is a zone transfer, the map it transfers to.
-     */
-    readonly mapKey?: string;
-    /**
-     * If the POI is a badge, the badge.
-     */
-    readonly badgeKey?: string;
-    /**
-     * If the POI is a partial for a badge, the partial key.
-     */
-    readonly badgePartialKey?: string;
-    constructor(data: VidiotMapPointOfInterestData);
-}
-
-declare class VidiotMap {
-    /**
-     * URL of the map image.
-     */
-    readonly imageUrl: string;
-    /**
-     * Name to display for the Vidiot map.
-     */
-    readonly name?: string;
-    /**
-     * List of Points of Interest labelled on the image.
-     */
-    readonly pointsOfInterest?: VidiotMapPointOfInterest[];
-    constructor(data: VidiotMapData);
-}
-
-declare class GameMap {
-    /**
-     * The database key for this map.
+     * Keys can only contain lowercase letters, numbers and hyphens (`-`).
      */
     readonly key: string;
     /**
-     * The name of the map as it appears in-game.
+     * The name of the zone as it appears in-game.
      */
     readonly name: string;
     /**
-     * List of external links for this Map. Wiki, forums, etc.
-     */
-    readonly links?: Link[];
-    /**
-     * List of Vidiot Map assets for this map.
+     * List of external links. Wiki, forums, etc.
      */
-    readonly vidiotMaps?: VidiotMap[];
-    constructor(data: GameMapData);
+    readonly links: Link[];
+    constructor(data: ZoneData);
 }
 
 interface Paged<T> {
@@ -588,18 +579,19 @@ interface Paged<T> {
 
 declare class BadgeIndex {
     #private;
-    constructor(badges: Badge[], maps?: GameMap[]);
+    constructor(badges: Badge[], zones?: Zone[]);
     getBadge(key: string): Badge;
+    badgeExists(key: string): boolean;
     searchBadges(options?: BadgeSearchOptions): Paged<Badge>;
 }
 
 declare class BundleMetadata {
     /**
-     * Name of the server group.
+     * Name of the content bundle.
      */
     readonly name: string;
     /**
-     * Description of the server group.
+     * Description of the fork.
      */
     readonly description?: MarkdownString;
     /**
@@ -607,7 +599,7 @@ declare class BundleMetadata {
      */
     readonly repository?: string;
     /**
-     * List of external links for this Server Group. Wiki, forums, etc.
+     * List of external links. Wiki, forums, etc.
      */
     readonly links: Link[];
     /**
@@ -617,6 +609,44 @@ declare class BundleMetadata {
     constructor(bundle: ContentBundle);
 }
 
+declare class Contact {
+    /**
+     * Unique key used to reference this contact.
+     *
+     * Keys can only contain lowercase letters, numbers and hyphens (`-`).
+     */
+    readonly key: string;
+    /**
+     * The name of this contact.
+     */
+    readonly name: string;
+    /**
+     * The contact's title.
+     */
+    readonly title?: string;
+    /**
+     * The zone this character is located in.
+     */
+    readonly zoneKey?: string;
+    /**
+     * The `/loc` coordinates of the contact.
+     */
+    readonly loc?: [number, number, number];
+    /**
+     * The level range this contact will offer missions for.
+     */
+    readonly levelRange?: [number, number?];
+    /**
+     * Freeform notes or tips about the contact.
+     */
+    readonly notes?: MarkdownString;
+    /**
+     * List of external links. Wiki, forums, etc.
+     */
+    readonly links: Link[];
+    constructor(contactData: ContactData);
+}
+
 declare class CohContentDatabase {
     #private;
     /**
@@ -624,20 +654,25 @@ declare class CohContentDatabase {
      */
     readonly metadata: BundleMetadata;
     /**
-     * List of the game server names in this server group.
+     * List of the game server names.
+     *
      * Torchbearer, Excelsior, etc.
      */
     readonly servers: string[];
     /**
-     * List of archetypes available in this server group.
+     * List of archetypes.
      */
     readonly archetypes: Archetype[];
     /**
-     * List of game maps supported by this server group.
+     * List of game zones.
+     */
+    readonly zones: Zone[];
+    /**
+     * List of contacts.
      */
-    readonly maps: GameMap[];
+    readonly contacts: Contact[];
     /**
-     * List of badges available on this server group.
+     * List of badges.
      */
     readonly badges: Badge[];
     /**
@@ -646,8 +681,12 @@ declare class CohContentDatabase {
      */
     constructor(bundle: ContentBundle);
     getArchetype(key: string): Archetype;
-    getMap(key: string): GameMap;
+    getZone(key: string): Zone;
+    getContact(key: string): Contact;
+    zoneExists(key: string): boolean;
+    contactExists(key: string): boolean;
     getBadge(key: string): Badge;
+    badgeExists(key: string): boolean;
     /**
      * Search, sort and filter the badge list.
      * This is a fairly brute-forced approach and will not be as performant as loading the badge data into a traditional
@@ -672,38 +711,46 @@ declare const CHANGELOG: Change[];
  *
  * @param target The badge or badge key to target.
  */
-declare function badgeUri(target: string | {
-    key: string;
-}): string;
+declare function badgeUri(target: string | Badge | BadgeData): string;
 /**
  * Returns a {@link MarkdownString} link to the given badge.
  *
  * Link format: `[<key>](badge://<key>)`
  *
- * @param target The badge or badge key to target.
+ * @param target The {@link Badge} or badge key to target.
+ */
+declare function badgeLink(target: string | Badge | BadgeData): string;
+/**
+ * Returns the URI of the given contact that can be used in {@link MarkdownString} links.
+ *
+ * URI format: `contact://<key>`
+ *
+ * @param target The {@link Contact} or contact key to target.
+ */
+declare function contactUri(target: string | Contact | ContactData): string;
+/**
+ * Returns a {@link MarkdownString} link to the given contact.
+ *
+ * Link format: `[<key>](contact://<key>)`
+ *
+ * @param target The {@link Contact} or contact key to target.
  */
-declare function badgeLink(target: string | {
-    key: string;
-}): string;
+declare function contactLink(target: string | Contact | ContactData): string;
 /**
- * Returns the URI of the given map that can be used in {@link MarkdownString} links.
+ * Returns the URI of the given zone that can be used in {@link MarkdownString} links.
  *
- * URI format: `map://<key>`
+ * URI format: `zone://<key>`
  *
- * @param target The {@link GameMap} or map key to target.
+ * @param target The {@link Zone} or zone key to target.
  */
-declare function mapUri(target: string | {
-    key: string;
-}): string;
+declare function zoneUri(target: string | Zone | ZoneData): string;
 /**
- * Returns a {@link MarkdownString} link to the given map.
+ * Returns a {@link MarkdownString} link to the given zone.
  *
- * Link format: `[<key>](map://<key>)`
+ * Link format: `[<key>](zone://<key>)`
  *
- * @param target The map or map key to target.
+ * @param target The {@link Zone} or zone key to target.
  */
-declare function mapLink(target: string | {
-    key: string;
-}): string;
+declare function zoneLink(target: string | Zone | ZoneData): string;
 
-export { ALIGNMENT, type Alignment, Alignments, type AlternateData, Alternates, Archetype, type ArchetypeData, BADGE_PARTIAL_TYPE, BADGE_TYPE, Badge, type BadgeData, BadgeIndex, BadgePartial, type BadgePartialData, type BadgePartialType, type BadgeSearchOptions, type BadgeType, BundleMetadata, CHANGELOG, type Change, CohContentDatabase, type ContentBundle, ENHANCEMENT_CATEGORY, type EnhancementCategory, GameMap, type GameMapData, Key, type Link, type MarkdownString, PLAQUE_TYPE, type Paged, type PlaqueType, SEX, type Sex, VidiotMap, type VidiotMapData, VidiotMapPointOfInterest, type VidiotMapPointOfInterestData, badgeLink, badgeUri, mapLink, mapUri };
+export { ALIGNMENT, type Alignment, Alignments, type AlternateData, Alternates, Archetype, type ArchetypeData, BADGE_REQUIREMENT_TYPE, BADGE_TYPE, Badge, type BadgeData, BadgeIndex, BadgeRequirement, type BadgeRequirementData, type BadgeRequirementType, type BadgeSearchOptions, type BadgeType, BundleMetadata, CHANGELOG, type Change, CohContentDatabase, Contact, type ContactData, type ContentBundle, ENHANCEMENT_CATEGORY, type EnhancementCategory, Key, type Link, type MarkdownString, PLAQUE_TYPE, type Paged, type PlaqueType, SEX, type Sex, Zone, type ZoneData, badgeLink, badgeUri, contactLink, contactUri, zoneLink, zoneUri };