BigWigs/ModuleAPI

From WowAce Wiki
Jump to: navigation, search

BigWigs modules can be pure boss modules or external helper applications.

This page details all the options available to these modules.

I realise that this documentation may look daunting at first, but it's just because there are so many things that can be done, and a normal boss module only requires a fraction of the stuff that is documented here.

Someone should write a short tutorial for creating them, and until that is done, you can really just look at the example code here and copy/paste.

Relationships

There are some things with BigWigs modules that "just work" because of some set restrictions and assumptions that we do. I've tried listing them all here.

AceLocale-2.2 Instance

BigWigs assumes that with any boss module, a AceLocale-2.2 instance exists with the name "BigWigs<bossName>", for example "BigWigsThe Lurker Below" - note the lack of space; also note that the boss name is *translated* here. It's not the enUS name.

All boss module options provided by .toggleoptions are tied to this AceLocale-2.2 instance, and so is the command line name for the module. Let's say, for example, that your toggleoptions property contains "plague" and "icon", so it looks like:

mod.toggleoptions = {"plague", "icon", "bosskill"}

Then your AceLocale-2.2 instance for that boss MUST contain the keys "plague" and "icon", and SHOULD contain "plague_desc" and "icon_desc", which would contain descriptive comments about the related option. Note that the text for the bosskill option is automatically fetched from the BigWigs core, since it is used on almost all bosses.

Like I mentioned, the AceLocale-2.2 instance must also contain the command line name for the module, and it must be specified in the "cmd" key, like

cmd = "Lurker"

Other than that, you can use the AceLocale-2.2 instance to put whatever you want in it.

Module name

BigWigs assumes that, for boss modules, the module name is exactly the same as the translated boss name. This means that if you're making a boss module for "The Lurker Below", the module must have the same name, and that if you are playing on a german World of Warcraft, the boss module must be called "Das Grauen aus der Tiefe".

Also note that it is impossible to replace a bossmodule with another. This is because AceModuleCore-2.0 does not allow 2 modules with the same name. If this limitation is removed from Ace2 some day, it will also be removed from BigWigs.

Common words

Some words are so common in boss modules that we provide a separate AceLocale-2.2 instance with those in it; currently it just contains translations for the words "You" and "are", which are usually checked against "You are afflicted by Something." combat log messages.

This AceLocale-2.2 instance can be used like this

local L2 = AceLibrary("AceLocale-2.2"):new("BigWigsCommonWords")
L2["you"]
L2["are"]

The example below uses it in its web trigger.

Synchronization

Synchronization for BigWigs modules is done through the addon channel with SendAddonMessage in the BigWigs namespace. We use synchronization for most modules because sometimes you are simply out of range to detect abilities that are used around the boss or centered at some player on the other side of the room.

In order to use synchronization in your module, you have to register for the BigWigs_RecvSync event. The arguments coupled with this event are sync, rest and nick, which contain the sync name like you sent it, anything else you provided with the sync and the nick of the toon that sent the sync to the addon channel.

So that, for example, your BigWigs_RecvSync handler would look like:

function mod:BigWigs_RecvSync(sync, rest, nick)
  if sync == "BossPlague" and rest then
    self:Message(string.format("Plague on %s!", rest))
  end
end

And in order to trigger this, you'd have to call self:Sync("BossPlague " .. player) somewhere in your code. Take a look at the example section below for more details on this.

Obviously, if 40 people in the raid use BigWigs, you would, by default, get 40 syncs like that, and you would produce 40 messages. This is prevented by throttling;

self:TriggerEvent("BigWigs_ThrottleSync", "BossPlague", 5)

This would make the communication library not accept any BossPlague messages that are less than 5 seconds within one another, and just discard them, no matter what other information the sync contained.

By default, if you do not throttle a sync, it is throttled at 1 second. If you do not wish a sync to be throttled at all, you MUST register it with a throttle of 0.

Engage and wipe checking

Since engaging and wiping on bosses is something that many boss modules would want to react to in some way (reset variables, etc), BigWigs provides some methods that you can register for in your boss module to automate this; they are CheckForEngage and CheckForWipe.

These two modules are traditionally tied to the PLAYER_REGEN_DISABLED and PLAYER_REGEN_ENABLED events; you'd want to do this in your OnEnable.

CheckForEngage

function mod:OnEnable()
    self:RegisterEvent("PLAYER_REGEN_DISABLED", "CheckForEngage")
end

