Home
Downloads
News
Forums
Contribute
Links
Back
Users
Download

KonferSK Admin Guide

Introduction

This page is for guild leadership or PUG raid leaders who use Konfer Suicide Kings (KSK) for distributing loot. Administrators and owners of KSK configurations get a very different view of the mod than normal users. There are several extra tabs that appear at the bottom, as well as a number of extra tabs at the top of each main panel. Administrators can see everything that the configuration owner can, except for one panel in the configuration tab that only the owner can see. This is the tab where co-administrators are assigned and where a few owner-only options are set. More on this shortly.

Configuration Spaces

It is important to understand how KSK uses "configuration spaces". For most users, there will only be a single configuration. Usually this is the name of a guild, and is a guild configuration. However, KSK supports any number of configurations, each of which is a completely discrete entity. Each configuration has its own users list, item list, roll lists, owner, and co-admins. You can think of a configuration space as a completely different mod that just happens to use the same interface. Only one configuration can be "active" at a time. This is indicated in the top right hand corner of the screen. If you do have more than one configuration defined, that top right corner element is actually a drop down menu that you can use to switch to another configuration. Configurations for which you are the owner are colored green, all others are white.

There are also two types of configuration: guild and PUG. The main difference is how and when they communicate. A guild configuration will do all of it's inter-mod communication through the guild addon communication channel. Thus any activity (such as adding a new user) is reported to the entire guild. Any guild users who are online and running KSK will receive these messages and act on them. A PUG configuration does all of its communication through the active raid addon channel. The idea behind a PUG configuration is to allow you to manage loot through KSK for a PUG you may regularly run. Since PUG users could be from many different guilds KSK cannot use the guild channels for communicating, so most of the inter-addon communication happens over the raid channel. This makes sense as the only time the PUG is likely to be together all at the same time is when they are in raid together doing a regular run.

Certain events, most notably those relating to loot, always happen over the raid channel. A guild using KSK could quite conceivably have multiple teams running separate instances, and you would not want loot from one raid causing screens to pop up in the other raid. Thus all loot events only happen over the raid channel, although events the whole guild needs to know about, such as a user winning an item and suiciding on a list do still happen over the guild channels. Almost all of this is completely transparent to an admin. You just need to know which configuration type you need and ensure you have the correct configuration selected before you loot. In case you are wondering, yes, KSK does still "obey" event messages for configurations that you know about that aren't your current active one.

Initial Configuration

When you use KSK for the first time, there will be no configuration and you need to create one. You do this using the /ksk createconfig command: 

/ksk createconfig "Configuration Name"
This will create the configuration you specify. Unless you are the guild leader or an officer (defined as anyone who can read officer chat), the default configuration type created with be a PUG config. If you need to change this to a guild configuration, you need to call up the configuration screen. Note that KSK will not prevent a normal user from creating a guild configuration. However, unless the person broadcasting events is either the guild master, a co-owner or an officer, the configuration will be ignored by all other guild members, so don't bother trying to create one unless you are guild leadership. You call up the KSK interface, simply type /ksk. You can then select any of the tabs along the bottom to get to the part of KSK you need to. There are short-cut commands you can type to get directly to the various tabs:
  • /ksk or /ksk lists
    This will call up the list manager, where you can create, delete, rename and import users into loot roll lists.
  • /ksk loot
    This will call up the loot distribution manager and item editor panel. You can select between these two views by clicking on the appropriate tab at the top of the screen.
  • /ksk users
    This takes you to the user editor panel, where you can add, rename, import and assign attributes to users.
  • /ksk sync
    This opens up the sync manager and allows co-admins to remain in sync with each other in case they were offline when changes were made to the configuration or users were moved on any lists.
  • /ksk config
    This will take you to the loot assignment options panel, and, if you are the list owner, the configuration options panel.

Configuration Administration

Since you have just created a new configuration, you will most likely want to go to the configuration options and ensure the correct type has been created, and set the few options only the owner can set. You can either click to get there or simply type /ksk config admin. This will display the following panel:

The left side of the panel is the list of configurations. Here you can create, rename, copy or delete configurations, using the buttons at the bottom. You click on a configuration name to select it, and its information is displayed on the right hand side. This is where you add co-admins too, which is displayed in the bottom right panel. The biggest choice you face, other than selecting the correct config type (guild or PUG) is whether or not you want "Alts Tethered to Mains". If this is enabled (checked), then when you define a user as an alt of another user, both the main and the alt will occupy the same slot in any roll lists. If one gets suicided, both do. This is the option you want to select if you believe that loot rewards are assigned to a human, not a toon. Some guilds want to treat mains and alts completely separately. In this case, leave this option unchecked (the default). With this option unchecked, each user in the user list (despite being displayed as tethered in the user manager) will be treated as a separate entity, and a user's main can be in one position and their alt in another, or not even on the list. How you set this is a matter of guild policy.

Only the configuration owner can assign co-administrators, and the user must already have been defined in the user edit (/ksk users). The configuration owner is always a co-admin and cannot be deleted. To add a new co-admin simply press the "Add" button and select the desired user from the drop-down menu. Likewise to delete a user simply select them and press the "Delete" button. NOTE: if you add or delete a co-admin, they will not know that they are a co-admin (or no longer one) until you broadcast the config to them. You do this through the sync manager, described below.

