About This Document
This document provides detailed information around the Guildomatic World of Warcraft in-game module ("Guildomatic Module") that forms an integral part of our streamlined and automated web site system for managing a World of Warcraft guild.
The guild members responsible for running the guild site and its associated in-game module should read this document so that they understand what the module is intended to accomplish, and how to install and make use of its functionality.
The Guildomatic module is under active development, so we'd love to hear what you would like to see. You can post feedback, comments or suggestions on the support forums linked to below.
How to Get Help
Table of Contents
- GUI Module Changes
- Guiding Module Principles
- Downloading the Module
- Installing the Module
- Uploading Module Data Files
- Using Uniuploader to Automatically Update Roster
- Downloading In-Game DKP Data
- Module Commands
- /gt snapshot Command
- /gt snapshot list Command
- /gt snapshot remove Command
- /gt snapshot <boss/event> Command
- /gt auction Command
- /gt roster Command
- /gt queue Command
- /gt queue <on/off> Command
- /gt queue print <raid/officer/say/party/guild/channel> Command
- /gt queue add <name> <class> Command
- /gt queue remove <name> Command
- /gt queue clear Command
- /gt queue config <channel> <# of mins> Command
- /gt queue status Command
The Guildomatic Module installs and run from within World of Warcraft. It aims to make your life dramatically easier as a GuildMaster, Officer, or site administrator, and lets you do things like:
- snapshot your guild roster
- run in-game auctions of items for DKP bidding
- snapshot raid events to determine who was present at a particular game "event", such as a boss kill, and grant them DKP for their presence
- queue management for automating in-game member signup to queue for a full raid
- in-game dkp lookups to retrieve dkp values for a member, class, or top dkp-based guild members with whom you may be competing in an item auction or just because you're curious.
Note that full functionality requires an active Pro Package subscription. If you have a Free Trial or Basic Package subscription you can upload your guild roster info, but you will not be able to upload or manage your game events and item auctions through the web. You can upgrade to the Pro package at any time if you decide you would like this additional functionality.
GUI Module Changes
Earlier versions of the Guildomatic module were entirely command-line driven, and had no graphical user interface (GUI) with windows, buttons, etc. to control things. The latest module adds a GUI for many of the most commonly required actions. This section highlights changes from the previous module to the new. It is mainly intended to help customers who are used to the older version of the module understand what the new features are, and get a handle on changes in usage. New users are probably fine skimming or even entirely skipping this section.
Note the module and associated data file names have changed to just "Guildomatic" where previously they were "GuildomaticDKP".
You'll need to reference the new Guildomatic.lua file for your SavedVariables data file upload. The Guildomatic_static.lua file usage is the same as always though obviously it now has to be placed in the Guildomatic addon folder rather than the GuildomaticDKP folder.
Important Note: Disable or remove the old GuildomaticDKP module when running the new one. You are likely to encounter strangeness if you run them in tandem.
Highlights of new features you will find in the GUI module include:
- gui display for roster, raids, auctions, dkp, with sortable columns
The main module window will appear when you first log in automatically, and thereafter should remember whether you had it visible or hidden as well as which tab was last open. You can also toggle its display with the "/gt window" command.
Clicking the minimap icon will toggle show/hide of the window, and right-clicking the minimap icon will bring up the module config panel. You can disable the minimap icon in the config panel.
All command-line commands are now moved under the "/gmatic" or
"/gt" prefix. So, "/gt snapshot list" or "/gmatic snapshot list"
instead of "/snapshot list", "/gt auction
The usage of a static data file ("Guildomatic_static.lua") downloaded from your web site to provide web-configured info like calendar events, raid snapshot events, etc. is same as always, and the data outputted in the "Guildomatic.lua" SavedVariables file should be compatible with your web site as previously. There is more info on the static data file for those unfamiliar with it.
Guiding Module Principles
There are a variety of other systems out there to manage DKP and guilds online, so it's worth spending a moment explaining how ours works and why we designed it the way we did.
Taken in totality, we believe that these principles, and the module and web site we've built out around them, allow for an extremely efficient, streamlined, and automated management workflow for running your World of Warcraft guild. These same tools have been in use for over a year in running one of the top raiding guilds on the Uldum US server, and their use is increasing on a daily basis as more and more guilds looking to run their site without the headaches of custom software installation, maintenance, and manual data tracking look to Guildomatic's services.
Some of our core guiding principles are:
- Make it specialized for and focused on World of Warcraft.
Some other systems have taken legacy modules such as those for Everquest or other MMORPGs and hacked on them to allow some form of sometimes painful or awkward usage within the context of a World of Warcraft guild and guild web site. In contrast, we designed and developed our module and associated web interface specifically for use with World of Warcraft.
Only the guild master/officers tasked with managing guild activities
and information should have to have the module installed.
Requiring that every guild member have a guild management module installed isn't just impractical, it's almost impossible, especially when a new patch comes out and suddenly every member in your 100+ person guild has to download a new module version.
Using whisper commands to the officer/admin running the guild module
is a clean, efficient, and effective way to empower guild members to
interact with the module's features.
For instance, when running an auction to bid on an epic item that dropped during a raid, the admin can announce the auction start, and interested players can send their bids to the admin via whisper commands.
Administrators like using simple text commands to
execute module functions.
We have added a basic user-interface to allow use of the module via a window and buttons, but inevitably guild admins will become familiar with the core functionality and just want to be able to start and stop events and snapshot rosters and so forth quickly and easily, and a text-command-based interface is ideal for this kind of thing. Everyone is used to running commands like /who, so we want to allow folks to use our module the same way.
For instance, /gt auction to run auction commands, or /gt snapshot list to list all game event snapshots currently stored in the module data file.
Uploading the data to the guild site, reviewing the information identified
in the data file, and hitting Submit is all it should take to
keep an up to date record of item drops, dungeon/raid events,
and guild roster membership.
At the same time, allow for the flexibility of manual revision to information post-upload.
Downloading the Module
You can always download the latest version of the module from our download page.
Blizzard occasionally releases a new WoW game patch that will require you to download a new version of our module to ensure compatibility with their changes. You can check the download page or contact us via the support forums or email after a patch to obtain any new version of the module.
Installing the Module
First, quit World of Warcraft if it is currently running. Next, unzip the module archive file once you've completed the download. It will unpack to a single directory called "Guildomatic". You will need to copy that folder (the whole folder itself -- not just the individual contents) into the "AddOns" folder in your World of Warcraft game folder.
On Windows XP, this is usually somewhere like:
C:\Program Files\World of Warcraft\Interface\AddOns
On Windows Vista, this is usually somewhere like:
C:\Users\Public\Games\World of Warcraft\Interface\Addons
On MacOS, this is usually somewhere like:
Macintosh HD:Applications:World of Warcraft:Interface:AddOns
Once you install the folder into your AddOns folder, you can run World of Warcraft and make sure it is properly installed by typing /gt or /gmatic. This command prints out the help menu describing all of the available commands. You may want to reference this frequently while you're learning how things work.
Uploading Module Data Files
Several of the common actions you'll be doing with the module end up storing data in a file on your computer, which you're then going to want to upload to your guild web site later to update your guild's information. These files are saved under your World of Warcraft game folder in a directory such as:
C:\Program Files\World of Warcraft\WTF\Account\<your account name>\SavedVariables\Guildomatic.lua
C:\Users\Public\Games\World of Warcraft\WTF\Account\<your account name>\SavedVariables\Guildomatic.lua
Macintosh HD:Applications:World of Warcraft:WTF:Account:<your account name>:SavedVariables:Guildomatic.luaYou'll need to use the "Browse" button on the guild web site file upload pages to navigate to this file and upload it. We will be adding a utility application to automate this process and make it easier in the future. You can simplify things for yourself in the meantime by creating a shortcut or alias to the data folder on your desktop so that you don't need to click through all six folders every time you need to upload a new file.
IMPORTANT NOTE: Make sure you always quit World of Warcraft before uploading any data files to your guild site. This is the only way to be sure that all of the module's data has been properly saved to disk.
Windows Vista Users: See tutorial tips for several additional tips on finding potential alternate locations for data files and troubleshooting data file issues under Windows Vista.
Using Uniuploader to Automatically Update Roster
Uniuploader is a client-side program for Windows that many people use to help automate the process of uploading module data files to their web site. The basic idea is that you configure it to point it at the module data file you want to upload, and then you tell it what URL it will upload the file to, and your login info for that URL. Uniuploader will then automatically upload your data file whenever you quit WoW (or whenever you configured it to do so), and thereby (assuming you ran the /gt roster command in-game to update your data file) accordingly update your roster.
This means your roster will be kept up to date automatically and you won't have to manually upload your data file whenever you have guild members come and go. You will still need to upload your module data file manually if you want to upload DKP snapshot and item loot data, since that requires manual review and approval of the data.
More info on the specific steps to get Uniuploader installed and configured:
- Download UniUploader. We used the version without the installer (just the .exe file).
- Run Uniuploader. In the Config section, put
http://yourdomain.guildomatic.com/members/auto_uploadNote: make sure you use your actual domain name and not yourdomain.guildomatic.com.
- Select your WoW account.
- Click "Show SVs" at the bottom and make sure Guildomatic is checked.
- Make sure "Use User/Pass" is checked in the "Upload Access" section.
- Enter the username and password you use to login on your guild site. It's important that the login credentials you enter here are for a user who has roster administrator permissions on your guild site, else the upload will fail as the user does not have permission to update the roster. More info on setting administrator permissions is available in the Guildomatic Tutorial.
- Try testing by pressing the "Upload" button at the bottom.
Additional notes and tips if you have trouble getting it working:
- We used (and recommend) "Simple Mode" in Uniuploader to configure things. If you don't use Simple Mode you may need to fiddle with some other settings (see below) to get it to work properly.
- If you're not using Simple Mode, make sure:
- You have your username and password set.
- You have compression disabled (under Advanced).
- You have "Send Password Securely" under "Additional Variables" section under the "Options" tab un-checked.
- Manually double-check the login credentials (username and password) you're entering into Uniuploader to make sure they work when you log in to the web site as well.
- Make sure the user whose login info you're using has roster admin permissions on the guild site. The site owner account always has these permissions, and can grant them to other users as described here.
Downloading In-Game DKP Data
The /gt dkp in-game module command lets your guild members look up their available DKP. For this command to work, you have to download the DKP data beforehand and make sure it is available for reference by the module. To do this:
- Download your static DKP data file from:
http://yourdomain.guildomatic.com/dkp/Guildomatic_static.luaNote: make sure you use your actual domain name and not yourdomain.guildomatic.com.
- Place the file in the module's folder, on Windows something like:
C:\Program Files\World of Warcraft\Interface\AddOns\Guildomatic
With the file in place, you will now have in-game DKP lookups, and automatic snapshots for any Raid Snapshot Events you had configured in your web site.
An example of DKP lookups — you can look up DKP using:
/gt dkp <player name> /gt dkp <class name> /gt dkp allPeople can then query you if you enable it like so:
/gt dkp onAfter which people can whisper you, e.g. "dkp <player>". For example: "dkp Krellmax". And they will get a response with that person's DKP. You can also do this per class, "dkp Hunter", and all, "dkp all".
On automatic snapshots, let's say you had used the web site "Raid Snapshot Events" page to configure a snapshot event for "Lady Vashj" with a default DKP value of 20 dkp. Then, when you download the static file it contains all configured event data. When you are running the mod and it sees a boss named "Lady Vashj" killed, it will automatically take a snapshot as if you had entered /gt snapshot Lady Vashj 20 as a command for the module. The nice thing here, then, is that you can configure bosses you frequently kill (or plan to kill), with their DKP values, in the website; download the data file; and the bosses will be auto-snapshotted with who was present for the kill, users will be awarded the corresponding DKP (which you can review and edit when you upload the snapshot data as needed), and you don't even need to type any snapshot commands at all.
The module provides commands detailed in its /gt help menu as follows:
Guildomatic Module Help
/gt dkp <name/class/all> [check dkp]
/gt dkp <on/off> [enable/disable dkp lookups]
/gt snapshot [help menu for snapshot]
/gt queue [help menu for queue]
/gt auction [help menu for auction]
/gt roster - records the guild roster
/gt snapshot Command
Guildomatic DKP Module Help
/gt snapshot list [list all snapshots]
/gt snapshot remove <snapshot #> [remove snapshot entry]
/gt snapshot <boss> <dkp> [snapshot raid members]
NOTE: You must be in a party or raid group to take a snapshot.
The general usage pattern expected here is something like:
- Configure the Raid Snapshot Events (such as bosses) for which you care about tracking attendance via the admin interface on your guild site, using the "Raid Snapshot Events" link. You'll want to create "New Events" for the bosses or other game events you want to track, entering the default DKP amounts members present at the event should receive.
- Start a raid, run through with your guild, and when a boss is killed or the tracked event otherwise occurs, take a snapshot via /gt snapshot <boss name> <dkp amount>. Specifying the DKP amount is optional — if you don't specify anything the members will receive the DKP amount you configured on the web site. If you do specify a DKP amount, that is the amount they will receive regardless of what is configured on the web site.
- Quit WoW and upload the module data file to the web site.
- Next time you run WoW, clear out the snapshots that you've already uploaded by running /gt snapshot list to see all of your snapshots, and /gt snapshot remove <snapshot number> to remove the desired snapshot.
If you don't clear out old snapshots you've already uploaded, don't worry — they won't get mistakenly re-processed when you next upload data because they are marked with a timestamp that the guild site checks to determine whether it's already processed that snapshot. However, over time the data will grow in your data file and the time it takes to upload your module data will grow, so it's still a good idea to periodically delete old snapshots.
Note that if another guild member ALSO snapshots an event, and you BOTH go to upload your snapshots, they will both be processed even though they're for the same event because they have different timestamps. So it's your responsibility to make sure only one guild administrator is snapshotting and uploading raid events at any point in time to avoid this kind of situation. You can always use the web site tools to manually adjust users as needed or delete incorrectly uploaded snapshot information.
In general you should name your snapshots (the "boss" parameter) the same as the "event" you configured on the web site, if possible, so that the default DKP value will be automatically applied and it will have the same name as other similar events previously recorded.
/gt snapshot list
Lists all snapshots recorded in your data file. Each snapshot is numbered so that you can refer to it with other commands, such as for removal with /gt snapshot remove.
/gt snapshot remove <snapshot #>
Removes the specified snapshot number. There is no confirmation or other way to retrieve the data once removed, so make sure you really want to do this before running the command. You can see a list of all of the snapshots and their numbers with the /gt snapshot list command.
This is intended to allow the administrator to clear out old snapshot data that has already been uploaded. Snapshots accumulate over time and once uploaded they don't need to be kept around, so they should be periodically cleared out in order to keep data size and snapshot lists manageable.
/gt snapshot <boss/event> <dkp>
Takes a snapshot of everyone currently in attendance at a raid. It makes it easy to determine who was present at any given point in time, e.g., when a particular boss is killed. This way you don't need to try to keep track of who was there at the start of the raid; whether they left partway through; whether they were actually there when the boss was downed; and so forth.
/gt auction command
Usage: /gt auction <item/stop/list> [start an auction/stop an auction/list auctions].
Provides raid leader with an easy way to manage auction-style bidding on things like epic items that drop from a boss. General usage looks something like:
- Raid leader starts the auction with /gt auction <item name>.
- Three rounds of 30-seconds of bidding ensue, with guild members wishing to bid on an item submitting their bids to the raid leader via whisper messages such as bid <bid amount>.
- At the end of the bidding rounds, the winning bidder is announced and the auction results (winner, date/time, winning dkp bid) is recorded in the module data.
- After the raid is over the admin/raid leader quits WoW and uploads the module data file to the guild site via the admin interface. The auctioned items will be associated with any raid events based on the item id, winning person, and date/time, so that your raid and item information will all tie together. If there is no raid event the item will still be uploaded and associated with an "Unknown" event.
It is preferred to start an auction with /gt auction <item name>, where the item name is inserted by shift-clicking on the item in the WoW chat window, since that will ensure the item name and id is exactly correct and that there are no typos.
The admin can cancel an auction early if something goes awry via /gt auction stop.
The admin can list all auctioned items recorded in the current module data with /gt auction list.
/gt roster command
Captures a list of all members in your guild to the module data file for later upload to the web site. Unlike the "snapshot" raid/game event facility, there is only a single entry for the roster data in the module data file and so if you re-execute the command it will just overwrite the earlier data. When you upload the roster data to the web site, it will add any members it sees in the data that aren't already in the roster, and disable any members that are in the web site data but are no longer in your roster data.
You can run through these steps as many times as you'd like — in theory you could update your roster every day with no harm done and your roster list would just be that much more up-to-date.
If you have problems getting all of your guild members captured, try opening your in-game guild member list (the "O" key or "Social" button, and then the "Guild" tab) and check the "Show offline members" checkbox, before you run the /gt roster command.
/gt queue command
Allows you to manage guild members waiting in an in-game queue, for instance, when you have a large raid scheduled and more people are waiting around to join in than can fit in the raid. In general usage, a single admin runs a "queue", and users who want to join the queue send a whisper message to the admin to join. The module will automatically inform people periodically on how to interact with the queue, and status on who is in the queue and where they are at.
The end goal is to relieve the admin from having to manually record and track who signed up first, and for which class. It also allows people playing on alternate characters to still follow the raid from the queue and sign up for it with the class they plan to use. The admin will have configured a particular channel (e.g. myguildqueue) in the module for use with the queue, and the queue status will be periodically sent to that channel automatically. So users waiting to join the raid will want to join that channel so that they can stay informed on where things are at.
To elaborate on common usage:
- All users should be informed what channel they should join if they want to hang out and wait for a raid. Note you can use "/gt queue print" (described above) to inform people, e.g. in guild or raid chat.
- When a user logs on, if they were in the guild specific queue chat channel last time they played, they'll auto-rejoin it. Then if the admin is running the mod with /gt queue on and it's configured to that channel, after a bit they will see a message with info on joining the queue, and status on who's in the queue, repeated periodically.
- As is mentioned in the info message users will receive/see, all a user needs to do to join a queue is whisper the admin running it, e.g. "/w myadmin q join". They can remove themselves with "/w myadmin q leave". They can get the very latest status on the queue with "/w myadmin q status". If users are on an alt, they can join the queue for a specific class with "/w myadmin q join <class name>", otherwise the class for the queue join will be automatically determined based on the requesting character's class.
- When the admin has an opening, they will check the queue for latest status via "/gt queue status", invite whomever they'd like, and then remove that character from the queue with "/gt queue remove <name>".
The full set of queue-related commands, with more detail on each below:
Guildomatic Queue Management Help
/gt queue <on/off> [enables/disables the queue]
/gt queue print <raid/officer/say/party/guild/channel> [prints queue to channel, specifying 'channel' will print to the configured channel]
/gt queue add <name> <class> [add a player to queue]
/gt queue remove <name> [remove a player from queue]
/gt queue clear [clears the queue]
/gt queue config <channel> <# of mins> [set the channel to output queue messages and how often to print queue status]
/gt queue status [view queue status]
/gt queue <on/off>
Enables and disables the queue feature. This allows the admin to turn on or off all of the auto-queue management, such as the automatic status updates, the processing of queue add/remove requests the admin receives from users, and so forth.
/gt queue print <raid/officer/say/party/guild/channel>
Sends a message alerting users to the existence of the queue, and how to use it, to the specified "destination". Per the help menu, possible destinations include: raid, officer, say, party, guild, or channel. Each of these will result in printing the queue info to the respective channel, except that actually typing a destination of "channel" (the actual plain text word, not the name of your guild-specific channel) will send the message to the guild-specific channel you configured via "/gt queue config".
An example message this command will print for a queue might look like:
[Biff] says: Queue status
[Biff] says: Mage: Isis, Atticus.
[Biff] says: Priest: Soli, Gregory.
[Biff] says: Whisper Biff 'q join' to join the queue. 'q leave' to leave the queue. 'q status' for the current queue.
This command is commonly used by admins to make it easy to send queue info to users, singly or in a group, when they ping you directly asking how to join the queue, get status on it, etc. It outputs the exact same message that gets automatically outputted periodically to the chat channel configured with the "/gt queue config" command.
/gt queue add <name> <class>
Adds the named user, of the named class (e.g. "Warrior"), to the queue for that class.
/gt queue remove <name>
Removes the named user from any queue they may be in.
/gt queue clear
Resets the entire queue contents, removing all players from the queue.
/gt queue config <channel> <# of mins>
Sets the name of the chat channel to which your queue messages are sent (with instructions on how to sign up, per examples in the "/gt queue print" section above). By having your users join that channel, they will automatically be periodically informed that the queue is available (if it is), and who they need to whisper to join it. The module will also use this channel to output, every few minutes (per the "# of mins" param), status on who is in which queue.
/gt queue status
Displays the current view status to your user console for your own review. This is frequently useful when you, the admin, have a spot open and need to see what the current queue status is immediately to determine which guild member to invite.
Common problems and other things to double-check before contacting us via the support forums or email (noted at the top of this document):
- Uploading the wrong file: make sure you're uploading the right data file per the paths described in the "Uploading Module Data Files" section above.
- Data file corrupted or otherwise bad or damaged: on rare occasions WoW may not exit gracefully or some other issue may cause the module's data file to become corrupted. In this case, you can move aside or delete the module data file and the module will automatically create a new empty data file.
- Not quitting WoW before uploading data: you must quit WoW before uploading your data file, as that is the only way to ensure that the module data is all written to your disk before uploading. If you receive errors attempting to upload your data, make sure you aren't trying to upload a file while the game is still running.
- Uploaded and saved a data file with obsolete or incorrect information: the web site provides facilities for manually editing or deleting uploaded data, e.g. recorded game events, items, and manual adjustments to the roster or user DKP values. So even if you or someone else in your guild uploads invalid or stale data, you can always make manual corrections as needed.
- Windows Vista security changes can lead to data files residing elsewhere or other problems with the data files being written out. See tutorial tips for several additional tips on finding potential alternate locations for data files and troubleshooting data file issues under Windows Vista.