Now, whenever your boss module is active (as dictated by .zonename and .enabletrigger), and you get in combat, the CheckForEngage method will be executed. If you have not created a method by that name in your own module, the core method will automatically be called (this is usually what you want).

The CheckForEngage method uses the Scan method (which you could also overwrite, but should not) to scan your target, focus and the targets of everyone in the raid to see if they have a mob contained in mod.scanTable (this is automatically generated from .enabletrigger and .wipemobs, unless set by the mod author) targetted. If it finds anyone that has, it checks if that boss is in combat, and if so, it sends a sync that has to be captured by BigWigs_RecvSync, like this

function mod:BigWigs_RecvSync( sync, rest, nick )
	if self:ValidateEngageSync(sync, rest) and not started then
		started = true
		if self:IsEventRegistered("PLAYER_REGEN_DISABLED") then
			self:UnregisterEvent("PLAYER_REGEN_DISABLED")
		end
	end
end

We tend to use a "local started = nil" in the boss module just to make absolutely sure that we do not trigger a boss engage more than once, but this is not strictly necessary, and we also just make sure that the PLAYER_REGEN_DISABLED event is unregistered, since we no longer need it.

At this point, the boss is engaged, and you can display the "Boss engaged - 10 minutes to enrage" message and start some bars or whatever.

CheckForWipe

function mod:OnEnable()
    self:RegisterEvent("PLAYER_REGEN_ENABLED", "CheckForWipe")
end

The CheckForWipe method, by default, scans your raid for the mobs specified in .enabletrigger and .wipemobs (.scanTable) and if it finds them, checks whether they are in combat or not.

It will repeat this scan every 2 seconds until it does not find any mobs as targets or noone in combat.

If it does not find any of those mobs as targets, or they are not in combat (and the player is not feigned), it triggers a reboot of the module, which will unregister all the events, call :OnDisable and then :OnEnable again, which should re-register all the events.

Notes

You can optionally override all these methods in your boss modules; CheckForEngage, CheckForWipe, Scan, ValidateEngageSync, GetEngageSync and .scanTable.

Also remember that you do not have to use these scanning methods, you should only register for them if you actually have to know when the boss is engaged and if you actually have to know when you wipe. In most cases, you do not really have to know.

Think before using it.

Boss death

From the very beginning, BigWigs has been unique in the way that it notifies you when a boss is defeated, and plays the famous victory music. Of course, since most of our boss modules do this, we have a generic way of doing this programatically; the GenericBossDeath method.

In OnEnable, you register for it like

self:RegisterEvent("CHAT_MSG_COMBAT_HOSTILE_DEATH", "GenericBossDeath")

So, whenever a mob dies and your boss module is enabled, it will check if the mob that died has the same name as the boss module, and if it does, it will print the "Boss has been defeated!" message, play the victory sound and disable the boss module for you.

We do not use this in all the modules, simply because the boss sometimes die more than once; examples include the Romulo and Julianne event in Karazhan and Al'ar in The Eye - also, sometimes you do not get a death message at all, when for example Majordomo Executus in Molten Core yields.

Example

local boss = AceLibrary("Babble-Boss-2.2")["Hyakiss the Lurker"]
local L = AceLibrary("AceLocale-2.2"):new("BigWigs"..boss)
local L2 = AceLibrary("AceLocale-2.2"):new("BigWigsCommonWords")

L:RegisterTranslations("enUS", function() return {
	cmd = "Hyakiss",

	web = "Web",
	web_desc = "Alert when a player gets webbed.",

	web_trigger = "^([^%s]+) ([^%s]+) afflicted by Hyakiss' Web.",
	web_message = "%s has been webbed.",
	web_bar = "Web: %s",
} end )

local mod = BigWigs:NewModule(boss)
mod.zonename = AceLibrary("Babble-Zone-2.2")["Karazhan"]
mod.enabletrigger = boss
mod.toggleoptions = {"web", "bosskill"}
mod.revision = tonumber(("$Revision: 31035 $"):sub(12, -3))

function mod:OnEnable()
	self:RegisterEvent("CHAT_MSG_SPELL_PERIODIC_SELF_DAMAGE", "Web")
	self:RegisterEvent("CHAT_MSG_SPELL_PERIODIC_FRIENDLYPLAYER_DAMAGE", "Web")
	self:RegisterEvent("CHAT_MSG_SPELL_PERIODIC_PARTY_DAMAGE", "Web")

	self:RegisterEvent("CHAT_MSG_COMBAT_HOSTILE_DEATH", "GenericBossDeath")

	self:RegisterEvent("BigWigs_RecvSync")
	self:TriggerEvent("BigWigs_ThrottleSync", "HyakissWeb", 3)
