Tuesday, March 31, 2009



LunarSphere is a mod that does a lot of things. At its heart, it is a sphere action bar mod, but unlike the other sphere mods I have tested, it is not class-specific, and has far more customizability and side options. LS's official user manual can be found here.
  • Up to 2 circular gauges for rep/health/energy/xp/5-second-rule/etc.
  • All buttons can have unique actions assigned to left, right, and middle-clicks
  • 10 main buttons that can be turned into menus
  • 12 extra buttons available per menu for a total of 120 buttons with 3 possible actions each
  • Main sphere can become minimap or an extra action button, with a text display
  • Built-in keybinding interface
  • Stance support per menu
  • All elements can be skinned with your own graphics
  • It can co-exist with other bar mods because the action buttons are not tied to the blizzard action bars
  • Speech tools for automated announcements on action or spell cast
  • Mount and vanity pet random selection, with controls for epics vs 60% and ground vs flying
  • Dynamic selection of "best" food/water/potion in inventory
  • Auto-repair, auto-sell greys, auto-reagent purchase
  • Simple tooltip skinning and positioning
  • And probably more.

To the left is a screenshot of my druid's LunarSphere, showing 5 of the 10 main buttons that are available. The buttons on either end of the chain have been made into menues.

The column of buttons reaching up the screen is a submenu. The submenus can be customized to show on your preference: at a click of the menu button, on mouseover, or always shown. Here, the submenu is closed:

The graphic in the center sphere is one that I made for myself, using artwork from a webcomic that I enjoy. You can download some of the graphics that I and others have made here (shameless self-plug!).

ALERT: When updating Lunarsphere, DO NOT overwrite your LunarSphereImports folder. If you use any sort of downloading/automatic install tool such as WoWMatrix or Curse's downloader, you will need to make sure you back up your imports folder before allowing it to update your LunarSphere, or you will lose all of the graphics and scripts you have imported previously.

Getting Started

When you first load LunarSphere, you will be prompted to either load a class template, a generic template, or start from scratch.

  • Class templates load up your known spells into pre-defined menus. If you learn a new spell after loading the template, you will need to add the spell manually, or reload the template.

  • Generic templates will not load your class spells, but will add mounts, food/water, potions, and trinkets.

  • Start from Scratch will begin with nothing bound to your buttons. It is my preferred method, since I like building it myself so that I know where everything is.

Starting from scratch, you can see that you have 10 main buttons surrounding a center sphere, which has two ring gauges (defaulted to your health and energy), and a blank center icon.

Ctrl-click on the main, central sphere to bring up the "mini menu." From here, you can open the main settings window, lock the buttons/sphere placement, and open the buttons for editing. When you first load LunarSphere, the editing mode will automatically be turned on.

Editing buttons:

The 10 buttons around the sphere are the main buttons, and they are the only buttons that can be made into menus. The submenus that each of these 10 main buttons can create contain up to 12 buttons each. You cannot nest menus within a menu.