User Administration

Once the configuration type is set you are ready to begin adding users. You do this in the user manager, accessed by typing /ksk users or pressing the "Users" tab button at the bottom of the window. This opens a panel that looks like this:

The left hand panel lists all of the currently defined users, sorted alphabetically. If a user is an alt of a character, it is displayed under the main character, as in the case of user "Crucitwo", who is an alt of user "Cruci". The right hand panel lists all of the attributes you can select for a user. The first is the user role. KSK allows you to select from the following roles: Healer, Tank, Spellcaster, Melee DPS, Ranged DPS. Setting the user roles accurately allows you to use the user role as a filter for loot. For example, you can mark a given item as for healers only, even though a spell caster may also be able to use it. You can get by without ever updating user roles, and simply not ever use that filter. The choice is yours and the feature is there if you want it.

Next, if the user is an enchanter, you should mark them as such. This allows you to select the user as a potential recipient of loot that needs to be disenchanted if no-one bids on an item. More on that topic in the loot options discussion below. Suffice it to say if the user is actually an enchanter, it is a good idea to mark them as such. Likewise if they change professions and are no longer an enchanter, it is a good idea to update their user flags and remove them as an enchanter.

Next you can assign this user as an alt of another character. The main character must already have been created. Simply enable the check box and press the "Select" button to select from a list of eligible users. KSK will automatically filter out other alts from the popup list. It is advisable to always set alts correctly, even if you are not using tethered alts.

If a user is going away for some extended period of time and you don't want to have to remember to keep marking them as reserved in the raid, you can mark them as "Frozen". This will ensure that they retain their current positions on the list as other users suicide and move around them. Marking a user as "Reserved" in the list manager is a session temporary setting and is not saved. This setting is permanent, until unset.

Once you are happy with all changes to the user, simply press the Update button to save the settings and send the new settings to all other admins and users. If other admins are online and fully synced with you they will see the change immediately.

Below the user options is a list that shows which lists the user is on (if the text is in green) along with their position on that list in brackets. If the user is not on a given list, the list name is shown in red. This allows you to quickly tell at a glance if a user is missing from a list they should be on.

At the bottom of the screen are buttons you can use to create a new user, delete the selected user, rename the user, import users from the guild roster, add users who are in your raid but not on the user list, and, if you have it installed, import the SKG players list. Note that you will only rename users if they have paid for a name change (or been forced to change their name by Blizzard). Changing the name here does not affect anything else in the system, as internally, a user ID is used, so they will retain their same positions on all lists.

List Administration

Once you have all of your users defined, you need to insert them into your roll lists. Roll lists are what KSK is all about, they are the ordered lists of users who are eligible to receive loot. You access the list manager by either pressing the Lists button at the bottom of the window, or by typing /ksk lists. Then select the Config tab at the top of the window (the default view is the Members view, which was briefly described in the Users Guide). The list configuration tab looks like this:

The left hand panel lists all of the currently defined lists, and the right hand panel lists the options you can set for each list. At the bottom right are buttons you can use to create, delete, rename, copy, import and export lists. All of these are largely self-explanatory, but please note that the copy option will create a new list, not copy members into an existing list. Also note that the import window will change whether or not you have SKG installed. If you do, you will be able to import members from an SKG list into the current list. Note that this imports members, not the list itself. You still need to create the list in KSK, and then import the SKG users into that list (as you may want to import members from more than one list into your KSK list if you are merging lists). The export button allows you to export the lists in either a comma-separated values (CSV) format or in XML.

The first option to set is the list sort order. By default, the list of lists on the left hand side is sorted alphabetically. However, you may do the majority of your loot distribution on one list and want it ranked at the top. You should make that list's sort order 1, and increase the sort order of all other lists. KSK will sort the list display (in all places where it is displayed) from lowest sort order to highest, and then alphabetically for lists with the same sort order.

Next comes the initial guild rank filter. If you prioritize loot for certain guild ranks (raiders first, casuals second, initiates third etc), it is a good idea to set the initial rank for each list. This will ensure that when the master looter selects an item from the loot list to begin bids that the correct initial rank is set. Any users who attempt to bid when they are not of sufficient rank will be informed of that. Please note that if you intend using guild rank priorities (discussed below) then you should not set an initial guild rank filter.

Next come two options that are a matter of guild/raid policy, and are frequently quite hotly debated. Strict class armor filtering will ensure that users can only bid on armor items that are appropriate for their class. For example, just because a druid can wear cloth does not mean they should be taking cloth items away from mages who can only wear cloth. With strict armor class filtering on, a druid would only be able to bid on leather items, a warrior only on plate (no mail) etc. Strict role filtering works the same way but for user roles. If you have assigned each user their correct role in the user editor, and you enable this option and select a given role in the loot window, only users who fill that role can bid on the item being looted.

