魔兽世界插件三部曲之一 ---- TOC

老血 · 发表于 2015-7-8 11:53:09

魔兽世界插件三部曲之一 ---- TOC

参考文献：http://www.wowwiki.com/TOC 　　　@Wowwiki (魔兽世界维基百科)

摘要：
《魔兽世界》之所以会被数以千万的玩家所追捧而风靡全球，不仅仅在于它本身游戏内容的丰富和具有可玩性高，操作性强等优点，还在于它有一个比较完善的系统体系。WOW之所以经久的另一个原因就是,BLZ为了让玩家在游戏过程中能更好的适应习惯游戏的操作，改善游戏操作环境而开放了“官方API函数接口”，让玩家可以在开放并授权的代码规则下自己定义自己的用户界面（User Interface，简称UI）。
 从05年运营至今，BLZ力求让游戏中的每一个细节都做到人性化，为此不断完善游戏系统...BLZ知道玩家在游戏过程中会对部分游戏功能和操作的不适应，可能会需要一些第三
方软件来辅助他们游戏，于是乎，便有了WOW API(官方API函数接口)，而事实上，在随着对游戏内容的不断了解和对游戏操作的熟悉后，玩家确实会渐渐的发现一些官方设置不如人意的地方，例如游戏内包裹打开的繁琐，内置动作条的局限，战斗提示的缺失，这些都或多或少影响了玩家游戏的操作性。同时UI接口的开放，让更多的编程爱好者、编程技术人员在休息之余投入到了WOW的插件开发，给WOW又增加了一份新的乐趣。通过游戏一些界面的修改,各种类型的插件辅助完善其游戏本身，以及BLZ在每次更新过程中对API进行的完善修正,可以这么说，WOW已经逐渐演变成续Windows之后的游戏中的"Windows".UI的添加使用,造就了WOW的繁荣，经久不衰...
 不过，UI制作需要了解一些专业的编程知识，因此大部分玩家还没有能力自己制作UI，只有一些熟悉XML和LUA语言的编程爱好者或者一些插件制作工作室能为我们提供他们制作的UI，并且放入WOW文件夹内发挥作用，这被称为X件（AddOn）。插件需要严格按照暴雪所设定的开源函数所编制，并且不能加入任何延时指令，即必须按照以下规则：“任何一个技能的施放必须由一个单独的鼠标或者键盘的物理动作来触发。”这就限制了插件不能做出自动施法的功能。插件并没有任何可执行文件，只是由一些以lua、xml、toc为后缀名的文件组成，将他们装到一个文件夹里，放置到魔兽世界文件夹下由暴雪指定的文件夹里就能够让《魔兽世界》来调用这些文件，这也是插件和非法第三方软件的最大区别。一个正常安全的UI只可能包含LUA、XML、BLP、TGA等脚本及资源文件，绝不可能含有EXE、COM、SCR等等可执行文件和以及.js、.vbs…脚本的，所有的脚本及资源文件全部是在玩家选择人物及载入插件列表后由WOW的脚本解释器编译执行的，这个时候所有的关于用户名及密码的操作都已结束，所以合法的插件是不可能盗号的。就目前来讲，WOW系统的这个LUA脚本语言和WOW UI提供的API接口还没有发现漏洞，所以插件是无法盗取你的帐号的。不过需要注意的是，BLZ虽然开放了WOWAPI，但是并没有承诺对其进行技术支持，所以错误的使用插件可能让游戏不正常甚至出错，如果玩家对插件没有足够的了解，那么建议玩家并不要使用插件。

〓TOC新手教程〓

魔兽世界的插件结构：
< World of Warcraft >(魔兽世界目录)
┗< Interface >
 ┗< Addons >
 ┗< *AddonName* > (以插件名字命名的文件夹)
 ┣*AddonName*.toc (插件的加载信息)
 ┣*AddonName*.xml (插件定义文档)
 ┣*AddonName*.lua (插件脚本文件)
 ┣...

任何一个ADDONS都是由3种文件组成: .LUA .XML .TOC
这里先介绍下*.TOC的结构和写法，TOC全称为Table of Contents，就是目录索引的意思，是ADDONS的标签，就好比是一本书的目录，它将告诉WOW我们所编写插件的名字、作者、版本号、注释、主要文件、依赖文件、保存文件等，所以任何一个ADDONS中TOC文件都是必不可少的。
简单的来说 *.toc中标注了关于插件信息的定义，以及需要加载的*.xml的位置。*.xml是插件的核心，包括界面、功能等元素都在其内。*.lua是一种嵌入式脚本语言，在WoW中实现*.xml调用的函数。换句话说，*.toc告诉WoW插件的名字和*.xml的位置，*.xml告诉WoW插件都有些什么元素，怎么工作，具体如何操作则交由*.lua来处理。