When you click on a button in the edit mode, you will bring up this settings menu.
  • Stances: individual warrior or druid stances can be applied to a main menu button, and if you enable stance support on a main menu button, all of its submenu buttons will have stance settings as well. If stances are enabled, you can apply a different set of actions to each of the clicks for every individual stance or shapeshift form that you know.

  • Click Actions: these drop-down lists are where you decide what each button does when you click it. You can select a different action for each of the three main mouse buttons.

  • Keybinds: this is where you click to set a keybind for that particular click action. Instead of having to click on the button with that mouse key, you can press your specified keybind to activate that action. If you have stances turned on, then that keybind will copy over to that mouse click for each stance, so lay out your actions wisely.

  • Show Icon, Count, Cooldown: This applies to the graphic on the button. You can select which of your assigned click actions shows its graphic icon, count (# of potions for example), and cooldown on the button.

  • Set button padding: individual control over this button's distance from other buttons.

When you have edited a button, be sure to hit "Save" at the bottom, or the changes you made will not be saved.

Advanced Button Editing:

Menu Buttons:
These are the click options available for a MAIN MENU BUTTON. Fewer options are available for submenu buttons.

In order to turn one of your main buttons into a menu, select "Open Menu" for one of your click actions on that button. When you save this button, its submenu buttons will show up for you to edit.

This will also open up new options on the settings menu below the icon/stack/cooldown choices. These new settings determine the scale of the "child" submenu buttons, their padding, and the direction the menu angles away from the main menu button. You can also choose if the button or its submenu will show or hide on different conditions.

Other actions:
You can see in the list on the left that there are lots of other actions you can apply to a button. All of these actions can be applied to any submenu button as well, EXCEPT for those pertaining to the creation of menus.

Moving buttons:
You can drag and drop a button to any other available action button or submenu action button. What this does is copy the contents from one place to another. All keybinds go with the contents of the button.

Detaching buttons:
You may detach any of the 10 main buttons from being locked to the center sphere by checking this option in the button's settings. The button will then appear in the center of your screen, where you can then move it where-ever you would like. Locking and unlocking detached buttons is done separately from the main sphere and its attached buttons, and is available as an option from the ctrl-right-clicked mini-menu.

Deleting buttons:
You can delete the contents of an action button by holding the CTRL key while right-clicking on the button. This action is irreversible, but does not completely remove the button from future use: it just clears out its contents.

Menu Example:
Below are some of the options I have selected for my "professions" menu button:

- Left Click to open submenu.

- Right Click to use the submenu action that I used most recently: in this case, it was leatherworking. I have keybound this click-use to be "i" so that I can quickly redo something, such as fishing or disenchanting, without having to reopen the menu, or even clicking on the menu button.

- Middle Click (scrollwheel) to use a random epic flying mount.

Stance support is not selected, and the button shows all the information on my last-used submenu action. The menu angle I chose is 90 degrees (vertically up) and is offset by 100 degrees (the submenu is set 100 degrees off of the main menu button, which is just slightly off-kilter).

I have it open/close my menu on mouseover for ease, though I can still left-click it to open or close as well. Since this menu is to be used for just my professions, I chose to have its submenu hide when combat starts.

Button Tips and Tricks:

- Show Major Cooldowns
Have your main sphere buttons show the icon and cooldown of a spell that is one of your major cooldowns. This way, you can monitor the cooldown at a glance. Any other actions you have bound to that button should be ones without a cooldown, unless you have a different method for monitoring those hidden cooldowns.

- Self-Cast Bandaging
Make use of the Spell/Item/Macro (self-cast) with a bandage. It saves time from having to target yourself, if you have not already macroed it.

- Alter your macros to account for button clicks.
"/cast [button:2] Thorns; Mark of the Wild" will, for example, not fire Thorns if you put it in the left-click position of the editing menu, because LunarSphere will only run the macro if it is left-clicked (button:1) and, in the given macro, thorns is only fired with a right-click (button:2). You can, however, place this macro in both the left and right-click positions at the same time, and then the macro will operate normally.

- Use macros to expand what your buttons can do.
Use Ctrl/Shift/Alt modifiers to enhance the number of clicks you can keybind into a single button. You can also use #showtooltip Spellname on a macro to have it show a completely different cooldown from any of the actions that you have bound to that button. For example: Left-click Mark of the Wild, right-click Thorns, middle-click vanity pet, shift-click Gift of the Wild, and yet show the cooldown on Wild Growth, all in one button.

NOTE: the macros you use in Lunarsphere MUST have unique names in order for the mod to call them up correctly. If two macros have the same name, they will not work.

~for tips on creating macros, you can see my guide here.~

- Mounts
Separate your epic ground and epic flying mount summons so that you have control over which (ground or flying) you choose to summon. The alternative is to create a mount-summoning macro with the [flyable] modifier, but this will not randomly select among your mounts and must be told specifically which to summon.

- Combine similar spells or actions
Keep similar actions bound to the same button, so you can easily remember where to find them. Hearthstone, Portal to Moonglade, and the Black Temple Portal necklace can all be click actions together in one button, for example; or left-click to open enchanting menu, and right-click to disenchant.

- Last-Used Submenu Action
Make use of this action on your menu buttons, particularly with a professions menu. This is exceptionally handy for disenchanting, milling herbs, prospecting ore, and fishing. I also suggest keybinding this action.

- Create a Bag Menu
One click to open the menu, one to open all the bags, and one to just toggle the primary backpack that your looted stuff filters into. Add your other bags individually as submenu actions. You can tell one of the submenu bags to also toggle the keyring, if you prefer.

LunarSphere Settings:

This is where you can find the settings for the main sphere, gauges, tooltips, speech, skin, and more.

The first tab is the Sphere settings panel. You can see the other option tabs listed along the far left.

You can select what text is shown on your main sphere. If you have a different click-action bound to your sphere, you can choose to have it report a completely different cooldown or count in this window. There are other options you could select for your text, or you can choose to have it show no text at all.

The overall scaling and spacing options here will apply to all of the buttons that have not been individually set in their own edit button settings.

You could also choose to completely hide the center sphere, which will hide its gauges as well.

Gauge Settings:

This tab controls the two rings circling the Sphere. There is an outer gauge and an inner gauge.
  • Gauge event: this is what that gauge is monitoring. There are many options in the drop-down menu.

  • Color: the color of the gauge.

  • Marks: this is the number of hash marks that circle the length of the gauge, helping you to visually see relative percentages. 5 marks will break it up into segments of 20%, and 10 marks will break it up into segments of 10%.

  • Angle Offset: this will rotate the gauge.

  • Reverse: the gauge will now fill clockwise. Unchecked, it will fill counter-clockwise.

  • Show gauge: you can choose to turn off one or both gauges. Hiding a gauge will show more of your center sphere graphic.

Button Settings:

Here you can customize all of the buttons.

  • Button Status Colors: Check the box if you wish to customize the colors that will mark your buttons when your current target is out of range, out of mana, or both.

  • Global Scale: this is the size of all of the main buttons and submenu buttons, and will affect all of the buttons that you have not individually scaled in their own button settings.

  • Cooldown Options: Select whether or not you want the GCD (global cooldown) timer to show on your buttons, to make them shine when they come off of cooldown, and if they will show the cooldown count in text format. You can change the colors of the cooldown tint and text colors, and select from a list of special cooldown effects.

  • Display Options: These are miscellaneous options regarding keybinds, DrDamage support (an outside mod), pet buttons, and how the mod handles your drag-and-drop of buttons from one place to another.

Reagent Settings:

In the Reagent tab, you can choose to auto-restock some of your reagents. Drag a stack of reagents from your inventory to add them to the list, and type out the number you wish to keep on you.

Now, whenever you visit a reagent vendor with that item, LunarSphere will automatically purchase the number of reagents you need to refill your current stack.

It will not go over this stack limit. If your reagents are purchased in stacks rather than individually, then it will only purchase the stacks that will get it as close as possible to your limit without going over that limit (such as symbols for paladins).

I highly suggest that you confirm purchases over 10g (once this feature has been re-enabled). I once copied my settings to an alt and about died when it auto-purchased 20g worth of reagents I didn't need.

Inventory Settings:

Hey, auto-repair!

Auto-selling gray items will occur the moment you talk to any vendor. Printouts of profit reports, if selected, will go in your chat window. There is currently no way to specify particular gray items that you don't want it to sell, aside from "non-equip," "weapons," and "armor," so if you want it to sell old plate boots but not your fancy Cloth Hat, don't select this feature.

Auto-repair will repair anytime you chat with a repair vendor, and log the results for your perusal. As with auto-selling junk, the printout goes to your chat log. You can choose to make it use guild repair when it has been made available by your guild leader. If you don't check the guild repair box, it will use your own funds every time.

There's a nice little option to bypass all vendor gossip text and jump straight to the buy/sell/repair window, eliminating the extra clicking.

Lastly, the Auction House options speed up your mail collection by automatically collecting all AH mail with money and/or items attached, and can also show your total bids/auctions price.

Speech Settings:

This window is where Resurrection Macros go wild.

Speeches are things that will automatically be said in the /say channel whenever you perform a specific chosen action. These are used primarily for humor and fun, a way to spice up the standard "Ressing %T" macros.

A Script is a list of different speeches you'd like to have available for a particular action. You can import or export your scripts. Making the script global will make that script available to all of your characters, rather than just your current character.

To add speeches, type one in to the "current speech" box and hit Add. To edit a speech, select it from the list, make your alterations, and hit Save.

%T will insert the name of your current target into the macro. %F will insert the name of your focus target, and %P will insert the name of your non-companion pet.

To bind your script to an action, select the Settings sub-tab.

You can drag and drop a spell or macro into the box next to the Add button, and then hit Add. This will add the new spell or macro to the list of things that will automatically fire off one of the speeches from the script.

You can change the chat channel to be a different one from the default /say channel. As a general warning, be gentle with your channel selection, as scripts can get spammy if mishandled.

The odds affects how often a speech might be selected when the action occurs, vs not happening at all.

If you choose to pick speeches in order, it will go down the list from one speech to the next each time you perform the chosen action. If not, it will select randomly.

The speeches in my revive/rebirth script can be found here.

Skins Settings:

The Skins panel controls the visual elements of LunarSphere. You can reskin the sphere graphic, button borders, gauge shading, and the main border.

You can select the style you like most from the designs that come packaged with LunarSphere, or you can import your own.

Imported art must be in .blp or .tga format, with pixel dimensions in multiples of 16, which is standard for all WoW imported art. 16, 32, 64, 128, 256, 512, etc must be the pixel heights or widths for any given graphic. For sake of ease, I recommend 64x64 TGA with a transparent background around the circular graphic. A detailed guide on creating your own sphere graphics can be found here. Alternatively, you could save your graphic as a .png and use a converter tool to change it to a .blp.

If you would prefer not dabbling in graphic editing yourself, there are several people who may be available to turn an image you have found into a sphere graphic that you can import into LunarSphere. To do so, I recommend that you put a post on the official LunarSphere forums asking for an icon to be made, with a link to your graphic.

To import art, you need to drop your (appropriately sized) .tga or .blp graphics into the LunarSphereImports folder in your addons folder (before you have started up WoW). Then, once the game is loaded and you have brought up this panel in settings, you click on the Import Art button, which will bring up this window.

Type in the EXACT NAMES of the graphic files in the folder, excluding the .tga and .blp extensions, each filename separated by a comma as shown. Some large collections you can download from LunarSphere's website include lists that you can copy-paste (ctrl c, ctrl v) to quickly import a large number of files without having to individually type them out. They will be uploaded to the selected category once you click "Import," and then be available for selection in the main skin settings panel.

Random Graphic Shuffle:

If you check the "Use random sphere texture," it will change your sphere texture from among those you have imported every time you log into your character. If you'd like to make this graphic change a click-action, you can use this script:

/script Lunar.Sphere:SetSphereTexture(math.random(1, (Lunar.includedSpheres + LUNAR_EXTRA_SPHERE_ICON_COUNT + Lunar.API:GetArtCount("sphere"))));

Turn the above script into a macro, and then insert the macro as one of your click actions.

LunarSphere Graphics downloads:

Tooltip Settings:

You can just click through the 4 information/size options to see the difference in-game. These are fairly straightforward, and you can see the changes to the tooltip size and configuration by selecting each at a time and mousing over one of your action buttons to test the changes. A beginner may wish to have full text showing for each click; as you grow more comfortable with your layout, you may choose to slim down the information showing so that the tooltips don't take up so much screen space.

You can also select a different location for your LunarSphere tooltips, and also change the location of the default tooltips. To change the game's default tooltip location, check the box next to "Set default GameTooltip anchor" and then press "Show." You will see a little moveable box appear with corners/sides you can select: this is the "anchor" for the tooltip, rather than the tooltip itself. The tooltip will rest on the side or corner of this anchor box that you have selected.

Personally, I prefer them both to be locked to the far right side of my screen, far enough up that they won't interfere with threat meters or standard backpack when opened.

** If you have any specific questions or bug reports, I recommend asking on the LunarAddons forums, where a team of LS addicts and our catlord Moongaze reside! **


Niniel said...

Sweet! I'm trying this when I get home! Very nice posts also, going to have to read then through when I get home from work.

Looks like we have a lot in common when it comes to being a raiding blogging restodruid with interest in macros and addons ;)

