
/\_*_/\_*_/\_*_/\ -- Segui ReadMe -- /\_*_/\_*_/\_*_/\

Addon type: Interface
Libraries used:
	DelaysManager2
	EventsManager1
	SimpleSlash1



-- == -- == -- Description of Functionality -- == -- == --

This addon is designed to facilitate and streamline a multitude of automatic chat messages, 
selected either randomly or non-randomly, to be sent in correspondence to any spell, ability,
or chat/combat message, and all with a convenient and intuitive user interface. The interface
is divided into sections:

Category: This is a superset of Actions, divided into logical groups. Select a Category on the
	configuration frame for more information about it.
Action: This is the spell, ability, etcetera. This contains Roll Ranges. When an Action is triggered,
	a random 1 - 1000 roll takes place, and all Roll Ranges belonging to the Action which encompass
	the random number are triggered.
Roll Range: This is the low-to-high range of numbers that give the optional element of randomness
	to configurable speech. If no randomness is desired, a Roll Range set to 1 - 1000 will always trigger.
	This also specifies the set of times (start, stop, or interrupt of the cast or channel) at which the
	Entries are allowed to be sent. If a roll lands in a Roll Range, all Entries therein are triggered in
	sequential order.
Entry: This is the actual message itself, and any options pertinent to that message, such as
	the channel to which it will be sent, the language in which it will be sent, the number of seconds
	to delay before sending it, and other options. When an Entry is triggered, the configured text
	is actually sent.

Essentially, when an Action is detected, a single 1 - 1000 roll is performed. Then, each Roll Range
within that Action is checked to see whether that roll falls between the minimum and maximum
for the range. If so, every Entry in the Roll Range is triggered, in sequential numerical order. This
is a powerful system, as Roll Ranges can overlap if desired.

Type "/segui" for slash commands. Typing "/segui config" will toggle the configuration frame,
wherein the majority of options are documented and explained.

Included in the various Categories is a combat event parser which is very powerful. However,
it is also somewhat complex, as a result of this power. Its formats are described in the Category
dropdown button's tooltip on the configuration frame in-game, but here are some examples of
the formats that it accepts:

<1 PARTY_KILL><3 playername>
	Assuming "playername" is replaced with your character's name, this Action configuration will
	trigger when you kill something. It works by first matching the "PARTY_KILL" combat event (the
	first argument) which propagates whenever someone in your raid group (including you) kills
	something. When that is matched, it moves on to checking the name of the source of the kill
	(the third argument) to determine whether that matches your own name. If it does, obviously
	this indicates that you just killed something, and Segui can send messages as a response to
	this occurence.
<1 PARTY_KILL><3 playername><6 enemyname>
	This is an extended version of the above, except this will only trigger when you kill a unit
	named "enemyname". This works in a similar fashion to the above, checking the name
	of the destination of the kill (the sixth argument) to determine whether it matches the
	name you input.
<1 PARTY_KILL><3 playername><7 0x4FF>
	This is another modified version, but this one checks to determine whether the unit you
	killed is a player. The fourth and seventh arguments (for the source and destination) in
	any combat event are "unit flags", which contain a great amount of information about
	the unit in question. These flags are described on http://www.wowwiki.com/UnitFlag.
	The particular flag used here, for argument number seven, means "a player of any
	affiliation and any reaction".
<1 _DAMAGE><4 0x411>
	This format ignores the event prefix and looks only at the suffix ("_DAMAGE"). In doing so,
	it can trigger from damage that you deal from any source, be it melee or ranged or spell.
	Also, unlike the other examples which match you as the source of the event by checking
	your name, this one uses the unit flag to determine whether you were the source. The
	flag used here means "a friendly player who belongs to me". Mind Controlled players
	are technically classified as pets, so this unit flag corresponds solely to you.

For extensive information about combat events, including their prefixes and suffixes and unit
flags, read http://www.wowwiki.com/COMBAT_LOG_EVENT_Details.

