WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
Help
Sign In Register
WelcomeHomeYourfirstAce3Addon
FromWowpedia
Contents
1Introduction
2GettingStarted
3BringingAce3totheParty
4SayingHello
5RespondingtoEvents
6ReloadingYourAddonWithoutRestartingWoW
7WorkingwiththeWoWAPI
8ChatCommandsandConfiguration
9GUIandBlizzardInterfaceOptions
10MakingtheMessageMoreProminent
11SavingConfigurationBetweenSessions
12LocalizingYourStringswithAceLocale
12.1AddingAceLocale3.0totheProject
12.2BuildingtheLocalizationDatabase
12.3UsingtheLocalizedStringsintheAddon
12.4Mixedinvariables
13Conclusion
14JointheAceCommunity
15FinalSourceFiles
15.1WelcomeHome.toc
15.2embeds.xml
15.3Core.lua
15.4enUS.lua
16Attribution
MainMenu
WoWAPI
WidgetAPI
MacroAPI
Luafunctions
Events
Widgethandlers
Datatypes
XMLUI
Changes
HOWTOs
Snippets
UItech.
Categorynav.
HOWTOs
Introduction
Ace3(http://old.wowace.com/wiki/Ace3)isanAddOndevelopmentframework,like(thenowabandoned)Rock(http://old.wowace.com/wiki/Rock),
Dongle,andSea.
Beforestartingthistutorial,it'srecommendedtoreadMakeitAce'd(http://old.wowace.com/wiki/Make_it_Ace%27d),andAce3Philosophy
(http://old.wowace.com/wiki/Ace3#Ace3_Philosophy)
Alternatively,thereisthemoreadvancedandofficialAce3GettingStarted(http://www.wowace.com/addons/ace3/pages/gettingstarted/)tutorial
GettingStarted
SincethisisatutorialaboutusingtheAce3libraries,Iwillstartbyshowingyouwhatweneedtodotogetabarebonesaddonloadedintothegame.
EveryaddonisstoredinafolderunderneaththeWoWmainfoldercalled<WoW>\Interface\AddOns.Eachaddongoesinitsownfoldernamedafterthe
addon.SotogetstartedwewillcreateanewfoldercalledWelcomeHome.
WhenWoWfindsafolderintheaddonsdirectory,itlooksinsidethatfolderforaTableofContents(TOC)filethathasthesamenameasthefolder.This
.TOCfilecontainsamanifestofalltheotherfilesthatmakeuptheaddonandisusedbyWoWtoloadyouraddon.
Letsgoaheadandcreateabarebones.TOCfilecalledWelcomeHome.toc:
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
Core.lua
Thesearethebasicmetadataassociatedwithyouraddon.Therearemanyotherattributesyoucanincludeinyour.TOCfile,foramorecomprehensivelist
seetheTOCFormat.
ThencreateanemptytextfilecalledCore.luainthesamedirectoryandstartupWoW.Afterloggingin,youshouldbeabletoclicktheAddOnsbuttonin
thelowerleftandseethatyourAddOnisbeingrecognizedbythegame.Goaheadandmakesurethatitisenabledbeforeexitingoutofthatscreenand
thenoutofthegame.
Step1complete!Weareinthegame.Butwearentdoinganythingyet.Thatisnext.
BringingAce3totheParty
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
1/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
SincethistutorialisaboutlearningtocreateaddonsusingAce3,itistimeforustogoaheadandbringthoselibraries
(http://en.wikipedia.org/wiki/Library_%28computing%29)intoouraddon.Ace3usesaconceptcalledEmbeddedLibrariesthatallowsmoddevelopersto
havethelibrariesintheircodebasewithoutactuallyduplicatingthecodewhenitisloadedalongsideothermodsthatusethesamelibraries.
Thismeansyouneedtogetlocalcopiesofthelibrariesyouintendtouse.AtthispointtheeasiestwaytodothisistodownloadthemfromtheAceSVN
filesmirrorandputthemonyoursystem.
Openabrowserandgotohttp://www.wowace.com/addons/ace3/files/.DownloadAce3.ThisisthemostrecentbuildoftheAcelibraries.Unzipitintoa
foldercalledLibsinyouraddon'sdirectory.Thengoaheadanddeleteallofthenewfoldersandfilesexceptthese:
AceAddon3.0(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/)
AceDB3.0(http://www.wowace.com/addons/ace3/pages/api/acedb30/)
AceConfig3.0(http://www.wowace.com/addons/ace3/pages/api/aceconfig30/)
AceConsole3.0(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/)
AceEvent3.0(http://www.wowace.com/addons/ace3/pages/api/aceevent30/)
AceGUI3.0(http://www.wowace.com/addons/ace3/pages/api/acegui30/)
CallbackHandler1.0(http://www.wowace.com/addons/callbackhandler/)
LibStub(http://www.wowace.com/addons/libstub/)
TherearelotsofAce3librariesforyoutouse,butforthistutorialweonlyneedsomeofthem.Formoreinformationontheselibraries,pleaseseetheAce3
APIdocs(http://www.wowace.com/addons/ace3/pages/)
Youshouldnowhaveafolderstructuresomethinglikethis:(Seetheoriginal(http://old.wowace.com/wiki/WelcomeHome_
_Your_first_Ace3_Addon#Adding_AceLocale3.0_to_the_Project)forabetterview)
WelcomeHome
Libs
AceAddon3.0
AceAddon3.0.lua
AceAddon3.0.xml
AceConfig3.0
AceConfigCmd3.0
AceConfigDialog3.0
AceConfigDropdown3.0
AceConfigRegistry3.0
AceConfig3.0.lua
AceConfig3.0.xml
AceConsole3.0
AceConsole3.0.lua
AceConsole3.0.xml
AceDB3.0
AceDB3.0.lua
AceDB3.0.xml
AceEvent3.0
AceEvent3.0.lua
AceEvent3.0.xml
AceGUI3.0
widgets
AceGUI3.0.lua
AceGUI3.0.xml
CallbackHandler1.0
CallbackHandler1.0.lua
CallbackHandler1.0.xml
LibStub
LibStub.lua
Core.lua
WelcomeHome.toc
YounowhavethenecessaryAce3librariesinyouraddon'sLibsfolder,butifyouweretolaunchWoWrightnow,theywouldn'tbeloaded.Weneedtotell
WoWtoloadthefileswhenitloadsyouraddonandforthatwe'regoingtouseafilecalledembeds.xml.Socreateanewfilewiththetextbelowandsaveit
as"embeds.xml"inthesamefolderasyour.TOCfile.
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>
Thefirstlineisjustsomexmlvoodoo(http://www.w3.org/TR/xmlschema1/#Schemas),justcopyandpaste.Thenit'salineeachforallthelibrarieswe
wanttoload.Noticethatit's<Script/>toloadLuafilesand<Include/>toloadXMLfiles.
ItisvitalthatweloadLibStubfirst,sincealltheotherlibsdependonthat.ThenCallbackHandlerthatisusedbyseveralofourlibrariesandAceGUIneeds
tobeloadedbeforeAceConfig.Otherwisetheorderisn'timportant,buttobesafe,thecorrectloadordercanbefoundintheAce3.toc
(http://forums.wowace.com/showthread.php?p=299390#post299390)file.
Nowlet'supdatethe.TOCfiletoincludetheembeds.xml.WeincludeitaboveCore.luatoensurethatthelibrariesareloadedandavailablebeforethecode
inCore.luaisexecuted.
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
2/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
##XEmbeds:Ace3
embeds.xml
Core.lua
I'veincludedafewotherthingsinthe.TOCthataren'tactuallyrequiredyet(e.g.SavedVariables),butwewillneedallofthateventually.The
OptionalDepspartisthereincaseauserofyouraddoncomesalonglaterandchoosestouseastandaloneAce3insteadofusingtheembeddedlibrariesin
yourLibsfolderandtheXEmbedsistheretotellupdaterswhatlibsitneedstodownloadseparatelyiftheuserdon'twanttousetheembeddedlibs.
SayingHello
Thissectionisgoingtomovealittlefasterthanwehavebeenmoving.StartbyopeningCore.luainatexteditorandtypinginthefollowingcode:
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0")
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
end
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
end
functionWelcomeHome:OnDisable()
Calledwhentheaddonisdisabled
end
ThisisthebasicstartingstructureofanAce3addon.ThefirstlinecreatesaninstanceoftheAceAddonclassusingtheNewAddon
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waceaddonnewaddonobjectnamelib)method.Sincewewillalsobeprintingtothe
chatwindowandacceptingslashcommands,I'vegoneaheadandincludedthemixinforAceConsole.Amongotherthings,thiswillgetusaccesstothe
Print(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/#waceconsoleprintchatframe)method.Therealsoisprint
(http://www.lua.org/manual/5.1/manual.html#pdfprint)(withlowercasep),whichisabasicLuafunction
Mixins(http://en.wikipedia.org/wiki/Mixin)areaconceptcommoninmanyobjectorientedlanguagesthatallowyoutobringadditionalfunctionalityinto
yourclass.We'reusingLibStub(http://www.wowace.com/addons/libstub/)forembedding/mixinginourlibraries
Followingthatarethreemethod(http://old.wowace.com/wiki/Coding_Tips#Methods)overrides:OnInitialize,OnEnable,andOnDisablerespectively.
ThefirstisexecutedonlyoncewhentheUIloadsandthenexttwoareexecutedwhentheaddonisenabledanddisabled.(YoucanEnable
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waddonenable)andDisable(http://www.wowace.com/addons/ace3/pages/api/ace
addon30/#waddondisable)Aceaddonsatwill.)
ItisimportanttonotethatOnEnableiscalledatthebeginningiftheaddonisenabledwhentheUIloads.Youwilloftenhavetochoosewhichofthesetwo
methodoverridestouse.Generally,youshouldusetheOnInitializeforthosethingsthatyoudon'tneedtoundoandredoiftheaddonisdisabledand
enabled.Anotherimportantpartofthisdecisionhastodowithwhatotherthingsyouwillneedandwhenyoucanbesuretheyareready.Moreonthis
later...
Justtodemonstratethattheaddonisloading,wewillhavetheaddonprint"HelloWorld!"tothechatwindowbyaddingonelineofcodetotheOnEnable
method.
functionWelcomeHome:OnEnable()
self:Print("HelloWorld!")
end
GoaheadandrestartWoWandenterintothegame.Onceyouarein,youshouldbeabletoscrollupinthechatwindowandfindyourmessage.Youare
nowtheproudauthoroftheWoWversionofHelloWorld!.
Beforewegoanyfurther,gobackovertoyourcodeandremovetheprintmessage.ItisgenerallyconsideredbadAceformforyouraddontotossabunch
oftextintothechatwindowjustbecauseithasloaded.Toomanyaddonsdothisalreadyandthereareotherways
(http://www.wowace.com/addons/ace3/pages/api/aceaddon30/#waceaddoniterateaddons)tofindoutwhatAceaddonshaveloaded.Youcanalso
removetheOnDisablemethodsincewewon'tbeusingit.
RespondingtoEvents
So,asIsaid,thisaddonwillgiveawelcomemessagetotheplayerwhentheyarriveintheirhomezone.Howwillweknowtheyareintheirhomezone?
Simple,wewillrespondtooneoftheZONE_CHANGEDeventswhichthegamefireswhentheplayerentersanewzone.
ImsureyouareaskingyourselfEvents?Whattheheckarethose?Itturnsoutthatlikemanyotherprogrammingenvironments,WoWiseventdriven.
Eventsareraisedwhenthingshappeninthegameandyoucanfireeventswhenthingshappeninyourcode.Infact,withoutevents,youraddonwould
neverevenknowwhattodoandwhentostartdoingthings.Eventually,everythingyouraddondoesisinresponsetoanevent.
ItappearsthatZONE_CHANGEDwillbetheonewewant,solet'shookthatonebymakingafewchangestoourCore.luafile.
Beforewecansubscribetoevents,weneedtogeteventsupportintoouraddonbyincludinganothermixinintoouraddon.Weneedtochangetheline
wherewecreateouraddontoincludetheAceEventmixin.Changeyourfirstlineasshownhere:
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
3/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
Oncewe'vedonethat,wewillusetheRegisterEvent(http://www.wowace.com/addons/ace3/pages/api/aceevent30/#waceeventregistereventevent
callbackarg)methodthatisnowavailabletoustosubscribetotheZONE_CHANGEDevent.WewillreplacetheOnEnableoverridewiththefollowing
code:
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
self:RegisterEvent("ZONE_CHANGED")
end
Wealsoneedtoaddintheeventhandlerforthateventbyaddingthefollowingcodetoour<fontcolor="#DDA0DD">Core.lua</font>file:
functionWelcomeHome:ZONE_CHANGED()
self:Print("Youhavechangedzones!")
end
YoumightbewonderingifweshouldcallUnregisterEvent(http://www.wowace.com/addons/ace3/pages/api/aceevent30/#waceeventunregisterevent
event)fromourOnDisableoverride,butwedon'thavetodothatbecauseAceEventdoesitforus.
Nowheadbackintothegameandhaveyourcharacterleavetheareahe/sheispresentlyin.Youshouldseeyourmessagegobydowninthechatareawhen
youchangezone.
ReloadingYourAddonWithoutRestartingWoW
Beforewegoanyfurther,Iwanttoshowyouatrickthatwillcomeinhandyforyouasyouworkonyouraddons.
Leavethegameupandrunning,butswitchovertoyourtexteditor.Changetheeventhandlerasfollows...
functionWelcomeHome:ZONE_CHANGED()
self:Print("Thisisadifferentmessage!")
end
Makesureyousaveyourchangesandthengobackovertothegameandswitchzones.Whichmessagedidyousee?Theoldone.
Why?BecauseWoWdoesn'tautomaticallyreloadyouraddonjustbecauseyoumadeachange.Onewaytogetyouraddonreloadedistorestartthegame.
Ugh.Amuchbetterwaytogetitreloadedisbyentering:
/reload
YourscreenwillfreezeforaminutewhiletheUIreloadsitselfandallyourotheraddonsreload,butwhenitcomesbackupyoushouldnowbeableto
switchzonesandseethenewmessage.
Fromnowonyoucanusethistechniquetoreloadyourmodwhenyouhavemadechanges.
Note:ifyouhaveAceConsole2.0(http://old.wowace.com/wiki/AceConsole2.0)loadedwithanyofyouraddonsorifyouhavethestandaloneversionof
Ace3(http://www.wowace.com/addons/ace3/),youcanusethefollowingcommandtoreloadyourUI:
/rl
WorkingwiththeWoWAPI
Wenowhaveamethodthatweknowwillgetcalledwhentheplayerchangeszones.Butwhatzoneishein?Wheredoeshekeephishearthstoneset?
IfweheadbackovertotheWorldofWarcraftAPIpageandlookintheCharacterFunctionssection,wewillseetheanswertothesecondquestionisa
functioncalledGetBindLocation.Thisfunctionreturnsthesubzonename(e.g."TarrenMill")thatcontainstheInnwhereyourhearthstoneisset.
Nextweneedtofigureouthowtofindwhatsubzonewearein.IfwelookintheLocationFunctionssectionoftheAPIdocs,wewillfindafunctioncalled
GetSubZoneTextthatlooksaboutright.Itreturnseitheranemptystring(ifyouaren'tinasubzone)orthenameofthesubzoneyouarein.
Weshouldbeabletosimplycomparethesetwovaluesinoureventhandlertodecidewhetherwearehomeornot:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
self:Print("WelcomeHome!")
end
end
That'sit!Weshouldnowhaveafunctionaladdondoingwhatwewant.ReloadyourUIandtestitout.
ChatCommandsandConfiguration
Buttherearestilllotsofinterestingthingswecando.Let'sstartbyaddingsupportfortheoutoftheboxslashcommandsbycreatinganoptionstableat
thetopofthefileandregisteringitwithAceConfig3.0(http://www.wowace.com/addons/ace3/pages/api/aceconfig30/):
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type='group',
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
4/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
args={
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options,{"welcomehome","wh"})
end
Atthispointtheoptionstableisemptyandwehaven'tprovidedanycommands.Foracompleterundownofthestructureoftheoptionstable,visitthe
AceConfig3.0OptionsTables(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/)page.
IfyoureloadtheUIandtype/welcomehomeor/wh,youshouldnowseeahelpmessageinyourchatboxthatprintstheAddonname,descriptionand
availablecommands.
Nowletsaddacommandthatletstheuserchangethetextthatisdisplayedbyupdatingtheoptionstable:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name="Message",
desc="Themessagetobedisplayedwhenyougethome.",
usage="<Yourmessage>",
get="GetMessage",
set="SetMessage",
},
Pageissafe
},
}
TotalSecurity2015
Thiswilldefineanewslashcommandcalledmsgthattakesatextargumentandusesthefunctionsnamedtogetandsettheunderlyingvariables.Let's
quicklywritethosemethods:
functionWelcomeHome:GetMessage(info)
returnself.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.message=newValue
end
Note:Usingtheinfo(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/#wcallbackhandling)argumentisanadvancedtopic,for
beginnersit'senoughtoknowthatthereissuchanargument,sojustignoreituntilyougetmorefamiliarwithAceConfig.
ThenreloadyourUIandtype/whtoseethecommand.Noticethatatthispointthereisnovalueforthemessagestring.Thatisbecausewedidn'tprovidea
default.WecanfixthatbyaddingthefollowinglinerightafterthecalltoRegisterOptionsTable(http://www.wowace.com/addons/ace3/pages/api/ace
config30/#waceconfigregisteroptionstableappnameoptions):
WelcomeHome.message="WelcomeHome!"
Thefinalstepistochangetheprintlineinoureventhandlertousethenewmessage:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
self:Print(self.message)
end
end
Playaroundwithitforalittlewhileandseehowitworks.
GUIandBlizzardInterfaceOptions
Butwhystopatchatcommands?AllcooladdonshaveaGraphicalUserInterfacethesedayssoWelcomeHomeshouldn'tbeanydifferent!WhenBlizzard
remadetheirInterfaceOptionsinPatch2.4theyintroducedtheabilityforaddonstoaddtheiroptionstothe"AddOns"tab.Forthisweneedfirsttohandle
ourchatcommandsslightlydifferent.
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self:RegisterChatCommand("welcomehome","ChatCommand")
self:RegisterChatCommand("wh","ChatCommand")
WelcomeHome.message="WelcomeHome!"
end
Nowtoincludeouraddonoptionstothe"Addons"tab,allweneedtodoiscalltheAceConfigDialog3.0
(http://www.wowace.com/addons/ace3/pages/api/aceconfigdialog30/)methodAddToBlizOptions(http://www.wowace.com/addons/ace3/pages/api/ace
configdialog30/#waceconfigdialogaddtoblizoptionsappnamename).ThismethodreturnsaframeweneedtospecifylatertoopentheBlizzard
InterfaceOptionsatthepageforouroptions,sowesaveitinself.optionsFrame.
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
5/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
WelcomeHome.message="WelcomeHome!"
end
HereweusetheAceConsolemethodRegisterChatCommand(http://www.wowace.com/addons/ace3/pages/api/aceconsole30/#waceconsoleregister
chatcommandcommandfuncpersist)tomake/welcomehomeand/whcallourChatCommandmethodinstead.Inthisfunctionwecandowhateverwe
want.AndwewantAceConfigDialogtoopenaGUIforouroptionsifthere'snootherinput,otherwisewe'llletAceConfigCmdhandletheinputlikeit
wouldbefore.ThiswaywehavebothaGUIandchatcommands(usingthesameoptionstable)soouruserscanusewhatevertheyplease.
functionWelcomeHome:ChatCommand(input)
ifnotinputorinput:trim()==""then
InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
else
LibStub("AceConfigCmd3.0"):HandleCommand("wh","WelcomeHome",input)
end
end
Tryitnowandseehowitworks.
MakingtheMessageMoreProminent
Nowthatwehavetheaddonworking,let'stweakitabit.Let'saddawaytodisplaythemessagesomewherethatisabitmoreprominent.Todothiswewill
showthemessageinaframecalledUIErrorsFrameandaddsomenewoptionstolettheuserdecidewhattheywant.
Note:I'mgoingtoassumethatyouarestartingtofigurethisoutandcanfigureoutwherethiscodegoes.
Firstthenewoptionstable:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name="Message",
desc="Themessagetexttobedisplayed",
usage="<Yourmessagehere>",
get="GetMessage",
set="SetMessage",
},
showInChat={
type="toggle",
name="ShowinChat",
desc="Togglesthedisplayofthemessageinthechatwindow.",
get="IsShowInChat",
set="ToggleShowInChat",
},
showOnScreen={
type="toggle",
name="ShowonScreen",
desc="Togglesthedisplayofthemessageonthescreen.",
get="IsShowOnScreen",
set="ToggleShowOnScreen"
},
},
}
Thenthenewdefaultvalues:
WelcomeHome.showInChat=false
WelcomeHome.showOnScreen=true
Implementationsofthenewcommand'sget/setmethods:
functionWelcomeHome:IsShowInChat(info)
returnself.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.showOnScreen=value
end
Andfinallytheneweventhandlermethod:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.showInChatthen
self:Print(self.message)
end
ifself.showOnScreenthen
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
6/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
UIErrorsFrame:AddMessage(self.message,1.0,1.0,1.0,5.0)
end
end
end
Note:SeeScrollingMessageFrame:AddMessageformoreinfo.
SavingConfigurationBetweenSessions
Onethingyoumayhavenoticedisthatyoursettingsaboutwheretoshowthemessagearen'tpersistedbetweensessions.Whenyoulogoutandbackin,you
willhavethedefaultsettingsagain.Thisisn'tideal.Weshouldbesavingthesesettingssomehow.
WoWprovidesawayforyoutodothiscalledSavedVariables,butthereisanAcewaytodoitwiththeAceDBmethod,New
(http://www.wowace.com/addons/ace3/pages/api/acedb30/#wacedbnewtbldefaultsdefaultprofile).Wealreadyhavethelibrarylistedinour.TOC
file,andnowit'stimetouseit.
localdefaults={
profile={
message="WelcomeHome!",
showInChat=false,
showOnScreen=true,
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
self.db=LibStub("AceDB3.0"):New("WelcomeHomeDB",defaults,true)
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
end
(InthisexampleweassociatethesevariableswiththeAce3profile"datatype",butyoualsocanassociatethemwithchar,class,race,faction,realmor
global.SeetheAceDB3.0(http://www.wowace.com/addons/ace3/pages/api/acedb30/)docsformoreinformationondatatypes.)
Thestring"WelcomeHomeDB"referstotheSavedVariablesdefinitionintheTOCfile.Ifyoudon'tspecifyanythingforthethirdargumentallcharacters
usingtheaddonwillgettheirownprofile.Herewepassthebooleantrue.Thismeansthatunlessyouchangeprofilemanuallyallcharacterwillsharethe
same"Default"profile.
Afterthatweneedtoreplaceallofthereferencestotheoldvariables(e.g.self.messageorWelcomeHome.message)withself.db.profile.<variablename>
(e.g.self.db.profile.message).Thiswillrequireustochangetheget/setmethodsreferencedbyouroptionstableandoureventhandler.
Herearethenewcommandget/setmethods:
functionWelcomeHome:GetMessage(info)
returnself.db.profile.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.db.profile.message=newValue
end
functionWelcomeHome:IsShowInChat(info)
returnself.db.profile.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.db.profile.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.db.profile.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.db.profile.showOnScreen=value
end
Andhereistheneweventhandler:
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.db.profile.showInChatthen
self:Print(self.db.profile.message);
end
ifself.db.profile.showOnScreenthen
UIErrorsFrame:AddMessage(self.db.profile.message,1.0,1.0,1.0,5.0)
end
end
end
Asyoucansee,itwasjustasimplesubstitutionoftheoldvariablewiththenewAceDBvariable.ReloadyourUIandnothingshouldchange.Exceptnow
ifyouchangeanyofthesettings,theywillbepersistedacrossrestarts.
Thiswholeexercisewasabitsilly,ofcourse,becauseinarealworldaddonyouwouldstartoutusingAceDBforyourconfigurationdata,butnowyou
knowwhatitisforandwhyyoushouldbeusingit.
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
7/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
LocalizingYourStringswithAceLocale
Onethingalotofnewaddondevelopers(especiallythoseintheU.S.)forgetaboutishowmanypeoplewillbewantingtousetheiraddoninanonenglish
versionofthegameclient.Thismeansthatthereshouldbeaniceeasywayforthemtolocalizethestringsinyouraddonintotheirlanguage.(Oreven
better,submitthelocalizedstringstoyousoyoucanincludetheminyournextrelease.)
WithAce3,wedothisusingtheAceLocale3.0(http://www.wowace.com/addons/ace3/pages/api/acelocale30/)library.Thislibraryisnotamixinlike
theotherlibrarieswe'veusedsofar,sothewayweuseitisabitdifferent.
AddingAceLocale3.0totheProject
Let'sstartbygrabbingtheAceLocale3.0folderfromthepackagethatwedownloadedearlierandputtingitintoourLibsfolder.Wealsoshouldcreateour
firstlocalizationdatabasefile.CreateanemptyfilecalledenUS.luaandsaveitinthesamefolderasyour.TOCfile.
Atthispointourfolderstructureshouldlooklikethis:(Seetheoriginal(http://old.wowace.com/wiki/WelcomeHome_
_Your_first_Ace3_Addon#Adding_AceLocale3.0_to_the_Project)forabetterview)
WelcomeHome
Libs
AceAddon3.0
AceAddon3.0.lua
AceAddon3.0.xml
AceConfig3.0
AceConfigCmd3.0
AceConfigDialog3.0
AceConfigDropdown3.0
AceConfigRegistry3.0
AceConfig3.0.lua
AceConfig3.0.xml
AceConsole3.0
AceConsole3.0.lua
AceConsole3.0.xml
AceDB3.0
AceDB3.0.lua
AceDB3.0.xml
AceEvent3.0
AceEvent3.0.lua
AceEvent3.0.xml
AceGUI3.0
widgets
AceGUI3.0.lua
AceGUI3.0.xml
AceLocale3.0
AceLocale3.0.lua
AceLocale3.0.xml
CallbackHandler1.0
CallbackHandler1.0.lua
CallbackHandler1.0.xml
LibStub
LibStub.lua
Core.lua
embeds.xml
enUS.lua
WelcomeHome.toc
Then,weneedtoupdateourembeds.xmlfiletoreferencetothenewlyaddedAceLocale3.0asshownhere:
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceLocale3.0\AceLocale3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>
Andour.TOCfile:
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3
##XEmbeds:Ace3
embeds.xml
enUS.lua
Core.lua
NoticethatthelocalizationfilecomesbeforetheCore.luafile.Thisisimportantoryourlocalizationdatabasewillnotbeinitializedbeforeitisusedbythe
codeinyouraddon.
Sincewehaveupdatedour.TOCfile,youwillneedtorestartWoWtogetthesechangesloadedintothegame.The/reloadtrickwon'tworkthistime.Once
you'vedonethat,goaheadandloginandmakesureeverythingisstillworking.
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
8/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
BuildingtheLocalizationDatabase
NowthatwehaveaplacetoputthelocalizedstringsfortheUSEnglish(enUS)versionofourAddon,weneedtopassthroughthesourcecodelookingfor
stringsthatshouldbelocalizable.(Inyourfutureaddonwork,Iwouldrecommendgoingaheadanddoingthisstepatthebeginningofyourdevelopment
insteadofwaitinguntiltheendaswedidhere.)
AftertakingapassthroughCore.lua,IaddedthefollowinglinestoenUS.lua:
localL=LibStub("AceLocale3.0"):NewLocale("WelcomeHome","enUS",true)
Chatcommands
L["welcomehome"]=true
L["wh"]=true
L["WelcomeHome!"]=truedefaultmessage
L["Message"]=true
L["Themessagetobedisplayedwhenyougethome."]=true
L["<Yourmessage>"]=trueusage
L["ShowinChat"]=true
L["Togglesthedisplayofthemessageinthechatwindow."]=true
L["ShowonScreen"]=true
L["Togglesthedisplayofthemessageonthescreen."]=true
Thisfilehastwoparts.ThefirstpartcreatesanewAceLocaleinstancewiththename"WelcomeHome"."enUS"isthelanguagecodeforUSEnglishand
trueasthethirdargumenttellsAceLocalethatthisisthedefaultlocale.Thesecondpartistheactualtranslations.Havingthevaluesbetruemakesthem
thesameastheirkeys.Thismeansthatinourcode,whenweaskforthelocalizedversionof"WelcomeHome!",wewillget"WelcomeHome!",oranother
stringdependingonthelanguage.
UsingtheLocalizedStringsintheAddon
TouseAceLocaleinouraddonnowweaskAceLocaleforaninstancewithtranslationsanditwillgiveusatableforthecurrentlocaleorthedefaultifit
doesn'thaveatranslationforthelanguagetheuserisplayingin.
Now,addthefollowinglinetothetopofCore.lua,thiscallstheGetLocale(http://www.wowace.com/addons/ace3/pages/api/acelocale30/#wacelocale
getlocaleapplicationsilent)method(besureyouadditabovetheoptionstabledefinition).
localL=LibStub("AceLocale3.0"):GetLocale("WelcomeHome")
NowwecanusethisanywhereweneedatranslatedstringbyputtingL[]aroundit.Forexamplethefirstpartofouroptionstablenowbecomesthis:
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name=L["Message"],
desc=L["Themessagetobedisplayedwhenyougethome."],
usage=L["<Yourmessage>"],
get="GetMessage",
set="SetMessage",
},
...etc...
Thisprocessisprettystraightforward,soIwon'tbothershowingallofithere.Youcanseethefinalsourcefilesattheendofthearticletoseeifyougot
themallinyouraddon.
UsingAceLocaleisasimplewaytogetgoodlocalizationsupportinyouraddon.[1](http://kb.wowace.com/projects/localizingyourproject/)
Mixedinvariables
Ifyouwanttousetextelementsmixedwithvariablesfordifferentoutputyoucanalsousefunctionsinyourlocaletable.Sothewordortextelementorder
doesnotmatterinyourscriptandtranslationswillsoundmorenatural.
enUS/enGB:
L['WeheartlywelcomeplayerX.']=function(X)
return'Weheartlywelcomeplayer'..X;
end
deDE:
L['WeheartlywelcomeplayerX.']=function(X)
return'Wirhei\195\159enSpieler'..X..'herzlichWillkommen';
end
script.lua:
self:Print(L['WeheartlywelcomeplayerX.'](playername));
Conclusion
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
9/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
Youhavestartedfromnothingandcreatedalocalizableaddonthatuseschatcommands,respondstoeventsandprovidesfeedbacktotheuserinacouple
ofdifferentways.Thereareanumberofinterestingthingsyoucandotothisaddonifyouwanttokeepgoing.Someexamples:
Provideaconfigurationmenu(http://www.wowace.com/addons/ace3/pages/aceconfig30optionstables/),inadditiontoslashcommands
AddsupportforLibDataBroker(https://github.com/tekkub/libdatabroker11/wiki/)forine.g.DataDisplayAddOns[2]
(http://forums.wowace.com/showthread.php?t=14903)
Showdifferentmessageswhenyouzoneintootherareas(e.g."WelcometoTheBadlands,HomeofUldaman!")
YoumightalsowanttoreadWowAce'sCodingTips(http://old.wowace.com/wiki/Coding_Tips)page,whichcanproveveryuseful.
HopefullythathelpsyougetstartedwithAce3developmentandleadsyoudowntheroadtosuccessfuladdonauthoring.Bestofluck!
JointheAceCommunity
AsyougetmoreinterestedinAce3development,youshouldconsidergettinginvolvedintheAcecommunityatwowace.com(http://www.wowace.com)
Thereisanumberofresourcesavailable:
Versioncontrol(http://en.wikipedia.org/wiki/Revision_control)serverforSubversion(http://en.wikipedia.org/wiki/Apache_Subversion),Git
(http://en.wikipedia.org/wiki/Git_%28software%29),orMercurial(http://en.wikipedia.org/wiki/Mercurial)[3]
(http://old.wowace.com/wiki/What_is_the_SVN%3F)[4](http://kb.wowace.com/projects/packaginganaddon/)
Webbasedforum(http://forums.wowace.com/)
IRCchannel(http://kb.wowace.com/ircinformation/)
Wiki(http://old.wowace.com/wiki/Main_Page)fullofdocumentationandhelp
YoualsoshouldconsiderpublishingyourAce3addonatwowinterface.com(http://www.wowinterface.com/).
FinalSourceFiles
HereisthefinalcontentsofWelcomeHome.toc,embeds.xml,Core.luaandenUS.luaincaseyouwanttocheatandgorighttotheend.
WelcomeHome.toc
##Interface:40200
##Version:0.1
##Title:WelcomeHome
##Author:YourNameHere
##Notes:Displaysawelcomemessagewhenyougettoyourhomezone.
##SavedVariables:WelcomeHomeDB
##OptionalDeps:Ace3
##XEmbeds:Ace3
embeds.xml
enUS.lua
Core.lua
embeds.xml
<Uixmlns="http://www.blizzard.com/wow/ui/"xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
<Scriptfile="Libs\LibStub\LibStub.lua"/>
<Includefile="Libs\CallbackHandler1.0\CallbackHandler1.0.xml"/>
<Includefile="Libs\AceAddon3.0\AceAddon3.0.xml"/>
<Includefile="Libs\AceEvent3.0\AceEvent3.0.xml"/>
<Includefile="Libs\AceDB3.0\AceDB3.0.xml"/>
<Includefile="Libs\AceLocale3.0\AceLocale3.0.xml"/>
<Includefile="Libs\AceConsole3.0\AceConsole3.0.xml"/>
<Includefile="Libs\AceGUI3.0\AceGUI3.0.xml"/>
<Includefile="Libs\AceConfig3.0\AceConfig3.0.xml"/>
</Ui>
Core.lua
WelcomeHome=LibStub("AceAddon3.0"):NewAddon("WelcomeHome","AceConsole3.0","AceEvent3.0")
localL=LibStub("AceLocale3.0"):GetLocale("WelcomeHome")
localoptions={
name="WelcomeHome",
handler=WelcomeHome,
type="group",
args={
msg={
type="input",
name=L["Message"],
desc=L["Themessagetobedisplayedwhenyougethome."],
usage=L["<Yourmessage>"],
get="GetMessage",
set="SetMessage",
},
showInChat={
type="toggle",
name=L["ShowinChat"],
desc=L["Togglesthedisplayofthemessageinthechatwindow."],
get="IsShowInChat",
set="ToggleShowInChat",
},
showOnScreen={
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
10/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
type="toggle",
name=L["ShowonScreen"],
desc=L["Togglesthedisplayofthemessageonthescreen."],
get="IsShowOnScreen",
set="ToggleShowOnScreen",
},
},
}
localdefaults={
profile={
message=L["WelcomeHome!"],
showInChat=false,
showOnScreen=true,
},
}
functionWelcomeHome:OnInitialize()
Calledwhentheaddonisloaded
self.db=LibStub("AceDB3.0"):New("WelcomeHomeDB",defaults,true)
LibStub("AceConfig3.0"):RegisterOptionsTable("WelcomeHome",options)
self.optionsFrame=LibStub("AceConfigDialog3.0"):AddToBlizOptions("WelcomeHome","WelcomeHome")
self:RegisterChatCommand("wh","ChatCommand")
self:RegisterChatCommand("welcomehome","ChatCommand")
end
functionWelcomeHome:OnEnable()
Calledwhentheaddonisenabled
self:RegisterEvent("ZONE_CHANGED")
end
functionWelcomeHome:ZONE_CHANGED()
ifGetBindLocation()==GetSubZoneText()then
ifself.db.profile.showInChatthen
self:Print(self.db.profile.message)
end
ifself.db.profile.showOnScreenthen
UIErrorsFrame:AddMessage(self.db.profile.message,1.0,1.0,1.0,5.0)
end
end
end
functionWelcomeHome:ChatCommand(input)
ifnotinputorinput:trim()==""then
InterfaceOptionsFrame_OpenToCategory(self.optionsFrame)
else
LibStub("AceConfigCmd3.0"):HandleCommand("wh","WelcomeHome",input)
end
end
functionWelcomeHome:GetMessage(info)
returnself.db.profile.message
end
functionWelcomeHome:SetMessage(info,newValue)
self.db.profile.message=newValue
end
functionWelcomeHome:IsShowInChat(info)
returnself.db.profile.showInChat
end
functionWelcomeHome:ToggleShowInChat(info,value)
self.db.profile.showInChat=value
end
functionWelcomeHome:IsShowOnScreen(info)
returnself.db.profile.showOnScreen
end
functionWelcomeHome:ToggleShowOnScreen(info,value)
self.db.profile.showOnScreen=value
end
enUS.lua
localL=LibStub("AceLocale3.0"):NewLocale("WelcomeHome","enUS",true)
Chatcommands
L["welcomehome"]=true
L["wh"]=true
L["WelcomeHome!"]=truedefaultmessage
L["Message"]=true
L["Themessagetobedisplayedwhenyougethome."]=true
L["<Yourmessage>"]=trueusage
L["ShowinChat"]=true
L["Togglesthedisplayofthemessageinthechatwindow."]=true
L["ShowonScreen"]=true
L["Togglesthedisplayofthemessageonthescreen."]=true
Attribution
ThisisanimportfromWelcomeHomeYourfirstAce3Addon(http://old.wowace.com/wiki/WelcomeHome__Your_first_Ace3_Addon),whichisa
continuationfromWelcomeHomeYourfirstAce2Addon(http://old.wowace.com/wiki/WelcomeHome__Your_first_Ace2_Addon)
Retrievedfrom"http://wow.gamepedia.com/index.php?title=WelcomeHome__Your_first_Ace3_Addon&oldid=2809447"
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
11/12
3/7/2016
WelcomeHomeYourfirstAce3AddonWowpediaYourwikiguidetotheWorldofWarcraft
Sign In
About Curse
Register
Advertise
Youtube
Careers
Terms of Service
Newsletter
Help
Privacy
Policy
http://wow.gamepedia.com/WelcomeHome__Your_first_Ace3_Addon
12/12