使用Lua的简单魔兽世界插件（译文）

原文地址：https://www.codeproject.com/Articles/284961/A-Simple-World-of-Warcraft-Addon-using-Lua

原文作者：Richard Chambers

译文由本站 robot-v1.0 翻译

前言

An example of a combat information addon for World of Warcraft using Lua and the World of Warcraft API

使用Lua和<魔兽世界> API的<魔兽世界>战斗信息插件的示例

• 下载源6.4 KB(Download source - 6.4 KB)

介绍(Introduction)

魔兽世界是一个服务器客户端应用程序,其中一些游戏功能驻留在服务器上,而其他游戏功能驻留在客户端上.大多数服务器功能都涉及其他玩家共享的游戏环境.客户端功能包括播放器的用户界面,来自服务器的消息的呈现以及将播放器动作的消息发送到服务器.在玩家的化身或卡通人物所在的三维世界的呈现中呈现一些信息,并且以文本和/或图形消息的形式呈现一些信息,这些文本和/或图形消息以各种方式显示以向玩家提供状态信息.(World of Warcraft is a server client application with some of the game functionality residing on a server and other game functionality residing on the client. Most of the server functionality involves the game environment that is shared by other players. The client functionality involves the user interface for the player, the presentation of messages from the server, and the sending of messages of player actions to the server. Some information is presented in the rendering of the three dimensional world in which the player’s avatar or toon is located and some information is presented n the form of text and/or graphical messages that are displayed in various ways providing status information to the player.) 魔兽世界为人们提供了一种向游戏客户端添加自己的组件(附加组件)的机制.创建大多数插件是为了添加到标准用户界面中,以便提供其他信息.有些旨在替换许多标准用户界面组件以提供更精简,更紧凑的控件集,或者旨在替换某些标准用户界面组件以为某些活动提供更丰富的环境(例如,拍卖行插件,以帮助玩家进行拍卖) ).(World of Warcraft provides a mechanism for people to add their own components, addons, to the game client. Most addons are created to add to the standard user interface in order to provide additional information. Some are intended to replace much of the standard user interface components to provide a leaner and more compact set of controls or to replace some of the standard user interface components to provide a richer environment for some activities (e.g. auction house addon to help players with auctions).) Blizzard Entertainment提供的许多用户界面都是用Lua编写的,扩展,增强或替换现有客户端功能的插件也必须用Lua编写.存在相当大的插件程序程序员社区,其中有几个致力于插件程序管理的网站,这些网站为插件程序构建者提供了丰富的源代码和想法.已安装的标准用户界面似乎是Lua代码的编译版本,但是Blizzard Entertainment提供了一个工具包,即<魔兽世界界面插件>工具包,该工具包使人们可以查看原始的Lua源代码和XML文件.该工具包可通过暴雪技术支持论坛获得,搜索应提供最新链接.(Much of the user interface provided by Blizzard Entertainment is written in Lua and an addon extending, enhancing, or replacing the existing client functionality must also be written in Lua. A fairly large community of addon programmers exists with several web sites devoted to the management of addons and these web sites provide a rich source of source code and ideas for the addon builder. The standard user interface that is installed appears to be a compiled version of the Lua code however Blizzard Entertainment provides a kit, the World of Warcraft Interface Addon Kit, that allows a person to see the original Lua source and XML files. The kit is available through the Blizzard Technical Support forums and a search should provide the most up to date link.) 有许多网站和出版的书籍提供了大量信息.有关编写插件的深入讨论,请查看可用的书籍和网站.这些书经常提供各种网站都缺少的讨论水平.另一方面,各个网站都非常擅长提供有关API的特定详细信息,并且可能提供的信息比书籍还多.本文的目的是提供一个示例Warcraft附加组件,为初学者提供指导性示例.(There are a number of web sites as well as books published that provide a fair amount of information. For an indepth discussion of writing an addon, take a look at the books and web sites available. The books often provide a level of discussion missing from the various web sites. On the other hand, the various web sites are fairly good at providing specific details about the API and may provide information that is more up to date than a book. The purpose of this article is to provide a sample Warcraft addon that will provide an instructive example for beginners.)

背景(Background)

用户界面插件有几大类,大致可分为:(There are several broad categories of user interface addons which can roughly be divided into:)

