Pitbull4
From EFWiki
Pitbull4 is the latest version of the unit frame mod by ckknight. It is, at time of writing, in beta. Which means as much as a potential plethora of updates. However ckknight has indicated that he considers the mod mostly done, and only minor tweaks are upcoming.
The mod itself is extremely modular, which makes the setup perhaps daunting, but if you dive into it you'll soon see everything makes lots of sense, and you'll be creating your own layouts by yourself soon enough. Yes layouts, frames are so passé. All kidding aside though, this page aims to guide people through the many option pitbull4 offers.
The latest version can be found here: http://wow.curse.com/downloads/wow-addons/details/pitbull4.aspx
Contents |
Layouts vs. Frames
As I indicated, you will soon be setting up layouts for Pitbull4. This is a distinct difference from modifying the looks for a frame seperately. There is a load of frames to make up an interface including, but not limited to, player, target, target of target, party, party pets, focus, focus target, etc. Modifying each of the frames you need seperately would be an insane job, so Pitbull4 introduces the concept of a layout. Basically a layout defines the look of *a* frame. Once you have defined a layout you can attach it to as many frames as you want.
A small example: Say you define a layout called 'enemy'. It defines a health bar with the name of the target and the health of the target. In addition it defines the mana/rage/energy/focus bar (conveniently called power bar) as having the level of the mob and it's mana (if any). It also has a cast bar so you can see and interrupt any cast. Lets also assume you watch your intended targets in three ways: by your own target frame, your focus frame and the main tank target frame. Now you simply attach the layout 'enemy' to the target, focus and mt target frame and voila, one setup for 3 frames, all looking exactly the same.
Profiles
Before we actually dive into pitbull I have to note something about profiles. Pitbull4, as do many other mods, use a profile system to customize settings by. If you do not change anything about the profile settings you will be working on the Default profile, which all characters happen to have selected by... well default. If you want to create different layouts for different characters I suggest the first thing you do is select a different profile, before starting with any of the customizing options. Or you can create the default look first, and copy the default profile to another one in order to create a more specific setup. By default there are 4 profiles available:
- Default
- Class
- Realm
- Character
This will probably suffice, but you can always create more if you need it.
Starting with Pitbull4
I'll assume everyone here knows how to install a mod, and as Pitbull4 is no different, we'll just skip that part. Once you get into the game, you'll notice frames on top of each other in the middle of your screen. Drag them around (hold the left mouse button) until you have a little bit of an overview if you want. Now it's time to start Pitbull. Type /pitbull in chat, or hit the minimap icon.
On the left side you'll notice some 'tabs' and you're currently looking at the Layout Editor. That's where you'll spend most of your time. To start with, there are two important things to do. First hit the "Units" 'tab'. It will show you a lot of data, but the most important thing is the "Current unit" dropdown with the different frame names. Go through them (yes one-by-one) and tick "Enable" off for any frames you do not want. This will save you space while editing (or not if you think you need everything). Do the same for the "Groups" 'tab'. Now lets start with your first layout!
A note on the Units and Groups page
As you can see there are a lot of fansy options on the Units and Groups screens. Those on the Units screen basically allow you to move, scale and resize individual units aside from the options presented in the layout. The Group page is slightly more obscure as it allows you to create new groups (raids and main tanks aren't in there by default for example). Currently using the Groups screen is beyond the scope of this guide (though I might include it at some point), however as a quick rundown to create raid frames: enter 'Raid' or somesuch in the "New group" input box and hit enter. Next in the "Unit group" dropdown select Raid. Go to the "Filtering" tab and check all the checkboxes. Go to "Unit formation" and change the "Units per column" slider (40 units in one column will look horrible). Change the "Sort method" to Group. Now, when you change the Config mode to any of the raid setups new frames will be created and shown on your screen. If you select "40-man raid", you might have to wait a while. Remember you might still want to create a seperate layout for your raid frames.
If people want I will create a section at the end of this guide on how to set up any specific frame, or I might even make an entirely new guide for it.
Your first layout
I said you could create layouts first and then attach them to frames. Though this is true in a sense, usually you attach the layout before editing. This is to see your changes as you make them.
The player frame
Go back to the "Layout editor" 'tab'. Select "Normal" in the "Current layout" dropdown. Now in the textbox next to that type 'Player' (or however you want to call it) and hit enter (you know, the button on your keyboard). Tadaaa! That's your first layout, aren't you awesome? Alright before we go editing there are two more things we need to do. Go back to the "Units" screen and select "Player" in the "Current unit" dropdown. Next select your created layout in the "Layout" dropdown. The layout you've just created is now attached to the unit. Editing it will cause the player frame to spontaneously change. One more thing, promise, before we start laying it out. See that "Config mode" dropdown in the top left part of your PitBull frame? Select "Solo". Now you'll see all potential frames you could have while playing solo, and wonder above wonder, your Player frame is right there too! With buffs, icons, and whatnot. We are now ready to start editing (isn't that grand).
I'll be running through the entire editor tab by tab I suppose, unless I find some more awesome way to do it. I hope a lot of stuff makes sense by itself, but I will try to explain what I need.
General
As a sidenote, I have disabled all other frames so I have a single frame to work on in Config mode - Solo.
Allright, the General tab. Not much interesting here, except it allows you to use the subtab Delete to remove the layout. Scale, Width and Height will probably make sense to most people. One thing should be noted about the height: this is an absolute value. All bars have a height value as well, but those will never be able to make your frame bigger than the height you set here.
- Personally I am one for stripping off as much unneeded stuff as possible, allowing me to make these frames decently small, for now, lets just stick with the default size and see where it brings us.
Bars
There's quite a decent amount of bars as you can see, and there's even blank space (which is disabled by default)! Most of what you see here is not particularly interesting. The Default Texture is either Blizzard or Gradient, and you can get more skins by installing a shared media lib mod LibSharedMedia. None of this is exactly rocket science, and you can quickly set it up. What you'll notice a lot is a Position dropdown. This is basically where in line you're current bit of layout will end up. For instance the cast bar is at position 6, selecting the threat bar in the drop down will move the cast bar one position up, and consequently will drop the threat bar one position.
Like I said before there's height sliders here as well. These are relative heights. For example, if health bar height is set to 2, mana bar height is set to 2 and all the other bars are set to 1, the health and mana bar will be twice as big as all the other bars. It's left up to Pitbull how high in pixels this actually is.
- Alright, I'm going to assume people here have seperate mods for Threat, Reputation, Experience and their own castbar so tick the enable button on those tabs and see the health and mana bar grow! Isn't that fun! Also, you immediately have a better overview of how your frame actually looks. A funny thing you can do, if you want a cast bar on your player frame is to leave it enabled and tick the Auto-hide checkbox. Now when you're not casting, there's no castbar.
Indicators
As you can see there is a lot of indicators present. These are all the icons around your frame, such as raid mark, role icon, leader, master looter, etc. I'm not going into all of it as most speaks for itself. One interesting aspect is the Location dropdown. It allows you to place any indicator just about anywhere in, on and around the frame. The position as bar option, while fancy is something you might not want to use for icons, as it's a bit overkill. However we will be using the option soon for something else.
The general tab has some interesting options such as padding and margins. Depending on where you attach indicators, different sliders will do different things. If anyone knows how Frame relation padding sliders work though, I'm all ears.
- Time to do some fancy stuff with these indicators. Switch off what you do not want. I switched the size of the icons to 10, moved the role icon to Edge, Top and resized the Raid Target icon to 125% size. And now for the fun part (just to show you one of the many options in Pitbull4). Enable portrait and set Style to 3D. Tick the Position as bar and select Side Center. Next select Position Health bar. Oh my gosh! A 3D portrait bar in the center of your frame, isn't that cute?
Texts
Now this is where the roughest part of Pitbull4 is hidden. Are you ready to read code? I hope you are, because that's what it boils down to if you want anything else than the standard options.
First of all note the dropdown "Current text". This is where all your default and custom created texts are located. There's more dropdowns as you scroll down, but this is the most important one. Now if you scroll down you'll notice something weird. There's actual code there. That's lua, the language in which mods are written. However, not to fear, you do not need to resort to learning the language right away. For every text you want to edit, you can first go through the "Code" dropdown to see if what you want has already been added.
For instance, for "Class: Standard", the code looks daunting, and non-lua programmers will probably have no idea what it says. However, presuming you are showing class colors for health bars "Class: Standard" is already showing to much information, so switch to "Class: Short level and race". Tadaa, much more readable code right? Now since we know what race we are, even this tag might be too long. If you just want level, but colored by difficulty, do the following:
Change:
local dr,dg,db = DifficultyColor(unit) return "|cff%02x%02x%02x%s%s|r %s",dr,dg,db,Level(unit),Classification(unit) and '+' or '',SmartRace(unit) or ''
To:
local dr,dg,db = DifficultyColor(unit) return "|cff%02x%02x%02x%s%s|r",dr,dg,db,Level(unit),Classification(unit) and '+' or ''
Once you hit accept, only your class number will show. Also note that your "Code" dropdown is now showing "Custom". As far as the lua goes I can only advice, go with the simplest thing closest to what you want, and read the code carefully. I'll try to explain how the texts work, but keep in mind I'm not an expert on LUA so this might be slightly off:
after the word "return" double quotes " are opened, after which the actual text ensues. Now everywhere you see a % (percent) sign you should be aware the text is not as it seems. A percent sign basically changes the meaning of whatever character(s) come behind. For instance, in the above example "%02x" says "this is not the text %02x, but rather a spot where you have to put a value formatted in a certain way" (I presume here the x is a number and 02 formats it to a hexadecimal to create a part of the color). In the same way %s tells the system that it is a spot to insert a certain value, rather than the text %s. Once the text is complete (with placeholders) the double quote is closed and a comma seperated list of values begins. In the above case dr, dg, db stand for the color parts of the text's %02x placeholders and Level(unit) and Classification(unit) are evaluated and inserted into the two %s parts, creating the entire text. The text is filled with the values from left to right.
One thing to note is in percentages. To create a text that contains the health percentage of a mob the following can be seen:
local cur, max = HP(unit), MaxHP(unit) return "%s%%", Percent(cur,max)
Because the % has a special meaning in the code you will need to tell the system to use it as a normal character by prefixing it with a percent sign.
A note on LUA and DogTag
Pitbull4 comes with a DogTag module. This basically turns the lua code for texts into something more readible. If you have big trouble with the LUA texts I suggest you switch this on. In the left menu go to Modules, find the "DogTag-3.0 texts" and tick the Enable checkbox. Next, find the "Lua texts" entry and tick off the checkbox. Beyond that I cannot currently help at this point, as I've very little understanding of DogTag, and will not look into it until after I finished the first version of this guide. In the meantime I believe Jadenn is an expert on this, so you can ask him.
- Ok, time to mess around with texts. I dislike the standard texts that are shown, except for the name, so I'm going to change the class indicator, the mana and the health (note that the below will not function with DogTag). My class text can be found in the code above, and can be even further shortened.
- Class:
local dr,dg,db = DifficultyColor(unit) return "|cff%02x%02x%02x%s|r",dr,dg,db,Level(unit)
- Health:
local s = Status(unit) if s then return s end return "%s",HP(unit)
- Power:
local max = MaxPower(unit) if max > 0 then return "%s",Power(unit) end
- I also changed the Default font to Fritz Quadrata TT and the Default size to 75%
Aura
Oh no! I skipped Faders! Well you could sue me I suppose, but better yet figure it out for yourself. It controls how your frame's opacity changes under certain conditions, such as in and out of combat, range and hostility. I don't particularly need it, so I skipped it. Now aura's, that is interesting. There seem to be a lot of options here, but once you go through everything you'll see it's not so bad. First off on the display tab you can set what you want to see in terms of buffs and debuffs. I think all tabs are pretty much self explanatory and you just need to go through them. Texts will place texts on debuffs to show stuff like time left.
Ok so Aura's were not all that interesting, but still!
- Since this is a player frame, and I'm assuming you're showing (de)buffs in a different matter I don't suppose you'll need this, just tick off Enable on top of the Aura page.
Other
Lastly there's the other tab. This holds some fancy features, that can or can not be important depending on your needs. The interesting ones are visual heal, which shows an overlay bar for incoming heals over your health, showing how much will be healed by the next spell, and Mana spark, which is an elegant way to show the 5 second rule for casting.
- Right that's about it. Tick off what you don't want from the Others tab and take a look at your frame as it is done. Note that the below screeny has turned Config mode off, so nothing special is showing.
The End?!
And that's how you create a layout. There are some (or you could say a lot of) finer points which I skipped over, simply because I feel they are easy to understand. Basically figure out what look you are going for, and for what frame(s) and create a layout accordingly. Texts will most likely take you the longest since you actually need to pay attention when customizing.
DogTag
Crash course
DogTags offer you a way to get very creative with the display of buffs, stacks, casts, auras, conditions, and pretty much everything else you can indicate with a line of text. The markup used by DogTags is friendlier and easier to read than LUA, and can satisfy most of your unitframe information needs. To start off with a simple example, this is what a simple "Target's Level" PB text would look like. Let's assume we placed this DogTag on the target unitframe.
[Level]
Easy, huh? What the syntax basically tells PB here is "show me the unit's level". The brackets define a 'sentence' that DogTag will process and replace with a result. If you were to remove them, you would just get the word "Level" tacked to your unitframe. With that in mind, you could also do this:
Level [Level]
And the result would be "Level 80". The first 'Level' word here is a simple string, while the second 'Level' is a tag of a unit's Characteristic. Brackets are around the second one only because we're not processing the first word "Level" yet. Now let's mix things up a bit.
[("Level " Level):DifficultyColor]
Now it starts getting a bit confusing because of all the brackets, but reading this tag isn't that ["difficult":Green] really. We've wrapped everything in square brackets because we're processing and coloring the whole tag. We also had to put double quotes around the first 'Level' to indicate it's a string and not a tag, and then grouped it with the Level tag using ferrets so we can color both. If you're asking yourself why this whole bracket and ferret madness, here's the explanation. If you were to do ["Level" Level:DifficultyColor] without the ferrets, the word Level would be white while only the actual level 1-80 would be colored by difficulty, because :DifficultyColor applies to only the previous Tag or Tag group, not the whole [mess].
As you may have already noticed, using just basic unit characteristics, colors and modifiers isn't that exciting. To really take advantage of DogTag's power you need to get a little creative (and crazy). DogTag's logic branching can be very useful in creating complex tags.
[if (Level(unit="target") - Level(unit="player") > 5) and (IsEnemy = "True") and ~HasAura("Soulstone Resurrection", unit="player") then
"omg run!":Upper:Red
end]
This translates to - if my target is 5 levels higher than me and it's hostile and I don't have my Soulstone on, then give me some friendly advice in big red letters.
While you can compose such conditionals inside the PB config window, the DogTag Help is a much better tool. It has a very comprehensive reference to all of the tags, modifiers and operators, a cool searchbox to sift through the whole mess and a Test Area where you can compose your tags and see the result while you type. To open DogTag Help just type /dogtag.
The DogTag lib is a massive beast and the best way to tame it is to just dive in. Take a look at the examples in the next section (or search the internets for dogtags other players made) and start tinkering with them, or borrow pieces and compose your own tag. If you need the syntax for a specific tag but you're not exactly sure what it's called or how it's used, just use DogTag's search box. Most of the time it'll point you in the right direction, but if it doesn't you can always ask around and someone should be able to shed some light.
Examples
Show Water Shield charges as colored dots
[Outline] [if NumAura("Water Shield") = 3 then
". . .":Cyan
elseif NumAura("Water Shield") = 2 then
". .":Yellow
elseif NumAura("Water Shield") = 1 then
".":Red
elseif NumAura("Water Shield") = 0 then
"!":Red
end]
Warn when the unit doesn't have any Intellect buff
[if (~HasAura("Dalaran Intellect") and ~HasAura("Dalaran Brilliance") and ~HasAura("Arcane Intellect") and ~HasAura("Arcane Brilliance")) then
"Missing Int!"
end]
Indicate types of debuffs on a boss. Includes Spell Hit, Spell Power, and TTW
[if IsEnemy then
(if (Classification(unit="target") = "Boss") or ((Classification(unit="target") = "Elite") and (Level(unit="target") > Level(unit="player"))) then
(if HasAura("Earth and Moon") then
"SP":Green
elseif HasAura("Curse of the Elements") then
"SP":Green
elseif HasAura("Ebon Plaguebringer") then
"SP":Green
else
"SP":Red
end) (if HasAura("Misery") then
" SH":Green
elseif HasAura("Faerie Fire") then
" SH":Yellow
else
" SH":Red
end) (if HasAura("Frost Fever") or HasAura("Thunderclap") or HasAura("Infected Wounds") then
" TtW":Green
else
" TtW":Red
end)
end)
end]
Shows dots for the three main priest buffs.
[Outline] [(if not InCombat then
(if HasAura("Prayer of Fortitude") or HasAura("Power Word: Fortitude") then
".":Green
end) (if HasAura("Prayer of Spirit") or HasAura("Divine Spirit") then
" .":Blue
end) (if HasAura("Shadow Protection") or HasAura("Prayer of Shadow Protection") then
" .":Color("8000FF")
end)
end)]
Hodir buff indicators
[(if HasAura("Toasty Fire") then
"Toasty Fire":Red
end) (if HasAura("Storm Power") then
"Storm Power":Yellow
end)]
Show the word "CURSE" on a cursed unit's frame if you are a mage, or "CURE " and C for curse, D for Disease and P for Poison if you are a shaman. You probably won't need this exact class combination tag, so edit to your heart's desire.
[Outline] [(if (Class("player") = "Mage") then
(if HasCurseDebuff then
"CURSE":Color("8000FF")
end)
elseif (Class("player") = "Shaman") then
(if (HasCurseDebuff or HasDiseaseDebuff or HasPoisonDebuff) then
"CURE":Color("FF0000") (if HasCurseDebuff then
" C":Color("8000FF")
end) (if HasDiseaseDebuff then
" D":Color("8C2600")
end) (if HasPoisonDebuff then
" P":Color("00FF00")
end)
end)
end)]
- More to come -
