A library to create user specified scripts.
This uses ideas similar to Outfitter's user scripts.
Current version is 1.0
This addon does nothing by itself. It does not register events, and it does not directly register any slash commands or Blizzard Options frames. However, it does present an AceConfig3 table for accessing and modifying created scripts.
It is mainly meant for allowing users to create scripts that respond to events.
See the Script API for the interface provided to created scripts.
Features
- Scripts can declare inline with the script text
- Interested WoW events
- Settings that can be modified outside the script
- User visible description
- Error reporting
- Abuse prevention
- Limited base environment
- Specified global environment
- Limiting frequency (using a 1 second sliding window)
- Limiting duration
Using the library
- Create an environment for running scripts.
This is a simple table where each key is the name of the global variable and the value is a reference to a Lua object (function, table, or value). While possible, it is not recommended to pass _G as this defeats all security (expect irate users whose gold has been lost in many creative ways).
Lets call this environment environment and set it to { TakeScreenshot = TakeScreenshot }.
This value is not modified by the library and can be shared amongst scripts.
- Create a new script object
script = LibStub("LibUserScript-1.0"):New(environment)
- Set the script text using the
SetText function
script:SetText("TakeScreenshot()")
- Execute the script
- a. Run the script directly
script:Execute()
- b. Register for an event using AceEvent-3.0 (similar for CallbackHandler-1.0) embedded in the current addon (self)
self.RegisterEvent(script, event_name_string, script.Execute, script)
Where event_name_string is something like "PLAYER_DEAD".
Script Callbacks
The state of the library can be tracked by registering for callbacks using RegisterCallback. The current list of callbacks include:
- OnSettingChanged
- OnStateChanged
- OnTextChanged
- OnResetSettings
- OnEnabledChanged
- OnMaxDurationChanged
- OnMaxFrequencyChanged
Script Functions
- Execute
- Runs the script defined by SetText.
- Takes no arguments.
- RegisterCallback/UnregisterCallback/UnregisterAllCallbacks
- These are CallbackHandler-1.0 functions. Everything that applies to that library applies here.
- IsStateNormal
- Check if the current script state is not an error or warning.
- Possible states include, Init, Ready and Running. Takes no arguments.
- IsStateWarning
- Check if the current script state is a warning.
- Warnings cause the script to be temporarily suspended for 5 seconds. Warnings are cause for concern. Currently warnings are produced when exceeding the MaxDuration setting or executing more frequently that MaxFrequency. Takes no arguments.
- IsStateError
- Check if the current script state is an error.
- Errors prevent scripts from running. The only way to clear an error is to change the text with SetText. Takes no arguments.
- GetText/SetText
- Get and set the text of the script.
- See Script API for more information. SetText takes a string to run and returns true on success.
- ResetSettings
- Resets all settings to their default values.
- The settings object is not directly visible to outside code, but this will reset all script settings to their default values. Takes no arguments.
- GetSetting (also GetSettingConfigValue)/SetSetting (also SetSettingSafe)
- Get and set a script setting.
- These settings are defined using special comments in the script. GetSettingConfigValue retrieves values appropriate for GetConfig. SetSetting will call assert on failure. SetSettingSafe returns true on success or false and a localized error string on error. The first argument to these functions is the name of the setting. The second argument to SetSetting/SetSettingSafe is the new value.
- GetEnabled/SetEnabled
- Enables or disables running the script.
- The enabled state of a script is separate from its "State".
- GetMaxFrequency/SetMaxFrequency
- Gets and sets the maximum frequency with which a script may execute.
- This value is in executions per second. Setting this value to 0 disables checking script frequency (this is useful for anything that will listen to the combat log). Currently uses an indexed array of size frequency, so do not set this value too large. For values larger than 128, you should probably just disable this feature.
- GetMaxDuration/SetMaxDuration
- Gets and sets the maximum duration with which a script may execute.
- This value is in seconds of execution time.
- GetUserData/SetUserData
- Gets and sets a user provided value.
- This value is not used by the script object, but stored with it.
- GetState
- Gets the current script execution state.
- If the state is not Normal, then the second value contains a localized message string.
- GetDescription
- Gets the scripts description as defined by the text passed to SetText.
- GetEvents
- Gets a list of events the script is interested in.
- The script object does not register for events.
- GetConfig
- Gets an AceConfig3 table.
Todo
- Provide ability to specify a set of initialization steps
------------------------------------------------------------------------
r14 | lokicoyote | 2008-11-24 00:11:54 +0000 (Mon, 24 Nov 2008) | 1 line
Changed paths:
A /tags/v1.0.4 (from /trunk:13)
Tagging as v1.0.4
------------------------------------------------------------------------
r13 | lokicoyote | 2008-11-23 19:02:02 +0000 (Sun, 23 Nov 2008) | 2 lines
Changed paths:
M /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
Added zhCN and zhTW translations from yeachan
------------------------------------------------------------------------
r11 | lokicoyote | 2008-11-21 01:30:51 +0000 (Fri, 21 Nov 2008) | 2 lines
Changed paths:
M /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
Typo with ipairs getting mapped to pairs
------------------------------------------------------------------------
r10 | lokicoyote | 2008-11-21 00:31:45 +0000 (Fri, 21 Nov 2008) | 2 lines
Changed paths:
M /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
Try to add some measure of protection against pathological scripts
------------------------------------------------------------------------
r8 | lokicoyote | 2008-11-20 23:33:38 +0000 (Thu, 20 Nov 2008) | 2 lines
Changed paths:
M /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
Fix a malformed select statement
------------------------------------------------------------------------
r6 | lokicoyote | 2008-11-20 21:30:08 +0000 (Thu, 20 Nov 2008) | 2 lines
Changed paths:
A /trunk/CallbackHandler-1.0.lua
A /trunk/LibStub.lua
Forgot to add unembedded library copies
------------------------------------------------------------------------
r5 | lokicoyote | 2008-11-20 21:29:00 +0000 (Thu, 20 Nov 2008) | 3 lines
Changed paths:
M /trunk/.pkgmeta
M /trunk/LibUserScript-1.0.toc
D /trunk/embeds.xml
A /trunk/lib.xml (from /trunk/embeds.xml:2
Removed externals
Removed embeds.xml and added lib.xml
------------------------------------------------------------------------
r4 | lokicoyote | 2008-11-20 21:19:04 +0000 (Thu, 20 Nov 2008) | 4 lines
Changed paths:
M /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
M /trunk/LibUserScript-1.0.toc
Cleaned up TOC
embeds aren't really optional (LibStub and CallbackHandler in standalone mode)
If we don't have revision don't abort on a simple addition
------------------------------------------------------------------------
r2 | lokicoyote | 2008-11-20 20:24:08 +0000 (Thu, 20 Nov 2008) | 3 lines
Changed paths:
A /trunk/.pkgmeta
A /trunk/Changelog-PhotoOp-r112.txt
A /trunk/LibUserScript-1.0
A /trunk/LibUserScript-1.0/LibUserScript-1.0.lua
A /trunk/LibUserScript-1.0/LibUserScript-1.0.xml
A /trunk/LibUserScript-1.0.toc
A /trunk/Libs
A /trunk/embeds.xml
Renamed from LibSimpleScript to LibUserScript
Initial commit from PhotoOp (see Changelog-PhotoOp-r112.txt for previous entries)
------------------------------------------------------------------------
r1 | root | 2008-11-20 00:49:44 +0000 (Thu, 20 Nov 2008) | 1 line
Changed paths:
A /branches
A /tags
A /trunk
"lib-user-script-1-0/mainline: Initial Import"
------------------------------------------------------------------------
Installation Guide
- Exit "World of Warcraft" completely
- Download the mod you want to install
- Make a folder on your desktop called "My Mods"
- Save the .zip/.rar files to this folder.
- If, when you try to download the file, it automatically "opens" it... you need to RIGHT click on the link and "save as..." or "Save Target As".
- Extract the file - commonly known as 'unzipping'
Do this ONE FILE AT A TIME!
- Windows
- Windows XP has a built in ZIP extractor. Double click on the file to open it, inside should be the file or folders needed. Copy these outside to the "My Mods" folder.
- WinRAR: Right click the file, select "Extract Here"
- WinZip: You MUST make sure the option to "Use Folder Names" is CHECKED or it will just extract the files and not make the proper folders how the Authors designed
- Mac Users
- StuffitExpander: Double click the archive to extract it to a folder in the current directory.
- Verify your WoW Installation Path
That is where you are running WoW from and THAT is where you need to install your mods.
- Move to the Addon folder
- Open your World of Warcraft folder. (default is C:\Program Files\World of Warcraft\)
- Go into the "Interface" folder.
- Go into the "AddOns" folder.
- In a new window, open the "My Mods" folder.
- The "My Mods" folder should have the "Addonname" folder in it.
- Move the "Addonname" folder into the "AddOns" folder
- Start World of Warcraft
- Make sure AddOns are installed
- Log in
- At the Character Select screen, look in lower left corner for the "addons" button.
- If button is there: make sure all the mods you installed are listed and make sure "load out of date addons" is checked.
- If the button is NOT there: means you did not install the addons properly. Look at the above screenshots. Try repeating the steps or getting someone who knows more about computers than you do to help.
Translations
When you download a mod, please be sure that the mod is compatible with your translation of wow. Some mods only work on the US versions, while some only work on some of the various European versions. These variations are called "Localizations".
TOC Numbers (Out of Date Mods)
When Blizzard patches WoW, they change the Interface number. This means that all mods will be "out of date" unless or until the author releases a new version for that interface. Some people go into the .toc files and update the numbers themselves, but this is STRONGLY advised against as it will cause problems locating possible incompatibilities addons. When you log into WoW after a patch, you DO NOT have to delete your interface directory. All you have to do is simply tell WoW to ignore the interface numbers and load all the mods anyway. All you have to do is, while at the "character select" screen, look in the lower left corner and click on the "addons" button. A window will pop up listing all your installed mods.
If you look in the upper left corner of that window there should be a box that says "Load Out of Date AddOns". You want to CHECK this box. Now simply go into WoW normally and all your mods should load. As of the 1.9 patch, you will have to do this after EVERY patch/update that Blizzard posts! If you encounter any problems with a mod after a patch, please be sure to let the author of the mod know so they can fix it.
See also: About "Out Of Date AddOns"
Mac Support
WoW addons are not platformed based. As such, they can be used on either Mac or PC. You can extract both .zip and .rar files on a Mac using StuffitExpander.
Directory Structure
World of Warcraft
|_ Interface
|_AddOns
|_*AddonName*
|_ *AddonName*.toc
|_ *AddonName*.xml
|_ *AddonName*.lua
|_ (possibly others as well)...
