[2020] Hey, Bungie. Its 2020, why can't we save a gear loadout?

This is a focus of our team (Bnet). We have a pretty small team, so we have to choose where to focus our resources. If we build lots of our own tools, we can't spend as much time focusing on including game features in the API, and building the stuff only we can make (Cross Save, etc). It would be really cool to build LOTS of features for everyone, but with a limited team size, it's very difficult to hit every use case. When we can, we provide features that enable the community to build super cool stuff on top of them. Finding that line is always a WIP, but it's really great to see that the community has made tools that provide stuff for everyone, even niche use cases.

If it helps, the biggest initial conceptual hurdle to jump over is the fact that the API is actually split into two big components that need each other but that are accessed in very different ways:

1. The static data, which you can download and provides information about any entity in the game that doesn't change dynamically as you play. For instance, the names of items, or what plugs could possibly be inserted into which sockets for an item, or other information critical to use when showing or interpreting "live" data, but has no information about a specific character or "instance" of an item and its state. This data is contained in lists of "entity definitions" (for instance, the "definition" of a particular weapon, or the "definition" of a specific Triumph rather than an actual instance of one) and each of these entities is referred to by it's identifying "hash" (a numeric identifier that is unique for that given type of entity)
2. The "Live" data, which you can access through the web services, that will get you information about specific character, instances of items, etc. The live data is mostly "hashes" that reference entities in the definitions, and values that relate to those entities.

For instance, the weapon "Thorn" (https://data.destinysets.com/i/InventoryItem:3973202132) might be identified as hash 3973202132. You can use that definition to pull some information (see the link here for a nice view of that "static" data, as provided by destinysets.com!), but for it to be useful for a player you have to combine it with "live" data - look up a character that has the Thorn item, find it in their inventory by looking for that hash, and then using the properties it returned like the stats on the item, what plugs are inserted into its sockets, etc...

Once you've gotten that figured out, the biggest problem becomes digging for what you want. We added documentation where we had time to here to try and give people more context about what each property on a definition or in the live data means, but it's a lot to work through: https://bungie-net.github.io/multi/index.html

Hopefully this helps! I've had a long running dream of making some kind of more in-depth tutorial or even youtube video series in hopes of teaching people about these core API topics, but the odds of me ever finding the time to do that feel low unfortunately. Fortunately though, many people in the community are super helpful in teaching folks the ropes!

No prob, glad to provide help when I can! I wish we had more resources and info to share.

Yes, this is true - some of the API actions are limited to certain areas of the game (or while offline). Unfortunately, this'll be the situation for the forseeable future: the potential for abuse vectors if the API could perform actions in combat-capable activities is too high. Funny story, you can actually see some of the cheese that came from it when the flashback activity during Moments of Triumph accidentally allowed API equipping back in the day. There's some humorous videos out there, but it's the kind of category of problems that could cause potential grief if those actions were allowed in potential combat situations.

Oh yeah, I definitely didn't see the OP as an API complaint for sure (nor any of your comments!). Sadly I don't have any control over the in-game choices and focus, but I do think it's good to know that people have this desire!

Thanks! I'm glad to be of help when the opportunity arises!

I totally understand how that goes! Have fun if you end up finding the time to, but no stress: it'll be here when the free time comes around!

Thank you! I am glad that it has been useful to folks!

Sure thing! So it depends on the situation. Some properties of an item, for instance the plugs that are initially inserted into the sockets or the "level" of the item that ends up determining things like the base power stat of a weapon etc... pull together info from the definition and sometimes random values assigned by the server when an instance of that item is created in the world, and then that resulting value gets saved off.

Other times, the truth about some property of the item lives in the definition because it doesn't change for any given instance, or requires both information from the definition and information from the live data to come up with a true value for an item. (We try to hide some of that complexity in the API because that can become excessively complicated, but for better or worse parts of the game systems are built so flexibly that if we try to hide it, a future design change could render our abstraction incorrect in a way that requires us to break our contracts. That is still a balance we are trying to learn from and still make mistakes judging to this day! You can see the cruft from some of the times where I made the wrong bet on the layer of abstraction when you find deprecated properties in the API, or two properties that mean similar things but one is more robust)

In the end, any of those values that aren't directly in the definition end up as instance data, and every instance of an item that can have such data has an "instance ID" that we also expose in the API to uniquely identify that specific item as it exists in the world, with all it's unique states compared to the definition.

Ha, I never knew about that one! That is clever!

Oh yes, it is more like deltas - though not strictly. The two have very different schemas, and not everything in the definition has the potential to have a live data override: and many live data properties are more "derivative" than a direct overriding of a definition property. For instance, the definition has properties pertaining to how sockets are first initialized, but all that content strictly exists for initialization purposes and then ends up as a different set of data once initialized.

As far as referencing them at runtime, the game side can locate definitions quickly because on their side these definitions are in sequential arrays and referred to by index which allows for very quick retrieval of that static data on demand. The live data for a character will store instance IDs for an item, and also it essentially stores the index of that item in the definitions, at least by the time the characters inventory is pulled into memory. (There are additional complexities in the game client that I am not well versed in, I can only really talk about the server side)

Bungie.net uses hashes of internal identifiers for these entities instead, despite the extra expense in lookup efficiency, because we have a greater need for content version agnosticism: that is to say, we can't guarantee that our definitions are in sync with the game at all times, and so if we too used indices then our index might point to a different item. (There are other reasons as well, for instance we might have our own configuration that refers to some entity in the game to build up extra information, and we need a content version agnostic way to refer to them in such configuration) This is also why you may note that the API turns off certain features like Vendors during game deployments. There are a couple of systems where we cannot safely rely on these identifiers as being truly content version agnostic, and thus to prevent showing incorrect data the systems are disabled until the content is brought back into alignment with the game! It's some ugly cruft that I would like to see resolved someday, but if you have ever spotted that and wondered why, that's the reason!

No problem! Glad it is interesting, and hopefully it's helpful!