官方注解：
The TOC format for files defines information about each addon installed, as well as specify which .xml and/or .lua files need to be loaded. It is
currently required for an addon to be recognized, show up in the addons list and be loaded. The TOC filename must match the folder name in order for it to be recognized by WoW; however, any other files can be named whatever you want as long as they have the proper extension and are listed in the TOC or in an XML file inside <Script> or <Include> tags.
WoW reads up to the first 1024 characters of each line only. Additional characters are ignored and do not cause an error.

大致翻译如下(E文不是很好，欢迎指正)

TOC文档包含着已安装插件储存的文件信息,它需要由*.xml和*.lua一起被加载工作.TOC的文件名必须和插件的文件夹名保持一致才能被wow导入，包括名字的大小写，而其他文件的名字不管多长都将被列在TOC或者XML文件的<Script> <Include> 标签中
需要注意的是，WoW只能编译1024字节/行，多出的部分将会被忽略而且不会报错。

TOC位置：

World of Warcraft\Interface\AddOns\MyAddon\MyAddon.toc
或
c:\users\games\World of Warcraft\Interface\AddOns\MyAddon\MyAddon.toc

其中高亮部分为你所装插件名称，必须保证文件夹名和文件名完全一致，包括大小写。

客户端识别:

所有标签都必须要以"##"开头，只有Title和Notes标签支持其他语言，除此之外都要用英语书写。

Interface(插件版本号):

获取当前客户端版本号有点麻烦，你当然可以启动游戏然后看看屏幕上显示的一串数字，但那个是错误的。WoW的每次更新会写一个版本号在FrameXML.toc里，但这个文件被埋在一个MPQ中。暴雪为此专门提供了一个工具<A href="http://ftp.blizzard.com/pub/WoW/other/InterfaceAddOnKit_Win.zip" target=_blank>http://ftp.blizzard.com/pub/WoW/other/InterfaceAddOnKit_Win.zip</A> 类似一个解压缩工具，然后用此工具打开World of Warcraft\Data\patch.mpq，文件较大可能需要需要一点时间。打开之后你会看到一个列表，找到Interface\FrameXML\FrameXML.toc，(framexml目录默认是隐藏的，只有用工具才能看见，这也就是为什么部分玩家有时候发现framexml目录错误却在Interface文件夹下找不到此文件夹的原因) 双击用默认的TXT记事本或者notpad之类的文本编辑器打开就可以看到版本号了。
具体方法：见<A href="http://bbs.duowan.com/viewthread.php?tid=14446296&page=2&fromuid=3455227#pid86387625" target=_blank>26楼</A>（点击进入）

复制代码

Title(插件名称):

"frFR": French
"deDE": German
"enUS": American english (what should be "enGB" clients return "enUS", too)
"koKR": Korean
"zhCN": Chinese (simplified)
"zhTW": Chinese (traditional)
"ruRU": Russian (UI AddOn)
"esES": Spanish (Spain)
"esMX": Spanish (Mexico)

复制代码

也可以为名称添加自己喜欢的颜色，WoW支持字串形式的颜色定义。插件管理面板默认字体颜色为黄，你可以根据自己的喜好自行定义文本颜色
颜色字串以"|c"开头"|r"结束。中间为16进制α(alpha透明度) RGB颜色代码和你要显示的文本。

例如：将"我的插件"几个字显示为蓝色。那么就应该是:

##Title: |cff0000ff我的插件|r

复制代码

颜色代码参照：http://www.zhaozi.cn/color.htm

其中|c表示接下来的8位字符是颜色代码，以α(alpha透明度)、R(红)、G(绿)、B(蓝)顺序排列。前面2位ff表示被着色的文本完全不透明（一般都取FF ）
XX表示红色的比率（从00到FF，16进制）
YY表示绿色的比率（从00到FF，16进制）
ZZ表示蓝色的比率（从00到FF，16进制）
不过并非所有的地方都支持透明。代码后面紧跟要显示的文本 "我的插件"，|r表示代码结束，如果没有标记|r，WoW将会把颜色代码应用到这一行结束的全部文本

Note(插件标签):

