DKPmon Module Developer Guide
I'm whipping this guide out as quickly as I can, so it won't be as complete as it should be for a while.
Get an IDE (Integrated Development Environment)
Don't start a programming project without a real IDE. I personally use eclipse, there are lua specific and even wow specific IDEs. You might take a loot at wowinterface.com
Also, look at http://www.wowwiki.com/Eclipse_(IDE)
You should also checkout some of the other modules as well as DKPmon and Bidder from svn so you can easily browse their source code. http://dev.wowace.com/wowace/trunk
Creating your module
You need to create two addons, one module for Bidder, and one for DKPmon.
I'll refer to your module's name as YourModule. Create a file structure like so:
The .toc File
The .toc file is common to all addons. It tells the WoW which lua files to load. Take a look at the other .toc files and write yours in a similar fashion. Make sure to have custom.lua above example.lua so it loads the users custom settings first.
The example.lua File
This file is where you should keep custom settings for the dkp system. All settings that are common to the guild's dkp system should be put here. The idea is that dkp managers in the guild can just edit and distribute a custom.lua file that contains the points for their dkp system.
Settings that a user may want to configure at runtime should be implemented as options within the fubar menu.
This is a localization file for the english language. You'll notice calls to AceLocale which set this up. It's pretty straight-forward, look at the other addon's examples.
This is where the meat of your code will be. Basically, you are implementing an interface. This interface is defined in DKPmon/DKPSystems/baseclass.lua
DKPmon is using AceOO for its modules.
The easiest thing to do is copy another DKPmon module's lua file and start editing it. You'll notice at the top of every module a number of local variable are setup for the module. None of these should be global.
Your module is handed to the DKPmon addon at the bottom of the file by creating an instance of the class and registering it, in BossAuction it looks like this:
local BossAuctionObj = BADKP:new() DKPmon.DKP:Register(BossAuctionObj, "BossAuction", L["Boss points auction"])
DKPmon essentially has an API. The DKPmon folder structure is fairly easy to follow. For example, lets say we want to get the points for a given player:
Looking at the folder structure you'll notice PointsDB. Under that folder is pointsdb.lua
In this file are some useful point accessing functions. You'll notice at the top of these files a local variable is assigned to DKPmon.SOMETHING this is the root object you should call the functions on.
So in this example, if you wanted to call: PointsDB:GetPlayerPoints(name, pool)
You should call DKPmon.PointsDB:GetPlayerPoints(name, pool) from your addon.
Remember, the semi-colon is important! It's "lua syntactic sugar" the equivilent of: DKPmon.PointsDB.GetPlayerPoints(DKPmon.PointsDB,name,pool)
If you forget it you'll get errors.
Developing your module
Your task now is to go into all the functions in YourModule.lua and tailor them to your dkp system. The following is a list of the baseclass functions and how you should use them.
I've only included the more interesting functions so far. The descriptions of the others are self explanatory.
- Called after DKPmon is loaded. You should set and check all your runtime variables here as well as register events and whatnot.
- Called when an item is added to DKPmon. Most of the modules do a check here for the quality of the item (epic,uncommon, etc)
- Called when you mouse-over an item.
- BuildWinnerSelectList(itembutton, dewOptions, iteminfo)
- Build the menu you get when you left-click an item. This menu should update the winner on the itembutton when you click it: itembutton.bidinfo.winner=<winner name>
- BuildItemActionMenu(itembutton, dewOptions, iteminfo)
- Called when you right click an item in the list.
- ProcessQueryConsole(bidname, bidclass)
- Called when a Bidder user requests points.
- PlaceBid(itembutton, bidder, dkpinfo, bidderlist, nbidders)
- Called directly from a Bidder client. Important: here dkpinfo just has dkpinfo.bid, I believe this comes directly from Bidder. Your item dkpinfo is under itembutton.iteminfo.dkpinfo
- GetCost(winner, itemdkp, winnerdkp)
- Get the cost to charge for the item.
- Actually deduct points from the winner
- Here you can edit the award frame and add custom gui elements, such as extra buttons.
- Here you define the options menu for your module under DKPmon.
DKPmon Data Objects
What are these iteminfo/dkpinfo tables? What fields in them?
- An instance of LootItem, see DKPmon/Looting/lootitem.lua One of the most useful things here is to call itembutton:GetDKPInfo() This is the same info table as the 2nd argument returned from your GetItemInfo()
- The same as itembutton:GetItemInfo() Contains the item name, source, quality, color, and other info.
- Usually refers to itembutton:GetDKPInfo() except in that case I mentioned in PlaceBid() where it's something different.
You can mixin additional libraries into your module by including them like so: local BADKP = AceOO.Class(DKPmon_DKP_BaseClass,"AceHook-2.1","AceEvent-2.0")
You can use AceHook to react to events happening within DKPmon that your module needs to be aware of.
For Example: In BossAuction I set a minimum bid on items when they are created. However, when items are created, no function in your module is called until they right-click the item. In order to correctly initialize the minimum bid I hooked into DKPmon.LootItem.SetItem like so: self:Hook(DKPmon.LootItem,"SetItem", "SetItemHook")
Make sure to call DKPmon's function within the Hook like so: self.hooks[DKPmon.LootItem]["SetItem"](lootItem, iteminfo)