end

function mod:Web(msg)
	local wplayer, wtype = select(3, msg:find(L["web_trigger"]))
	if wplayer and wtype then
		if wplayer == L2["you"] and wtype == L2["are"] then
			wplayer = UnitName("player")
		end
		self:Sync("HyakissWeb "..wplayer)
	end
end

function mod:BigWigs_RecvSync(sync, rest, nick)
	if sync == "HyakissWeb" and rest and self.db.profile.web then
		self:Message(L["web_message"]:format(rest), "Urgent")
		self:Bar(L["web_bar"]:format(rest), 8, "Spell_Nature_Web")
	end
end

Provided API

:Message(text, priority, noRaidSay, sound, broadcastOnly)

Displays a message in the configured message frame (defaults to BigWigs' own message frame) with the color configured for the given priority.

Arguments

text: string - The message to show.

priority: string - Optional, one of "Important", "Personal", "Urgent", "Attention", "Positive", "Bosskill" or "Core".

noRaidSay: boolean - Optional, if this is non-nil, the message will not be relayed to the raid warning channel, even if that option is enabled.

sound: string or boolean - Optional, if this is a string, it must be either "Long", "Info", "Alert", "Alarm" or "Victory". If 'true' is passed, the default "RaidWarning" sound provided by WoW will be played.

broadcastOnly: boolean - Optional, if this is provided, the message will only be broadcasted to the raid warning channel (if that option is enabled), and not be shown locally.

Returns

Nothing

Remarks

You should almost always provide a priority - if not, the message will be white. Remember that you should NOT surround the text with "***".

Also note that priority can be a RGB tuple, like { r = 1.0, g = 0, b = 0 }, and also just a color name, like "Yellow".

Example

self:Message("Fear in 2sec!", "Important")
self:Message("You have the plague!", "Personal", true, "Info")

:DelayedMessage(delay, ...)

This will schedule a delayed message to be printed after delay seconds.

Arguments

delay: number - The number of seconds to wait before printing the message.

...: The rest of the arguments are exactly like the ones for :Message.

Returns

The scheduled event ID, which is useful if you may want to cancel the scheduled message later.

Example

self:DelayedMessage(55, "Something happens in 5 sec!", "Important")
local x = self:DelayedMessage(55, "Something happens in 5 sec!", "Important")
-- Then, a bit later, the boss enters phase 2, and you no longer want this message to display
self:CancelScheduledEvent(x)

:Bar(text, length, icon, otherColor, ...)

Starts a timer bar that counts down for the specified length of time.

Arguments

text: string - The text to show on the bar.

length: number - The length of the bar in seconds.

icon: string - What icon to show on the bar.

otherColor: boolean - Optional, if not specified, the configured colors will be used. If specified, you must provide 1 or more colors to use as arguments after otherColor.

Returns

Nothing.

Remarks

"Interface\\Icons\\" is automatically pre-pended to the icon path. If you have to show a bar with an icon that is not part of the default icons provided by WoW, this is still possible using the self:TriggerEvent("BigWigs_StartBar", ...) syntax.

Note that it is possible to stop bars using events, too

self:TriggerEvent("BigWigs_StopBar", self, "text")

Where 'text' is the exact text as it is shown on the bar.

Example

self:Bar("Adds incoming!", 30, "Spell_Nature_Web")
self:Bar("Testing colors!", 60", "Spell_Nature_Web", true, "red", "yellow", "green")

:Sync(sync)

Sends a communication sync to the other BigWigs users in the group.

Arguments

sync: string - The synchronization token to send to the other people in your group. Note that these tokens are recieved by all the BigWigs modules, so you should make sure you pick something unique.

Returns

Nothing.

Remarks

The tokens we use are typically prefixed by some portion of the boss name, like "HyakissWeb". When sending a sync, if you want to send more data (this will be provided by the second argument to :BigWigs_RecvSync, detailed later), you have to use string concatenation; "HyakissWeb " .. playerName (which would become "HyakissWeb MyToon").

Note that synchronization throttling is done only on the first part, not the additional information you include in the sync.

Of course, sync messages are sent using SendAddonMessage, and as such there are some restrictions inherited. Take a look at wowwiki for more information.

Example

self:Sync("BossAbility")
self:Sync("BossTargettedAbility " .. player)

:Icon(name)

Puts the configured raid icon on the specified player, only works if you are promoted in the raid or the raid leader.

Arguments

name: string - The name of the player you want to put an icon on.

Returns

Nothing.

Remarks

You can also forcibly clear the icon from the player it was set on using

self:TriggerEvent("BigWigs_RemoveRaidIcon")

This is done automatically if you use GenericBossDeath or CheckForWipe. If not, you should clear it yourself.

Example

self:Icon("SomePlayer")

User API

.revision (all modules)

number - Must be set for all modules.

.zonename (boss modules)

string or table - The zone or zones where this boss resides. This is required for boss modules.

Note: These zone names should be the translated names, and not the enUS ones (so Babble-Zone comes in handy).

Note: If more than one zone name is provided, and the module does not have a .otherMenu property set, or the addon it is packaged within does not have the X-BigWigs-Menu field set in its TOC, the boss module will be placed under a menu according to the first zone in the .zonename table.

.enabletrigger (boss modules)

string or table - Names of mobs that should enable this boss module. Boss modules are enabled when one of the mobs listed here are moused over or targetted in a zone specified in .zonename.

Note: The mob names listed here should be the translated ones, and not the enUS one (so Babble-Boss comes in handy).

.toggleoptions (boss modules)

table - List of toggle options for this boss module. Toggle options are the options visible in the ingame menu for this boss module.

The keys listed in the toggleoptions are automatically available to you through the profile database, so you can check if an option is enabled or not like

if self.db.profile.option then
  self:Message(...)
end

Note: Options listed in the toggleoptions are automatically tied to a AceLocale entry of the name "BigWigs<bossName>", for example "BigWigsThe Lurker Below". Note the lack of space before the boss name. The name of the option will be fetched using the toggleoption key and the option description will be fetched using the key "<optionKey>_desc".

.external (non-boss modules)

boolean - Setting this to true forces the module to be placed in the Extras submenu in the BigWigs options - should not really be used by boss modules, only by helper modules like CommonAuras and such.

.wipemobs

string or table - List of additional mobs that should be scanned for before determining if a wipe has occured or not.

Note: This property is only used if you use the CheckForWipe method. The mob names listed here should be the translated ones, and not the enUS one (so Babble-Boss comes in handy).

.scanTable

table - A list of names to scan for during CheckForEngage and CheckForWipe. Obviously only used when you use any of those methods, and also by the default Scan method for the checks. This property is auto-populated by .enabletrigger and .wipemobs, and should really never be set manually (but it can be, so it's listed here).

Note: The mob names listed here should be the translated ones, and not the enUS one (so Babble-Boss comes in handy).

.otherMenu

string - You can optionally set this to make the boss module appear in another menu instead of the menu generated from .zonename. For example, places that have 2 bosses or less are generally put in the "Azeroth" or "Outland" menus instead of a menu generated from their zones, since this would create too much clutter in the menu.

Note: Modules that use this property have to be packaged in an addon using the TOC field X-BigWigs-Menu, which should contain exactly the same as the .otherMenu property.

Note: This should not be translated, but should be a raw enUS zone name, as available in Babble-Zone-2.2.

.defaultDB

table - Used to provide a set of default database settings for modules that are not boss modules (all the .toggleoptions for boss modules default to 'true').

.consoleOptions

table - Used to provide a AceOptions table for modules that are not boss modules (since they use .toggleoptions).

.consoleCmd

string - The console command that should be associated with the given .consoleOptions table. Only used if .consoleOptions is set.

.synctoken

string - Set this if you want to namespace your syncs aside from the rest of the communication traffic. This can be used to version streams, for example, or just to make sure that your 3rd party module never interferes with anything.

:OnRegister()

This method is invoked on your module when it is registered with the BigWigs core.

Note: The traditional OnInitialize method used by Ace2 and Ace2 modules is not available to BigWigs modules, and trying to implement it will cause an error. Use OnRegister instead, it will only ever be called once.

:GetBarGroupId(text)

Only invoked if you are running the Bars module provided with the standard BigWigs package, this method is optional and should only be overrided in a module if you want the modules bars to be positioned using a different anchor than the default one provided by BigWigs.

Arguments

text: string - The exact text of the bar when registered with :Bar or the BigWigs_Start Bar event.

Returns

Must return a string identifying the CandyBar group which the bar should be registered with.

Remarks

You should almost *never* implement this function. None of the existing boss modules or external BigWigs addons do as per today, and you really have to know what you're doing if you implement this.

You need to set the CandyBar group position and other properties yourself if using this, and you need to set them on the Bars module. Retrieved from "http://www.wowace.com/wiki/BigWigs/ModuleAPI"