README file for
RandomSayings:  An Addon for Warhammer Online / Return of Reckoning

Description:
============
Have you ever wanted to give your character a "pool" of quotations.... that you could randomly 
summon from... into local chat with a button press?

Maybe you'd like to be able to hit a button and shout one of five different battle-cries?  Or 
maybe(like I once did in "City of Heroes") you'd like to be able to press a button and randomly 
say one of 50 "Yo momma" jokes!

What if you EVEN wanted to have MULTIPLE buttons you could press, with each one "tied to" a 
DIFFERENT group of phrases?

If so, this is the Addon for you!
Install it. Configure it with your phrases list. Create a Macro for it.  Drag the Macro icon to 
your hotbar...and go!


Upgrade Instructions:
====================
If you are upgrading from the previous version, 1.0, please note:
The "sayings" file structure HAS CHANGED.  Version 2.0 of the AddOn will NOT be able to properly 
read that file!  Therefore, I recommend:

1) Finding any and all character-specific saved versions of your custom "sayings" file.  Do this 
by: 
    a) Going to your <Warhammer Installation Directory>\user\settings\Martyrs Square\ folder.
    b) Searching that entire folder for all paths containing a "RandomSayings" folder.
    c) Search each found "RandomSayings" folder for a file named "SavedVariables.lua"

2) Copying that SavedVariables.lua file off somewhere so that you can go copy your sayings from it 
later on.

3) DELETE that/those SavedVariables.lua files from that original profile folder location.

4) Proceed with installation instructions.  When you reach the point where you want to customize 
your new default phrases (step #3 in the "Configuration Instructions"), you can manually import 
and substitute your "old phrases"...one-at-a-time or in clusters... over into the new file(s). 




Installation Instructions:
==========================
1) As with most Warhammer Addons, you simply have to extract the .zip package that this file came 
in into the game's "Addons" directory.  So, your extraction path would be something similar to:  
     <Warhammer Installation Directory>/Interface/AddOns
	 
2)  When you've finished, you should find that the "AddOns" directory now contains a 
"RandomSayings" sub-directory.

3) Please proceed to the Configuration Instructions below, as you'll want to change the "default 
sayings" that I've pre-packaged with the AddOn.


Configuration Instructions:
===========================
1) Open up the DefaultSettings.lua file with a text editor.

2) If you look at this file, it contains three groups of phrases, each contained within a set  of 
parentheses { }... and each phrase itself ends with a comma. 

(These "default sayings" are ones that I set up for my Sorceress, "Karen Killjoy".)  

First, you need to decide how many "groups" of sayings do you want?  In other words, how many 
buttons/macros do you want to set up?

If your answer is "only one", then you'll probably just want to edit the FIRST group here. (Don't 
worry, even if you leave the other two groups alone, they aren't going to interfere with anything. 
None of those phrases will ever be triggered, if you never purposely build a macro -- a later step 
here -- to call them.)


3)  So, if you want to use one, two, or three macros in-game, you'll edit either one, two, or 
three groups of phrases here!  (You can use as few or as many phrases as you want!)

Each phrase-line must start with a double-quote ("), and end with a double-quote, followed by a 
comma (",).

Please be warned that you should NOT use any double-quotation marks WITHIN each "saying" / line, 
as this will "break" that line of text.  (The computer will "think" that the second quotation mark 
that it finds in that line of text marks the end of it.)

Note that it is very important to leave the rest of the file's structure....the two lines that 
mention "DefaultSettings", the groupings, and the set of parentheses that surround your "sayings 
lines".... intact.

4) What if you want to add a 4th group, a 5th group, or even more?  Well, just follow the pattern 
in the file. Each "group" of phrases must begin with a set of brackets containing the NEXT 
sequential number (example:  [4] ), followed by an equals-sign, followed by a set of curly 
brackets that will contain your phrases.  And finally, this should end with a comma (just so you 
don't have to worry about adding a comma later, if you decide to add even MORE groups).

5) Save your file.

6) Start your game.  It should prompt you that it has found a new AddOn and ask if you want to 
enable it. 