Next up is the ability to actually cause a user to suicide on two lists, not just the list they bid on. Many people have two lists, one for normal gear and one for tier gear. When they bid on normal gear, their position on the tier list remains static. However, you may want them to be suicided on the normal gear list as well as the tier gear list if they win a tier item. If so, simply select the appropriate additional list to have the user suicided on, and when they will an item on this list, they will be suicided on the additional list as well.

There are two of the buttons at the bottom worth discussing a little more. The first is the Export button. This allows you to export a list as a comma-separated values (CSV) string, to export just the current list as XML, or to export all lists as XML. When you press this button the main window will disappear and you will see something like this:

You select the type of export you want to do from the drop-down menu, and as you change your selection, the export string changes. To copy this string for pasting elsewhere, press Ctrl+C to copy it to your clipboard. You can then paste this into a notepad file, a web form or whatever using the key-press Ctrl+V. Note that this dialog reminds you what the currently selected list is, so you can make sure the CSV or single list XML export will produce data for the correct list.

The other button worth discussing is the "Add Missing" button. This provides a quick and easy way to add users to a list. When you press it you will see something like this:

This too will show you a reminder of which list you have selected, and allow you to either add only members who are currently in the raid but not on the list (which will only work when you are actually in a raid), or to add all users in the user database who are not on the list. Select which of these two options you want from the drop-down menu. You can also have users added to the list in random order. To do so, ensure that "Insert Randomly" is selected. If that is not selected, the users are inserted at the bottom of the list in whatever order they happened to be scanned from the missing raid members list or the user list. You will be told what users were added and what position they were added in.

Loot Distribution

Now we come to the whole reason for KSK's existence: distributing loot. By default the loot manager will be displayed as soon as you loot a corpse (and KSK will automatically loot any gold from the corpse). You can disable this feature (see below) but it is on by default.

Loot Options

Before discussing the actual loot process, it is worth discussing the various options that control how looting is done. These options are accessed through the Config tab at the bottom of the window, or by typing /ksk config. This will display the following tab:

The first option does exactly what it says it will: it will automatically open the loot assignment and bidding panel when the master looter loots a corpse or chest. All other users in the raid will have their loot screen open too. I can think of no reason why you may not want this option on, and it is on by default, but you can disable it if you so desire.

By default, when users bid on an item, KSK will send a message to all other users of the mod so they can see who has bid (and it will show in their bidders list), and it sends a raid message telling the raid who has bid, and who is the current highest bidder. However, you may not want that to happen, and want all bids to be silent. If so, simply enable silent bidding. Note that this option (and all others on this tab) only affect how you loot, not other admins. These settings are not synchronized between admins.

If you want KSK to display item tooltips when you hover over an item in the loot list, enable the "Display Tooltips in Loot List" option (it is enabled by default). If you do not want your looting screen cluttered with tooltips, you can disable this.

When you are a master looter, you are likely to get a lot of whispers from users either whispering you commands like "bid" or "retract" to bid and retract bids on items, or to ask you questions. Some of those whispers may be important. If you select the "Enable Chat Message Filter" option, KSK will filter out all of the messages that it sends and receives, in order to reduce the clutter that you see. It does not prevent the messages from being received or sent, it just simply doesn't display them for you. For example, it will not show bid open and close messages sent to the raid, or show you the whisper command sent in response to the help command or other KSK commands. Mostly, you don't care about those messages. You know exactly what item is being bid on because you are the person controlling the bidding. However, some users really want to see everything the mod produces, and for those users, you can simply uncheck this option.

Next is the choice of whether or not to record loot assignments. If you enable this, each time an item is awarded to a user, it will be recorded. This does not just include successful bids. It will record winners of rolls, whether or not an item was assigned in order to be disenchanted, or if a BoE item was assigned to the master looter. If you enable this, the loot history can be displayed from the item editor (see below).

Some guilds like to let all guild members know what dropped off a boss when it is killed. Alternately, you may want to display the loot list to the raid. In either case simply select with of those two (if either) from the "Announce Loot" drop-down. Next to the loot assignment option is a multi-selection dropdown that allows you to control all of the announcement messages KSK sends out for various events. Pressing the dropdown button will show the following list:

  • Announce Bid List Changes
    When you first open an item for bids, it tells the raid which list the bids are opened on. If no-one bids on the item on that list, you may have an offspec or alts list you will allow users to bid on. You can change the bid list at any time simply by selecting it (see below). If this option is enabled, then KSK will warn the raid that the bid list was changed, and tell them what it was changed to.
  • Announce Winners in Raid
    Does exactly what it says. When a user wins a roll or a bid, announce that to the raid in normal raid chat.
  • Announce Winners in Guild Chat
    When a user wins a roll or a bid, you may want to let guild members who are not in the raid know about it so the winner can be congratulated. If so, enable this option and winners will be enabled in guild chat. For a PUG configuration, you probably want to turn this off.
  • Announce Bid Progression
    This options controls the messages relating to new bidders, retractions etc. If disabled, none of those messages are sent.
The rest of the options should be self-explanatory.

"Use Default Roll List" allows you to set a global default list where bids should begin. This default can be over-ridden in the item editor (see below) if you want to use a different list for specific items. It is useful to set this to the list you most commonly bid on in case you changed lists during a bid.

