Character Profile Standard

[Yellowfive]

Hey all -- I'm one of the main developers over at Ask Mr. Robot, and we're working on getting the Character API up and running. Figured it would be worth jumping in to show you what we are using internally, which will likely be very similar to what is exposed via the public API.

Code:

{
    "ProfileId": "9674b96a-d94a-47c8-b268-17e65c432915",
    "ProfileName": "Yellowsix of Juyo (US)",
    "LastUpdated": "2012-03-15T02:20:08",
    "Region": "US",
    "Server": "Juyo",
    "Name": "Yellowsix",
    "Guild": "GH-AMR",
    "Faction": "Empire",
    "AdvancedClass": "Powertech",
    "Level": 48,
    "Gender": "Male",
    "Race": "Rattataki",
    "Alignment": "Dark3",
    "SocialLevel": "Social1",
    "ValorRank": 8,
    "CraftingCrewSkill": "Armormech",
    "CrewSkill2": "Scavenging",
    "CrewSkill3": "UnderworldTrading",
    "SkillString": "1521022102122320032-00000000000000000202-000000000000000020",
    "ItemLists": [
    {
        "Companion": "None",
        "GearSets": [
        [
            {
            "CharacterSlot": "Chest",
            "Slot": "Chest",
            "Id": "30045",
            "VariantId": 0,
            "Mods": [
                {
                "Slot": "Mod",
                "Id": "5890",
                "VariantId": 0,
                "Name": "Advanced Deflecting Mod 25B",
                "ItemLevel": 58,
                "Quality": "Artifact",
                "Icon": "circuitry1_aim",
                "Stats": [
                    {
                    "Stat": "Aim",
                    "Value": 61
                    },
                    {
                    "Stat": "Endurance",
                    "Value": 37
                    },
                    {
                    "Stat": "Defense",
                    "Value": 11
                    }
                ]
                },
                {
                "Slot": "Enhancement",
                "Id": "9207",
                "VariantId": 0,
                "Name": "Advanced Astute Enhancement 25",
                "ItemLevel": 58,
                "Quality": "Artifact",
                "Icon": "armorunderlay1_def",
                "Stats": [
                    {
                    "Stat": "Endurance",
                    "Value": 40
                    },
                    {
                    "Stat": "Accuracy",
                    "Value": 51
                    },
                    {
                    "Stat": "Defense",
                    "Value": 20
                    }
                ]
                }
            ],
            "Name": "Battlemaster Supercommando's Body Armor",
            "ItemLevel": 58,
            "Quality": "Artifact",
            "Icon": "ipp.class.bh.pvp.rtank.t8x3.chest",
            "ArmorType": "Heavy",
            "WeaponType": null,
            "ShieldType": null,
            "Stats": [
                {
                "Stat": "Aim",
                "Value": 94
                },
                {
                "Stat": "Endurance",
                "Value": 108
                },
                {
                "Stat": "Expertise",
                "Value": 50
                },
                {
                "Stat": "Accuracy",
                "Value": 51
                },
                {
                "Stat": "Defense",
                "Value": 31
                }
            ],
            "ItemSetId": null
            },
            {
            "CharacterSlot": "Glove",
            "Slot": "Hands",
            "Id": "15384",
            "VariantId": 0,
            "Mods": [
                {
                "Slot": "Armoring",
                "Id": "10228",
                "VariantId": 0,
                "Name": "Reflex Armoring 21",
                "ItemLevel": 48,
                "Quality": "Prototype",
                "Icon": "overlay1_aim",
                "Stats": [
                    {
                    "Stat": "Aim",
                    "Value": 38
                    },
                    {
                    "Stat": "Endurance",
                    "Value": 27
                    }
                ]
                },
                {
                "Slot": "Mod",
                "Id": "7294",
                "VariantId": 0,
                "Name": "Nimble Mod 21A",
                "ItemLevel": 48,
                "Quality": "Prototype",
                "Icon": "circuitry1_aim",
                "Stats": [
                    {
                    "Stat": "Aim",
                    "Value": 38
                    },
                    {
                    "Stat": "Endurance",
                    "Value": 22
                    },
                    {
                    "Stat": "Crit",
                    "Value": 6
                    }
                ]
                },
                {
                "Slot": "Enhancement",
                "Id": "7913",
                "VariantId": 0,
                "Name": "Advanced Assault Enhancement 21",
                "ItemLevel": 48,
                "Quality": "Artifact",
                "Icon": "armorunderlay1_dps",
                "Stats": [
                    {
                    "Stat": "Endurance",
                    "Value": 17
                    },
                    {
                    "Stat": "Crit",
                    "Value": 28
                    },
                    {
                    "Stat": "Surge",
                    "Value": 33
                    }
                ]
                }
            ],
            "Name": "RD-16B Enforcer Gauntlets",
            "ItemLevel": 47,
            "Quality": "Custom",
            "Icon": "ipp.class.bh.bis.rdps1.t6x2.hands",
            "ArmorType": "Heavy",
            "WeaponType": null,
            "ShieldType": null,
            "Stats": [
                {
                "Stat": "Aim",
                "Value": 76
                },
                {
                "Stat": "Endurance",
                "Value": 66
                },
                {
                "Stat": "Accuracy",
                "Value": 0
                },
                {
                "Stat": "Crit",
                "Value": 34
                },
                {
                "Stat": "Surge",
                "Value": 33
                }
            ],
            "ItemSetId": null
            },
            {
            "CharacterSlot": "Belt",
            "Slot": "Belt",
            "Id": "1328",
            "VariantId": 598,
            "Mods": [],
            "Name": "Kessler Durasteel Girdle",
            "ItemLevel": 50,
            "Quality": "Premium",
            "Icon": "ipp.class.bh.randgreen.rdps2.t7x1.waist",
            "Sources": null,
            "ArmorType": "Heavy",
            "WeaponType": null,
            "ShieldType": null,
            "Stats": [
                {
                "Stat": "Armor",
                "Value": 409
                },
                {
                "Stat": "Aim",
                "Value": 60
                },
                {
                "Stat": "Endurance",
                "Value": 40
                },
                {
                "Stat": "Power",
                "Value": 5
                }
            ],
            "ItemSetId": null
            },
            {
            "CharacterSlot": "Leg",
            "Slot": "Legs",
            "Id": "15541",
            "VariantId": 0,
            "Mods": [
                {
                "Slot": "Augment",
                "Id": "0",
                "VariantId": 0,
                "Name": null,
                "ItemLevel": 0,
                "Quality": "Cheap",
                "Icon": null,
                "Stats": []
                }
            ],
            "Name": "RD-17A Master Striker Greaves",
            "ItemLevel": 50,
            "Quality": "Prototype",
            "Icon": "ipp.class.bh.bis.rdps1.t7x1.legs",
            "ArmorType": "Heavy",
            "WeaponType": null,
            "ShieldType": null,
            "Stats": [
                {
                "Stat": "Aim",
                "Value": 58
                },
                {
                "Stat": "Endurance",
                "Value": 68
                },
                {
                "Stat": "Accuracy",
                "Value": 34
                },
                {
                "Stat": "Power",
                "Value": 34
                }
            ],
            "ItemSetId": null
            }
        ]
        ]
    }
    ],
    "Datacrons": [
    8
    ]
}

