Upwell 2.0 ESI Structure Changes
Upwell 2.0 ESI Structure Changes
Greetings developers!
If you've been watching our dev blogs you'll know that there are some upcoming changes to structures coming on February 13th. This blog will serve as a short summary of the changes that affect ESI and how ESI is going to accommodate those changes. These structure changes will also be the catalyst for the removal of two CREST routes.
ESI changes to expect on February 13th
Before jumping into the details of what is changing in game and in ESI, it is best to give a higher level view of which ESI routes are affected and how these changes will be handled. There are two ESI routes affected by these structure changes:
- GET /corporations/{corporation_id}/structures/
-
PUT /corporations/{corporation_id}/structures/{structure_id}/
After downtime on February 13th a few changes will take place with GET /corporations/{corporation_id}/structures/:
-
The v1 version will be labelled as legacy only, meaning it will start returning a deprecated warning header.
-
The properties
current_vulandnext_vulreturned by the v1 route will start returning an empty list (e.g.[]). This is to ensure that it doesn't break the spec for any software currently using it. -
A v2 version of this route will then be released and labelled as latest.
A disabled v2 version has already been released and labelled dev so you can see the spec now.
Our metrics indicate that the PUT /corporations/{corporation_id}/structures/{structure_id}/ route has no usage. Therefore, we have elected not to create a replacement for the new structure vulnerability system. On release day (February 13th) this route will be labelled as legacy only, start returning deprecated headers, and will always return HTTP status code 204. It will remain this way for two weeks when it will then be completely removed and start returning 404s. If you feel strongly that a replacement is needed, please make a case for it on our esi-issues Github repository.
For more details about what is changing in game and how that will be represented in v2 of /corporation/{corporation_id}/structures, read on.
New "Full Power" and "Low Power" Modes
Structures will now be in one of two modes: "full power" or "low power". If a structure has one or more online service modules it is considered be in full power mode. If a structure is in low power mode (meaning it has no online service modules) it will affect the structure in two ways:
- The structure will have significantly reduced shield and armor resistances.
- The structure will have one less reinforcement cycle (read on for more details about reinforcement cycles).
A low power structure can be identified in the client by a label on their text bracket beside the structure name:
The determination of whether a structure is high or lower power will be left to third party developers at this time. But there is only one question you need to answer to determine if a structure is in full power mode:
Does it have more than 0 online service modules?
If it does, it's in full power mode. If it doesn't, it's in low power mode. All services of a structure are returned in the property services from /v2/corporations/{corporation_id}/structures/ and each service has a state property saying whether is online or offline. Here is an example of a structure that is considered to be in full power mode:
{
"structure_id": 1000000013521,
"type_id": 35832,
"corporation_id": 98000002,
"system_id": 30004240,
"profile_id": 1,
"reinforce_weekday": 3,
"reinforce_hour": 2,
"state": "shield_vulnerable",
"services": [
{
"name": "Manufacturing (Standard)",
"state": "online"
}
],
}
This is because the state of it's service is "online". If the service's state was "offline" it would be considered low power.
New Vulnerability and Reinforcement System
The February 13th release will see a change to the systems surrounding structure vulnerability and reinforcement. Attacks against upwell structures will now consist of a possible three phases depending on whether the structure is in full power or low power mode:
- An initial attack that can occur at any date and any time chosen by the attackers.
- An optional attack if the structure is in full power mode that will occur in the time zone of the defenders, on the day chosen by the attackers.
- A final battle that occurs in the time zone and day chosen by the defenders to allow them a last stand.
Under this new system, the shield hitpoints of Upwell structures will be vulnerable to attack at all times. This allows attackers to attack at any time they choose. If a structure's shields are brought to 0 it will either enter its first reinforced state if it is at full power or go straight to it's final reinforced state. Here is a flow chart detailing all the states a structure can be in with the new system:
For more detailed information about the new reinforcement system please see this blog.
Each structure displayed by /v2/corporations/{corporation_id}/structures/ will have three new required properties and three optional properties to represent these in game mechanics.
The required properties are:
-
state- This string property will return which state (from the flowchart above) that a structure is in (e.g. shield_vulnerable, hull_vulnerable, etc.). -
reinforce_weekday: This int32 property represents the day of the week when the structure will exit its final reinforcement period and become vulnerable to attack against its hull. It is represented from 0 - 6 with 0 being Monday. -
reinforce_hour: This int32 property represents the hour of day that determines the four hour window when the structure will randomly exit its first and final reinforcement periods and become vulnerable to attack against its armor and/or hull. The structure will become vulnerable at a random time that is +/- 2 hours centered on the value of this property.
The optional properties are next_reinforce_weekday, next_reinforce_hour and next_reinforce_apply. These will only show up if a change to the reinforce_weekday and reinforce_hour have been requested in the client. All changes to reinforce_weekday and reinforce_hour take seven days to be applied in game. The date and time these changes will take effect will be the value of next_reinforce_apply.
Here is an example return from /v2/corporations/{corporation_id}/structures showing two structures where the first structure is in full power mode and has requested to change its reinforcement day and hour and the second structure is in low power mode:
[
{
"structure_id": 1000000013521,
"type_id": 35832,
"corporation_id": 98000002,
"system_id": 30004240,
"profile_id": 1,
"reinforce_weekday": 3,
"reinforce_hour": 2,
"state": "shield_vulnerable",
"services": [
{
"name": "Manufacturing (Standard)",
"state": "online"
}
],
"next_reinforce_weekday": 1,
"next_reinforce_hour": 4,
"next_reinforce_apply": "2018-02-15T14:42:25Z"
},
{
"structure_id": 1000000013514,
"type_id": 35832,
"corporation_id": 98000002,
"system_id": 30004238,
"profile_id": 1,
"reinforce_weekday": 5,
"reinforce_hour": 18,
"state": "hull_vulnerable"
}
]
Changes to CREST
As CREST is in maintenance only mode, it will not be updated to reflect the new system. On February 13th, both CREST endpoints will simply be deleted, and will start returning 404 errors.
- GET /corporations/<corporationID:corporationIdType>/structures/
- PUT /structures/<structID:integerType>/
Conclusion
We're excited to continue releasing new features in ESI along with new features in the game. Happy structure hunting and as always you can chat with us and our helpful community about these changes and more on our #esi slack channel.
o7
-- Team Tech Co
Get a sneak peek at what's coming to ESI by watching our deployment timeline.
Migrating from the XML API? Find equivalent ESI endpoints to the XML API.
Migrating from CREST? Find Equivalent ESI endpoints to CREST.