插件文件夹的内容
所有魔兽世界的插件都必须位于Interface/Addons/目录下. 只有位于此目录中的程序才会被加载. 在此目录中除了玩家自行安装的插件外, 还有一些是暴雪默认的界面.
暴雪默认插件
绝大多数默认用户界面中的功能通过默认插件来实现, 这些插件被放在独立的几个目录中, 只有在需要的时候才从外部读入. 例如, Blizzard_AuctionUI是拍卖行的默认插件, 只有在玩家访问拍卖师的时候才会被加载. 这样的设计可以有效地减少游戏登陆时的插件加载时间.
以下是所有由玩家行为触发加载的默认插件列表.
插件名称 触发条件
Blizzard_AuctionUI 当玩家访问拍卖师时
Blizzard_BattlefieldMinimap 在玩家按下绑定的按键 或Shift点击战场
或竞技场图标试图显示战场小地图时
Blizzard_BindingUI 当玩家打开主菜单的键位设定界面时
Blizzard_CombatText 当玩家开启浮动战斗文字选项时
Blizzard_CraftUI 当玩家执行需要此插件的特定功能(附魔等)时
Blizzard_GMSurveyUI 当玩家和游戏管理者交流过后被要求完成服务调查时
Blizzard_InspectUI 当玩家试图观察另一位玩家时
Blizzard_ItemSocketingUI 当玩家Shift右击一件装备, 试图对其插入宝石时
Blizzard_MacroUI 当玩家开启宏编写界面时
Blizzard_RaidUI 当玩家加入一个团队时
Blizzard_TalentUI 当玩家打开天赋界面时
Blizzard_TradeSkillUI 当玩家打开商业技能界面时
Blizzard_TrainerUI 当玩家访问一位训练师时
每一个暴雪默认插件均有一个自己的*.pub文件, 文件名同其插件相同. 此文件是暴雪的一种数字签名, 用来表示该插件由暴雪开发, 是安全插件.
按需加载插件是加快游戏加载速度的一种非常有效的方法.
自定义插件
所有的自定义插件也都位于Interface/Addons目录下, 并各自拥有独立的子目录. 插件目录的命名没有任何限制.
插件的成员
每个插件目录下的文件都会有一些不同, 但有一些成员则非常相似. 下面的部分记录了一个插件可能包含的各种文件.
成员列表(Table of Content, 后缀名*.toc)
这是一个必须包含在插件目录中的文件, 其名字与插件相同. TOC文件提供了插件的一些基本信息, 包括标题, 描述, 作者等等, 以及文件列表.
以下是一个TOC文件的例子:
## Interface: 20300
## Title: My Addon Name
## Notes: This is my sample addon
MyAddon.xml
MyAddon.lua
以下将逐行解释这段代码.
## Interface: 版本号
这个标签提供插件的版本数据. 如果插件的版本不对应当前游戏版本, 游戏可能将插件标示为:
· 过期(Out of date): 客户端的版本比插件新, 插件的功能可能不能正常运作, 但可以强制加载该插件, 该插件的功能可能依然可以运作.
· 不兼容(Incompatible): 客户端将不会加载这个插件, 因为它对应的版本后游戏UI有过大的改动, 该插件无法正常运作.
插件版本数字和游戏版本的对应规则是: 将游戏版本中的所有点都换成0, 例如和2.3.0版客户端同版本的插件版本号是20300.
## Title: 插件名
插件在插件列表中所显示的名称是由这条标签决定的, 而非插件目录的目录名. 在未添加该标签时, 游戏将选择插件所在目录的目录名作为插件名称.
此标签还支持根据客户端的不同对插件名进行本地化, 这个时候使用 Title-区域名称 代替Title标签. 例如, 可以用这样的语句设置在韩文客户端中显示的插件名称:
## Title-koKR: My Addon Name
合法的区域名称包括: deDE(德文), enUS(美式英语), enGB(英式英语), esES(西班牙语), frFR(法语), koKR(韩语), zhCN(简体中文), zhTW(繁体中文).
## Notes: 描述
Notes标签允许插件编写者对插件添加更详细的描述. 在插件列表界面下, 鼠标悬停在插件名称上的时候, 左侧将显示这段描述文字. 同样支持本地化.
## Depencies | ## RequiredDeps: AddonA, AddonB, ...
为了正常工作, 一部分插件需要其他插件的协助. 当插件包含这个标签时, 只有在所有关联插件均被加载时游戏才会加载此插件.
当关联插件缺失或被禁用时, 插件列表界面将相应地显示关联插件缺失/禁用字样.
这个标签还将保证关联插件先被加载.
## OptionalDeps: AddonA, AddonB, ...
和上一个标签类似, 不过顾名思义, 这条指令只影响插件的加载顺序. 列表中的插件缺失或被禁用不会导致插件无法被加载.
## LoadOnDemand: 1 / 0
如前所述, 一部分插件是按需加载(Load On Demand, =LoD)的, 只有在特定行为发生时插件才会被加载, 用以减少游戏的内存消耗. 绝大多数插件的设置界面是按需加载的.
但并不是所有的插件都支持按需加载, 因此需要这个标记来指明. 只有被标记为LoadOnDemand: 1的插件才是支持按需加载的. 如果没有这条指令, 系统将默认该插件不支持按需加载.
## LoadsWith: AddonA, AddonB, ...
一个插件可以通过LoadsWith指令关联几个插件, 当这些插件被客户端加载时, 使用了LoadsWith的插件也将一并被加载.
LoadsWith可以和LoadOnDemand标签搭配使用, 使一个LoD兼容的插件在它的关联插件被加载的同时立刻被加载.
例如, 下面的标签将使系统在加载Blizzard默认团队界面时同时加载该插件.
## LoadsWith: Blizzard_RaidUI
## DefaultState: enabled / disabled
正常情况下, 某个插件被放入插件目录后首次运行游戏时就会被加载(只要没有版本问题). 但是, 有些插件是为特定职业或角色设计的, 开发者可能觉得对其他的职业/角色, 加载这个插件是不必要的. DefaultState标签可以决定一个插件默认是否加载. Enabled代表这个插件被放入插件目录后, 首次运行游戏时, 该插件在插件列表界面中就是被选中的(即会被加载); Disabled则反之.
当玩家在插件列表界面中手动修改加载/不加载设置后, 是否加载将由玩家修改的设置决定, DefaultState指令将不再产生影响.
这个功能在一次性提供打包的多个插件时特别有用. 如果这个标签缺失, 默认其值为Enabled(即装入后首次运行即加载).
## LoadManager: AddonA
这个标签是LoD功能的一个延伸, 表示: 当LoadManager所关联的插件被加载时, 使用LoadManager指令的插件视作LoD兼容, 反之视为LoD不兼容. 看上去有点复杂, 这个标签的实际功能是: 通过挂接另一个插件来管理一个插件的LoD功能.
例如, 插件AddonsLoader被许多插件用来作为LoadManager. AddonsLoader允许开发者在插件的TOC中添加特定的语句, AddonsLoader将识别这些语句并执行对应的功能. 比如, 专为盗贼开发的插件可以在TOC文件中添加以下标签: ## X-LoadOnClass: Rogue, 这样插件只有当游戏角色为盗贼时才会加载. 当然, 这个功能只有玩家安装了AddonsLoader插件时才会实现.
## SavedVariables: VariableName
如果插件需要保存一些变量(例如设置), 就必须在TOC文件中通过SavedVariables标签指明这些变量的名称. 游戏将在关闭时保存这些变量的内容, 并在下次启动时读入. 被储存的变量可以是一个字符串, 一个数字或一个表.
## SavedVariablesPerCharacter: VariableName
同SavedVariables功能基本相同, 不同之处是每个不同的角色会拥有独立的文件储存对应的变量.
非标准指令
有一部分TOC文件中的标签不是官方支持的, 但部分插件可以识别这些标签, 比如:
## Author: 作者名
## Version: 1.0
一个可供参考的信息是: 所有X-开头的标签都是非标准的标签, 并且都支持本地化, 例如:
## X-Website: http://www.myaddon.com
## X-FAQ-Website: http://www.myaddon.com/faq/
## X-FAQ-Website-esES: http://www.myaddon.com/faq/esES
X-Category是一个常用的X标签, 用来指明插件的分类, 例如:
## X-Category: Warrior
下面是通用的插件类别列表: Action Bars(动作条), Auction(拍卖), Audio(音频), Battlegrounds/PVP(战场/PVP), Buffs(增益效果), Caster(施法), Chat/Communication(聊天), Combat(战斗), Compilation(编译), Data Export(数据导出), Development Tools(开发工具), Druid(德鲁伊), Frame Modification(框架修改), Guild(公会), Healer(治疗), Hunter(猎人), Interface Enhancements(界面增强), Inventory(背包), Library(库), Mage(法师), Mail(邮件), Map(地图), Miscellaneous(杂项), Paladin(圣骑士), Priest(牧师), Quest(任务), Raid(团队), Rogue(盗贼), Shaman(萨满), Tank(坦克), Tradeskill(交易技能), UnitFrame(单位框架), Warlock(术士), Warrior(战士).
Lua脚本文件列表
TOC文件中可以列出任意数量的Lua文件, 支持带路径. 所有列出的Lua脚本文件将按列出的顺序被读取、编译并执行, 因此, 可以在不同的文件中定义本地变量, 这些变量显然不能被其他文件获取. 在需要在不同文件间共享数据时, 应注意这一点.
基本上, Lua脚本文件用于定义插件的行为, 而非其视觉样式. 不过, Lua仍然可以用来创建动态的框架.
XML文件列表
TOC文件同时也可以包括任意数量的*.xml文件, 所有这些XML文件中的标签都将按照暴雪提供的模式文件UI.xsd进行加载. 例如, XML文件可以通过<Script file="文件名.lua"/>的标签加载Lua脚本文件. 每一个XML文件都应以<Ui>元素开头(也就是说所有的XML样式文件的根元素都必须是<Ui>):
<Ui xmlns="http://www.blizzard.com/wow/ui"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui/
..\FrameXML\UI.xsd">
</Ui>
所有的XML样式文件加载中出现的错误均会在魔兽世界安装目录下的Logs\FrameXML.log文件中记录下来. 当插件工作异常时, 查阅FrameXML.log可以确保错误不是由非法的XML样式文件引起的.
多媒体文件
插件可以包括图像、声音、字体等多媒体元素, 为插件增加视觉和音响效果. 这些文件必须单独存放在此插件所在的目录下, 在列出时, 则必须书写从魔兽世界安装目录开始的完整路径.
声音文件
例如有一个MP3文件名为mysound.mp3, 作为插件MySound的一部分, 那么它的路径应当是:
Interface\Addons\MySound\mysound.mp3
在游戏中播放时, 可以用下面的命令:
/run PlaySoundFile("Interface\\Addons\\Mysound\\mysound.mp3")
魔兽世界客户端支持MP3及WAV格式的声音文件. 其他声音文件需要转为这两种格式才能播放.
图像文件
在加载框架的纹理图片时，魔兽世界只支援TGA和BLP形式，并且图片必须满足以下要求：宽度及高度在2~512像素间，并且均为2的次幂。例如32x64的图片是合法的，但512*400的图片是不合法的。
BLP格式是暴雪自行开发的图片格式，需要特殊的方法转换为常规工具可编辑的格式。一般除非需要修改默认UI，否则不常使用BLP格式。
插件的本地化
暴雪支持8种不同的本地客户端，其对应代号如下：
代码 语言 代码 语言
deDE 德语 enUS 美国英语
enGB 英国英语 esES 西班牙语
frFR 法语 koKR 韩语
zhCN 简体中文 zhTW 繁体中文
附注：拍卖相关的插件还支持俄语，绝大多数提示信息可以按照此语种本地化。但目前尚未有支持该语种的客户端。
实现本地化的方式，是将所有的界面文字、提示信息等等中的字串，在代码中以变量而非实际字串的方式书写，并提供一个对应不同本地代码用的查找table。除此之外，插件作者还应在插件携带的readme.txt文件及插件代码中添加适当的注释以方便本地化工作者的工作。
实际实行本地化的工作主要包括以下几步：
为每个本地区域建立一个本地化文件
每个本地化区域都要对应一个本地化文件。例如，要对当前插件添加对应美国英语的本地化资料时，需要添加本地化文件Localization.enUS.lua，并置于当前插件*.toc文件的顶部，以保证它被最先加载。第一个加载的本地化文件对应的区域称作基础本地区域(base locale)，在这之后还可以添加更多的本地化文件。
建立基础字符串的全局表
全局表的命名规则是：若插件的名字为MyAddon，则在Localization.enUS.lua中，对应的全局表名为MyAddonLocalization。之后就要向该表内添加基础字符串，添加时的Key可以是两种：完整字符串，或代号。
例如，下面首先声明全局表, 然后添加两条关于框架解锁/锁定的提示信息所用的字符串。
完整字符串作为Key值
MyAddonLocalization = {}
MyAddonLocalization["Frames have been locked"] = "Frames have been locked"
MyaddonLocalization["Frames have been unlocked"] = "Frames have been unlocked"
可以看出在字符串变长后，这种写法将会非常麻烦。
代号作为Key值
MyAddonLocalization = {}
MyAddonLocalization["FRAMES_LOCKED"] = "Frames have been locked"
MyaddonLocalization["FRAMES_UNLOCKED"] = "Frames have been unlocked"
代号法在书写上，明显具有较方便的优势。
在实际代码中使用本地化表
例如，在实际游戏中需要显示上述的提示信息，可以用以下的语句：
ChatFrame1:AddMessage(MyAddonLocalization["Frames have been locked"])
如果是用代号建立的本地化表，则这样书写：
ChatFrame1:AddMessage(MyAddonLocalization["FRAMES_LOCKED"])
如果仍嫌繁琐。还可以建立本地化表的别名：
local L = MyAddonLocalization
ChatFrame1:AddMessage(L["FRAMES_LOCKED"])
在代号法书写的情况下，甚至可以这样简写：
ChatFrame1:AddMessage(L.FRAMES_LOCKED)
添加更多的本地化区域及对应本地化文件
如前所说，其他的本地化文件在TOC文件中应置于基础本地区域的本地化文件之后。在声明本地化表时，与基础区域有所不同：
if GetLocale() == "zhCN" then
if not MyAddonLocalization then
MyAddonLocalization = {}
end
MyAddonLocalization["FRAMES_LOCKED"] = "框架已锁定。"
MyAddonLocalization["FRAMES_UNLOCKED"] = "框架已解锁。"
end
首先检验当前客户端语言是否为对应区域语言，是对应语言才加载本地表；然后判断本地表是否已存在。最后添加本地化字串。
部分翻译缺失
在非基础本地区域的本地化文件中没有被重新翻译的字串，在客户端中将自动显示基础本地区域的本地化文件中的对应字串。
插件的基础结构
综上所述，建立一个全新插件的架构，主要包括以下几部分：
对插件命名并建立目录
例如，插件名为WoWXMLExample，则插件目录为World of Warcraft\Interface\AddOns\WoWXMLExample
建立*.toc文件
最初建立时应包括以下代码，声明版本、插件名、插件描述、所包含文件：
## Interface: 30102
## Title: WoWXMLExample
## Description: Example addon for World of Warcraft Programming
WoWXMLExample.xml
建立基础的*.xml文件
最基础的xml文件应包含以下代码：
<Ui xmlns="http://www.blizzard.com/wow/ui/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.blizzard.com/wow/ui
..\FrameXML\UI.xsd">
</Ui>
浙公网安备 33010602011771号