Some notes on this format:

1. Lists of possible values for all enumerated values will be provided in API documentation. Things like AdvancedClass, Race, SocialLevel, etc.

2. The SkillString is a triplet separated by dashes, with each section representing a tree (from left to right as it appears in-game). Each digit corresponds to a specific skill in the tree: the least significant digit (right-most) is the bottom-left skill in the tree; the most significant digit (left-most) is the top-right skill in the tree. (bottom to top, left to right.) Pretty basic. On the website for URLs, we strip leading 0s and compress it to base 36 (from base 6). That compression is only used for URL shortening, and we won't be using it in the public API, though we could provide e.g. a SkillUrl field that is like "http://swtor.askmrrobot.com/skills/powertech#blahblah" for the sake of ease, so people could add a link directly to the talents without mucking about.

3. Datacrons are a list of proprietary IDs -- we will provide documentation (and a separate API call) to provide which IDs correspond to which datacrons.

4. ItemLists -- this is a dump of our internal format, and it may be simplified for final outside consumption. At the moment, a profile can have multiple ItemLists associated to it, one for the base player, and one for each companion. The list with Companion "None" is the base player's gear.

Each of those is a collection of GearSets -- a profile can support an arbitrary number of gear sets per player, e.g. on the website we provide "My Gear" and "Wishlist" at the moment, but will likely make this more customizable.

It is likely that the final API will have parameters that let the caller choose which gear set they wish to retrieve, rather than returning all of them, in which case we would flatten this to a single GearSet property on the overall profile. That's still up in the air.

5. Item IDs -- currently we use a proprietary ID assigned to each item, which are used in the URLs to items on our website as well. We also have the game IDs available, and better yet, the moniker. We will likely have a parameter to indicate whether the game id/moniker should be included in the returned json.

6. We can display a high level of detail about a person's gear, down to the stats on every item. We will have parameters to control the level of detail returned.

7. When stats are included, the stats on an item will always be the total of the stats on the item plus the stats of any mods currently equipped in the item.

8. The final API will also include "dynamic" stats on items, such as Armor, Rating, and weapon damage.