Kae said...

Wow, I've been found :D Grats on being the first to comment on my blog, and thanks for checking it out!

I still have a lot of work to do on this post, screenshots I need to sift through and sections to write. Moongaze, Lunarsphere's developer, is checking it out as I go to make sure I get everything accurate :)

Niniel said...

You're welcome, I made a comment on your very first post as well.

Honestly, I'm stunned by the quality of your posts. Wish I could write as interesting and informative as you do! Keep it up! /praise

Animagis said...

Very impressive startup here Kae.

Amazingly helpful and detailed posts.

Dierna said...

Pretty.. oh so pretty! I can't wait to do this when I get home tonight. I have been trying to mod my UI into something pretty and this looks to be the answer!

everpc said...

I've been playing with this and am impressed--but are you aware of any way to manually set the icon of one of the menus buttons? I can't seem to change them once they're set...

Kae said...


Every time I've made a menu, I've had its graphic be one of the other key-clicks I've tied to the menu button (ie last-used submenu action, or some macro or ability I want to see the cooldown of). The icon will be whatever graphic that you tell it to be, from one of the 3 click actions of that button. If you'd like to choose a completely different icon, you can make a macro using that icon and have it be the graphic that shows on your menu button.

There's a thread on the addon's forums that addresses this topic in more detail:


Alyiena said...

I have a quick question. Is there anyway to make all the buttons disappear and only appear when you click on the say arcane button or maybe the frost button? I may have missed it and really suck at new addons lol.

Kae said...

Alyiena, do you mean closing/opening submenus, or do you mean having all the main menu buttons hide too?

Alyiena said...

when i pull it up and turn it on
all the circles are still up and i cant hide em like i do with necrosis.

Kae said...

If you mean the empty circles, they will disappear when you turn off the edit mode.

If you mean the sub-menus (assuming you set it up to have all arcane spells under one menu, and frost in another), then the setting is in the menu button's Edit Button settings. At the bottom of the panel is a drop-down menu that you can use to select how you want the menu to show; you may want to set it to "Click to open, click to close."

You can see a screenshot of that in the guide, in the "Advanced Button Editing" section, in my Menu example.

Let me know if that works!

Anonymous said...

I got a huge problem!On one of my characters i have hidden the sphere,and then close the menu!Now i only got the 10 other buttons!How can i get back the central sphere?Plz help me

Kae said...

Hmm... try this:

Type /lunarsphere settings

On the first page that comes up, at the bottom of the window, is an option to "hide center sphere." Uncheck this, and it should come back.

Anonymous said...

Thank you so much,it works!^^Very nice of you!I could give you a hug!^^I wish you a good time,and thank you again!see you

