AddOn Studio

WoW:Getting started with writing AddOns: Difference between revisions

WoW Talk

WoW:Getting started with writing AddOns (source)

Revision as of 17:34, 19 August 2018

166 bytes removed ,  19 August 2018
m
→‎What should I make
Line 1: Line 1:
{{uiaddon}}
{{uiaddon}}
The idea of picking up any programming language can be daunting, and when you have to tie your program into someone else's APIs it can be nearly overwhelming. Creating your own AddOn will be a difficult process for novice coders, but the end satisfaction is worth it.  
The following is a guide for getting started with building WoW AddOns. Creating your own AddOns can be a difficult process at first, but can be very satisfying and is a great way to learn programming in general.


== First Steps ==
If you are mostly interested in what files and structure comprise a WoW AddOn, you can skip to [[WoW AddOn]], and come back here or move on from there.  
These first step detail what someone might do to get started writing AddOns for World of Warcraft for the first time.


=== What should I make ===
== What should I make ==
Figure out what you want your AddOn to do. Don't try and get into the details too much, just decide what you want the overall goal to be. I usually start by asking myself these questions:
Pick a simple goal or idea for your AddOn. It's often a good idea to just make an AddOn that only opens a window or prints a message to get started, especially when everything is new for you. After that works the way it should, and you have learned everything necessary to make an AddOn work at all, you can move on to adding one piece at a time toward your goals. Writting software in general is often a never ending process because you can always think of something new to add or improve.
 
Examples of good questions to ask yourself:
* What's my end goal?
* What's my end goal?
* What information will I need from WoW for my AddOn to work?
* What information will I need from WoW for my AddOn to work?
* Will I need to make custom frames?
* Will I need to make windows (called 'frames' in WoW)?
* Will I need to interact with Blizzard's frames?
* Will I need to interact with Blizzard's windows or frames?
* Do I know the functions needed to do everything I want to do?
* Will I need to print messages to the chat box?
* Do I know how to talk to WoW in my AddOn to do everything I want to do?


=== How do I make it ===
== How do I make it ==
Research the programming environment.
Research the programming environment:
* Learn the WoW UI language, [[Lua]], by reading a few pages of the reference for the basic idea.
* [[Lua]] - This is the programming language used by WoW for UI AddOns.
* Learn the WoW UI API, [[World of Warcraft API]] and UI constructs, by reading a bit from each section.
* [[WoW AddOn]] - These pages explain the basic structure of a WoW AddOn.
* Learn the basic structure, as detailed below, also skimming [[WoW AddOn]] reference page for structure.
* [[World of Warcraft API]] - These are the functions and ways to talk to WoW with Lua.
* Find a real but simple example, like from [[Curse]], to get a basic idea of what's involved in a real AddOn.
* [[Curse]] - Find a real but simple example of an existing AddOn. However most real AddOns, even the simple ones, are honestly very difficult to read for getting started, with too many moving parts.
* Make a barebones test AddOn to do something simple, using the reference material described above.
* [[Lua editors]] - A long list of code editors and other tools often used by other AddOn creators.


The following sections help with some of the various aspects of completing these first steps.
Start with making a simple AddOn that has almost no moving parts, where you can see what all of the basic parts are and move forward from there. Use the reference material described above, especially [[WoW AddOn]], as that describes what really makes up an AddOn.


== Getting into the WoW API ==
After completing your first one you will then have enough skill to start to build the real AddOn you wanted to originally make.
Getting information on how the WoW UI works is critical to making your AddOn function. The [[World of Warcraft API]] has a list of functions that will give you that information. These are your building blocks, and if you don't have a block you need (or thought you needed) then you'll have to find another way to get information for your AddOn. Don't be discouraged, as with any programming language there are many different ways to accomplish your goal, so keep looking until you find a way.


