Third Party Developer Blog

Jul
7

Aegis Sovereignty API Changes

CCP FoxFour | 2015-07-07 11:05 | Comments

With just under a week to go before the new Sovereignty system hits Tranquility it's probably time that we start getting you information on the APIs we will be deploying to support it. So without further rambling, here’s the details.

Structures

All of the new APIs are in CREST and the first resource to look at is the SovStructures resource. This lists every structure in New Eden that is contributing to sovereignty be it a TCU, IHub, or a station. This is completely public information that will be available from within the client and so we are also making available via public CREST to everyone. Here is how it looks in the client:

Via the client you can show info on any solar system in the game to get details about the structures in that system. You can also find a list of all your alliances structures via the Corporation -> Alliances -> Sovereignty interface. Here is an example of how it will look in the CREST API: https://gist.github.com/Regner/78ad881108dcf2ea3600

Let’s walk through some of the details:

  • The route is: /sovereignty/structures/
  • We are going to start with a 5 minute cache on this resource.
  • This is a collection, which means it will have an items element containing a list of all the "things".
  • Collections may be paginated, but ideally they won’t be. I am waiting for this to hit Duality to get a better feel for how many structures there should be per page. Either way, you should be prepared to follow page links if they are present. See the alliances resource for an example.
  • Each entry in the items list contains:
    • solarSystem: The system in which the structure is located.
    • structureID: Unique item ID for this structure.
    • type: A reference to the type of structure this is. This contains its typeID, name, and a link to the types resource.
    • alliance: The alliance that owns the structure.
    • vulnerableStartTime: The next time at which the structure will become vulnerable. Or the start time of the current window if current time is between this and vulnerableEndTime.
    • vulnerableEndTime: The time at which the next or current vulnerability window ends. At the end of a vulnerability window the next window is recalculated and locked in along with the vulnerabilityOccupancyLevel. If the structure is not in 100% entosis control of the defender, it will go in to 'overtime' and stay vulnerable for as long as that situation persists. Only once the defenders have 100% entosis control and has the vulnerableEndTime passed does the vulnerability interval expire and a new one is calculated.
    • vulnerabilityOccupancyLevel: The occupancy level for the next or current vulnerability window. This takes into account all development indexes and capital system bonuses. Also known as Activity Defense Multiplier from in the client.  It increases the time that attackers must spend using their entosis links on the structure.

The trickiest part of that resource is understanding the vulnerability window information. The most important bit to understand is that at the end of a vulnerability window we calculate the next vulnerability window. It is at that time we look at the development indexes and capital system, and lock that information in. This is then used to calculate not only how big the vulnerability window will be but also what vulnerabilityOccupancyLevel bonus will be used for modifying things like the entosis link time.

You can find an example of this resource on Gist: https://gist.github.com/Regner/78ad881108dcf2ea3600

Campaigns

When a sovereignty structure is successfully contested by using entosis links, it will trigger what is called a Command Node Campaign - the event in which alliances must capture nodes throughout the constellation. Depending on a few conditions the type of campaign will be different. Before we dive into the structure of the API I just want to briefly review what that flow looks like.

For TCUs and IHubs: if the attackers manage to complete an entosis capture on the structure, it will create a structure defense campaign of type 1 or 2 respectively. These events pit the owning alliance against all other alliances in New Eden for the campaign. If the defender successfully wins the campaign, then the structure will revert back to its normal, owned state. However if they lose the campaign then the structure will explode. 

Stations are slightly different. They start off the same as a TCU or IHub, in that when the attackers complete the entosis capture a Station Defense campaign (type 3) is started, where the defending alliance is against all other alliances. The difference is that if the defenders lose, the station does not blow up like a TCU or IHub. Instead, when Station Defense campaign is won by the attackers the station goes into a Freeport mode, and schedules another campaign (type 4 - Station Freeport). This second campaign is different from the first 3 in that there is no defending alliance. All attackers show up in a list and simply the first to 100% wins.

Details for the campaigns resource:

  • The route is: /sovereignty/campaigns/
  • To start with it will have a 30 second cache time.
  • Like the structures resource it is a collection which can be paginated. It will start by listing all campaigns on one page but that may be changed.
  • Each entry in the items list contains:
    • campaignID: Unique ID for this campaign.
    • sourceItemID: The structure item ID that is related to this campaign.
    • sourceSolarsystem: The solar system the structure is located in.
    • constellation: The constellation in which the campaign will take place.
    • eventType: Type of event this campaign is for. 1 = TCU defense, 2 = IHub defense, 3 = Station defense, 4 = Station Freeport.
    • startTime: Time the event is scheduled to start spawning command nodes.
    • scores: This is an optional field that is present in eventType 4.
      • team: Alliance participating in the event.
      • score: Score for the specified alliance.
    • defender: This is an optional field that is present in eventType 1, 2, and 3.
    • defender: Defending alliance.
    • score: Score for the defending alliance.
    • Score for all attacking parties.
    • attackers: This is an optional field that is present in eventType 1, 2, and 3.

You can find an example of this resource on Gist: https://gist.github.com/Regner/69190d239609fb8b016a

Alliances

We have added two new optional fields to the alliances resource. Those fields are the primeHour and capitalSystem.

Test Server

These changes are available on Duality for testing right now. You can access it here: https://public-crest-duality.testeveonline.com

As always with a test server this information is subject to change.

back