The "Initial Guild Rank Filter" allows you to set the default guild rank for new bids. This can be over-ridden on a per-list basis in the list configuration screen (as discussed above). Note that if you plan on using guild rank priorities (see below) then you should set this to "None".

The "Auto-assign Loot When Bids Close" option is one of the more useful improvements in KSK versus other similar addons. When set, and a winner is determined by either bidding or rolling (or there were no winners and the assign to enchanter option below is enabled), you will get a confirmation asking you if you want to assign the loot to the given user. If you confirm the assignment, KSK will automatically give the user the item, there is no need to find out what group the user is in, or to navigate the irritating Blizzard menus that frequently close on you while you look for a user. This can considerably speed up the looting process. I can think of no reason why you would ever want to disable it, but you can if you so choose.

The "Use Guild Rank Priorities" option is one of the more unique KSK innovations. It changes the way suicide kings works in a pretty important way. Usually, the user with the highest list position wins, but many people feel this disadvantages very frequent loyal raiders and rewards more casual raiders, as the casual raiders will always "creep up" the lists as more active users suicide from receiving items. If you enable guild rank priorities, it allows you to control which ranks will beat out which others in a bid. When you enable this button you can press the "Edit" button next to it to see a list of all of the guild ranks and their current priority. For example:

Here you can see that the guild master, officers and veteran raiders all have the same priority. Normal members have a lower priority, and initiates have the lowest priority. What happens when a bid takes place is that KSK will look at the bidders rank first. A higher priority raider will always win over a lower priority raider, even if the lower priority raider is at the number 1 position on the list. In order for this to work effectively, guild management should ensure that regular raiders always have a higher rank (and rank priority) over more casual raiders. If two users with the same rank priority (for example, both the GM and an officer bid on an item), then the list position determines the winner as normal. However, if a veteran raider and an initiate are the only two bidders, the veteran will always win, regardless of his position on the list.

Last come three options that control what happens to loot when there are no successful bidders or no-one rolled on an item. First, if the item is a bind-on-equip (BoE) item, you can have it assigned to the master looter, hopefully so they can sell it or put it in the guild bank. Second, you can choose whether or not to have non-BoE items rolled on if there were no bidders by selecting the "Try Open Roll" option. As a final resort, or if no-one rolls on the item, you can assign all non-boe items to one of 6 enchanters. Press the "Select" button next to each slot to assign an enchanter to that slot. A user must be marked as an enchanter in the user editor in order to be set here. KSK will assign items to be disenchanted to the first user on this list that is in the raid and eligible for loot, so set the order carefully. If you unmark a user as an enchanter in the user editor, they will be automatically removed from this list.

The Item Editor

Before discussing the actual looting process, you should know about the item editor. This is where you can set specific constraints and features on an item by item basis. You reach the item editor by selecting the Loot tab at the bottom of the window, and then the item editor tab at the top of the loot panel. The item editor looks like this:

By default there are a few items that are hidden that are always ignored (this is hard-coded into KSK and can not be changed). To add items to the item editor, you must have a visible link from chat, a mod like Atlas Loot, or loot from a corpse. You then type /ksk additem and then Shift-Click the item link to get it into your chat buffer. For example /ksk additem [New Uber Sword]. "[New Uber Sword]" is an item link not the actual typed out words. The new item will then appear in the item list, with no options except the default class filters set (based on the item type, slot etc). The item editor is split into two parts, the list of items on the left, and the options you can set for each option on the right. The options will reflect what is set for the currently selected item, which is highlighted on the left side.

If this is an item you wish to ignore, simply click the ignore item checkbox. All other options on the page will then be disabled. When an item is ignored, it will not even appear in the loot lists. It will be completely ignored by KSK, and you will need to manually assign it to someone based on whatever criteria you decide.

If you do not ignore the item, you have a range of options you can set for the item. They should be self-explanatory, but briefly, the "Roll on Specific List" option will simply set the default list when the master looter selects an item in the loot list, over-riding the default list set in the loot options as described above. The "Initial Guild Rank Filter" can be used to change the default initial rank set by a list configuration. The user role setting can be used to limit this item to a specific user role.

Last, there is another unique KSK feature, the ability to auto-assign an item to a user. This has a few uses, such as correcting for loot mistakes where a user that should not have received an item did (and the BoP trade timer has expired). You can then assure that the next time the item drops it is automatically assigned to a specific user. Since this is most likely a once-off assignment, you will want to ensure that the "Auto-remove when assigned" option is selected. This will remove the item from the item editor list as soon as the specified user has received the item. You will most likely also want to select a list to suicide the user on when they receive the item. The more typical use for this option is to assign items that a user has to collect (such as the shard splinters for the legendary mace in Ulduar) to a given user. In this case you will most likely not want to auto-remove the item. Whether or not the user is also suicided on a list is a matter of guild policy. To select the user who will receive the item, press the Select button. The user must be defined in the user editor.

Once you are happy with the item attributes, press the Update button to send the item information to other admins.

Loot Assignment and Bidding

