coa-details/API.txt

This is a short document for Details! API, describing attributes, combat, container, actor.
It still is incomplete, we are working on.

This is a diagram showing the structure: http://i.imgur.com/vyTjpFh.png

Attributes:
=======================================
All these keys are globals:

DETAILS_ATTRIBUTE_DAMAGE = 1
DETAILS_SUBATTRIBUTE_DAMAGEDONE = 1
DETAILS_SUBATTRIBUTE_DPS = 2
DETAILS_SUBATTRIBUTE_DAMAGETAKEN = 3
DETAILS_SUBATTRIBUTE_FRIENDLYFIRE = 4
DETAILS_SUBATTRIBUTE_FRAGS = 5
DETAILS_SUBATTRIBUTE_ENEMIES = 6
DETAILS_SUBATTRIBUTE_VOIDZONES = 7

DETAILS_ATTRIBUTE_HEAL = 2
DETAILS_SUBATTRIBUTE_HEALDONE = 1
DETAILS_SUBATTRIBUTE_HPS = 2
DETAILS_SUBATTRIBUTE_OVERHEAL = 3
DETAILS_SUBATTRIBUTE_HEALTAKEN = 4
DETAILS_SUBATTRIBUTE_HEALENEMY = 5
DETAILS_SUBATTRIBUTE_HEALPREVENTED = 6

DETAILS_ATTRIBUTE_ENERGY = 3
DETAILS_SUBATTRIBUTE_REGENMANA = 1
DETAILS_SUBATTRIBUTE_REGENRAGE = 2
DETAILS_SUBATTRIBUTE_REGENENERGY = 3
DETAILS_SUBATTRIBUTE_REGENRUNE = 4

DETAILS_ATTRIBUTE_MISC = 4
DETAILS_SUBATTRIBUTE_CCBREAK = 1
DETAILS_SUBATTRIBUTE_RESS = 2
DETAILS_SUBATTRIBUTE_INTERRUPT = 3
DETAILS_SUBATTRIBUTE_DISPELL = 4
DETAILS_SUBATTRIBUTE_DEATH = 5
DETAILS_SUBATTRIBUTE_DCOOLDOWN = 6
DETAILS_SUBATTRIBUTE_BUFFUPTIME = 7
DETAILS_SUBATTRIBUTE_DEBUFFUPTIME = 8

TL;DR
=======================================
A history segment container is the higher table in the hierarchy, it holds combat objects.
Current and overall combat objects are directly attached to the core. When a combat finishes, it detach and is sent to history container.
A Combat Object has 4 tables: damage on index 1, healing on index 2, energy on index 3, misc on index 4.
Those tables are called 'containers', these containers holds 'Actor Objects'.
Actor Objects hold a target table and a spell table.
Each player will have 4 tables, one for each attribute, e.g. 1 for store its damage, another for the healing done.
Actor Objects also has specific members for each attribute, see below.

Getting Details! Object:
=======================================
Just get the global 'Details', for instance:
local details = _G.Details


Getting a Combat Object:
=======================================

combat = Details:GetCurrentCombat()
returns the current combat object.

combat = Details:GetCombat (combat)
returns the requested combat object.
if 'combat' is omitted, returns the current combat.
combat can be a number: -1 for overall, 0 for current and > 0 for past segments.
combat also can be a string "overall" or "current".

history_segment_container = Details:GetCombatSegments()
returns the numeric table containing all past segments.

Gettings an Actor:
=======================================

local actor = Details:GetActor (combat = "current", attribute = 1, actorname = playername)
returns the actor for the requested combat, attribute and actor name.
if all parameters are omitted, returns the damage actor object of the player for the current combat.

Combat Object:
=======================================

A Combat object is a table with 4 numerical indexes holding: damage, healing, energy and misc containers.
function for combat objects:

actor = combat ( attribute, character_name )
returns an actor object

characterList = combat:GetActorList ( attribute )
returns a numeric table with all actors of the specific attribute, contains players, npcs, pets, etc.

combatName = combat:GetCombatName ( try_to_find )
returns the segment name, e.g. "Trainning Dummy", if try_to_find is true, it searches the combat for a enemy name.

bossInfo = combat:GetBossInfo()
returns the table containing informations about the boss encounter.
table members: name, zone, mapid, diff, diff_string, id, ej_instance_id, killed, index

time = combat:GetCombatTime()
returns the length of the combat in seconds, if the combat is in progress, returns the current elapsed time.

minutes, seconds = GetFormatedCombatTime()
returns the combat time formated with minutes and seconds.

startDate, endDate = combat:GetDate()
returns the start and end date as %H:%M:%S.

isTrash = combat:IsTrash()
returns true if the combat is a trash segment.

encounterDiff = combat:GetDifficulty()
returns the difficulty number of the raid encounter.

deaths = combat:GetDeaths()
returns a numeric table containing the deaths, table is ordered by first death to last death.

combatNumber = combat:GetCombatNumber()
returns the unique ID number for the combat.

container = combat:GetContainer ( attribute )
returns the container table for the requested attribute.

chartData = combat:GetTimeData ( chart_data_name )
returns the table containing the data for create a chart.

start_at = GetStartTime()
returns the GetTime() of when the combat started.

ended_at = GetEndTime()
returns the GetTime() of when the combat ended.

DETAILS_TOTALS_ONLYGROUP = true

total = combat:GetTotal ( attribute, subAttribute [, onlyGroup] )
returns the total of the requested attribute.

--------------------------------------------------------------------

Other Calls:

Details:GetCombatNumber()
returns the current unique combat number counter.
combat number is a unique number given to each combat started, this number won't 
reset when data is wiped and each character have its own combat number counter.

Details:IsInCombat()
returns if Details! is in combat or not.
 