Note: Due to current technical limitations, pet abilities cannot have configurations in Segui.



-- == -- == -- History of Changes -- == -- == --

1.5.1 (Jul 30, 2008):
	- Updated tooltip text for Action, Roll Range, and Entry dropdowns to try to more clearly
		explain the purpose of each.
	
	- Fixed an error that occurred as a result of the "You resurrect" miscellaneous event.


1.5.0 (Jul 30, 2008):
	- Added new option to the Action config box, "Always try to activate a Roll Range". This
		option, if enabled, will cause at least one Roll Range to be activated every time the
		Action is triggered, if at least one is not on cooldown. If a normal roll fails to trigger
		any Roll Ranges, this option forces a second loop through the available Roll Ranges
		to determine whether there is one which can be triggered in lieu.
	
	- The messages of delayed Entries are now prepared when the Entry triggers, instead
		of after the delay. This fixes a lot of potential issues with different data being available
		after the delay as opposed to before it.
	
	- Fixed a bug where global hotkey Actions could not be activated by calling Segui(#).
	
	- Clarified tooltip text on the Category dropdown button when the Combat Events
		Category is selected.
	
	- Clarified tooltip text on the Message editbox.
	
	- Rewrote the way the configuration panel handles abilities with multiple ranks, to
		be more efficient.
	
	- Fixed a bug where the settings of the Action config box would persist instead of
		resetting when switching from viewing an Action with Roll Ranges configured to
		an Action without any.


1.4.5 (Jun 29, 2008):
	- Fixed an error that occurred on-load when using Misc. Event type Actions.


1.4.4 (May 30, 2008):
	- Fixed an error that occurred when attempting to create a new custom Action.
	
	- Fixed an error that occurred when attempting to rename a custom Action.
	
	- Fixed an error that occurred when clicking the Delete button while a custom Action
		was selected.


1.4.3 (May 16, 2008):
	- Fixed a bug where having only one rank of the final spell in one tab of the spellbook
		would cause the first spell in the next tab of the spellbook to not appear in the
		Action dropdown menu.


1.4.2 (May 15, 2008):
	- Fixed a bug wherein only one Entry could be created per Roll Range.


1.4.1 (May 13, 2008):
	- Fixed a misnamed variable that caused an error when attempting to substitute in a unit's
		name in an Entry's message text.


1.4.0 (May 6, 2008):
	- Removed "Send At Start" checkbox from Entry config and replaced it with a "Trigger Times"
		dropdown in Roll Range config. The new dropdown allows you to select any combination
		of "Cast Start", "Cast Stop", "Channel Start", "Channel Stop", or "Interrupt" as times to
		allow the Roll Range to be triggered.
	
	- Fixed an issue where channeled spells were not being detected properly. Specifically,
		Segui was only watching the ignition for the channel instead of the channel itself.
	
	- The configuration window no longer automatically deletes Entries with no message,
		Roll Ranges with no Entries, or Actions with no Roll Ranges.
	
	- Restructured configuration window code into multiple files to be clearer and more efficient.
	
	- Miscellaneous code style updates.


1.3.2 (Apr 25, 2008):
	- Fixed an error that popped up when trying to create a new Roll Range in the Misc. Events
		Category.


1.3.1 (Apr 8, 2008):
	- Fixed a load order issue where the addon would start listening for ability usage events
		before the config was loaded, potentially allowing the code to reference the config upvalues
		before they were set properly.
	
	- Added an error handler to the speech memory update function which will report issues
		that occur therein, and prevent the addon from fully loading if a problem does occur.


1.3.0 (Apr 6, 2008):
	- Now includes support for all ranks of all abilities in the spellbook. To create a configuration
		which will trigger upon use of any rank of a given ability, simply select the unsuffixed name
		at the top of the ranks dropdown list.
	
	- Fixed a bug where if a Category had a number of Actions that was greater than 30 but
		still divisible by 30 (such as 60, 90, etcetera), the final 30 Actions would not be shown
		in the dropdown list.


1.2.1 (Mar 29, 2008):
	- Fixed an issue with combat event parsing where the PARTY_KILL, UNIT_DIED, and
		UNIT_DESTROYED events were being parsed as though they had 3 prefix arguments,
		when in fact they have 0.
	
	- Rewrote the combat event parsing code to first determine whether each event is even
		relevant to the user's configuration before building the arguments array, thus saving
		a lot of resources when considering how frequently combat events trigger.


1.2.0 (Mar 25, 2008):
	- Added a "Rename" button to the Action config box, for renaming user-created Actions.
	
	- Rewrote the combat event parsing to work with 2.4. The new system is much more powerful,
		but due to the nature of the change and the way the old system worked, the old Actions
		cannot be converted programmatically. Instead, each old Action can now be found under
		the new "Combat Events" Category, with the tag "<deprecated>" and its old combat event
		at the start of the text. Select these Actions and click the "Rename" button in the Action config
		box to edit them into a format compliant with the new system.
	
	- Changed the format of argument checks in chat message Actions. They were previously formatted
		as "<args:#:expected;#:expected>", but are now formatted as "<# expected><# expected>".
		These will need to be updated manually.


1.1.1 (Feb 25, 2008):
	- Fixed a bug wherein the "Your health goes below 20%" event was watching mana instead of
		health, and the "Your mana goes below 20%" event wasn't working at all.
	
	- Miscellaneous updates to code style.


1.1.0 (Feb 10, 2008):
	- Added extensive message parsing support in three new Categories: "Messages: Chat", "Messages:
		Combat", and "Messages: Other". These Categories will allow you to parse any chat, combat,
		or miscellaneous messages in a given sub-Category, the likes of which are divided based on Blizzard's
		CHAT_MSG_* events. This is a very powerful system. It can be used to parse and respond to boss
		emotes, attacks on you, spells cast by group members, loot received, and essentially anything else
		that appears in the chat or combat logs. As such, the Combat Events, Self Buffs, and Self Debuffs
		Categories has been removed, since most of their Actions can be replicated with this new system
		and will be converted. The "You enter combat" and "You leave combat" Actions, the only ones which
		cannot be replicated, have been relocated from Combat Events to Misc. Events.
	
	- Added new message type, "Raid or Party", which will send the text to Raid if you're in one,
		or Party if you're not.


1.0.3 (Jan 21, 2008):
	- Removed some debug prints.


1.0.2 (Jan 21, 2008):
	- The repeat delay algorithm now uses time() instead of GetTime(), since the latter actually
		returns system uptime, not current time.


1.0.1 (Jan 19, 2008):
	- Fixed a bug where Entries with an activation delay were not being delayed.


1.0.0 (Jan 16, 2008):
	- Initial release.



-- == -- == -- Developer Notes -- == -- == --

Data storage format:

Segui_SpeechMemory = { -- Per-character settings
	version = integer;
	[string] = { -- simplified name of Category (messageEvents, combatEvents, miscEvents, generalActions)
		[string] = { -- name of Action
			repeatDelay = integer or nil;
			timeLastSent = float or nil;
			alwaysTrySend = true or nil; -- If true and no Roll Ranges trigger as a result of the normal roll, a random Roll Range will trigger.
			rollRanges = {
				[n] = { -- Index in the array of Roll Ranges.
					minRoll = integer;
					maxRoll = integer;
					repeatDelay = integer or nil;
					timeLastSent = float or nil;
					triggerBits = integer or nil; -- from TRIGGER_BITS_BY_EVENT at the top of Segui_Speech.lua
					entries = {
						[n] = { -- Index in the array of Entries.
							message = string;
							messageType = integer; -- from MESSAGE_TYPE_LIST at the top of Segui_Speech.lua
							activationDelay = integer or nil; -- time, in seconds, to delay before sending this Entry after it has been triggered
							language = integer or nil; -- language index, as would be used in GetLanguageByIndex(); nil if it would be 1
							channelOrTarget = string or nil; -- name of custom chat channel or whisper/emote target
							repeatDelay = integer or nil;
							timeLastSent = integer or nil;
						};
					};
					-- If there's only one Entry, it's stored directly.
					entries = {
						-- The first Entry from what would've been the Entries array (rollRange.entries[1]).
					};
				};
			};
		};
	};
};

Segui_GlobalSpeechMemory = { -- Global settings
	version = integer;
	hotkeys = { -- simplified name of Category
		-- Identical format to Segui_SpeechMemory
	};
};



-- == -- == -- License and Contact Information -- == -- == --

This addon may be used or modified in any way which exhibits full compliance with the
World of Warcraft Terms of Service (TOS) and End User License Agreement (EULA), as well
as the rules of the website from which the files were downloaded. You may redistribute this
addon, but only if it is completely unchanged from the way it was found in the zip file. If you
wish to distribute a modified version, you must first obtain permission directly from me.

If you found a bug in this addon, want to provide feedback, want to help translate it, or even
just want to ask a question, please contact me using one of these methods:

Email address: saeris.sanoora@gmail.com
ICQ number: 119161819
AIM screenname: SaerisSanoora
Penny Arcade forums name: Saeris

If you use any other method, it might take me significantly longer to see your message and reply.

If you wish to support my efforts, you can donate via PayPal by following this link:
http://tinyurl.com/yo4asg



-- == -- == -- Addon Type System -- == -- == --

This addon uses a system in which there are three distinct types:
	Interface - These addons actually provide functionality to the user. They may be entirely self-
		contained, or they may make use of Library-type and Plugin-type. They are always top-level,
		meaning that they appear in the addons configuration menu at the character selection screen.
	
	Library - These addons exist simply to provide functionality to other addons of any type, and
		as their type name suggests, they may be shared between multiple other addons as a single,
		efficient source of the aforementioned functionality. A Library type addon may be embedded
		(included in a subdirectory folder with the client addon, usually "\libraries\" or something similar)
		or non-embedded (existing as a top-level addon, such that it appears in the addons configuration
		menu at the character selection screen). Both types have their advantages, but if you wish to
		reduce login time and monitor memory and CPU usage properly, you must use non-embedded
		Libraries. To do this, simply ensure that only a single copy of the Library is present in the entirety
		of the "Interface\AddOns" directory structure, and that this single copy is at the top level, as
		explained before. For convenience, all Library-type addons are prefixed with "Lib-" to identify
		them from the other types of addons.
	
	Plugin - These addons are generally optional, and "plug in" to Interface-type addons to provide
		additional functionality. They are always top-level, meaning that they appear in the addons
		configuration menu at the character selection screen. Most Interface-type addons which use
		plugins will not actually provide any significant functionality on their own. Generally, Plugins
		will include the name of their parent Interface addon in their own name to help identify them.

An addon's type and any libraries it uses are listed at the top of its readme file.



-- == -- == -- Versioning System -- == -- == --

This addon adheres to a #.#.# versioning format:

The first number (the 1 in 1.2.3) denotes the current major version. This number is
incremented when the addon's functionality or style of code changes so significantly
as to barely resemble previous versions. For Library-type addons, which provide
functionality to client addons, this number is also a guarantee that every release
within this major version will be backwards compatible with previous releases that
are also within this major version. In these cases, this number is actually a suffix on the
library's name. This is done so newer major versions of libraries will not overwrite
older ones, since those may still be in use by other clients.

The second number (the 2 in 1.2.3) denotes the current minor version. This number
is incremented when functionality is added, modified, or removed.

The third number (the 3 in 1.2.3) denotes the current subminor version. This number is
incremented when a release's purpose is to fix bugs or errors, or to increase efficiency
in some way, or to make a minor cosmetic adjustment.