At last we come to what KSK is all about: letting users bid on loot and getting the loot to the correct user. If enabled the loot assignment window will automatically open when the master loot loots a corpse or chest, and it will automatically loot any money from the corpse. If you have auto-opening disabled, you can open the loot assignment panel by selecting the loot tab at the bottom, and then selecting the Assign Loot tab at the top. Alternatively, you can type /ksk loot. This will open the main loot distribution panel, shown here:

The loot window is divided into 5 sections. The top left section is the list of roll lists, with the currently selected one highlighted. Below that is the list of members on the selected list (in the loot options window you can elect to not display users who are not in the raid so that all you see in this list are the current raid members). Users who are not in the current raid are grayed out. The top right panel is the actual list of loot dropped by the boss that meets the master loot threshold. Below that is the list of bidder filters, which are used to restrict the users who can bid on an item, and below that is the list of bidders and buttons for either bidding yourself, or controlling other bidders. When the master looter selects an item, if a default list is specified in the loot options (or a default list is specified for the item in the item editor), that list will be automatically selected. You can of course change that list before or even during bidding. KSK will also set the class filters automatically if the item has a specific class list (as in the example shown above). If strict class armor filtering is on, the list will be restricted to those classes whose highest armor level matches the armor type of the item.

When the master looter click on an item and the item is listed in the item editor as being automatically assigned to a user, the filter screen will be replaced with a notification of this fact, as shown here:

If you press OK, the item will be given to the specified user, and if so configured, the user will be suicided on the specified list. If you press Cancel, you can open the item up for normal bids or rolls. Please note that this window will only be displayed if the user is in the raid, and eligible to receive the loot.

Once an item has been selected that isn't being auto-assigned, or the auto-assignment was canceled, you can open the item up for bids. Simply press the "Open Bids" button in the loot window. This will start with the selected list, and any selected default rank. If a user attempts to bid on the item that is not eligible to receive loot, or does not match the class criteria or role criteria, the will be informed that their bid was rejected. Note that as the loot master you will not see their whispers or the whispered replies if you have the chat message filter enabled, but you will be informed of them being rejected. When you open an item for bids, the screen at the bottom changes to allow you to bid, and shows the list of current bidders:

You will notice that the Bid button was changed to "Retract" for this user, because they had bid on the item. As the master looter you can select a user from the members list (bottom left panel) and force them to bid, or you can select an existing bidder (bottom right panel) and force them to retract. When you have given your raiders sufficient time to bid, press the "Close Bids" button to close the bids and assign the item to the winner. If you have auto-assignment enabled, you will see a screen like this:

If there were no successful bidders and you have the option enabled, and a suitable enchanter is in the raid, you will be given the opportunity to assign the item to an enchanter for disenchanting:

Sometimes, for certain items, you don't want users to bid, but instead to roll for the item. Instead of pressing "Open Bids" you can instead press "Open Roll" and users can then /roll for the item. The roll timer is controlled by the roll timeout option on the loot configuration screen. If any rolls are detected within the last 5 seconds, the timer is extended back up to 5 seconds. You can change this 5 second threshold in the loot configuration screen. Only the top 5 rolls are shown in the roll window. When you open the item for rolls, the filter window is replaced with the roll window that shows the 5 highest rollers and the time left:

If you need to you can pause the countdown timer by pressing Pause, which will then become a Resume button which you can press to resume the roll timer. KSK supports the notion of "alt-rolling", where a user wants to roll but its for an alt or offspec. Normal users who want the item for their main spec simply type /roll which will roll between 1 and 100. If a user wants to roll on the item for an off-spec or is playing on an alt, they can alt-roll by typing /roll 101-200. KSK knows that a main spec roll of 89 is higher than an offspec roll of 190. If a user made a mistake and alt-rolled when they are on their main, or main-rolled when they are on an alt, they can re-do their roll. However, KSK is smart enough to ignore the actual number rolled, and just set the roll type correctly, so if you rolled a 75 by mistake, and then alt-rolled a 180, you actual roll recorded will be 175 (your original 75, but on the alt-roll list). KSK also temporarily disables LootHog if you have it installed while it is managing rolls.

Loot History

If the option is enabled in the loot option screen, KSK can record all loot assignments it controlled. If you do this, the loot tab has a third panel at the top, the Loot History tab. This will show a list similar to this:

This really shouldn't require any explanation. The "Export" button allows you to export the loot history in XML format only. See the discussion on XML exports at the end of this document for ways in which you can use that data on your own web pages.

Synchronization

Up until the moment you define co-administrators, you do not need to worry about synchronization. If you are the sole administrator of a configuration, at best you need to broadcast the config to other raid members at the start of the raid if you have users running KSK in user mode. However, once you define co-admins, you need to concern yourself with synchronization. Since any co-admin can be a master looter and use KSK for distributing loot or managing lists and users, each admins view of the data needs to be the same as each other admin. If both (or all) admins are always online when each change to the configuration takes place, well and good, they will remain in sync with each other. However, the problems arise when one or more admins are not online when you make changes or use the mod to distribute loot and users move on the lists. This is what the KSK sync manager is designed to deal with.

