CastCommLib: a library for communicating spell casts and their targets

[Pastamancer]

BSD-licensed, tiny, locale-independent, no dependencies, embeds nicely.

I'm looking for feedback from other addon developers and hoping to get addons other than Grid using it .

Get it here: http://grid.13th-floor.org/svn/trunk...astCommLib.lua

--[[ DOCUMENTATION
Description:

CastCommLib is an embedded library for communicating spell casts and their
targets using the AddonMessage channel.  Addons can register with CastCommLib
to receive notification of these messages.

CastCommLib will use ChatThrottleLib if it is available.

API:

CastCommLib:RegisterCallback(key, func)
-- Adds a callback funciton to be invoked when a spell event is received
--
-- If key is a table, then func must be a string and the callback will be
-- invoked as:
--   key[func](key, sender, senderUnit, action, target, channel, spell, rank,
--             displayName, icon, startTime, endTime, isTradeSkill)
-- otherwise func must be a function and will be invoked as:
--   func(sender, senderUnit, action, target, channel, spell, rank,
--        displayName, icon, startTime, endTime, isTradeSkill)
--
-- string sender:
--   the name of the character that sent the event
-- string senderUnit:
--   the unitid of the character that sent the event
-- string action:
--   one of "START", "DELAYED", "INTERRUPTED", "FAILED", "SUCCEEDED",
--          "CHANNEL_START", "CHANNEL_UPDATE", or "CHANNEL_STOP".
--   depending on the event that caused the message to be sent
-- string target:
--   the name of the target for the spell
-- boolean channel:
--   if the spell is channeled
-- string spell:
--   the name of the spell
-- string rank:
--   the rank of the spell
-- string displayName:
--   the name of the spell (not sure how this differes from spell, but it's
--                          from UnitCastingInfo())
-- string icon:
--   the path to the texture for the spell
-- number startTime:
--   the time the spell started casting/channeling
-- number endTime:
--   the time the spell will finish casting/channeling
-- boolean isTradeSkill:
--   if the spell is a tradeskill
--
-- Usage:
--   CastCommLib:RegisterCallback(MyAddon, "CastCommLib")
-- or
--   CastCommLib:RegisterCallback("MyAddon", OnCastCommLibReceived)


CastCommLib:UnregisterCallback(key)
-- Removes the callback function specified by key
--
-- Usage:
--   CastCommLib:UnregisterCallback(MyAddon)
-- or
--   CastCommLib:UnregisterCallback("MyAddon")

CastCommLib:GetUnitId(name)
-- returns the cached unitid for the specified name

CastCommLib:IterateGroupMembers(name)
-- returns an iterator suitable for use with for
-- return values for each iteration is the name of the next person in the
-- specified person's group

CastCommLib:GetCastingInfo(name)
-- returns target, channel, spell, rank, displayName, icon, startTime, endTime,
--         isTradeSkill
--
-- See CastCommLib:RegisterCallback for details

CastCommLib:Enable()
-- Enables the library.  You probably shouldn't be calling this.

CastCommLib:Disable()
-- Disables the library.  You probably shouldn't be calling this.

CastCommLib:ToggleDebugging(on)
-- Enables, disables, or toggles the debugging state of CastCommLib
--
-- If on is nil, the debugging state will be toggled, otherwise it will be set
-- to the value of on.

--]]

[JoshBorke]

looks good and i like it :-D

what about instant casts? ;-)

[Pastamancer]

Originally Posted by JoshBorke looks good and i like it :-D what about instant casts? ;-)

Since UnitCastingInfo is useless for instants, you need a translation table to avoid locale issues. If someone wants to compile a list of castable spells (all of them because there are buffs that make any spell instant), they can take a look at the translation code I wrote for Healcomm. Otherwise, screw instant spells.

[ngollon]

Hi!

What format is "endtime" given in?
From the things I testet I think, that it is given in Ticks since system boot and therefore comparable to GetTime()*1000.
But since this is system-dependant there seems to be not much use in sending it to others.

Hopefully, I am totally wrong =)
Is there a way to know the time, when a party member finishes a spellcast? (You could try to sync clocks first, but this would be laggy...)

Thanks =)
Vaeyl

[JoshBorke]

times aren't sent across the com channel, only events. once a message is received all time information is captured locally using UnitCastingInfo() which means GetTime() works just fine.

[JoshBorke]

1) bumping
2) pasta, release this :P

[Pastamancer]

Originally Posted by JoshBorke 1) bumping 2) pasta, release this :P

Oh, I guess this thread is the release. Is it really worth creating a release on wowi for just one file?

[JoshBorke]

yes, release this as an actual mod on wowi imo. that way we'll always be able to point at it on this website rather than your personal svn

[thoughtlover]

Right off I'd like to praise the idea behind CastCommLib. I've always thought such a library would be useful if people would all write towards it: multiple addons sharing spell target information. I've been thinking about the implementation, here are my thoughts:

Summary:
In my opinion, UNIT_SPELLCAST_ trigger events for units other than just the "player" should be used in addition to communication channel messages. While the information received across communication channels are adequate, the speed benefit to using the spell triggers (that you are receiving anyway) can not be ignored.
Below, I raise question if a spell registry or a private channel interface should be part of a comprehensive shared spell cast communication channel library. I cannot answer this question until I first know what the impact is of 25-40 people sending every spell/action they do across a raid channel. How much network lag/communications lag does it cause? This I cannot answer without running a rather massive test with cooperative people.

Discussion:

Question: Should STARTS/DELAYS/STOPS be sent across communication channels (as opposed to just broadcasting spellTarget from sent)?
Answer: For the case of future proofing, yes.
Advantages: Future Proofing
Currently the advantages to CastCommLib are being able to see spell casts at any distance and providing spellTarget information. Broadcasting all spell STARTS/DELAYS/STOPS future proofs it against possible events that could span an area greater than can be seen, although I can think of only a handful spells where this actually comes in useful currently: Resurrection, Ritual Summoning and Mind Vision.
Disadvantages:Ping times
People with high ping will not send their spell cast information quickly. STARTS, STOPS, INTERRUPTIONS, DELAYS will all be subject to other people's ping times. The sad part is such delays are avoidable, as all of this information can be gleaned directly from the server, so long as they are in range.

Follow-up Question: Should UNIT_SPELLCAST_ trigger events for units other than just the "player", like START/STOP/DELAY/UPDATE/STOP, be utilized?
Answer: Yes, as such information can be used in addition to communication channels
Advantages:Reduced Lag
Spell cast updates will be subject to your ping time only. This information can be used to supplement communications channel information.
Disadvantages:Asynchronous Complexity
The problem becomes an asynchronous one. How do you know when a unit is no longer in sight, and that you should use a message received from a communication channel message. This is a complex problem, but I believe it to be an ultimately solvable one.

Question: Should Spell Registration be part of CastCommLib as it was originally part of SpellSyncLib?
Answer: Maybe.
Advantages:Less Channel Spam
If addons were to register only the spells they were interested in receiving/broadcasting, then less channel spam would be necessary.
Disadvantages:Inter-Addon Compatibility
Broadcasting only spells an addon is interested in reduces inter-addon compatibility UNLESS the CastCommLib Develops a way to share which spells it is interested in with other CastCommLib clients.
It comes down to what you believe the library's purpose is: 1) The library's purpose is to provide anyone who has the library installed with information on any spell cast by anyone else with the library installed -or- 2) The library's purpose is to reduce channel spam by sharing a communication method and sending only the information each addon needs to see.

Follow-up Question: If channel spam is enough to warrant a spell registry, should addons be allowed to also designate a private channel to communicate over?
Answer: Maybe.
Advantages:Less Channel Spam
Only players that would need the information would receive it.
Disadvantages:Further Inter-Addon Combatibility
Addons that didn't know about the channel wouldn't be able to share in that information without it again/instead being broadcast across a channel the addon does know about. A solution to this issue is to have a multi-channel approach. If two different addons want the same spell information, but one wants it over a private channel, default to broadcasting it over raid/party if the casters are all in the same group. If there is a caster not in the same group/raid, broadcast it over both raid/party and the private channel.



The reason I have made such a careful analysis of this library is because I am considering making a next generation Spell Bar tracker; one where you would be able to track any set of spells bars being cast on any name/unitid (player, target, focus, party#, raid#, partypet#, raidpet#, mouseover) and see them in spell bar format. Like Healsync/Dorjae's Healing Bars/Forcast, only for any unit and any set of spells.

[Pastamancer]

Sorry about the slow response time, I don't read the wowi forums very often.

I've been inspired by some of the preliminary discussions about AceComm-3.0 and I'm planning a rewrite of CastComm in the next couple of months.

I'm planning to send target information from UNIT_SPELLCAST_SENT for all spells. Addons will be able to enable sending of start/stop/delay for particular spells. Addons will not be able to ask another player to enable sending start/stop/delay for any spell because transmitting spell names between different locales is a headache waiting to happen. I'm never going to allow it to use a custom channel because that is a huge headache and not worth it. I'm also trying to decide how to allow addons to send additional data with the cast/target message.

[JoshBorke]

Originally Posted by thoughtlover <snip> The reason I have made such a careful analysis of this library is because I am considering making a next generation Spell Bar tracker; one where you would be able to track any set of spells bars being cast on any name/unitid (player, target, focus, party#, raid#, partypet#, raidpet#, mouseover) and see them in spell bar format. Like Healsync/Dorjae's Healing Bars/Forcast, only for any unit and any set of spells.

Hey! I've been "working" on that too! I started about a year ago but got caught up in trying to manage the configuration. I've recently found the motivation again (sorta) and am sorta starting to write it with Ace3 as the backbone (I'm hoping I can somehow leverage the huge community to help write the configuration portion).

Feel free to PM here or email [email protected]

-josh

[Eidolarr]

Hey, FYI you don't need to have a table to check for instant casts. I wrote a guide for how to do it in detail on WoWWiki. The basic idea is that the only case in which you hear _SPELLCAST_SUCCEEDED without a preceeding _START or _CHANNEL_START is if the spell is an instant cast.

[e] If you add that to this library I will seriously consider using this for my addon, as long as the compression is alright.