WoWBench/Getting started

WoWBench » Getting started
== Starting WoWBench ==
=== Example startup ===
Getting up and running with WoWBench is really only a matter of starting it, e.g.:
:C:\wowbench>lua wowbench.lua -f
The "-f" switch probably isn't what you want to use for each startup, but if you give no command line arguments, it will show parameter help rather than starting up.
 [WoWBench v1.11.0.a4 +bitlib]
 
 
 -------- [Parsing .TOC files] -------------------------------------------------
 
 ---[world.toc]
 Running <OnLoad>s and <Scripts>s...
 Your name is Mikk.
 Alice has entered the world.
 Bob has entered the world.
 Charles has entered the world.
 
 ---[blizzardui.toc]
 Running <OnLoad>s and <Scripts>s...
 
 ---[BlizzardInterface/FrameXML/FrameXML.toc]
 Running <OnLoad>s and <Scripts>s...
 
 -------- [Loading saved variables and firing ADDON_LOADED for each addon] -----
 
 -------- [Firing VARIABLES_LOADED] --------------------------------------------
 
 -------- [Startup events, showing frames, first OnUpdates, etc] ---------------
 Firing SPELLS_CHANGED...
 Showing frames initially shown...
 Firing PLAYER_LOGIN...
 Firing PLAYER_ENTERING_WORLD...
 
 
 -------- [I am alive!] --------------------------------------------------------
 Use "help" for help
 
 cmd>
At this point, you have a vanilla WoW emulator up and running. 
You can get help directly at the prompt:
 cmd> help
 Available commands:
 [Enter] - fire <OnUpdate> in all visible frames
 
 click <unit or UI element>
 clickm <unit or UI element>
 clickr <unit or UI element>
 
 dump <globalvarname> [<maxtabledepth>]
 dump [-i] <pattern>
 dump <stackdepth>:<localvarname> [<maxtabledepth>]
 
 editdump <globalvarname> [<maxtabledepth>]
 editdump [-i] <pattern>
 editdump <stackdepth>:<localvarname> [<maxtabledepth>]
 
 fire <EVENT NAME> [<arguments>]
 
 look
 look <frame name>
 
 mouse <unit or UI element>
 
 /<slashcmd> [<params>]
 - Executes any WoW slash command
 
 Or any valid Lua command.
 
 Use help <command> for more information.
 
 cmd> help look
 would produce help for the look command
=== Command line arguments ===
;Usage:lua50 wowbench.lua [<parameters>] addon1 [addon2 ...]
Parameters:
* -q - Quick mode (use "FrameXML-lite", which loads ~3 times faster)
* -x - Syntax checker mode (load Lua, verify XML syntax, run nothing)
* -d - Enable debug output according to WOWB_DEBUGCAT in config.lua
::WoWBench has a fairly intricate debug output system using the DP() function
* -v - Verbosely list all parsed Lua and XML files during load
* -f - Forced reparse of all files, do not use precompiled copies
::WoWBench will precompile as much as possible into compiled Lua to speed up load times. It is especially noticeable for FrameXML.
=== Loading AddOns ===
Easy:
:lua50 wowbench.lua ct_raidassist ace archud
Note that WoWBench currently does not handle dependencies. If an AddOn depends on something else, you have to make sure to load it yourself.
AddOns will be loaded from the WoW directory that you specified in config.lua.
== The WoWBench prompt ==
At a glance, these are things that WoWBench can do:
* Call functions in your AddOn directly from the prompt:
:: MyAddOn_DoSomething("someParameter")
* Make Alice, Bob or Charles (the default player characters) say something:
:: say Alice Help! Help! The horrible Murloc Warrior is hitting me!
* Fire an event:
:: fire DUEL_REQUESTED Charles
* Run a slash command:
:: /myaddon dosomething
* Look at the frame that popped up:
:: look MyAddOnMainFrame
* Click a button in it:
:: click MyAddOnMainFrameIWinButton
=== How to interact with things ===
Interacting with the game world is a bit rough but fairly straightforward. The only actual WoWBench-specific emulation is mouse movements and "looking" at frames (and the game world around you).
==== Looking at the world ====
 Cmd> look
 Looking at World:
 1: World World
 2: Player Charles
 3: NPC Murloc Warrior
 4: Object Mailbox
 5: Object Signpost
 6: Player Alice
 7: Player Mikk
 8: NPC Northshire Worker
 9: Player Bob
 
 You can now use $1--$9 in command line expressions.
 Hint: Use 'look $1' to re-examine this object.
These are NPCs and objects that you can interact with via the WoW APIs, e.g. API TargetUnit, etc.
The only other interaction possible from the command line is simulating mousing over things, and clicking them.
==== Interacting with units and objects ====
 cmd> mouse Signpost
 You read the signpost. It says:
 
 Welcome to WoWBench v1.10.2.a3
 
 It is dark and you are in a maze of hairy lua scripts, all alike but subtly different.
 You are likely to be eaten by a grue.