damage, healing, energy, misc = Details:GetAllActors (combat, actorname)
returns all the four actor objects for the requested combat and actor.
combat must be a combat object.


Container Object:
=======================================

A container is used to store actors, each combat have four containers, one for each attribute.

amount = container:GetAmount (actorName [, key = "total"])
returns the amount of the requested member key, is key is not passed, "total" is used.

total = container:GetTotal (key = "total")
returns the total amount of all actors inside the container, if key is omitted, "total" is used.

total = container:GetTotalOnRaid (key = "total", combat)
similar to GetTotal, but only counts the total of raid members.

ipairs_list = container:ListActors()
returns a iterated table of actors inside the container.
Usage: 'for index, actor in container:ListActors() do'


Actor Object:
=======================================

Holds keys, spells and targets of a character.

name = actor:name()
returns the actor's name.

displayName = actor:GetDisplayName()
returns the name shown on the player bar, can suffer modifications from realm name removed, nicknames, etc.

name = actor:GetOnlyName()
returns only the actor name, remove realm or owner names.

class = actor:class()
returns the actor class.

activity = actor:Tempo()
returns the activity time for the actor.

isGroupMember = actor:IsGroupPlayer()
return true if the actor is a player and member of the raid group.

isPlayer = actor:IsPlayer()
return true if the actor is a player.

IsneutralOrEnemy = actor:IsNeutralOrEnemy()
return true if the actor is a neutral of an enemy.

isEnemy = actor:IsEnemy()
return true if the actor is a enemy.

list = actor:GetSpellList()
returns a hash table with spellid, spelltable.

spell = actor:GetSpell (spellid)
returns a spell table of requested spell id.

r, g, b = actor:GetBarColor()
returns the color which the player bar will be painted on the window, it respects owner, arena team, enemy, monster.

r, g, b = Details:GetClassColor()
returns the class color.

texture, left, right, top, bottom = actor:GetClassIcon()
returns the icon texture path and the texture's texcoords.

Keys for Damage Actors:
=======================================

members:
actor.total = total of damage done.
actor.total_without_pet = without pet.
actor.damage_taken = total of damage taken.
actor.last_event = when the last event for this actor occured.
actor.start_time = time when this actor started to apply damage.
actor.end_time = time when the actor stopped with damage.
actor.friendlyfire_total = amount of friendlyfire.

containers:
actor.targets = hash table of targets: {[targetName] = amount}.
actor.damage_from = hash table of actors which applied damage to this actor: {[aggresorName] = true}.
actor.pets = numeric table of GUIDs of pets summoned by this actor.
actor.friendlyfire = hash table of friendly fire targets: {[targetName] = table {total = 0, spells = hash table: {[spellId] = amount}}}
actor.spells = hash table with spells used to apply damage: {[spellId] = spellTable}.

Getting Dps:
For activity time: actor.total / actor:Tempo() 
For effective time: actor.total / combat:GetCombatTime()

Keys for Healing Actors:
=======================================

members:
actor.total = total of healing done.
actor.totalover = total of overheal.
actor.totalabsorb = total of absorbs.
actor.total_without_pet = total without count the healing done from pets.
actor.totalover_without_pet = overheal without pets.
actor.heal_enemy_amt = how much this actor healing an enemy actor.
actor.healing_taken = total of received healing.
actor.last_event = when the last event for this actor occured.
actor.start_time = time when this actor started to apply heals.
actor.end_time = time when the actor stopped with healing.

containers:
actor.spells = hash table with spells used to apply heals: {[spellId] = spellTable}.
actor.targets = hash table of targets: {[targetName] = amount}.
actor.targets_overheal = hash table of overhealed targets: {[targetName] = amount}.
actor.targets_absorbs = hash table of shield absorbs: {[targetName] = amount}.
actor.healing_from = hash table of actors which applied healing to this actor: {[healerName] = true}.
actor.pets = numeric table of GUIDs of pets summoned by this actor.
actor.heal_enemy = spells used to heal the enemy: {[spellid] = amount healed}

Keys for Energy Actors:
=======================================

actor.total = total of energy generated.
actor.received = total of energy received.
actor.resource = total of resource generated.
actor.resource_type = type of the resource used by the actor.

actor.pets = numeric table of GUIDs of pets summoned by this actor.
actor.targets = hash table of targets: {[targetName] = amount}.
actor.spells = hash table with spells used to generate energy: {[spellId] = spellTable}.

Keys for Misc Actors:
=======================================
these members and container may not be present on all actors, depends if the actor performed the action.

cc_done = amount of crowd control done.
cc_done_targets = cc done targets {[targetName] = amount}.
cc_done_spells = spells used to make the cc.

interrupt = amount of interrupts.
interrupt_targets = target which was its spell interrupted {[targetName] = amount}.
interrupt_spells = spells used to interrupt.
interrompeu_oque = spells interrupted.

buff_uptime = seconds of all buff uptime.
buff_uptime_targets = 
buff_uptime_spells = 

debuff_uptime = 
debuff_uptime_targets = {[targetName] = amount}.
debuff_uptime_spells = 

cooldowns_defensive = amount of defensive cooldowns used.
cooldowns_defensive_targets = in which player the cooldown was used.
cooldowns_defensive_spells = spells used.

ress = amount of resses.
ress_targets = {[targetName] = amount}.
ress_spells = 

dispell = amount of dispells done.
dispell_targets = {[targetName] = amount}.
dispell_spells = 
dispell_oque = 

cc_break = 
cc_break_targets = {[targetName] = amount}.
cc_break_spells = 
cc_break_oque = 


Other API Calls:
=======================================

Details:SetDeathLogLimit (limit)
Set the amount of lines to store on death log.