• 辅助战斗的附件(Addons to assist with combat)
• 辅助农耕的活动(采矿等聚会活动)(Addons to assist with farming (gathering activities such as mining))
• 用来协助与其他玩家互动和管理公会的插件,以及(Addons to assist with interacting with other players and with managing guilds, and)
• 可以协助拍卖行和非玩家角色供应商的插件.(Addons to assist with the auction house and with Non-Player Character vendors.) 战斗类型有几种,还有专门的插件可协助玩家对环境(PvE)战斗(倾向于在与人工智能对抗的小组中一到两个或五个到五个玩家),玩家对战(PvP)战斗(往往是一群大群人与其他人对战),并在突袭中作战(倾向于一群大群人在与人工智能对战).(There are several types of combat and there are specialized addons to assist with Player versus Environment (PvE) combat (tending to be one or two to perhaps five players in a group playing against an artificial intelligence), Player versus Player (PvP) combat (tending to be larger groups of people playing against other people), and combat in raids (tending to be large groups of people playing against an artificial intelligence).) 随着<魔兽世界>游戏的成熟以及各种人创建的插件来帮助执行特定的操作,暴雪修改了API,并且暴雪提供了用户界面,因为他们了解了人们在游戏中的行为.某些更改导致不再使用较旧的插件,因为暴雪已将其功能集成到其客户端中.某些更改导致较旧的插件不再起作用,因为暴雪修改了API,因此当暴雪确定插件所提供的功能与游戏原理冲突时,这些插件将不再起作用.(As the World of Warcraft game has matured and various people have created addons to help with particular actions, Blizzard has modified the API and the Blizzard supplied user interface as they have learned more about what people do in the game. Some of the changes have resulted in older addons no longer being of use as Blizzard has incorporated that functionality into their client. Some of the changes have resulted in older addons no longer functioning as Blizzard modified the API so that those addons no longer work when Blizzard determined that the functionality supplied by the addon conflicted with the philosophy of the game.)

使用代码(Using the Code)

此示例附加组件的功能非常简单明了.它仅向播放器提供状态信息,这使源代码更加简单.显示状态还避免了执行操作的加载项所需的许多注意事项.暴雪娱乐(Blizzard Entertainment)的开发人员多年来修改了可用的API和功能,以提供额外的防范措施,以防止插件执行许多开发人员认为只能由玩家完成的操作.由于这是一个信息显示插件,因此不考虑那些减少软件代理扮演角色的可能性的规定.源代码包含大量注释,以帮助其他人理解源代码.(The functionality of this example addon is simple and straightforward. It provides status information to the player only which makes the source code much simpler. Displaying status also avoids a number of considerations that are required for an addon that performs actions. The developers at Blizzard Entertainment have modified the API and the functionality that is available over the years to provide additional guards against addons that do many of the actions that the developers believe should be done only by a player. Since this is an information display addon, those provisions to reduce the possibility of software agents playing a character are not a consideration. The source code contains a large number of comments to help others to understand the source.) 该示例插件是战斗信息类型的插件.它显示一组简单的框架,显示玩家角色的生命值和力量(法力,专注力,怒气等),玩家角色的宠物(如果有的话)以及当前选定目标(目标)的生命值和力量在这个意义上说,是玩家角色已选择作为目标的世界上的其他玩家角色,非玩家角色,野兽或其他演员).该插件还显示目标的威胁级别,这表明目标的攻击意愿.(This sample addon is a combat information type of addon. It displays a simple set of frames showing the health and power (mana, focus, rage, etc.) of a player character, the player character’s pet if there is one, as well as the health and power of the currently selected target (target in this sense is some other player character, non-player character, beast, or other actor within the world that the player character has selected as a target). This addon also displays the threat level of the target which is an indication as to the target’s willingness to attack.) 这个插件以及大多数插件的基本过程是:(The basic procedure in this addon as well as most is:)

