ESO UI API Patch Highlights (V100019)Battlegrounds
Battlegrounds have been added to ESO. There are a number of code concepts that support this:
Battleground Alliance
Players are randomly assigned to one of three battleground alliances when they enter the battleground. The battleground alliances are:
- BATTLEGROUND_ALLIANCE_FIRE_DRAKES
- BATTLEGROUND_ALLIANCE_PIT_DAEMONS
- BATTLEGROUND_ALLIANCE_STORM_LORDS
You can query a unit’s battleground alliance with:
- GetUnitBattlegroundAlliance(unitTag) – battlegroundAlliance
- GetBattlegroundAllianceName(battlegroundAlliance) - name
Battleground Game Type
There are a number of battleground game types, each with their own rules and objectives:
- BATTLEGROUND_GAME_TYPE_CAPTURE_THE_FLAG
- BATTLEGROUND_GAME_TYPE_CRAZY_KING
- BATTLEGROUND_GAME_TYPE_DEATHMATCH
- BATTLEGROUND_GAME_TYPE_DOMINATION
- BATTLEGROUND_GAME_TYPE_KING_OF_THE_HILL
- BATTLEGROUND_GAME_TYPE_MURDERBALL
Note that of these, CAPTURE_THE_FLAG, DOMINATION, and DEATHMATCH are active for this release; other game types are in various stages of development and are subject to change or not being released.
The following functions have been added to learn about the battleground game type:
- GetCurrentBattlegroundId() – battlegroundId
- GetBattlegroundGameType(battlegroundId) – gameType
- GetBattlegroundName(battlegroundId) – name
- GetBattlegroundDescription(battlegroundId) – description
- GetBattlegroundInfoTexture(battlegroundId) – path
- GetScoreToWinBattleground(battlegroundId) – scoreToWin
- GetBattlegroundNearingVictoryPercent(battlegroundId) – nearingVictoryPercent
- GetCurrentBattlegroundScore(battlegroundAlliance) – score
- LeaveBattleground()
- IsActiveWorldBattleground() - isBattleground
EVENT_BATTLEGROUND_RULESET_CHANGED is sent when the game type changes. ZONE_SCORING_CHANGED is sent when the battleground score changes.
Battleground State
A battleground moves through a number of states as it goes through its lifetime. The states are:
- BATTLEGROUND_STATE_PREGAME
- Waiting for enough players to start.
- BATTLEGROUND_STATE_STARTING
- Counting down until the battleground starts.
- BATTLEGROUND_STATE_RUNNING
- BATTLEGROUND_STATE_POSTGAME
- Game is done, counting down until players are removed.
EVENT_BATTLEGROUND_STATE_CHANGED is sent when the state changes. The query functions are:
- GetCurrentBattlegroundState() – battlegroundState
- IsCurrentBattlegroundStateTimed() – isTimed
- GetCurrentBattlegroundStateTimeRemaining() – timeRemaining
Objectives
Objectives will be familiar to those who have worked with the capture areas in Cyrodiil or Imperial City. Battlegrounds make use of a number of different objective types, each with their own mechanics and state. The relevant objectives for this patch are:
- OBJECTIVE_CAPTURE_AREA
- Stand near a banner to capture.
- When there are multiple of these they are distinguished by their designation. Use GetObjectiveDesignation(keepId, objectiveId, battlegroundContext) – designation.
- OBJECTIVE_DESIGNATION_A
- OBJECTIVE_DESIGNATION_B
- OBJECTIVE_DESIGNATION_C
- OBJECTIVE_DESIGNATION_D
- OBJECTIVE_FLAG_CAPTURE
- Pick up a flag and return it to your base to score.
Objectives have a lot of shared functionality for finding objectives and learning about them:
- GetNumObjectives() – numObjectives
- Number of objectives the client knows about. Will also include Cyrodiil objectives if you have a home campaign.
- GetObjectiveIdsForIndex(index) – keepId, objectiveId, battlegroundContext
- The three part key that uniquely identifies an objective. For battlegrounds, keepId is always 0 and battlegroundContext is BGQUERY_LOCAL. From here on these three values will be replaced with “ids” for brevity.
- IsBattlegroundObjective(ids) - isInBattleground
- DoesObjectiveExist(ids) – exists
- GetObjectiveType(ids) – objectiveType
- GetObjectiveControlState(ids) – controlState
- There are many states an objective can be in.
- OBJECTIVE_CONTROL_STATE_AREA_ABOVE_CONTROL_THRESHOLD
- OBJECTIVE_CONTROL_STATE_AREA_BELOW_CONTROL_THRESHOLD
- OBJECTIVE_CONTROL_STATE_AREA_MAX_CONTROL
- OBJECTIVE_CONTROL_STATE_AREA_NO_CONTROL
- OBJECTIVE_CONTROL_STATE_FLAG_AT_BASE
- OBJECTIVE_CONTROL_STATE_FLAG_AT_ENEMY_BASE
- OBJECTIVE_CONTROL_STATE_FLAG_DROPPED
- OBJECTIVE_CONTROL_STATE_FLAG_HELD
- GetObjectiveInfo(ids) – name, objectiveType, objectiveState
- GetObjectivePinInfo(ids) – pinType, normalizedX, normalizedY, continuousUpdate
- continuousUpdate is true if the objective moves around like a capture flag.
- GetObjectiveSpawnPinInfo(ids) - pinType, normalizedX, normalized
- Capture flag objectives have a spawn location in addition to the objective itself.
- GetObjectiveAuraPinInfo(ids) – pinType, r, g, b
- The aura pin sits behind the objective pin to give information on which team is influencing the objective. It is always at the same location as the objective pin. The r, g, b is used to color it.
- GetObjectiveReturnPinInfo(ids) - pinType, normalizedX, normalizedY, continuousUpdate
- Capture flag objectives are also returned to a specific location to score.
Carryable objectives such as the capture flag have carrying related APIs:
- IsCarryableObjectiveCarriedByLocalPlayer(ids) – isCarried
- GetCarryableObjectiveHoldingAllianceInfo(ids) – holdingAlliance, lastHoldingAlliance
- GetCarryableObjectiveHoldingCharacterInfo(ids) – characterName, displayName, classId
- GetCarryableObjectiveLastHoldingCharacterInfo(ids) - characterName, displayName, classId
Capture areas alone have:
- IsCaptureAreaObjectiveCaptured(ids) – isCaptured.
- A capture area is captured when the owning alliance is above 50% on the meter.
Capture Flags alone have:
- GetCaptureAreaObjectiveOwner(ids) – ownerAlliance
- GetCaptureAreaObjectiveLastInfluenceState(ids) – alliance, wereInfluenceSourcesInRangeOfCaptureArea
- Provides information on which team is influencing an objective. Influencing means pushing the capture meter in their direction. wereInfluenceSourcesInRangeOfCaptureArea is false when no one is around. When it is true, if the alliance is NEUTRAL then there are equal numbers of players from multiple teams so no one is actively influencing the area. This information is also available for Cyrodiil.
- GetCaptureFlagObjectiveOriginalOwningAlliance(ids) – originalOwningAlliance
- The team that starts with control of this objective.
Objectives have a number of specific events for when they change. These are the relevant ones for this patch:
- EVENT_CAPTURE_AREA_STATE_CHANGED
- EVENT_CAPTURE_FLAG_STATE_CHANGED
Medals
Each battleground has a number of different medals it can award. Each medal is worth a fixed number of points and is granted when a condition is met. Querying the medals that a battleground can award is done with:
- GetBattlegroundNumUsedMedals(battlegroundId) – numMedals
- GetBattlegroundMedalIdByIndex(battlegroundId, medalIndex) – medalId
Learning about the medals can be done using the medalId in the following APIs:
- GetMedalInfo(medalId) – name, textureName, iconTexture, condition, scoreReward
- GetMedalName(medalId) – name
- GetMedalScoreReward(medalId) – scoreReward
Finally, you can query which medals each person in a battleground has earned using the scoreboard APIs:
- GetNextScoreboardEntryMedalId(slotIndex, lastMedalId) – nextMedalId
- GetScoreboardEntryNumEarnedMedalsById(slotIndex, medalId) – count
When the player earns a medal EVENT_MEDAL_AWARDED is sent.
Scoreboard
The battleground scoreboard has entries for all players in the battleground. You can query its contents with:
- GetNumScoreboardEntries() – numEntries
- GetScoreboardPlayerEntryIndex() - playerIndex
- GetScoreboardEntryInfo(slotIndex) – characterName, displayName, battlegroundAlliance, isLocalPlayer
- GetScoreboardEntryBattlegroundAlliance(slotIndex) – battlegroundAlliance
- GetScoreboardEntryClassId(slotIndex) – classId
- GetScoreboardEntryScoreByType(slotIndex, scoreType) – score
- This function can return information on a number of stats that we collect over the course of the battleground for each player. scoreType is one of:
- SCORE_TRACKER_TYPE_ASSISTS
- SCORE_TRACKER_TYPE_CAPTURE_DEFENSE_POINTS
- SCORE_TRACKER_TYPE_CAPTURE_KILLED_ATTACKER
- SCORE_TRACKER_TYPE_CAPTURE_KILLED_DEFENDER
- SCORE_TRACKER_TYPE_DAMAGE_DONE
- SCORE_TRACKER_TYPE_DAMAGE_TAKEN
- SCORE_TRACKER_TYPE_DEATH
- SCORE_TRACKER_TYPE_FLAG_CAPTURED
- SCORE_TRACKER_TYPE_HEALING_DEFENDERS
- SCORE_TRACKER_TYPE_HEALING_DONE
- SCORE_TRACKER_TYPE_KILL
- SCORE_TRACKER_TYPE_KILLED_FLAG_CARRIER
- SCORE_TRACKER_TYPE_KILL_STREAK
- SCORE_TRACKER_TYPE_SCORE
Leaderboards
The battlegrounds system includes several leaderboards ranking players by total personal score accumulated. There are presently three leaderboards, one for each battlegroundLeaderboardType (Deathmatch, Flag Games, Land Grab).
- QueryBattlegroundLeaderboardData()
- GetNextBattlegroundLeaderboardType(lastBattlegroundLeaderboardType) – nextBattlegroundLeaderboardType
- GetNumBattlegroundLeaderboardEntries(battlegroundLeaderboardType) – numEntries
- GetBattlegroundLeaderboardEntryInfo(battlegroundLeaderboardType, entryIndex) – rank, displayName, characterName, score
- GetBattlegroundLeaderboardLocalPlayerInfo(battlegroundLeaderboardType) – currentRank, currentScore
- GetBattlegroundLeaderboardsSchedule() – secondsUntilEnd, secondsUntilNextStart
Subscriber Bank
A new bank bag has been added to the game for ESO Plus subscribers and is named BAG_SUBSCRIBER_BANK. The size of the bag is the same as BAG_BACKPACK. We have also added a new bag function, GetBagUseableSize(bagId), to return how many usable slots a bag has. This will return 0 for the subscriber bank if the player does not have ESO Plus. This new bag also necessitated some changes in the lua inventory objects to support multiple bags appearing in a single inventory view. Look out for functions that once took inventoryType now taking bagId as an additional parameter.
Skill Discovery
Some skill lines are now hidden by default and are awarded based on completing quests or other game actions. The GetSkillLineInfo(skillType, skillIndex) API now also returns discovered to indicate if the player has discovered that skill line. EVENT_SKILL_LINE_ADDED is sent when a skill line is discovered.
Center Screen Announcements
Center screen announcements have been refactored in a few ways. Instead of supplying a long, long, long list of returns to specify all of the details of the announcement, you now return messageParams object created from CENTER_SCREEN_ANNOUNCE:CreateMessageParams(type, sounds). All of the existing functionality can be accessed by calling the appropriate functions on the messageParams object. We have also changed priority and filtering to be based on the new CENTER_SCREEN_ANNOUNCE_TYPE enum instead of events because there were more and more announcements not triggered by events. Finally, we have added two new announcement types called CSA_CATEGORY_MAJOR_TEXT and CSA_CATEGORY_COUNTDOWN_TEXT. These are used for battleground messages and countdowns (battleground start and dueling) respectively.
Compass Group Members
New settings have been added to control when group members appear on the compass. By default they only appear on the compass in battlegrounds. The settings are:
- UI_SETTING_COMPASS_GROUP_LEADER
- UI_SETTING_COMPASS_GROUP_MEMBER_AVA
- UI_SETTING_COMPASS_GROUP_MEMBER_BATTLEGROUND
- UI_SETTING_COMPASS_GROUP_MEMBER_DELVE
- UI_SETTING_COMPASS_GROUP_MEMBER_DUNGEON
- UI_SETTING_COMPASS_GROUP_MEMBER_GENERAL
- UI_SETTING_COMPASS_GROUP_MEMBER_RAID
The settings can be set to either true or false.
Furnishing Materials
ITEMTYPE_FURNISHING_MATERIAL has been added to distinguish furnishing materials. We have also added specialized item types for these:
- SPECIALIZED_ITEMTYPE_FURNISHING_MATERIAL_ALCHEMY
- SPECIALIZED_ITEMTYPE_FURNISHING_MATERIAL_BLACKSMITHING
- SPECIALIZED_ITEMTYPE_FURNISHING_MATERIAL_CLOTHIER
- SPECIALIZED_ITEMTYPE_FURNISHING_MATERIAL_ENCHANTING
- SPECIALIZED_ITEMTYPE_FURNISHING_MATERIAL_WOODWORKING
Guild Permissions
GUILD_PERMISSION_BANK_VIEW_DEPOSIT_HISTORY, GUILD_PERMISSION_BANK_VIEW_GOLD, and GUILD_PERMISSION_BANK_VIEW_WITHDRAW_HISTORY have been added but are not yet functional.
Compass Pin Colors
Compass pins can now be tinted using SetPinTint(pinType, r, g, b, param1, param2, param3)
Miscellaneous
- JumpToSpecificHouse(displayName, houseId)
- PreviewItemLink(itemLink, dyeBrushId)
- GetItemLinkGrantedRecipeIndices(itemLink) – recipeListIndex, recipeIndex