-
Notifications
You must be signed in to change notification settings - Fork 92
2.4.0 (Shadowkeep) API Changes
The Destiny API will have some significant changes with Shadowkeep. Below is an overview of those changes.
Swagger Specs for 2.4.0 can be found here for the time being: https://github.com/Bungie-net/api/tree/2.4.0
Documentation for 2.4.0 can be found here: https://github.com/Bungie-net/Bungie-net.github.io/tree/2.4.0 (Until it's merged into the master branch, Github Pages functionality won't work - so if you want this documentation early, you'll likely have to sync this branch and view it locally)
There's a lot of changes centered around Seasons and Season Passes.
First, Seasons are something purchased with silver - as such, they will stay with the Destiny Profile that purchased them, regardless of the platform on which you play.
DestinyProfileComponent.seasonHashes will be an in-order list of the Hash Identifiers for all Seasons purchased by a player. They will point to the DestinySeasonDefinition entity, which has additional information such as pointers to the season's season pass, the progression, etc... note that many of these properties will not be populated until just before a season begins, so plan on only having reliable data for many of these properties for the current season, or possibly the next season in the days or weeks before it goes live.
With Seasons come Season Passes: these are special types of Progressions with rewards you can earn over time. DestinyProgression.rewardItemStates has been added to return this Season Pass reward data and your state related to it, but could be used for any progression-related rewards in the future. Combine this data with DestinyProgressionDefinition.rewardItems to get info such as: - Which level it's rewarded at - What the item is that's being rewarded
Note that the index into rewardItemStates matches the index into DestinyProgressionDefinition.rewardItems as long as your content version matches. Similar to socket indexes, this means the data is content version dependent and you may show incorrect data if you have an out of date manifest.
Seasons also have Artifacts, which we'll talk about later in this document.
This data reflects a weapon's compatibility with the new Breaker mechanic, where certain enemies in challenges require usage of a specific type of "Breaker" weapon in order to open them up to damage.
There are new definitions, DestinyBreakerTypeDefinition, to support this mechanic. Similar to Damage Types, these have icons and string representations. Also similarly to Damage Types, we don't actually get this data from the game for reasons and thus the assets and strings will not necessarily match any string that you'd see in the game.
DestinyItemInstanceComponent will have a breakerType enum and breakerTypeHash field - the former being provided for convenience and I already regret it even before we've shipped it, but it was nice to have for damage types so we'll see if my pre-regret will turn into actual regret.
With Armor 2.0, there is a new system of "Costs" and Progression on items that is layered on top of the Sockets system. Because Sockets wasn't confusing enough already.
Plugs will cost "Energy" to be inserted into Armor 2.0 sockets, and will be reusable and shared across Armor 2.0 items. Whether you can actually insert them, however, will depend not just on whether the Reusable item is "canInsert" (in the DestinyItemPlug contract), but also if that specific item matches the Energy Type and has sufficient available Energy to perform the insertion.
Energy: what it is and how it works
Energy at the moment can be one of three possible types, or it can be a generic ("Any") energy type, in which case any Energy type can be spent to insert the given plug. We created a new definition, DestinyEnergyTypeDefinition, to give information about these types (along with a corresponding Enum). Though at the moment they are very similar to Damage Types, we didn't want to assume that this will always be true.
Determining Costs
DestinyItemPlugDefinition now has an energyCost property that you can use to determine if the plug can be inserted into a given instance of an item. If the energyType contained therein matches the item's or is "All", then it is possible to be inserted if enough Energy Points are available on the item. The "energyCost" property will specify the amount of energy that will be spent on the item in insertion.
Determining available energy and type on an item
IF an item uses the Armor 2.0 energy system, it will have an "energy" property populated in its DestinyItemInstanceComponent.
That property will tell you how much energy is available, what type of energy it is, and other information related to the item's energy.
Note that the available energy stat on item instances is itself determined by a plug that provides the corresponding energy stat. It is swapped using an identical mechanism to how Masterwork Plugs worked in the Forsaken era. You'll see it when you inspect the data, the same set of available reusable plugs of which only one is actually able to be inserted at a time for the purpose of "leveling up" the item.
Other Info
Fun fact, and also something you should be aware of as you're looking at stats. Under the surface, this whole Energy system has been implemented as item stats. You'll see some ugliness in there that we tried to hide with the definition data above, but I left the raw stats that were used to build up the Energy system in just in case someone can do something creative with them. You'll see stats for capacity and cost, one per energy type, on various items.
Plug Sets were a BNet-created concept that we added to try and prevent massive duplication of plug data caused by the Emote Wheel.
The game now supports a similar concept due to the multitude of Reusable Plugs added by Armor 2.0, and so we have retrofit DestinyPlugSetDefinition (in static definitions) and DestinyPlugSetComponent (in live data) to support it.
The end result is that the definitions and live data are the same, but if you weren't bothering to support Plug Sets before you will need to support it now. It is now used by most/all items with sockets, and not just for Emotes.
Some Triumphs will now have multiple "intervals" of rewards that they provide. For instance, let's say there's a "Kill Dudes" Triumph. It may now have "Intervals" on them where you can get rewards for Killing 10 dudes, 50 dudes, and 100 dudes. In the game, you'd click the Triumph each time you passed the boundary to earn those rewards. In the API, we will be returning data about the intervals you've earned and activated through a new "intervalInfo" property on DestinyRecordDefinition and "intervalObjectives"/"intervalsRedeemedCount" on the DestinyRecordComponent of Triumphs that have intervals.
Each interval is treated as its own DestinyObjective with a separate DestinyObjectiveDefinition that may or may not have useful human readable info.
Under the surface, Artifacts are a hodgepodge of various systems that are wired together with special game UI. In the API, we have attempted to pull those systems together into a comprehensible definition and set of live data for your convenience.
This data is centered around the new DestinyArtifactDefinition data, and new "seasonalArtifact" data on the DestinyProfileProgressionComponent and DestinyCharacterProgressionComponent.
Note that, as you examine this data, you'll see there's only one artifact available at a time. The current plan is that an artifact will only exist in content for a single season. We have built the Artifact Definition with the understanding that this could change in the future, but for now the live contract data will only return the current seasons' Artifact. If this does change, there will be additional data added to the API to provide historical Artifact data.
Examine the new DestinyArtifactDefinition for details about how the artifact will work. There are Tiers that you can gain experience to unlock, and each of those tiers provide a set of Armor 2.0-compatible Plugs that you will be able to choose to activate.
The live data is split between Profile and Character progressions, as some data about the artifact applies to all characters equally (such as the progress in unlocking tiers, and your power bonus) while others will be character specific (how many "points" you have spent on unlocking Plugs from the Artifact).
Some convenience properties have been added. For instance, DestinyItemPreviewBlockDefinition.artifactHash will be populated if an inventory item is an Artifact - this will point to the relevant DestinyArtifactDefinition.
VexOffensive = 78 NightmareHunt = 79 Elimination = 80 Momentum = 81
We have not had the time to do a larger overhaul of the existing Activity Modes, as I've long been hoping we would be able to do. I cannot provide a timeframe for if or when this will happen: with our current resources, I don't predict that we will have those changes anytime in the forseeable future, so for now we are stuck with the insufficiently partitioned modes that we currently provide. I apologize for the inconvenience this causes for folks who have been hoping for and dealing with our current partitioning of Activity Modes.
-
DestinyItemComponent.tooltipNotificationIndexes
- These are conditional tooltips that may appear on an item when hovered over in-game
- Use these indexes to look up DestinyInventoryItemDefinition.tooltipNotifications for further data/localized strings for the tooltip.
- Note that because this uses indexes, this is content version dependent: it is possible to show the wrong tooltip if your manifest is out of date.
-
REMOVAL of DestinyItemSocketEntryDefinition.randomizedPlugItems, replacement with randomizedPlugSetHash
- The game removed the ability for items to have individual randomized plug definitions, instead they must refer to a Plug Set for randomized plugs.
- Ideally, you shouldn't have to worry about either of these properties if you're looking at live data, as the live data will filter down to what's available appropriately. But if you do use it for some reason, be aware of this breaking change.
-
DestinyProfileResponse.profileTransitoryData
- Contains some information about a user's current game state that should not be considered canonical, but may be "good enough" to make better estimates about what activity a player is playing, what their current status is in the game etc.
- Examine that property and its related contract class for details.
-
New DestinySocketCategoryStyles
- EnergyMeter -> This indicates that the socket should use the new Armor 2.0 "Energy" UI. Unfortunately, you'll have to build this UI yourself out of the data that we provide about the item.
- LargePerk -> An alternative view for the chosen item, indicating that it should be shown larger than normal.