7) OK, now we have to set up one or more Macros.  A macro is a special button that you're going to 
drag onto one of your hotbars. When you press it, it runs a special script. (In this case, it 
would ask the RandomSayings Mod to find a particular group of phrases and then randomly "say" 
one.)  To build a macro for RandomSayings:

	a) Go to the central game menu, choose "Macros".  

	b) A small window should pop up.  The window shows quite a few icons.  Underneath that is a 
field for "Macro Name" and a larger field beneath that for "Macro Text".   Select/click on one of 
the "empty" icon image boxes in that probably say "No icon set".  Make sure that the "Macro Name" 
and "Macro Text" fields both appear blank when you do this.  

	c) For "Macro Name", type in "RandomSayings1".  (Remember how each set of sayings you defined 
in the DefaultSettings.lua file had a number?  We're adding the number of the group you want to 
use with this macro...at the end of the phrase "RandomSayings" here, just for reference.)

	d) For "Macro Text" type or paste in "/script RandomSayings.Speak(1)".  
	
	(Notice the "1" in the parentheses.  The number you put in there DETERMINES WHICH GROUP OF 
SAYINGS the macro-button will call!  So, if you're building a macro that you want to call your 
"group 3" of sayings, you'd put a "3" in there instead!)

	e) To the left of the "Macro Name" field is a box that represents what image is assigned to 
this new macro. Click on that box.  A pop-up form should appear that will show you the available 
images to choose from.  Select one.  

	f) Then click the "Save" button.

	g) Your macro is now saved.  If you look at the collection of icons in the top portion of this 
"Macros" form, the one that you clicked on in step "b" now should show the Macro Image that you 
selected in step "e".  Click on that image and.... DRAG it onto one of your hotbars.  

6) You're all set!  Click on that button and you should immediately say one of your "Random 
Sayings"... from group #1 in the DefaultSettings.lua file...locally!

Repeat this procedure to build a macro for each "group" of sayings that you want to be able to 
randomly say!  (Example: Macro named RandomSayings2 rigged to do "/script RandomSayings.Speak(2)".)



How to Update Your Phrases Later On:
====================================
The Addon is rigged to save your custom settings out to your character's profile, once the UI 
reloads after you enable the AddOn.   After that, whenever you launch the game, it will look at 
that character-specific copy of the "Sayings List" instead of the DefaultSettings.lua file that 
you modified in the "Configuration Instructions" above. 

So, if you want to make any changes to your sayings in the future, you'll need to go edit that 
character-specific copy. It will be located in this path:

     <Warhammer Installation Directory>\user\settings\Martyrs Square\<character 
name>\<profilename>\RandomSayings\SavedVariables.lua

Simply:
	a) Make sure your game is shut down first. 
	b) Edit and save this file (in the same manner that you edited and saved the 
DefaultSettings.lua file).   

[NOTE:  Any comments that you may have seen or made in the original DefaultSettings.lua file were 
automatically removed by the game when it created this file. But you can always add them back here 
manually.  Just be sure not to accidentally "break" the file's overall structure! ]


TROUBLESHOOTING
===============
Here are some tips to keep in-mind when trying to figure out what may have gone wrong with the mod:

1) Keep in mind, if the mod LOADED successfully, it will state this in your chat window when you 
first log in.
   "[RandomSayings] version X.Y has loaded"...

2) At the end of that sentence it will say how many "sayings groups" it loaded.  This can be 
useful info for debugging. If this number is incorrect (if it doesn't match the number of saying 
groups you made), the mod may be reading in an older saved sayings file, perhaps from a Profile 
folder you're not aware of.

3) Also, the last half of that sentence indicates WHERE the "sayings groups" were loaded from. If 
it says the settings groups were "pre-saved", that means they were taken from ones that were saved 
to disk the last time you logged on:

     <Warhammer Installation Directory>\user\settings\Martyrs Square\<character 
name>\<profilename>\RandomSayings\SavedVariables.lua

If it says the settings were "Default", that means the mod didn't SEE any previously-saved 
settings, so it took the original ones from the Mod installation folder.

4) Turn on debug logging and reload your UI if you seem to be having issues. RandomSayings will 
write an initial "Initializing Settings" message to this log as a sort of "debug" / "hello, I'm 
here" message.

5) Any time you press one of your macro keys for RandomSayings (assuming that they are built 
correctly) you should see a sort of debug message about it.  It will say something like "User 
selected set #1, which has 19 options in it".)

THANKS !!
ENJOY !!