格式:## Notes: This is my first AddOn.
## Notes-deDE: Informationen
## Notes-zhCN: 这是我的第一个插件。

复制代码
Notes包含对插件的说明内容，也就是对插件功能的简单描述，插件管理面板中鼠标经过插件名称时将会出现此介绍标签

RequiredDeps(依赖插件):

格式:## Dependencies: someAddOn, someOtherAddOn
## RequiredDeps: someAddOn, someOtherAddOn

复制代码
如Grid的GridManaBars模块
## Dependencies: Grid 意为需要Grid核心库的支持

为了让插件更好地工作，某些插件开发者会使用第三方库或其他现成的插件作为基础和辅助，这么做的有点就是节约了开发成本，也使开发过程简便了许多，缺点是，要让插件
正常工作，系统必须确保所依赖的文件都要存在，否则，如果任何依赖的库或插件缺失，当前插件加载都会失败。依赖的名称即依赖插件的名称，也就是目录文件夹的名称。如果
需要依赖多个库或插件，彼此用逗号","隔开。注意大小写一致。
这就是为什么禁用部分插件后，部分插件会因为依赖功能缺失而导致无法加载的原因，用过大脚、精灵之类整合包的玩家应该会有所了解，禁用bigfoot核心文件，将会造成部
分插件功能无法启用，就是这个道理。

Tip: Dependencies、RequiredDeps、Dependancies[sic]效果是一样的。

OptionalDeps(可选依赖库):

格式:## OptionalDeps: someAddOn, someOtherAddOn

复制代码
当前插件为了实现某些附加功能而依赖的外部库或插件，若依赖的库/插件不存在addons下，那么当前插件仍然可以正常工作，但是使用可选依赖的插件就必须在可选依赖存在时
才能正常工作。

LoadOnDemand(命令加载):

格式: ## LoadOnDemand: 1
## LoadOnDemand: 0

复制代码

插件可以用命令来加载，而不用非得在用户第一次登录的时候加载。如果启用这一功能，此插件则必须在某个时候被另一个插件加载。这是为了避免加载一些特殊的不常用的插件而导致内存资源占用，如DBM的一些模块的toc中就有这类命令，在插件管理中启用/禁用相应模块，其实就是通过调整此参数完成的。

LoadWith(跟随加载):

格式:## LoadWith: someAddOn, someOtherAddOn

复制代码
和LoadOnDemand一起用，使你的插件跟随某个插件一起被加载(通常是暴雪自带的UI模块，像Blizzard_AuctionUI)。

SavedVariables(统一的角色信息变量):

位置：/WTF/Account/<account name账号名>/SavedVariables/<addon name插件名>.lua
格式:## SavedVariables: someVariable, someOtherVariable

复制代码
保存的变量是当前流行的存储不同人物角色的方式。这些变量在客户端启动或UI重载(reload)时被载入。SavedVariables标签现以取代RegisterForSave函数，后者已经不再受客户端支持。注意在OnLoad事件过程中，SavedVariables并未完全加载所以必须假设包含nil(空)值直到以插件文件名为参数的ADDON_LOADED事件被触发。
即便插件被禁用或因为错误、版本不匹配等问题没有加载，SavedVariables依然会被保存。所以一般插件的设置相关信息我们都可以通过拷贝WTF文件夹保存下来

SavedVariablesPerCharacter(单独的角色信息变量):

位置：/WTF/Account/<account name账号名>/<realm name服务器>/<character name角色名>/SavedVariables/<addon name插件名>.lua
格式:## SavedVariablesPerCharacter: somePercharVariable

复制代码
SavedVariablesPerCharacter 标签不能区分用于不同的角色. 如果需要, 应使用SavedVariables标签替代.

DefaultState:

格式:## DefaultState: enabled
## DefaultState: disabled

复制代码
这里的enabled/disabled状态被写在WTF\Account\{account name账号名}\AddOns.txt里，并且这个文件会覆盖的DisabledAddOns.txt，后者为了保持兼容仍然会
被老版本的加载。

Secure:

格式:## Secure: 1

复制代码
这个标签被添加到Blizzard_UI。它的确切目的无从知晓，但一种可能就是它告诉客户端是否要为插件寻找一个签名。貌似像智能手机证书签名一样的道理

Non-Standard Tags(非标准标签)：

用##标示还可以添加更多额外的信息，某些第三方插件甚至使用自行提供的信息。下面是一些常用的标签:

AddOn Metadata Tags （插件元数据标签）:

这些标签和Title、Notes放在一起，并可用GetAddOnMetadata("addon", "field")来调用。

Author (作者):

格式: ## Author: MyName

复制代码
作者的名字

Version(插件版本号):

格式: ## Version: 1.0

复制代码
插件的版本号。

X-<data>:

格式## X-email: Author@Domain.com
## X-Foo: I love pancakes
## X-Foo-esES: Te quiero, mi esposa

复制代码
任何以X-开头的标签。代表插件的相关信息

Ace2注视标签:

## X-Revision: 4025
## X-Revision: $Rev$

复制代码
和Ace不一样，Ace2直接从TOC文件提取插件元数据，特定的域(field)进行特定的处理，即Version和X-Date，那么你就可以用CVS和Subversion关键字例如$Rev$作为它们的值。除了正经域以外，它还可以寻找下列自定义的域。

X-Date(插件-日期):

格式: ## X-Date: 07-05-2009

复制代码

插件的发布日期。

X-eMail (插件-邮箱):

格式: ## X-eMail: frankcupid@hotmail.com

复制代码
X-Website: (插件-网站):

格式:## X-Website: http://maplezone.spaces.live.com

复制代码
X-Category(插件-目录):

格式: ## X-Category: Raid

复制代码
local CATEGORIES = {
["Action Bars"] = "Action Bars",
["Auction"] = "Auction",
["Audio"] = "Audio",
["Battlegrounds/PvP"] = "Battlegrounds/PvP",
["Buffs"] = "Buffs",
["Chat/Communication"] = "Chat/Communication",
["Druid"] = "Druid",
["Hunter"] = "Hunter",
["Mage"] = "Mage",
["Paladin"] = "Paladin",
["Priest"] = "Priest",
["Rogue"] = "Rogue",
["Shaman"] = "Shaman",
["Warlock"] = "Warlock",
["Warrior"] = "Warrior",
["Healer"] = "Healer",
["Tank"] = "Tank",
["Caster"] = "Caster",
["Combat"] = "Combat",
["Compilations"] = "Compilations",
["Data Export"] = "Data Export",
["Development Tools "] = "Development Tools ",
["Guild"] = "Guild",
["Frame Modification"] = "Frame Modification",
["Interface Enhancements"] = "Interface Enhancements",
["Inventory"] = "Inventory",
["Library"] = "Library",
["Map"] = "Map",
["Mail"] = "Mail",
["Miscellaneous"] = "Miscellaneous",
["Quest"] = "Quest",
["Raid"] = "Raid",
["Tradeskill"] = "Tradeskill",
["UnitFrame"] = "UnitFrame",
}

X-Feedback(插件-留言版):

## X-Feedback: http://www.cosmosui.org/forums

复制代码

※其余详细代码请参阅：http://www.wowwiki.com/TOC


-------------------------------------------------------------------------------------------------------------------------------------

*.toc文件实例，以大家比较熟悉的 Omen3 为例:

## Interface: 30000    ---客户端版本
## Version: 3.0.6 ---插件版本
## Title: Omen3 ---插件名称
## Notes: A lightweight, flexible, multi-target threat meter. ---插件简介注释
## Notes-ruRU: Лёгкий, гибкий, измеритель угрозы.
## Notes-frFR: Un "threat meter" léger, flexible et multi-cibles.
## Notes-zhCN: 一个灵活的，多目标的，低资源占用的威胁值计量器。
## Notes-zhTW: 一個輕量級、有彈性、可監視多個目標的仇恨統計插件。
## Notes-koKR: 다중-대상에 대한 위협수준 미터기로 보여줍니다.
## Author: Xinhuan ---插件作者
## OptionalDeps: Ace3, LibSharedMedia-3.0, AceGUI-3.0-SharedMediaWidgets, LibSink-2.0, LibDBIcon-1.0  ---插件可选库
## X-eMail: xinhuan @ gmail DOT com ---插件联系邮箱
## X-Donate: PayPal:xinhuan @ gmail DOT com
## X-Category: Combat  ---插件类型目录
## SavedVariables: Omen3DB ---插件储存目录信息
## X-Curse-Packaged-Version: v3.0.6
## X-Curse-Project-Name: Omen Threat Meter
## X-Curse-Project-ID: omen-threat-meter
## X-Curse-Repository-ID: wow/omen-threat-meter/mainline

		自动登录	找回密码
密码			加入我们

[综合] 魔兽世界插件三部曲之一 ---- TOC

浏览过的版块