GJ Davies said...

I'm just wondering, as someone who likes a minimal interface and will probably only use this for non-combat menus, is it possible to hide the entire lunar sphere addon and have it pop into view on mouse-over or even keystroke?

Importantous said...

Thanks for taking the time to put this together.

I have a "speech" issue I'm hoping you might be able to help me with.

I created a new entry, Ritual of Refreshment, entered five selections, set the action assignment to Spell/Item (Conjure Refreshment) and chose Say.

Nada, zip, zero, bupkiss. Have deleted the action item, readded it. Chose different chat channels, got squat.

I'd really like to have some of my old BC lines I used in Cryolysis3 back. Any suggestions?

Again, thanks for your time.

Kae said...

Gramlin, I don't think the developer included this functionality. You can poke him about the possibility on the addon's own forums, however.

Importantous, I am not sure what the problem would be. Only things off the top of my head may be that the odds aren't set to 100, the script not being saved (top of the tab), or the action assignment needing to be actually added to the pane after the spell was selected (by hitting the add button beside the spell selection). Hopefully one of these solves your problem?

Anonymous said...

Hi, i've just set up LunarSphere and it's great apart from one problem - even thought i have told it to show my combo points it won't - the text remains on zero.. i find i spend so much time watching combo points on the target portrait that i don't see what's going on in the fight (and die a lot!) which is why i wanted LunarSphere in the first place - please help :)