Before discussing the sync manager in any detail it may help to understand why it is important for admins to remain in sync with each other, and the ways in which they can get out of sync. Consider a large guild that has more than one group that runs Ulduar at different times. The guild uses two lists, one for normal gear and one for tier gear. There are two admins in the guild, the config owner and one other admin. The owner leads the first group and the other admin leads the second group. Before either of the runs take place the two admins are in sync, their lists are identical. Now the first group starts its run, with the config owner being the loot master. However, the co-admin is not online because it is still too early for her. The first group does its run and loot is distributed. Due to the way in which users are suicided on the lists, any user who is not in the raid has their position frozen, and only those people in the raid or on reserve are moved whenever someone bids on an item. At the end of the run, the owners list is now considerably different to the admins list, because of all of the list movement as users suicided and won loot. The owner logs off, and a few hours later the second group runs. The co-admin is the loot master for that group, and they also distribute loot, and an entirely different set of users move on the lists. Now the owner has had list movement that the admin didn't know about, and the admin has had list movement that the owner didn't know about, and their two lists are horribly out of sync. It just so happens that after the second group's run, you want to go and do the Obsidian Sanctum, and both the owner and the admin are present in the raid, and you have some raiders that were in the first Ulduar raid and others that were in the second. Those raiders need to be moved on the lists as if both admins had been online and present together the entire time so that both the owner and the admins lists look the same. If you do not do this, some raiders may have an artificially high position on the list. Enter the sync manager.

Before the raid starts, the owner and the co-admin need to ensure that they have the same events that each other has seen, so that all users are in their correct positions before the raid starts. Both admins need to display the sync manager either by hitting the Sync tab at the bottom of the screen, or by typing /ksk sync. This will display a window that has the list of all possible admins other than yourself on the left hand side, and a blank list on the right hand side. At the bottom right are several buttons you can press to either request sync information from other admins, or to broadcast the configuration to non-admins so that their view of the lists is the same as yours. The most commonly used button is the "Request Sync (All)" button. This will request sync information from all admins in the guild (for guild configs) or the raid (for PUG configs). If you want to sync with just one user you can select their name on the left hand side, and press the "Request Sync" button, which will become enabled as soon as you select an admin on the left. No matter which button you press, whichever admins are online will reply with information about their own sync status, and the right hand list will be populated with these replies. Each entry in this list is 3 lines long, and contains a "Sync" button, which may or may not be disabled (grayed out).

The first line in each sync entry will contain the coadmin who replied to your sync requests name, and a "Sync" button, which may be disabled. If the button is disabled (grayed out) it means that that admin has no sync data for you that you do not already have. The second line displays an internal checksum for that admin. Each time an event takes place (such as adding a user, suiciding a user after a bid, moving users on lists etc) your local checksum will change. When two admins have the same checksum, it means they have both processed the exact same set of events (and are therefore in sync with each other). If this line is green, and their checksum matches your own (your checksum is displayed just above the list of admins), then the sync button will be disabled, as you have no data to exchange with them. If this second line is red, it means one of you has received events that the other hasn't. There is a special case where this line can contain the words "Not active!" which means that you have not yet done an initial sync with anyone, as you have only recently been made a co-admin. More on this in a little bit. The third line contains two fairly big numbers, separated by a slash. The first is the last event ID that you received from the admin, and the second is the highest event ID they have recorded. If these two numbers are different, this line will be red, if they are the same, it will be green. If it is green, it means that the admin who replied has no data for you and your "Sync" button for them will be disabled. However, if they have events you have not yet received, you will need to get all of the events they recorded for you while you were away.

The third button at the bottom is the "Broadcast" button. This is used to send the entire contents of the configuration to users in the guild or the raid. This serves two purposes. The first is that it gives all guild or raid members who are not admins an up to date view of the config, as you know it. Non-admin users will set their roll lists and user lists to exactly the values you have at the time you pressed the button. You usually do this at the start of the raid after all of the admins in the raid are in sync with each other. The second purpose this button serves is to let a user know they have become an admin (or that they are no longer and admin if you have removed them from the co-admin list). If you have just added a user as a co-admin, they will not be aware of that fact until you broadcast the config. One of the bits of information in the broadcast is the complete list of co-admins (this is only sent out by the config owner, as only the config owner can assign co-admins). So when a user who was previously just a normal user receives this broadcast, they will check the list of co-admins and see if their name appears in the list. If it does, it knows they have been added as an admin, and all of the extra buttons and menus that are normally hidden from users are enabled. One of these is the sync tab at the bottom. Likewise, if a user thought they are an existing admin and they get a broadcast from the config owner that does not have their name in the list of admins, they know they have been removed as a co-admin and all of those extra buttons and screens are hidden, and they become just a normal user again. When an admin is assigned for the first time, they will still have a user's view of the data, not an admins view. In order to get an admin view of the data, the newly appointed admin will need to do an initial sync with one of the other admins, usually with the config owner. Since the new admin does not yet have a sync relationship with any other admins, they are "inactive" syncers, and when they press "Request Sync (All)" the second line for any admins who are online and respond will simply say "Not active!". When you press the "Sync" in this state, you will in fact be doing a "full sync" with whichever user you have chosen. Once you have received their reply, your list of syncers will clear, and you will have the exact same set of data that they do. If you now press "Request Sync (All)" again (which you cannot do more than once every 10 seconds to prevent flooding a user) you will notice that the user from which you requested sync is all in green, and your checksums and event IDs will match. You may be out of sync with respects to other admins, but that's OK, it just means the user you requested the full sync was out of date too, at the time you requested sync.