• 初始化任何全局变量(Initialize any global variables)
• 注册玩家进入魔兽世界虚拟世界时的首个事件(Register for the first events for when the player enters the World of Warcraft virtual world)
• 进入虚拟世界后,从Warcraft API中可用的各种小部件构建用户界面(Upon entry into the virtual world, build the user interface from the various widgets available in the Warcraft API)
• 注册更新用户界面所需的事件,并(Register for the events required to update the user interface, and)
• 在收到事件时更新用户界面(Update the user interface as events are received) 在此示例中,有两个文件,(In this example there are two files,)**主lua(main.lua)**其中包含插件的Lua源代码和(which contains the Lua source code for the addon and)**SimpleCombatHud.toc(SimpleCombatHud.toc)其中包含该插件的目录.因为此插件使用Lua创建用户界面,所以不需要描述用户界面窗口结构的XML文件.的名称(which contains the table of contents for the addon. Because this addon creates the user interface using Lua, there is no need for an XML file that describes the user interface window structure. The name of the).toc(.toc)文件必须与文件所在的文件夹相同,并且名称,文件夹名称和(file must be the same as the folder in which the files are located and those names, the folder name and the).toc(.toc)**文件名,必须与插件本身的名称相同.(file name, must be the same as the name of the addon itself.) 插件的命名很重要,因为所有插件以及<魔兽世界>客户端的nam空间都是全局命名空间.程序员必须小心在其插件中使用尽可能少的全局变量,而他们确实使用的变量应该是唯一的名称.这就是为什么插件编程人员将使用一个与自己的插件相同的全局名称的Lua表变量,然后将该插件所需的任何持久数据输入该表的原因.诸如设置数据之类的辅助全局变量将使用插件名称的派生形式,以减少该名称与任何其他全局变量冲突的可能性.使用(Naming of an addon is important in that the nam space for all addons as well as the World of Warcraft client is a global namespace. Programmers must be careful to use as few global variables as possible in their addons and those that they do use should be unique names. This is why addon programmers will use a Lua table variable with a global name that is the same as their addon and then any persistent data needed by the addon goes into the table. Secondary global variables such as data for settings will use a derivative of the addon name in order to reduce the possibility of the name clashing with any other global variable. The use of the) local 关键字对于临时变量很重要,这样可以减少混乱的全局名称空间,并避免与现有变量冲突.(keyword is important for temporary variables in order to reduce cluttering the global name space and possibly colliding with an already existing variable.)

.toc文件(The .toc File)