Kae said...

Regarding bugs or errors, you'd probably have better luck asking the mod's developer on the lunaraddons.com foums:


Though my sphere's main text event of a cooldown monitor (for warstomp) seems to be working fine at the moment.

Max said...

Thanks for the guide!

I have a few questions though:

For my Rogue, is it possible to have the spheres switch out when I am in stealth?

Same goes for my Druid when I switch forms?

Kae said...

Just have to enable "stance support" in the button settings (top of the window when you click on a button to edit), iirc. Now, druids don't really have an official "stealth" stance, so you may have to just go to macros with a [stealth] modifier for your druid (which is what I do).

Anonymous said...

Hey how do I hide wow default action bar? THanks!

Kae said...

In the main LS settings window, go to the "other" tab, and you'll find a list of items you can check off to hide, including the action bars.

Bel said...

I have recently gotten this add-on and your guide helped TREMENDOUSLY with setting it up how I like. So first off, TY! :-D Ok - now to my question. While I like the scrolling battle text, I'd like to be able to change the font and size of it? Thx!

Bel said...

Ok - so lame. soz. I had tried a UI pkg and that pkg and re-enabled WoW's defaults. Lame. Soz, but thanks anyway for the guide!

lol :-S

Bel said...

Ok - Well, nvm. But thx anyway the response I know you were going to leave and for the guide. I had tried a UI pkg which had changed my WoW settings so . . . Soz! But really, great guide. Much appreciated! :-D

Anonymous said...

You might want to consider editing your section about "Detaching Buttons". Following your directions I managed to delete the button I just detached because I "ctrl+right clicked" it to get the menu to move it. "Locking and unlocking detached buttons is done separately from the main sphere and its attached buttons, and is available as an option from the sphere's ctrl-left-clicked mini-menu." I added "sphere's" and "left" (hopefully in bold) to help clear things up for idiots like me. 8>) Thanks!


Kae said...

Hmmm I'll look at it tonight. I remember that the option is not under the actual sphere main menu, but in the individual button-editing menu as a check-box for that particular button.

I think the correction would be, "is available as an option from the button's editing mini-menu." I'll get a screenshot for it when I'm home from work.

Thanks for pointing out the change!

Unknown said...

How do you get the buttons to change for different specs...i.e. I have a pally ret spec but when I change to prot spec, the buttons stay the same....please help

Grant said...

I cant seem to figure out how to get the buttons to change when switching specs. I have a ret/prot pally. When switching from ret to prot the buttons stay the same. It will not let me choose stances. Please help

Kae said...

I can't look into it from my office, so if you need a quicker solution to the point that you ask twice (hehe), I suggest asking on the Lunarsphere forums themselves where the developer and other LS users might be able to answer more quickly ;)