It is highly advisable that you only ever request a full sync with the owner of the config, and then only when they are fully synchronized with all other admins. This will just save potential headaches in the long run. Once you have a full sync with the owner, all other admins will begin recording events for you, and you for them.

You may encounter a situation where you have synced with a user, and your third line in the sync box is green (you both have the same events) and yet their checksum differs from yours (the second line is in red). All this means is that one of you has received events that the other has not. For example you could have synced with an admin but they haven't synced with you, or they have synced with another admin that you have not. Only when both lines are green and the checksums are identical can you be sure that you and other admin have received the exact same set of events. When you request sync info from users, the golden rule of thumb is that if their sync button is active, press it. Wait for it to become deactivated before pressing someone elses button. As soon as you have received sync information from a user, their sync button will be disabled, and you should wait for the third line to turn green (which signals you have finished processing all of their events) before attempting to sync with another user. Here is a screenshot of a case where only one user replied to your request for a sync, and you are out of date with them:

Contrast this to what things look like when you are finally in sync with another user:

A final word on syncing. KSK keeps the events that it has saved for each admin around until such time as that user informs you that they have safely received a given set of events. This does not occur when the sync has just completed! Although you may just have received the events from the user, if you happen to have a PC crash or a WoW error, that data you just received will not have been saved. Rather, when you first log in to the game, you will silently broadcast to all admins the last event you had received from them. Since you just logged in, KSK knows this was from safely saved variables files, and that the data is on your disk and not subject to loss when the game crashes. Only when an admin receives this broadcast from you will they remove the events up to that event you had safely received. This way, each admin is constantly "trimming" their sync data, but only when it can be reasonably sure that the data it is deleting is safe to delete.

Synchronization Internals

Several users have asked for more detail on exactly how synchronization works, so I am documenting the internals here. Hopefully this will help people better understand exactly what to do to avoid problems.

The heart of the synchronization code is the notion of an "event". Every action you take that changes data that needs to be shared generates an event. For example, adding a new user, changing a user's attributes, adding a user to a list, removing a user from a list, moving a user on a list, suiciding a user on a list when they receive loot, adding an item for custom handing, or changing list config parameters are all typical events that get generated while using the mod. Things that do not need to be shared, such as the loot options (/ksk admin) do not generate events when they change, as each admin may have good reasons to have different loot options. Whenever an event is generated, it is assigned a unique event ID. No two events generated by a given user will ever have the same ID. It is entirely possible, although unlikely, that two different admins will generate the same event ID for different events, but this does not matter to the algorithm at all. The only requirement is that each admin never generates the same event ID for any events they themselves generate.

Every admin (and in this context the config owner is just another admin) records the last event ID they generated. This data is key to the synchronization process. Whenever an event is generated, it always has two bits of information that are important: the target of the event and the event parameters. The event parameters always travel with the event and are really indistinguishable from it. However, the event target is very important. Every time an admin generates an event, the target of the event is every other admin that the user currently knows about. So if you currently know about 3 other admins, when you generate an event, the target of that event is each of those three admins. The event (and its parameters) is stored for each of those admins, as well as sent via the private guild addon channel (for a guild config) or raid addon channel (for a PUG config), along with the last event ID you had before this event was generated. When another admin receives this event, they look to see if the last event they received from you matches the last event you think you generated, and if they match, that admin knows they are in sync with you and they process the event immediately, and update their last event id for you. If the last event ID's do not match, the admin knows they are out of sync with you and they ignore the event just sent.

For every admin that you know about, your view of the data will store the last event ID you received from that admin. It also stores a list of all of the events that you have generated that were targets for that admin (in others words, all events from the moment you became aware that the user was a co-admin). If you have never received any events from the user, their last event ID will be 0, and their status in the sync manager will be "Not Active". Only once you have actually ever received an event from an admin are you considered to have an "active sync relationship" with that user. Likewise, if they have never received an event from you, their last event ID for you will be 0, and you will be marked as inactive for them.

Now that you understand the data that is involved with synchronization, it is a pretty easy task to describe the actual algorithm. In KSK all synchronization is by request. The only time any data is ever forced on an admin is when the list owner does a broadcast, and then only to update data that is not synchronized (currently, the owner name, configuration type, full co-admin list and configuration name). So the start of synchronization begins with a user requesting sync information from other users. There are two ways to do this. The "Request Sync (All)" button will broadcast a sync request to the guild addon channel (for guild configs) or the raid addon channel (for PUG configs). If you select an individual admin and press "Request Sync" then the request is sent via whisper just to that admin. Whoever receives the request for sync replies to the sender with a sync acknowledge, which sends the highest event ID and the current checksum for the responder. The person who originally requested the sync gets that data and compares it to the last event ID they received from that user. If the newly received last event ID is greater than the stored last event ID, it means the person who responded has outstanding events for us, and we need to request them. If their last event ID is the same as ours, they have no new events. If their checksum and ours does not match up, it means either we have events for them, or one of the two of us has synced with another admin that the other hasn't. If the checksums match, then it means we have both received the exact same set of events and our databases are identical. If their last event ID was later than our stored last event ID for them, then their "Sync" button in the list of syncers who responded will be enabled. When you press that button, it sends a request for events to that user, telling them what the last event ID we had stored for them was. They then reply with a list of all events for us between that number and their latest event ID. When we receive the events from them, we carry out whatever command the event tells us to (add a user, move a user on a list, suicide a user etc). After we have processed all events in the list, we update our last event ID for that admin, and we are now in sync with that admin. Once all admins have synced with each other, they should all have identical checksums.