I'm sure there are a few other details worth discussing that I am forgetting, but that should be a decent start. Let me know if you all have any comments/feedback on this format.

[kray]

Caltiom, did I mistype something? I suggested

xxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx

for the talents. Just putting hyphens in there to separate the trees. Does that differ from what you're saying?

Edit: Bam. Yellowfive has what I'm talkin bout.

So, as far as the base character info, that format is exactly what I would like to use. It makes perfect sense, doesn't require an item lookup table, and contains all the character information we need. The next thing to talk about is the inclusion of theorycrafting-specific info. I know the initial proposal you mentioned having various tools have their own "section" of the save. Although convenient, the logistics behind implementing something like that are a bit staggering. Tell me your thoughts on the matter, Caltiom, as originally I hadn't even considered it.

[Jothay]

Yellow, I'm using a straight up NodeId >> 32 to get my Item Id's, can you tell us what you were doing in that?

[Yellowfive]

Jothay -- a 32 bit shift on the node ids doesn't seem like a very reliable approach to me... there's nothing guaranteeing that approach will always work as new stuff is added to the game.

Thus, we simply generate a short unique id for each item in our database. We will provide adequate information for people to relate these IDs to either the game ids and/or moniker -- by either including the game id/moniker right on the item, or providing a mapping file for anyone to download that maps our ids to the game ids/monikers.

I would recommend that the moniker be used for universal identification of items when necessary (e.g. itm.eq.random.cdps1.lightsaber.premium.level_38_dark). There is nothing guaranteeing that the game (node) ids will remain the same as the game progresses.

[Caltiom]

(03-15-2012 12:46 PM)kray Wrote:  Caltiom, did I mistype something? I suggested

xxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx

for the talents. Just putting hyphens in there to separate the trees. Does that differ from what you're saying?

Edit: Bam. Yellowfive has what I'm talkin bout.

So, as far as the base character info, that format is exactly what I would like to use. It makes perfect sense, doesn't require an item lookup table, and contains all the character information we need. The next thing to talk about is the inclusion of theorycrafting-specific info. I know the initial proposal you mentioned having various tools have their own "section" of the save. Although convenient, the logistics behind implementing something like that are a bit staggering. Tell me your thoughts on the matter, Caltiom, as originally I hadn't even considered it.

Sorry kray, I wasn't aware of your second post when writing my response yesterday.

About tools own sections: Well that's as I said up to each tool, not something we can discuss much here.
There might be some variables a tools could share with another ( eg. CombatLength ), but even there start the problems as for example SimC varies it's combat length by x% ( another parameter ), I don't think many others support that.
Action Lists are even worse, everyone has different standards here. I just don't see it possible to achieve much communication here unless tools use similar systems behind it.
Buffs/Debuffs might be something we could agree upon, but even there can be problems.

I'd really focus on the character information first, not everything is solved yet. The discussion about unique identifiers remains ( 32 bit shift not guaranteed to be unique, a map between item ids/arm monikers requires a extra third source, and original item id's are very long ) open, but that mainly concerns Rage and ARM.

About the structure of the whole thing: Here the question is if we want to just adapt to the ARM format or add a bit more structure to it?
This mainly concerns ARM-specific field like the ProfileID, ProfileName and LastUpdated. Would ARM be willing to move those to a specific ARM-section? And CrewSkills into its subsection, as well as some MetaData about a character. See First Post for what I mean.

Edit: Detail questions:

- I know one can have max 1 crafting crew skill. But can he have 0 crafting skills and 3 gathering ones?

[Yellowfive]

In the near future (next week or so), we'll be including a player's selected stance (form, cylinder, etc.), buffs, and stims with their profiles -- that information will be available via the API as well, I'll update when I've completed that part.

As for the profile id, profile name, and last updated date -- I feel that those are generic enough to leave as "first class citizens" of any standard format. ProfileId is simply a unique ID to identify the profile as a whole -- we use and I highly recommend a standard GUID, so that any tool or user can give an ID to a profile and be guaranteed that it will not collide. ProfileName is a human-readable name for the whole profile, a file name or label, if you will. LastUpdated is useful for versioning, sorting, if-modified-since optimizations, etc.

Those fields could of course be optional in some scenarios -- many tools may not need them. But in general, I could see many tools wanting/needing those 3 fields. It also gives a standard way to identify the same profile no matter where it gets loaded or used.

[Zoopercat]

Our API is live for those of you looking to use it: http://blog.askmrrobot.com/2012/03/chara...mentation/

[Marduc]

(03-15-2012 06:12 PM)Caltiom Wrote:  - I know one can have max 1 crafting crew skill. But can he have 0 crafting skills and 3 gathering ones?

Yepp, btdt