UPDATE [05/31/16]: CAPI has now been submitted to the Halo API Hackathon. You can see it here, thanks for all the support folks. There is still more work to be done, but the hard part is over:

Hackathon Entry - Cartographer API [CAPI]​

The Cartographer API, or CAPI for short, is a map analytics extension of the Halo API. It provides the ability to grab game data based on Maps, Gametypes, and Forgers rather than just Players and Games like the standard Halo API. This means that people will be able to see every custom game ever played on a map, be able to see how often their map is being played, generate statistics on their maps, and so much more.

I'm currently just previewing CAPI to draw up some discussion on it. My current projection will probably be within the next month. I've got the core of the system working that can essentially store every custom game available and keep the system up to date. At this point it is stress testing, catching edge cases, building the discovery system, and building out every materialized view for every question we could possibly want to answer. So expect it to come soon. On to the details...




API stands for a Application Program Interface. Basically it is a way to communicate with an application. So CAPI will be your interface for accessing map analytics. Data is returned in JSON format (a fairly standard format for web APIs), so the data will come back looking like this (this is just a rough example):

Code:

{
  "Map": "Goliath",
  "GamesPlayedOnMapTotal": 73,
  "CreatedDate": "2016-04-23T00:00:00Z",
  "UpdatedDate": "2016-04-23T00:00:00Z",
  "URL": "https://www.halowaypoint.com/en-us/games/halo-5-guardians/xbox-one/map-variants#ugc_halo-5-guardians_xbox-one_mapvariant_A%203%20Legged%20Goat_1849cde2-b4bc-40c2-a385-a689992da3fd",
  "Authors": [
  {
  "Gamertag": "Black Picture"
  },
  {
  "Gamertag": "Whos Blaze"
  }
  "GamesPlayedOnMapData": [
  {
  "PlayerStats": [
  {
  "KilledOpponentDetails": [
  {
  "GamerTag": "moo43",
  "TotalKills": 2
  },
  {
  "GamerTag": "THEMASTER952009",
  "TotalKills": 1
  },
  {
  "GamerTag": "LunaticLawyer",
  "TotalKills": 2
  },
  {
  "GamerTag": "MultiLockOn",
  "TotalKills": 3
  },
  {
  "GamerTag": "Hi Im Shaz",
  "TotalKills": 1
  },
  {
  "GamerTag": "A Wild Iron",
  "TotalKills": 1
  }
  ],
  "KilledByOpponentDetails": [
  {
  "GamerTag": "LunaticLawyer",
  "TotalKills": 2
  },
  {
  "GamerTag": "MultiLockOn",
  "TotalKills": 2
  },
  {
  "GamerTag": "moo43",
  "TotalKills": 1
  },
  {
  "GamerTag": "A Wild Iron",
  "TotalKills": 2
  },
  {
  "GamerTag": "Null Parameter",
  "TotalKills": 1
  },
  {
  "GamerTag": "Hi Im Shaz",
  "TotalKills": 2
  },
  {
  "GamerTag": "THEMASTER952009",
  "TotalKills": 1
  }
  ],
  "FlexibleStats": {
  "MedalStatCounts": [],
  "ImpulseStatCounts": [
  {
  "Id": "ba327946-418c-495d-90c0-89f084bf7447",
  "Count": 10
  },
  {
  "Id": "7dcd7306-f905-401a-97f2-345d4b25170a",
  "Count": 7
  },
  {
  "Id": "ea38d25f-d887-4bdf-b17b-8e8e649b9a87",
  "Count": 11
  },
  {
  "Id": "a1d97ad4-c1d9-4807-b619-ca3710cc5a8d",
  "Count": 0
  },
  {
  "Id": "3465eba1-608c-47d7-9cb6-ef4c7a55a2dd",
  "Count": 6
  },
  {
  "Id": "780104cb-5b86-4ed9-8fb1-40b919de0766",
  "Count": 1
  },
  {
  "Id": "a5a0d0d5-5c9f-4888-b42a-2c87f8e58336",
  "Count": 0
  },
  {
  "Id": "71ce2293-23bb-492f-a8c0-46e095b55eb7",
  "Count": 1
  }
  ],
  "MedalTimelapses": [],
  "ImpulseTimelapses": [
  {
  "Id": "f1c317ee-1ac4-4089-85e8-a9c536c6cf18",
  "Timelapse": "PT6M25.5491296S"
  }
  ]
  },
  "Player": {
  "Gamertag": "Time Glitch",
  "Xuid": null
  },
  "TeamId": 0,
  "Rank": 8,
  "DNF": false,
  "AvgLifeTimeOfPlayer": "PT23.319986S",
  "PreMatchRatings": null,
  "PostMatchRatings": null,
  "PlayerScore": null,
  "TotalKills": 10,
  "TotalHeadshots": 6,
  "TotalWeaponDamage": 1323.2091388702393,
  "TotalShotsFired": 166,
  "TotalShotsLanded": 82,
  "WeaponWithMostKills": {
  "WeaponId": {
  "StockId": 4096745987,
  "Attachments": []
  },
  "TotalShotsFired": 91,
  "TotalShotsLanded": 51,
  "TotalHeadshots": 6,
  "TotalKills": 7,
  "TotalDamageDealt": 917.58932113647461,
  "TotalPossessionTime": "PT2M32.5333S"
  },
  "TotalMeleeKills": 0,
  "TotalMeleeDamage": 70,
  "TotalAssassinations": 0,
  "TotalGroundPoundKills": 0,
  "TotalGroundPoundDamage": 70,
  "TotalShoulderBashKills": 0,
  "TotalShoulderBashDamage": 95,
  "TotalGrenadeDamage": 114.51982879638672,
  "TotalPowerWeaponKills": 1,
  "TotalPowerWeaponDamage": 93.5999984741211,
  "TotalPowerWeaponGrabs": 1,
  "TotalPowerWeaponPossessionTime": "PT35.0833S",
  "TotalDeaths": 11,
  "TotalAssists": 7,
  "TotalGamesCompleted": 0,
  "TotalGamesWon": 0,
  "TotalGamesLost": 0,
  "TotalGamesTied": 0,
  "TotalTimePlayed": "PT6M25.5491296S",
  "TotalGrenadeKills": 0
  }
  ]
}

With data like above, websites and applications can pull the data out of it and display it however they want. It is how websites like HaloCarnage.com exist. CAPI will do the same as the Halo API except give data centered around User Generated Content.

• What games have been played on my map?
• What players have played on my map?
• Who has played the most on my map and may be a good resource for feedback?
• What does the heatmap look like for my map?
• How much of an impact does this weapon have on my map?
• How often are people leaving games that are played on my map?
• Are players playing on the right version of my map?
• Has this reviewer even played on my map and how much have they?
• Have any pro/semi-pro/amateur pro players tried playing on my map?
• Who are my biggest fans as a level designer?
• How many people are playing on my map when I'm not there to ask them to?
• How has my map's popularity grown over time?
• How does this version of my map play compared to this version?

Spoiler: Level Designers (like you)

As a level designer this means that you can watch your content go viral. You can see how it is tested throughout the community. Imagine being able to see the statistics for every single custom game ever played on your map. Imagine being able to see a list of every single player that has played on your map. Even better see who has played your map the most and then ask to get some feedback from them since they have played your map X times. Perhaps you are interested in a heatmap of your level from every game ever played on it. Maybe you are curious to see how changing that DMR to a BR affected how your map played. Perhaps the average WeaponPossessionTime on the BR is less than it was when you had a DMR there instead. Or maybe you move a weapon from bottom blue to to blue, how did the WeaponPossessionTime change based on that? This is all stuff that you could learn from CAPI and more.

Spoiler: Communities (like Forgehub and Forge.World)

Your users are looking to post their maps on your site already... but with CAPI they can get statistics on their maps as well. Show them the latest game that was played on their map. Show them how many times their map has been played on. Use CAPI to get a list of popular maps based on criteria that would be difficult to aggregate on your own. Track versioning and update the version and link to a map as CAPI figures out what is the latest version for them. Perhaps reviews are getting out of hand and are a bit too troll-y... well then add testing statistics next to reviews and ensure that Forgers can get a glimpse of how much the reviewer has played the map before posting their review. This will help weed out the quality reviews from the useless reviews.

Spoiler: Halo App Developers (like the creator of HaloCarnage)

Time to build your next big app that is centered around the source of unlimited content for the Halo Community. Perhaps it is time to build a mobile app that allows Forgers to submit reviews for a map directly from their phone after playing on a map. How about a MapCarnage site that shows the latest games and auto-updates with the latest games based on maps rather than players? Have you thought about running a tournament site revolving around a particular set of maps? Have CAPI automatically finds these custom games for you based on that map's ID, and automatically verify who played in the game and have access to the statistics right there at your finger tips. The possibilities are endless.

Spoiler: Non-Halo Software Engineers

CAPI is a public display and open sourced project that will be streamed throughout its development. It will give software engineers of a variety of skill levels a glimpse and an example into using AWS as a serverless solution for an API. It will also show techniques that will help developers build code that is easier to read, easier to maintain, and easier to add features to. We want CAPI to be able to grow quickly and we have processes that are being followed to allow rapid development. Things like the Repository pattern, working with strictly domain objects to speed up development, and also using pub/sub models to not have to edit old services when new services are introduced. This will also help people take enterprise level concerns into account like monitoring and logging on a massive scale. AWS is a beautiful tool and show how small time devs can use it to maximize their productivity is part of the goal.

Spoiler: Halo

Halo will become a platform in which level designers have access to a tool like CAPI in order to quickly refine and iterate their maps with full blown analysis of how their changes affected the map. This will grow the quality of community maps which means better content for the community. The ability to watch your own map grow throughout the community means that more developers of maps will be more engaged and more motivated to complete and test content. More testing is always better. More playing is always better. Was there a problem finding content for matchmaking? Are the wrong maps being pushed up? This can be validated with CAPI, finding out what content is actually trending in terms of people actually playing on the map. Validate if someone who proposes a map for matchmaking isn't doing it prematurely. Find the best maps out there based on actual playtime statistics not just based on how many times someone has saved a file.

Because CAPI is an API this means that it can be tapped into just like the Halo API and custom web apps, mobile apps, and more can be created based on the data that CAPI provides. It does this by storing every single custom game ever played and then running those custom games through an analytics system that takes note of answers to questions like what map was this game played on? Sounds like a lot of information right? Well it is. Storing every custom game and the analysis for maps will take a huge amount of storage and the entire system will need to have a ton of processing power to pull this off. And this would normally be a huge development effort? Open up the spoiler below for more details on how that will be handled.

Spoiler: Tech Details

Enter Amazon Web Services (AWS)... AWS provides an infinitely scalable platform that will allow CAPI to grow to whatever it needs to grow to. Using the latest tech like AWS Lambda and AWS Gateway means that CAPI is backed by enterprise level tech and hardware to ensure it meets the expected demands of the Halo Community. I won't bore you too much with the technology, but if you are interested then there are some details on the Bitbucket repository page. And that leads to my next point.

CAPI is an open source project. This means that not only does CAPI exist for the improvement of the Halo Community, but it also exists for the teaching of an enterprise level API that is easy to manage thanks to the beauty of AWS. And that means that any member of the Halo Community that has the know how can participate in the development of CAPI. All of my development for CAPI will be live streamed for the world to watch how the system grows and learn from its explorations through LiveCoding.tv. And those that have even a bit of development experience can learn, ask questions, and help build CAPI to be the best that it can be.

In addition CAPI is looking to also hold some key software engineering principles to speed up development. A serverless architecture will be used to remove the overhead of most of the systems work. No managing servers, deploying servers, or dealing with databases crashing. Nanoservices is how things will be segmented. Thanks to AWS Lambda we are able to keep our business logic in small compartmentalized portions without ridiculous overhead to deployment of new features. Also following things like the SOLID principles, pub/sub systems, and things like automation will speed up the development of features. And thanks to AWS we will have a lot of features covered for us like logging, monitoring, and scaling. All in all this means that it will be wonderfully simple to add new features to CAPI within a matter of hours or a few days. This will allow developers to focus on what matters. Below is a current model of the architecture that is in place right now. Anything in red lettering has not been implemented yet and this is far from complete as the system is just going to keep growing from here.

​

When I first saw the Halo API, my first thought was is it possible to have these kind of statistics for maps? And then I saw it... the map and game variant data on a game. So here I am today, after having built a forge team and experienced the new Forge for myself. Last month I made plans to build this project as I had finished my contract with Nike in February. Not only did I feel that this would be powerful for my hobby and the community I care about, but also that it would help be a display of public code to show what I know how to do. Because all of my work has been proprietary so no new employer will ever get a feel for what I know at first glance. So I plan to go all out with this project and with the support of my partner, Jessica, I have the time to devote to this ambitious project. So expect me to pull out all the stops to make this a success.

I dreamed big while designing CAPI. One of the ideas I had while designing CAPI's functionality is that CAPI can be an additional Artificial Intelligence character in the Halo universe. CAPI cares about the growth of the future. It cares about the builders and the architects and hopes to support their endeavors as environments come into fruition. CAPI is being designed with this thought in mind. Perhaps its interface will be a little more interactive than most sites... perhaps CAPI will communicate with Cortana on Windows 10. CAPI is here to assist the Forgers of the Halo Community to achieve great things. I hope that CAPI will do good for this community. I've been around since the birth of Forgehub... that is a LONG time since Forge came to life in Halo 3. And I hope that the experiences that I have gained (both as a level designer and as a software engineer) will help bring this community a tool that helps it thrive going forward. I grew up in Halo... and I'm looking forward to seeing how it grows with this new addition to the universe.

​

• https://bitbucket.org/GodlyPerfection/cartographer-api

The open sourced public repository for CAPI development.

• https://www.livecoding.tv/godlyperfection/

My LiveCoding.tv stream where you can watch me code CAPI. This means you can ask questions, stay up to date on the roadmap, and more.

• https://www.reddit.com/r/halo/comments/4grdmm/for_the_halo_community_and_hackathon_contest/

The reddit post for those that want to help CAPI get out there into the world.




Do you have any ideas on what CAPI could do? Use this thread as an idea generation space. Help design a tool that will bring the level design community that much further.