It may appear from above that KSK keeps all events indefinitely. That is not the case. That would waste a great deal of memory. KSK implements an "auto-pruning" algorithm to remove events it knows are safe to remove. Here's how it works. WoW saves data in a file called a "savedvariables" file, which has the same name as the addon that is storing data. Whenever WoW shuts down cleanly (i.e you exit without errors) it saves the variables your addon told it to in the saved variables file. If you have a power failure or get a critical error, this addon data is not saved. In order to implement auto-pruning, when KSK first starts up (which means it is reading its variables from a saved to disk version of the variables file) it sends a broadcast to the guild or raid with a list of all admins it knows about and the last event it received from that admin. If an admin is logged on when that broadcast is sent, it will automatically remove all events prior to the event ID sent in the broadcast. This is safe to do because it knows that the saved state of the sender includes all events prior to the one they sent out. In this way, old events are automatically removed from each admins list as soon as it is safe to do so. It is a pretty good idea at the end of a night for all admins to log out and log back in again, one at a time, so that firstly their own databases are saved safely to disk, and secondly, so that they are trimmed when the other admins log in.

And that, in a nutshell, is how synchronization works. The system is as robust as possible but there are ways it can go wrong, especially if you have too many admins making too many changes when other admins are not online. Some guilds are tempted to make 5 or 10 officers all co-admins. That is usually not a good idea at all. It is far better to pick 2 or 3 people who are always going to be in every raid and just make them co-admins. If a given admin is going to be away for a long period of time, it is best to remove them as a co-admin while they are away, and re-add them when they return. Otherwise all other admins will accumulate possibly hundreds of events for that admin, and this does indeed waste memory.

XML Exports

There are two places in KSK where data can be exported in XML format. One of the many benefits of XML is that more than one program can read and interpret the data and display it in a variety of formats. If you have never used XML before, or you are not a programmer that can use PHP, Perl, C or C++ to parse and transform the XML into HTML, I have added two XSLT stylesheets to the distribution that will help. In order to use this solution you need access to a webserver, and you need to be able to upload files to it. If you are using a guild management website that does not allow you that most simple level of control, I am unable to help you. The rest of this section assumes that you are able to at least upload basic files to a webserver, and then view those files.

The first step is to upload the two XSLT stylesheets to your webserver. You can find these stylesheets inside the KSK archive in the XSLT directory. They are called ksklist.xslt and kskitems.xslt respectively. Put those files on your webserver in whatever location is appropriate for you. You only need to do this step once.

This next step you need to do each time you export the lists from the mod and want to update your web server. First, open your favorite text editor (notepad will do on Windows) and add the following two lines (for the list position export): 

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="ksklist.xslt"?>
Immediate after these two lines, paste the export string from the mod using Ctrl+V.

If you are exporting the loot history list, you need to add these two lines instead of those mentioned above: 

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="kskitems.xslt"?>
You will notice the only difference is the name of the XSLT stylesheet to use. ksklist.xslt is for the list export, and kskitems.xslt is for the loot item history export. In both cases you do the same thing: insert the correct two lines from above and then paste the export string the mod produces. Then save the file. If this is the list position export, call the file you save ksklist.xml and if it is the loot item history export, call it kskhistory.xml. You can really call them anything, as long as the extension is .xml and not .html or .txt or any other such thing.

Finally, upload the saved XML file (or files) to the exact same location on the webserver that you uploaded the XSLT files to. That is really important (unless you change the href lines above to point elsewhere). Now all your users need to do is browse to http://www.youserver.com/path/to/ksklist.xml or http://www.youserver.com/path/to/kskhistory.xml and it will transform the XML into pretty, readable HTML. You need a relatively modern browser for this to work.

There are other more complicated ways you can do things, including configuring your Apache webserver to transform the XML for the user if they do not have a browser that can do it for them, but that is way beyond the scope of this document. The key to making this work is adding the correct two lines above to the XML export string, and ensuring that the href in those two lines points to the correct stylesheet as provided by the mod. If this does not help you, please consult your nearest web expert. I can not help individual users with their unique setups, as much as I'd like to.

In Closing

That is pretty much all there is to KSK at the moment. I sincerely hope that KSK will help your guild or raid with loot distribution. Please send me comments or suggestions either by email or by leaving a comment at Curse Gaming. Thank you for your support and I hope this guide was useful to you.