This just a simple <OnEnter> trigger in world.xml, in <Object name="Signpost">, which demonstrates that you can more or less define the world to behave exactly the way you like it to. A more meaningful implementation of OnEnter in objects is probably to trigger the GameTooltip object to show:
 cmd> mouse Bob
 Show: GameTooltip GameTooltip
WoWBench will tell you about frames being shown or hidden after startup. In this case, mousing over Bob triggered a GameTooltip object named "GameTooltip" (you'll recognize this from how it actually works in-game) to show. And we can even look at the tooltip!
==== Looking at frames ====
Continuing from the past example where we moused over Bob, we can proceed to look at the tooltip frame that popped up:
 cmd> look gametooltip
 Looking at gametooltip:
 1: GameTooltip GameTooltip
 2: FontString [Level 60 WARRIOR] GameTooltipTextLeft2
 3: FontString [Bob] GameTooltipTextLeft1
 (+60 hidden frames not shown)
 
 You can now use $1--$3 in command line expressions.
 Hint: Use 'look $1' to re-examine this object.
You'll notice that WoWBench is case insensitive about findings frames. It will continue to be so until it clashes with something important (to Lua itself, "GameTooltip" and "gametooltip" are two entirely different variables).
In this case, we are being told that we're looking at a top frame called "GameTooltip", which is a GameTooltip object.
It has two visible children, 2 fontstrings, containing "Bob" and "Level 60 WARRIOR". They're out of order since the "look" command has no idea about what it actually would look like on-screen, but the object names to the right should clue you in as to the order they'd be shown in on-screen. (Also, the actual tooltip text is totally different from the in-game text. It's the game engine itself that decides what these tooltips should look like, so it's up to you to modify it to emulate WoW better!)
To see everything on-screen (well, nearly), you can look UIParent, but that dump, we're not going to show here :-)
==== Summary of interaction commands ====
; mouse: Simulate mousing over an UI object or a game-world unit or object. Not giving an argument means mousing over nothing in the game view.
; click, clickr, clickm: Click the left, right and middle mouse buttons, respectively, on an UI object or a game-world unit or object. Will send MouseDown, MouseUp and Click events as appropriate. Clicking something implicitly means mousing over it first.
; look: Seeing game-world units or objects around you, or looking at the contents of an UI object.
=== More commands ===
==== Firing events ====
You can fire any of the game events with the fire command. See the full list of events, or the list of what is actually registered:
 Cmd> fire
 Registered events:
 
 ACTIONBAR_HIDEGRID - 73 frames
 ACTIONBAR_PAGE_CHANGED - 74 frames
 ACTIONBAR_SHOWGRID - 73 frames
 (...)
 AUTOFOLLOW_END - 1 frames
 
 BAG_CLOSED - 12 frames
 (...)
To actually fire an event, simply enter its name and, optionally, parameters:
 Cmd> fire DUEL_REQUESTED Alice
 Firing DUEL_REQUESTED
 Show: Frame StaticPopup1
 Processed by 1 frames 
 cmd> look StaticPopup1
 Looking at StaticPopup1:
 1: Frame StaticPopup1
 2: FontString [Alice has challenged you to a duel.] StaticPopup1Text
 3: Button [Accept] StaticPopup1Button1
 4: Button [Decline] StaticPopup1Button2
If you need to provide more complex arguments, you can call the underlying function directly:
 cmd> fire("DUEL_REQUESTED", "Alice");
==== Logging in multiple players ====
WoWBench allows you to log in multiple players. It simply fires up a whole new, independent WoWBench session inside itself!
 Cmd> login Myaltchar
 [WoWBench v1.10.2.a3]
 
 -------- [Parsing .TOC files] -------------
 
 (snip)
 -------- [I am alive!] --------------------
 
 [2] Myaltchar> login
 Current sessions:
 1: Mymain
 2: Myaltchar
 
 [2] Myaltchar> 1 
 
 [1] Mymain> /whisper Myaltchar heya!
 ChatFrame1: To |Hplayer:Myaltchar|h[Myaltchar]|h: heya!
 
 [1] Mymain> 2 
 
 [2] Myaltchar>
 <OnUpdate> triggered in 19 visible frames
 ChatFrame1: |Hplayer:Mymain|h[Mymain]|h whispers: heya!
 
 [2] Myaltchar>
 
== How to use the built-in debugger ==
* Hint: To emulate breakpoints, just insert WOWB_Debugger() calls where you'd like to break!
== More ==
* Continue to WoWBench/Extending - How to extend WoWBench
* Continue to WoWBench/Documentation - WoWBench code structure documentation
* Back to WoWBench
Getting started