=== Getting the UI Source Code ===
The following sections help with some of the various aspects of completing these first steps.
:''See also [[Extracting interface files]] and [[Viewing Blizzard's interface code]].
You may want to extract the Blizzard interface files, where you can view all of the XML and Lua files that make the game's default UI work> This can be useful as example code and provides you with two introductory tutorials.


==== Enable the WoW "console" ====
== Lua ==
:''Note: the Battle.net launcher now has an option to launch in console mode, which can be used instead.''
[[Lua]] is a language used by many games different games for their customizable UI AddOn code and other code. In WoW, if you learn a few Lua basics it will go a very long way to creating your first WoW AddOn, and toward understanding all of the other documentation and help here.
This section helps open WoW with the console flag enabled to use the WoW console, necessary for extracting the WoW interface.
;For Windows
* Navigate to your WoW install directory, usually in 'C:\Program Files (x86)'.
* Right-click the 'WoW.exe' file
* Click 'Send to → Desktop (create shortcut)'
* Navigate to, or look at, your Desktop
* Right-click on your newly created shortcut
* Select 'Properties', a new window will pop up
* In the target line you need to add '-console' to the very end of the line it should look similar to this:
"C:\Program Files (x86)\World of Warcraft\Wow.exe" -console
* Make sure to hit 'Apply', close the window and launch your created shortcut


;For Mac OS X
== World of Warcraft API ==
* Open 'Terminal.app', located in '/Applications/Utilities'.
The [[World of Warcraft API]] has a list of functions that you can interact with and to talk with WoW using Lua. These are your building blocks for manipulating WoW windows and chat boxes and so forth. Looking at these for the first time can be very daunting. But don't be discouraged. After getting more familiar with Lua the WoW API gets much easier, and the documentation gets much easier to read. Keep in mind there are many different ways to accomplish your goals, so when going though the API keep looking until you find a way that best suits what you need.
* Paste the following command and press return:
Open "/Applications/World of Warcraft/World of Warcraft-64.app" --args -console
* WoW will launch
* Note that the command was tested with WoW [[Patch 5.0.5|5.0.5]] on Mac OS X 10.8


==== Extract the API ====
== Editing Tools ==
* At the login page ('''before''' logging in) press the tilde (<tt>~</tt>) key (the key to left of the 1 key, labeled <sub><tt>`</tt></sub><sup><tt>~</tt></sup>) to open the World of Warcraft console<br />If this is not working because you need to press a modifier to access this key. Log into the game, then enter the following slash command: /run SetConsoleKey("z")
Before you can write any sort of code, you'll want to have a tool that lets you edit your AddOn files. However do not get overly distracted with the tools themselves while trying to get your first AddOn created. Any text editor, like Windows Notepad can edit the files. All AddOn files are plain text files. The editors can make the coding and many repetitive tasks easier for day to day editing, but it's often very difficult to learn the tools and try to learn the AddOn at the same time.
NOTE: the SetConsoleKey command will not persist after exting the game
* Type "<tt>exportInterfaceFiles code</tt>" or "<tt>exportInterfaceFiles art</tt>". Code is probably what you're looking for, you will notice the game will lock up as it is exporting the files, this is normal.
* You can now find the current version of the stock UI files in the <tt>BlizzardInterfaceCode</tt> folder of your WoW directory.


== Editing Tools ==
Before you can write any sort of code, you'll want to have a tool that lets you edit your AddOn files.  All AddOn files are plain text files, meaning even Notepad will do.  You can also get LUA and XML specific text editors, which will highlight syntax for you, in turn making your coding a lot easier.
To review the list of tools and get one you'd like, head to the [[Lua editors]] page.
To review the list of tools and get one you'd like, head to the [[Lua editors]] page.


== File Types ==
== Anatomy of a WOW Addon ==
There are three primary types of files that you'll need to worry about with AddOn editing:
Strongly suggest looking here: [[WoW AddOn]], and then come back here to this section, to review this mini-review of the same material to put into better context. The WoW AddOn page shows all of the AddOn elements, where then are explained here for getting started.
* [[TOC File]] - This file is required for any AddOn. This is the file that supplies WoW with information about your AddOn and which files are required for your AddOn to work.
 
* LUA Files - This contains all the programing for your AddOn.  
=== File Types ===
* XML Files - This holds the layout of frames you have created for your AddOn.
There are three main types of files that you'll need to worry about with AddOn editing:
* [[TOC File]] - This file is required for any WoW AddOn, and supplies WoW with information about your AddOn and its files.
* LUA Files - This contains Lua code for your AddOn.  
* XML Files - This holds the layout of UI windows, buttons, and similar for your AddOn.


=== TOC File ===
=== TOC File ===
This is the file that instructs WoW in some basics about your AddOn and what other files you want loaded. Here's a short example of one:
This is the file that instructs WoW in some basics about your AddOn and what other files you want loaded. Here's a short example of one. If you pasted this code into a 'MyAddOn.toc' file it would work as a beginning toc file:


  ## Interface: {{API LatestInterface}}
  ## Interface: {{API LatestInterface}}
Line 74: Line 56:
  ## Notes: This AddOn does nothing but display a frame with a button
  ## Notes: This AddOn does nothing but display a frame with a button
  ## Author: My Name
  ## Author: My Name
  myAddOn.xml
  MyAddOn.xml
  # This is a comment. Interface: 60200 refers to WoW client version 6.2
  MyAddOn.lua


You can read more about what you need or can put in a TOC over at [[The TOC Format]]
You can read more about what you need or can put in a TOC over at [[The TOC Format]].


=== Lua Files ===
=== Lua Files ===
[[Lua]] files contain functional pieces of code. You may choose to only have one of these or break up your code into multiple files for a specific purpose. Here's a short example of one:
[[Lua]] files contain functional pieces of code. You may choose to only have one of these or break up your code into multiple files for a specific purpose. Here's a short example of one:


  function MyAddon_OnLoad()
  function MyAddOn_OnLoad()
     SlashCmdList["MyAddon"] = MyAddon_SlashCommand;
     SlashCmdList["MyAddOn"] = MyAddOn_SlashCommand;
     SLASH_MYADDON1= "/myaddon";
     SLASH_MYADDON1= "/myaddon";
     this:RegisterEvent("VARIABLES_LOADED")
     this:RegisterEvent("VARIABLES_LOADED")
end
function MyAddOn_SlashCommand()
    print("Hello, WoW!")
  end
  end


Line 100: Line 86:
  </Frame>
  </Frame>


== Start Coding! ==
== Start Coding ==
Start with the tutorials extracted by the [http://us.blizzard.com/support/article.xml?locale=en_US&articleId=21466 Interface AddOn Kit]. The [[HOWTOs]] here has a ton of great examples to help you learn. Don't be shy to dig through someone else's AddOn for help, just be sure to not steal code, and give credit where credit is due.
Start with the tutorials extracted by the [http://us.blizzard.com/support/article.xml?locale=en_US&articleId=21466 Interface AddOn Kit]. The [[HOWTOs]] here has a ton of great examples to help you learn. Don't be shy to dig through someone else's AddOn for help, just be sure to not steal code, and give credit where credit is due.


Line 134: Line 120:
* Basically, WoW makes a SavedVariables file for you named after your AddOn.  You only get to specify in your TOC *which* variables get saved into that file.
* Basically, WoW makes a SavedVariables file for you named after your AddOn.  You only get to specify in your TOC *which* variables get saved into that file.


== Localization ==
 
== Advanced but Important Topics ==
 
=== Getting the WoW API ===
After learning all of the basics, there are times where you may want to see how the Blizzard UI code works to help you in making your own AddOn. And getting information on how the WoW UI works can be helpful to making your AddOn function.
 
See [[Extracting interface files]] for getting the Blizzard UI AddOn source code which can also be used as a reference.
 
=== Localization ===
It's a good idea to plan from as early as possible to have your AddOn be localizable, even if you yourself only speak one language.  Review this great article for some things to think about: [[HOWTO: Localize an AddOn]].
It's a good idea to plan from as early as possible to have your AddOn be localizable, even if you yourself only speak one language.  Review this great article for some things to think about: [[HOWTO: Localize an AddOn]].


Retrieved from "https://addonstudio.org/wiki/Special:MobileDiff/7637"