2.3.0 and 2.3.1 Changes (Forsaken Release)
Today we will be releasing Destiny API version 2.3.0, in preparation for the release of Forsaken. It will have some of the features mentioned below, and will be followed up quickly by the 2.3.1 release next week alongside Forsaken. For the specifics of what features are being supported in which upcoming version, see the API Reference - I have tagged two changelists with the respective versions so that you can compare and contrast the differences.
Support for new features in the game:
- Collectibles, a replacement for Kiosks that provides you with data for every collectible item in the game
- Triumphs (henceforth referred to in this documentation and in the API as “Records” to avoid confusion with Moments of Triumph and its related features), a set of accomplishments that you can achieve in-game, and that provide a Grimoire Score-like feature
- Presentation Nodes, a new construct used by the game to categorize hierarchical data for presentation in the game UI. Exposed in the API for you to use our built-in categorization for Collections and Triumphs.
- “Equipment Slots 2.0,” a new approach to equipment where your primary and secondary slots can hold a more diverse array of potential weapons, and may use different types of ammo depending on your chosen weapon’s type.
- Randomized Sockets, a change to the socket system to allow different weapons to “roll” with different reusable plugs, allowing for greater item diversity.
- “Challenge-based Milestones”, which are Activity Challenge-based daily/weekly/special objectives and replaced many former Milestones, are supported in Milestone data in the API in an attempt to provide remedial backwards compatibility. It does come with a lot of new and useful data, however.
- Stats will return data for the new Gambit mode, along with a host of new stats specifically built for Gambit and the new “PvE Competitive” mode of gameplay.
- Korean support was officially added, you should be able to get korean language Destiny and BNet content as of v2.3.0!
Improvements and concepts for existing features:
- Vendors can override the inserted plugs in the sockets of items they sell. They also will have more consistent data which has been a problem as of v350.
- Activity data now provides information about loadout requirements for activities that provide such limitations, a feature long missing in the API. There is also some new data being exposed for those of you who wanted more details about Activities in general (some information about the Phases and their order, information about locations and their relationship to activities, and some new Activity Graph information for those willing to do a bit of manual wire-up to make something externally presentable)
- Items with objectives have additional optional information that may be returned related to those objectives.
- Objectives now have completion values that are determined at runtime.
- Characters now have Titles, that can be earned by completing specific Records.
- Objective information for **Uninstanced items **(like the Moments of Triumph bounties, that weren’t instanced but had objectives to complete) is now returned in the API.
All of this in addition to the normal maintenance data: new item types, activity modes, medals, and other information that comes with a Destiny release.
Collectibles and Records are new features in Destiny 2 - they are found in the game as new menus alongside the existing inventory, character, etc… menus.
Collectibles are a permanent and more complete/organized version of the old Kiosks data: a place where you can view items that you’ve collected while playing Destiny.
In Destiny API Manifest content, these are defined with the new DestinyCollectibleDefinition root-level entities. It contains information about the item being collected and some presentation data, but note that it doesn’t have any information about things like what Armor Set it belongs to: that is (for better or worse) the generic purview of the Presentation Nodes, which I will cover below.
At runtime, you can request collectible summary information by passing the new “Collectibles” component to GetProfile or GetCharacter requests. It will return DestinyCollectibleComponent information for the collectibles at a profile or character level (depending on if the collectible’s state can vary by character, or is guaranteed to be consistent across all of your characters). The component returns information about both visibility and acquisition/retrieval capabilities, which I go into more detail about in the reference guide. As was the case with previous definitions split in this manner, the DestinyCollectibleDefinition has a “scope” property that you can use to determine whether you will find it in the profileCollectibles or characterCollectibles results.
In addition to this summary data, there is a new detail endpoint that you can call for getting more in-depth details of collectible items that are found under a given Presentation Node. This endpoint was built specifically with the Bungie.Net Companion App in mind, and returns too much data for me to consider putting it in the general GetProfile/GetCharacter endpoint. I will go over that in more detail in the “New Endpoints” section.
Records are accomplishments that you can complete while playing Destiny. They have point values similar to the old Grimoire, and can be associated with Lore and contain interesting tracking information.
In Destiny API Manifest Content, these are defined with the new DestinyRecordDefinition root-level entities. (not to be confused with the Destiny 1 Record Definitions: these are similar, but contain a superset of data) You will find information about the related objective, the points that can be rewarded for completing the Record, and the Title rewarded to the player if completing the Record results in earning a title.
At runtime, you can request record information by passing the new “Records” component to GetProfile or GetCharacter requests. DestinyRecordComponent information will be returned with the state of the record, which behaves much like Triumphs from the Moments of Triumph (in that they must be completed via an Objective, and then redeemed in-game before they count for points/rewards). Records will have not just completion status, but also a variety of different visibility/presentation states that are honestly somewhat confusing. I go into more detail in the Reference guide.
As with Collectibles, these will be split into profile and character-level components, and you can use the scope property on the DestinyRecordComponent if you want to know in which it will be found in advance.
Presentation Nodes account for everything else you see in the in-game screens for Triumphs and Collectibles: they are a new semi-generic concept for representing hierarchical data in Destiny content. The content defines a “Root” node for each of the four main concepts found in the Triumphs and Collectibles screens:
- “Triumphs”, the aforementioned achievements; with nested Presentation nodes for categories and potentially multiple levels of subcategories (Root Presentation Node Hash: 1024788583)
- “Seals”, which are simply Records that aggregate the result of other Records and reward the player Titles for their completion (Root Presentation Node Hash: 1652422747)
- “Collections”, the aforementioned kiosk replacement; with nested Presentation Nodes for categories, subcategories, and Armor Sets where relevant (Root Presentation Node Hash: 3790247699)
- “Badges”, which aggregate the Collections with an alternative pivot and have their own Objective that tracks them (Root Presentation Node Hash: 498211331)
Presentation Nodes are represented in Destiny API Manifest Content by the new DestinyPresentationNodeDefinition root-level entities. It contains a wealth of information about what it considers its child nodes/collectibles/records, and hints for how it is meant to be used in the UI.
At runtime, passing the new “PresentationNodes” component type to GetProfile or GetCharacter will return DestinyPresentationNodeComponent data: split into profile and character in the same manner as Records and Collectibles. They have presentation data informing you about whether the node itself is visible to the given profile/character.
Putting all of these systems together, you get a relationship like the following:
With the pre-release of Forsaken on 8/28, Equipment Slots will undergo significant gameplay changes. While the gameplay changes are extensive, the changes to the API are blissfully minimal: depending on your application, you may require no further work to support the feature at all.
Any given Item (as defined by its DestinyInventoryItemDefinition) will still always be instantiated and bound to a single character-level inventory bucket and equipment slot: the changes are that you will see new and existing items moved permanently to buckets where they wouldn’t previously have been located due to their weapon type.
Different weapons in the same bucket may also use different ammo types: as a result, Item Definitions now have an “ammoType” property, that uses a new DestinyAmmunitionType enumeration to indicate what type of ammo a given weapon uses. If you wish, you can use this and combine it with a static image or text representing the ammo type in your own UI. I have not yet created a localized/asset-laden Ammo Type Definition as we did with Damage Type, but as time permits I will attempt to do so in order to relieve you of having to create these manual relationships between ammo type and static content.
In Forsaken, weapons will drop that have choices of randomized plugs for sockets. This will allow weapons, armor, etc... to have larger variations in the benefits and drawbacks available to it. These are defined in DestinyItemSocketEntryDefinition, as a new set of plug data: the randomizedPlugItems property is a list of the possible plugs that can be allowed to be inserted into this given socket.
At runtime, we consolidate this information into the existing reusablePlug data that we pass back: for all practical purposes at runtime, you can treat randomized plugs as reusable plugs, including passing the randomizedPlug’s hash to the InsertPlugs action when Advanced Write Actions becomes available publicly. We handle the mapping of the plug data to randomized plugs on the backend for your convenience.
UPDATE: Apparently I'm getting reports that items are already dropping with randomized rolls. Haven't been able to confirm, but just a heads up: this data may already be relevant to you in some situations.
In Forsaken, most repeating milestones have been replaced with Challenges attached to Activities and Playlist Activities. In an attempt to provide something that wouldn’t require extensive reworking, I decided to include this new “Ritual” Challenge data in our DestinyMilestone and DestinyMilestoneDefinition data.
The good: if you weren’t using Quest data on the DestinyMilestone, or you were falling back to the generic Milestone data if there was no quest data, then you should be able to use this in some form without much changes.
The bad: If you were depending on quest data, these new Milestones don’t have it. The data was not mapped to a Quest, and as such DestinyMilestoneDefinitions and Instance data alike both have a new top-level “activities” property to handle the data coming down from these “challenge-based milestones.”
At runtime, these will be instances of DestinyMilestoneChallengeActivity, and will have the related Activity that can be played, the Challenges as they are specifically defined for that Activity, and other related data: Modifiers, Phases (for Raids), and even Loadout data. See the reference guide for the specifics of this data. I plan to include other information in the future if time allows, such as more explicit relationships between these challenges and their related Triumphs, and between any related Bounties (if there are any).
For the week between 8/28 and 9/4, some of these new challenge-based milestones won’t be returning correct data, particularly for start and end dates: this is a bug we found late in testing and do not have time to safely fix before today’s release.
Gambit is a mode that is a mix of PvP and PvE, and as such a new DestinyActivityModeCategory is being added, PvECompetitive. There is also a new PvECompetitive DestinyActivityModeDefinition (activity mode 64, AllPvECompetitive) which will contain Gambit (activity mode 63, Gambit) and any other PvE Competitive modes that come along if there ever are any more.
Gambit will have its own medals and a variety of new stats, which I will go into detail about in another document.
URL: /Destiny2/{membershipType}/Profile/{destinyMembershipId}/Character/{characterId}/Collectibles/{collectiblePresentationNodeHash}/
See the information about Collectibles and Presentation nodes in the “New Features” section for more context.
Given the hash identifier of a Presentation Node that has Collectibles as descendants up to two layers deep, this will return item details about those descendants in the context of the requesting character.
This endpoint accepts all of the usual item-level DestinyComponentType enumeration values: through this endpoint, you can get all of the details of the collectibles as if you had an instance of them.
The intent of this endpoint is to be used and called only when navigating to the given Presentation Node in your own UI. I urge you to not call this method in bulk to get all of the data at once: it is a terrible amount of data, enough that I intentionally decided to make it a separate endpoint along the lines of Vendors. My hope is that doing so will make us all think more carefully about how and why we use that data, and the costs involved for using it.
The most important breaking change is around Milestones. If you are relying on the existence of Quest data for Milestones, this will break your current implementation. Please see the information above and the new reference guides for more information and how to port your existing implementations over.
You should no longer use completionValue on the Objective definition: as of Forsaken, completionValue is now determined dynamically at runtime, and must be acquired in the live data responses in order to guarantee accuracy.
There is also going to be a period of significant instability in the week between 8/28 and 9/4. Notable points:
- Nightfall and Heroic Adventure challenges will not be returned by the API
- Challenge-based Milestones will be showing incorrect start/end date information until 9/4
- Vendors will be turned off until 9/4, when the new infrastructure supporting Vendors comes online
- Gambit stats will not be returned during the pre-9/4 Gambit Trial
- New items will not have screenshots deployed for them until 9/4
- Items that don't actually spawn in-game until 9/4 may not/many will not have valid icons. If you're browsing around, you'll see our handy little temp icon. Hang tight, they'll come around on 9/4's manifest update.
- You will see Presentation Node, Collectible, and Record definitions: but they are not in final form. I suggest you use them to make sure that your apps are ready for 9/4, but don't take the data contained therein as final. A lot of iteration happened between the 8/28 and 9/4 branches on this data.
Regarding the Collectibles Checklists that I added over the summer, I'm going to attempt to wait until the 9/12 deployment (2.3.2) to remove them: but they will be removed. You are encouraged to convert your code over to using the new Collectibles and Presentation Nodes as needed once 2.3.1 goes live on 9/4! My hope is that this early release of information will aid that effort.
Thank you for your interest in the Destiny API! We hope that you find these improvements useful - and I look forward to continuing our discussions, receiving input, and answering questions right here!