的(The)**.toc(.toc)文件用一些条目描述了插件,这些条目包含版本号,插件的描述以及为使插件起作用而需要加载的文件的列表.还有一些注释,允许程序员将信息提供给正在查看内容的任何人.(file describes the addon with a number of entries that contain a version number, a description of the addon, and a list of the files that need to be loaded to make the addon functional. There are also comments to allow the programmer to provide information to anyone who is looking at the).toc(.toc)文件.某些插件网站会使用(file. Some addon web sites use the information in the).toc(.toc)文件,作为描述性信息的一部分,呈现给正在寻找特定类型插件的人们.这些网站可能有特殊的指令,要求它们用于(file as a part of the descriptive information presented to people who are looking for an addon of a particular type. These web sites may have special directives they require to be used in the).toc(.toc)网站解析的文件,以确定附件的类型以及如何对其进行分类.(file which the web site parses in order to determine the type of addon and how to categorize it.) 的前几行示例(An example of the first few lines in a).toc(.toc)**文件如下.界面行指示了该附件所针对的<魔兽世界>客户端版本.如果指定的值是Warcraft客户端的早期版本,则插件将被禁用,除非玩家选择加载过期的插件.注释行提供了基本描述,该标题将与标题行中的内容一样显示在Warcraft插件管理对话框中.(file are below. The Interface line indicates the version of the World of Warcraft client that the addon targets. If the value specified is of an earlier version of the Warcraft client, the addon will be disabled unless the player chooses to load out of date addons. The Notes line provides a basic description that will show in the Warcraft addon management dialog as will what is on the Title line.) 可以通过在行首使用单个井号(#)将实际注释添加到文件中.(Actual comments can be added to the file by using a single pound sign (#) at the beginning of the line.)

## Interface: 40000

## Title: A simple combat HUD
## Version: 1.0.0.1
## Author: Richard Chambers
## Notes: Provides a simple status bar showing the amount of health and 
   power of the player as a Heads Up Display.
...

的(The)**.toc(.toc)**该文件允许使用两个指令来保存变量,从而允许插件在玩家注销时保存状态信息,以便下次玩家登录时返回相同状态.保存的变量基于插件,这意味着这些变量及其变量值可用于玩家的所有角色,和/或基于角色,这意味着这些变量及其值仅适用于特定角色.(file allows for two directives for saving variables allowing an addon to save state information when the player logs out in order to return to the same state the next time the player logs in. Saved variables are on an addon basis, meaning that those variables and their values are available for all characters of the player, and/or on a character basis, meaning that those variables and their values are available only to a specific character.)

## SavedVariables: SimpleCombatHudDB
## SavedVariablesPerCharacter: SimpleCombatHudPerCharDB
...

main.lua文件(The main.lua File)

文件(The file)**主lua(main.lua)**包含插件的Lua源代码.魔兽世界客户端是事件驱动的.有很多事件和各种事件,因此插件必须注册它希望接收的特定事件.每个框架小部件都有一个(contains the Lua source code for the addon. The World of Warcraft client is event driven. There are many events and kinds of events so the addon must register for the specific events that it wishes to receive. Each frame widget has an) OnEvent 为了接收已注册帧的事件而需要重写的方法.因此,基本过程是:(method which needs to be overridden in order to receive events for which the frame is registered. So the basic procedure is to:)

• 创建框架(Create the frame)
• 添加自己的(Add your own) OnEvent 框架处理程序(handler to the frame)
• 注册您希望框架小部件处理的事件(Register for the events you want the frame widget to handle) 为了使Lua源代码更易于阅读和理解,使用的约定是创建一个事件处理程序,该事件处理程序具有少量源代码,仅将事件消息分发给其他功能.事件处理程序被编写为特定事件的函数,事件分派器检查该事件是否存在函数.如果框架通过定义的事件名称具有功能,则事件分发程序将调用该函数以处理事件.如果框架没有该名称的功能,那么将忽略该事件.这样的(In order to make the Lua source code easier to read and to understand, a convention used is to create an event handler that has a small body of source to just dispatch event messages to other functions. Event handlers are written as functions for specific events and the event dispatcher checks to see if a function exists for the event or not. If the frame has a function by the name of the event defined, then the event dispatcher calls the function to handle the event. If the frame does not have a function by that name, then the event is ignored. Such an) OnEvent 处理程序如下所示,使用未命名,匿名或lambda函数覆盖(handler is shown below using an unnamed, anonymous, or lambda function to override the) OnEvent 框架的方法,用于将事件消息分派到框架的适当功能.(method of the frame to dispatch event messages to the proper function of the frame.)

-- Create our main table for this addon
SimpleCombatHud = SimpleCombatHud or {};

-- Create the frame that we will use for our events
SimpleCombatHud.frame = CreateFrame("Frame", "SimpleCombatHud", UIParent);
SimpleCombatHud.frame:SetFrameStrata("BACKGROUND");

-- Override the OnEvent() method to dispatch events to our processing functions.
-- Notice first argument is self referring to the frame allowing use of colon (:) notation.
SimpleCombatHud.frame:SetScript("OnEvent", 
function(self, event, ...) if self[event] then return self[event](self, ...) end end);

覆盖后(After overriding the) OnEvent 使用上述约定的框架方法,我们现在可以通过做两件事来处理事件:(method of the frame using the above convention, we can now handle events by doing two things:)

• 注册活动并(Register for the event and)
• 使用与事件本身相同的名称为事件提供处理功能(Provide a handling function for the event using the same name as the event itself) 这样做的好处是,在某些情况下,处理事件的功能可能会以其他方式重用.在下面的Lua源代码片段中,我们有一个事件处理函数,该函数在某些情况下使用另一个事件处理函数.该函数处理事件(A nice benefit of doing this is that in some cases, the function to handle an event may be reused in other ways. In the Lua source snippet below, we have an event handling function that uses another event handling function under some circumstances. This function handles the event) PLAYER_TARGET_CHANGED 通过检查是否有针对性的单位.如果是这样,那么它将更新目标的显示的健康状况和力量.如果不是,则目标健康状况和电源显示框将被隐藏.(by checking to see if there is a unit that has been targeted. If so, then it updates the target’s displayed health and power. If not, then the target health and power display frames are hidden.)

function SimpleCombatHud.frame:PLAYER_TARGET_CHANGED()
    if (UnitExists("target")) then
        self:UNIT_HEALTH("target");
        self:UNIT_POWER("target");
    else
        SimpleCombatHud.statusbar["target"].health:Hide();
        SimpleCombatHud.statusbar["target"].power:Hide();
    end
end

兴趣点(Points of Interest)

玩魔兽世界很有趣,虚拟世界又大又有趣,尽管有时是重复的.暴雪娱乐(Blizzard Entertainment)提供的标准用户界面看起来相当不错,并且对于一般游戏的播放来说效果很好,尤其是添加了一些精选的宏.无论如何,认真的硬核玩家发现在许多方面都缺乏标准的用户界面.通过浏览<魔兽世界>附加组件网站,可以找到数百个处于各种修复和有用状态的附加组件.有些是小而基本的,例如此示例,而有些又是大而复杂的,例如插件Deadly Boss Mods,它以警告的形式为玩家提供了大量帮助.(Playing World of Warcraft is fun and the virtual world is large and interesting though at times repetitive. The standard user interface provided by Blizzard Entertainment looks quite nice and for general playing of the game works well especially with a few well chosen macros added. However serious, hard core players find the standard user interface lacking in a number of ways. Looking through the various World of Warcraft addon web sites, one can find hundreds of addons in various states of repair and usefulness. Some are small and basic, like this example and others are large and complex such as the addon Deadly Boss Mods which provides a great deal of assistance to players in the form of warnings.) 为<魔兽世界>编写插件的问题是缺少文档.已经编写了许多书籍,有大量的源代码示例,并且有多个论坛供人们提问和获得帮助.但是,缺少文档对插件程序员来说是一个障碍,尤其是在魔兽世界编程环境也是一个移动目标时,随着开发团队通过补丁和扩展进行更改,必须适应插件以应对更改.插件呈现的内容大部分基于各种事件,以及程序员如何使用Lua语言和Warcraft API将事件转换为呈现的信息.插件的作者必须意识到,带有特定标签的事件可能与它似乎关联的事件没有关联.而在魔兽争霸的早期版本中使用的事件可能在更高版本中不再有用.各种网站可以帮助您确定有用的和无效的.那些随着新扩展和补丁发布而维护和升级的插件,被大量的<魔兽世界>社区使用,对于插件程序员来说是有用的资源.(The problem with writing addons for World of Warcraft is the lack of documentation. A number of books have been written, there is a large body of source code examples, and there are multiple forums for people to ask questions and receive assistance. However the lack of documentation is an impediment for addon programmers especially as the World of Warcraft programming environment is also a moving target As the development team makes changes with patches and with expansions, addons must be adapted to handle the changes. Much of what an addon presents is based on the various events and how the programmer translates the events to the presented information using the Lua language and the Warcraft API. The writer of addons must be aware that an event with a particular label may not be associated with what it appears to be associated. And an event that is used in an earlier version of Warcraft may no longer be useful in a later version. The various web sites can be helpful in determining what is useful and what is not. Those addons that are maintained and upgraded as new expansions and patches are released and which are used by a large body of the World of Warcraft community are useful resources for an addon programmer.) 在开发过程中,您很可能需要将变量和信息打印到聊天区中,以便测试正在发生的事情.很简单(During development, you will most likely need to print variables and information into the chat area in order to test out what is happening. A very simple) debug 如下的打印声明可以帮助打印信息.在示例插件中有很多地方我使用了这个(print statement such as the one below can be helpful in printing information. There are a number of places in the sample addon where I used this) Debug 函数检查值并查看发生了什么.在使用它的那些地方,我已将函数注释掉,以显示如何使用它来查看可能引起问题的原因.只要确保在完成在源代码区域中的使用后,就可以删除调试调用.这不仅是一个严重的性能问题,也将是玩家的主要烦恼.大多数玩家都希望插件实现其功能,而不再需要其他功能.(function to check values and to see what was going on. In those places where it was used, I have left the function commented out to show how it can be used to see what may be causing a problem. Just make sure that when you are done with using it in an area of the source code that you remove the debug calls. Not only would this be a serious performance issue, it would also be a major annoyance to a player. Most players want an addon to do its function and no more.)

local Debug = function  (str, ...)
    if ... then str = str:format(...) end
    DEFAULT_CHAT_FRAME:AddMessage(("Addon: %s"):format(str));
end

在开发和维护期间必须对附加组件进行测试.暴雪娱乐提供了免费下载和播放的魔兽世界客户端版本,但存在许多限制,其中之一是不允许使用插件.因此,如果您有兴趣撰写<魔兽世界>附加组件,则需要成为订阅者.播放测试需要在各种情况下包括所有各种播放器类.在着手构建自己的插件之前,您应该首先寻找一个类似的插件.您很可能可以获取该插件的源代码,并按原样使用它,或者进行一些调整即可进行所需的修改.如果它们是有用的mod,请联系插件的开发人员,也许他们会将您所做的更改纳入整个社区.(Play testing an addon during development and maintenance is a must. While Blizzard Entertainment provides a version of the World of Warcraft client that is free to download and play, there are a number of restrictions, one of which is that the use of addons is not allowed. So if you are interested in writing World of Warcraft addons, you will need to be a subscriber. Play testing needs to include all of the various player classes in a variety of circumstances. Before setting out to build your own addon, you should first look for a similar addon. It may very well be that you can take the source code for that addon and either use it as is or with a few tweaks make the modifications you would like to see. And if they are useful mods, contact the developer of the addon and perhaps they will incorporate your changes for the entire community.) 使用此附加组件进行游戏测试的一个示例是将其用于有宠物的角色和没有宠物的角色.播放测试以及Debug功能的使用使我能够收集各种经验,以检查插件是否提供了合理准确的信息显示.我需要在各种环境中使用各种字符类检查插件,然后调查异常行为.一种这样的行为是当某些非玩家角色被选为目标时,目标的力量显示不正确.原来是由于以下事实:某些非播放器角色的最大功效为零,在原始源代码中最终导致了被零除的问题.(An example of play testing with this addon was using it with characters that had pets and those that did not. Play testing, along with the use of the Debug function allowed me to collect a variety of experiences to check that the addon was providing a reasonably accurate display of information. I needed to check the addon in a variety of environments and with a variety of character classes and to then investigate unusual behavior. One such behavior was the target’s power showing improperly when some Non-Player Characters were selected as the target. It turned out to be due to the fact that some Non-Player Characters have a maximum power of zero which in the original source code ended up resulting in a divide by zero issue.) 流行插件的开发者通常会为发现插件有用的人提供一种机制,以向开发团队捐款.暴雪娱乐有一项附加组件政策,其中描述了一些基本的附加条件.如果您访问魔兽世界网站并搜索附加政策,则应该可以找到它.基础知识是:(Developers of popular addons will often have a mechanism for people who find the addon useful to make a donation to the development team. Blizzard Entertainment has an addon policy which describes some of the basic do’s and don’ts for addons. If you go to the World of Warcraft web site and do a search for addon policy, you should be able to find it. The basics are:)

• 尽管您可以接受捐赠,但无法为此付费(You cannot charge for it though you can accept donations)
• 插件不得包含广告(包括捐赠广告)或令人反感的材料(The addon must not have advertisements (including advertisements for donations) or objectionable material)
• 源必须是开放的,可见的且可检查的,并且(The source must be open and visible and inspectable, and)
• 插件行为不得对游戏产生不利影响,并且必须遵守使用条款和许可协议.这基本上意味着,对于大多数人来说,编写魔兽世界插件是一件有趣而有趣的工作,而不是一种赚钱的方法,至少不会,并且不在官方插件政策之内.(Addon behavior must not adversely affect the game and must abide by the Terms of Use and the license agreement. What this basically means is that for most people writing of a World of Warcraft addon will be a fun and interesting effort and not a way to make money, at least not and be within the official addon policy.)

历史(History)

• 2011年11月25日-更新了(November 25, 2011 - Updated the)**主lua(main.lua)**文件以更正发现的缺陷,在该缺陷中进行区域更改后,所显示的健康和功耗值可能已过时.(file to correct the defect found in which after doing a zone change, the displayed values for health and power may be out of date.)

许可

本文以及所有相关的源代码和文件均已获得The Code Project Open License (CPOL)的许可。