diff --git a/api/shapes/wishlist.ts b/api/shapes/wishlist.ts index 8d0dd03..b0b7a9e 100644 --- a/api/shapes/wishlist.ts +++ b/api/shapes/wishlist.ts @@ -2,47 +2,87 @@ import { DestinyItemSubType } from 'bungie-api-ts/destiny2'; -interface WishList { - /** Indicates that this JSON file is in the format described by this file. */ - format: 'DIMv1'; +export type ItemHash = number; + +export interface WishList { + /** + * Indicates that this JSON file is in the format described by this schema. If + * the format is changed in a non-backwards-compatible way this string will be + * changed. It otherwise has no semantic meaning. + */ + format: 'wishlist.v1'; + + /** + * The name of the wish list itself, as a plain string. e.g. "Voltron". + */ name: string; + /** The description of the wish list itself, as a plain string. */ description: string; - /** URLs of other wish lists that are transitively included into this wishlist. */ - includes: string[]; - /** UNIX timestamp (milliseconds) representing when this wish list was created. */ - date?: number; + + /** Information about the author(s) of this wish list. */ + authors?: Author[]; + + /** + * URLs of other wish lists that are transitively included into this wishlist. + * This allows wish lists to be composed of other wish lists, which are then + * fetched individually. A wish list may specify multiple includes, and no + * rolls of its own. + */ + include?: string[]; + + /** + * UNIX timestamp (milliseconds) representing when this wish list was first + * created, for display to humans. + */ + createdTime?: number; + /** + * UNIX timestamp (milliseconds) representing when this wish list was last + * updated, for display to humans. This shouldn't be used to manage cache + * freshness - use HTTP headers for that. + */ + updatedTime?: number; + + /* + * Rolls - these are the various rules that match weapons and perks in order to + make recommendations. Multiple rolls may apply to a single weapon, and all + of them will be shown. The order of rolls is not significant. + */ + /** * Per-item-hash rolls - each one specifies one or more rolls that are - * specific to a particular DestinyInventoryItem. - * E.g. "These are the god rolls for The Messenger" + * specific to a particular DestinyInventoryItem. E.g. "These are the god + * rolls for The Messenger" */ - itemRolls: ItemRoll[]; + itemRolls?: ItemRoll[]; /** - * Perk rolls match specific plug combinations, but without specifying an item. - * E.g. "Outlaw + Kill Clip is always good" + * Perk rolls match specific plug combinations, but without specifying an + * item. E.g. "Outlaw + Kill Clip is always good" */ - perkRolls: Roll[]; + perkRolls?: Roll[]; /** - * Rolls that apply to any weapons in a specific category. - * E.g. "Shotguns with Shot Package + Slideshot are always good". + * Rolls that apply to any weapons in a specific category. E.g. "Shotguns with + * Shot Package + Slideshot are always good". * * If you specify the intrinsic perk hash, you can also specify things like * "Adaptive Frame Scout Rifles with Surplus + Demolitionist are good" */ - categoryRolls: CategoryRoll[]; + categoryRolls?: CategoryRoll[]; } /** These tags are meant to match the Little Light JSON wishlist tags. */ type Tag = /** This roll is intended for use in PVE */ - | 'PVE' + | 'PvE' /** This roll is intended for use in PVP */ - | 'PVP' + | 'PvP' /** This roll is specifically good for mouse+keyboard users */ - | 'Mouse' + | 'MnK' /** This roll is specifically good for controller users */ - | 'Controller' - /** God Roll - "don't you dare throw this away" - not all guns need to have one of these! */ + | 'Ctrl' + /** + * God Roll - "don't you dare throw this away" - not all guns need to have one + * of these! + */ | 'Godroll' /** * Good Roll - "this is worth keeping/trying" - for guns you would tell @@ -57,34 +97,82 @@ type Tag = */ | 'Recommended' /** - * Trash - this sucks, these perks clash - controversial. makes people very - * sad when they see it, but like the roll + * Trash - this sucks, these perks clash - controversial. Makes people very + * sad when they see it, but like the roll. Allowing users to uncheck tags + * when importing wish lists may make using this viable. */ | 'Trash' // Users are free to specify any other tag | string; -// TODO: should we try to reduce the size of this? interface Roll { - name?: string; // Not used in DIM + /** + * An explanation about this roll. Usually contains a general explanation of + * the good and bad parts of this weapon. + */ description?: string; // e.g. notes - plugs: number[][]; - // Can be used to filter which rolls to show! - tags?: Tag[]; /** - * UNIX timestamp (milliseconds) representing when this roll was created or - * updated. If not specified, uses the date from the wishlist it's in. + * Describe a combination of perks, which are really plugs for sockets. + * + * ItemHash is the `DestinyInventoryItem` hash for a socket plug. + * + * Each element in the top-level array represents a "group" of perks, which + * means they belong to the same socket (column) in the perk selection UI. + * + * Masterworks, Weapon Mod, Shader, and other non-Perk plugs *should not* be + * included. + * + * The order of perks group is not specified. Do not include empty groups. + * + * For hash in the same group, their relation is OR. For different groups, + * their relation is AND. (e.g. `[[1, 2], [3, 4]]` means `(1 OR 2) AND (3 OR + * 4)`) + * + * e.g. For `"Randy's Throwing Knife" <3292795429>`, + * - `[[247725512, 2387244414]]` is a valid value meaning "the weapon must + * have plug 247725512 or 2387244414 available on it". + * - Implementers should iterate the groups in `socketEntries`'s `plugSet` + * info to determine the actual socket. (Recommended) + * - `[[247725512], [2387244414]]` is a valid value meaning "the weapon must + * have plug 247725512 and 2387244414 available on it on different sockets". + * + * Implementers must ignore any invalid combination they can't match. + */ + plugs: ItemHash[][]; + + /** + * Tag for the current combination. This can be used to show special flair on + * the item, as a search filter, or to allow users to select which types of + * tags they want to import from a wishlist. + * + * All tags that are not ReservedTags should be treated as user-defined tags. */ - date?: number; + tags?: Tag[]; } interface ItemRoll extends Roll { - /** Inventory item hash */ - hash: number; + /** Inventory item hash this roll applies to. */ + hash: ItemHash; } interface CategoryRoll extends Roll { + /** + * The subtypes of items this roll applies to. This allows targeting rolls to + * "Shotguns" for example. + */ categories: DestinyItemSubType[]; - /** Optional intrinsic perk hash, used to narrow this to a specific archetype. */ - intrinsic?: number; + /** + * Optional intrinsic perk hash, used to narrow this to a specific archetype. + * + * If you specify the intrinsic perk hash, you can also specify things like + * "Adaptive Frame Scout Rifles with Surplus + Demolitionist are good". + */ + intrinsic?: ItemHash; +} + +interface Author { + /** The name of one of the authors of this wish list. */ + name: string; + /** An optional URL to a public profile or home page for the author. */ + url?: string; }