Difference between revisions of "WMLsyntax ch"

From The Battle for Wesnoth Wiki
Line 6: Line 6:
 
== 标签和属性结构 ==
 
== 标签和属性结构 ==
  
−
WML有一个包含两个成员的语法结构: ''标签'' and ''属性''. 其中属性又由''键''(keys)与''值''(value)组成。作为例子:
+
WML有一个包含两个成员的语法结构: ''标签'' 与 ''属性''. 其中属性又由''键''(keys)与''值''(value)组成。作为例子:
 
   [tag]
 
   [tag]
 
       key=value
 
       key=value
Line 60: Line 60:
  
 
一个属性值除了被赋予纯文本，也可以赋予其他形式，这些形式有不同的意义。
 
一个属性值除了被赋予纯文本，也可以赋予其他形式，这些形式有不同的意义。
−
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.
+
* '''key = "value"''': '''引用形式''':引用形式无条件的将双引号包围的内容当做一个文本值。这提供了可写多行的值和转义能力(双引号自己的转义使用连双双引号，"" 见下)。不过在多数时候并不用写出这一形式，如果没有特殊情况，一段文本自动当做加上了双引号组。
−
* '''key = _"value"''': a ''[[translatable|translatable value]]'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.
+
* '''key = _"value"''': ''[[translatable|translatable value]]'' 可翻译形式:使用一个下划线(_)与一个引用形式组合的形式。这一形式的文本可以被翻译[[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. ,自然它应该只用于会对外显示的文本而不是内部数据。除此以外它与引用形式工作方式一样。
−
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left.  To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.
+
* '''key = "value1" + "value2"''': ''字符串连接'':这种形式下两个字符串将从左往右连接作为一个新字符串。显然，由于这种形式的存在，要想在文本里表示加号必须使用引用形式。
−
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
+
* '''key = "quoted ""double quoted value"" value"''': 字符串转义:由于双引号表示引用，要想在文本里表示字符串必须使用两个双引号连在一起的形式。注意这并不需要成对使用。
−
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just  a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].
+
* '''key = $variable''': 变量代入形式:键将被赋给所标示的WML变量所含有的值。变量通过美元符号($)标示,这种标示法只是一般的变量代入法的特殊情况。看之后的内容获得更多关于WML的信息。(注意:一些键需要的是变量的名字而不是变量的值，这时候不加$)。变量代入有一些支持文档，如[[IntroWML]] 与 [[EventWML]].
−
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[FormulaAI]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
+
* '''key = "$(formula-expression)"''': 格式化表达式:格式化表达式是引用形式的特殊情况，这时有如上形式的表达式$(formula-expression)不会作为文本本身，而是代入对应变量所记录的字符串描述的表达式返回的字符串以生成新字符串。这有时可以理解为"string1"+$string-variable+"string2"的一种简写。更多关于formula的信息见[[FormulaAI]].
  
−
== Variables ==
+
== 变量 ==
  
−
Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.
+
变量是WML用来暂时保存值延后再用的.每个变量被识别通过它的名字，这个名字只能包含字母数字和下画面。变量一建立就一直存在直到战役结束或被明确指出清空。
  
−
The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.
+
以下是三种简单的WML变量的操作方式，赋值，获取值与清空变量。
−
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.
+
* '''变量赋值''': 保存一个值到一个变量当中去的操作。这通过像 {{tag|InternalActionsWML|set_variable}}或宏 [[PreprocessorRef|macros]] 像这样 <tt>{VARIABLE}</tt>.
−
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.
+
* '''变量取值''':返回最后被保存在变量的值(或空字符串值，如果这个变量还没创建)。需要使用美元号加变量名为标示出是哪个变量,如$variable，有时变量名后面会加竖线|,如$variable|.
−
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].
+
* '''清空一个变量'''：让WML系统忘记一个变量。这在保存游戏时减少存档大小方面有用。 {{tag|InternalActionsWML|clear_variable}} 以及 <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].
  
−
=== Kinds of Variables ===
+
=== 变量类型 ===
−
==== Scalar ====
+
==== 标量 ====
−
A scalar variable can store a single string or number.
+
一个标量变量可以存储一行文本或数字。
  
 
   [set_variable]
 
   [set_variable]
Line 85: Line 85:
 
   [/set_variable]
 
   [/set_variable]
  
−
The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).
+
标量变量的全名就是给它的名字，如my_variable。注意变量的值可以是可翻译形式或是一个格式化表达式，见特殊属性值节。([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).
  
−
==== Array ====
+
==== 数组 ====
−
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:
+
一个数组变量是一个由容器变量组成的序列。存在一些特殊的标签指派数组的信息。如[store_unit]和[store_location].创建一个数组使用[set_variable]像这样:
 
   [set_variable]
 
   [set_variable]
 
       name=my_awesome_array[0].x
 
       name=my_awesome_array[0].x
Line 102: Line 102:
 
   [/set_variable]
 
   [/set_variable]
  
−
However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:
+
不过一般可以使用一种更简单的写法创建的一个数组如使用[set_variables]。这将可以写成这种形式:
 
   [set_variables]
 
   [set_variables]
 
       name=my_awesome_array
 
       name=my_awesome_array
Line 116: Line 116:
 
   [/set_variables]
 
   [/set_variables]
  
−
If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar
+
如果foo是数组的名字，那么foo[0]就是第一个容易变量的全名，foo[1]是第二个，以此类推、foo.length是一个特殊变量,它储存数组中的容器数目。比如若foo.length为18，则这个数组的最后一个容器就是foo[17].如果你想取一整个数组作为值，那么只要使用第一个索引[0]。一般的，$foo.bar 等价于$foo[0].bar.
  
−
''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)
+
注意：不要尝试像保存一个标量值一样保存数组容器变量值。如foo[3]并不是一个标量，不能直接赋值。而应使用foo[3].value形式。(虽然某些情况下可以使用那种形式，如果你无视这条规则，它将在更多时候出现不确定的行为。如载入一个文档存档文件时出现WML错误)
  
−
==== Container ====
+
==== 容器 ====
−
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.
+
一个容器变量可以保存任何数量的标量或数组变量。存在一些标签指派特殊信息，如[store_side]。若一个变量bar被保存到一个容器foo，你可以用foo.bar调用。一个数组加一个索引构成的项也被认为是一个容器变量而不是标量。
  
−
=== Conditionals ===
+
=== 条件分支 ===
−
Variables and be compared with and used in a conditional block by [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].
+
变量可以被用在所谓的分支块内，如让[variable]在[if]或[while]标签里。更多信息请参考，[[ConditionalActionsWML]].
  
−
=== Variable Substitution ===
+
=== 变量代入 ===
−
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
+
当使用一个有一个$号在变量名前的形式，那么这个形式将被"代入"，即将这个形式换成之前保存在变量名所代表的的变量里的内容。如:
 
   [event]
 
   [event]
 
       name=turn 1
 
       name=turn 1
Line 140: Line 140:
 
   [/event]
 
   [/event]
  
−
The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.
+
上面的WML代码导致德叔说:"你好，科纳德，最近过的怎么样"，在第一回合。
  
−
When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.
+
当写一个剧本事件([[EventWML]]), 一个出现在赋值表达式(key=value形式)右边的变量可能被代入。如果值的任何部分前面有$，WML解释器会将其视为一个代入的申请，并分析出变量全名(通过空格或|)，找到变量的值，然后置换掉发出询问的形式。
  
−
In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.
+
在不引起歧义的情况下，|号可以省略。确切的规则是:如果没有|,被识别的变量名会跨过字母，数字，下划线，方括号和一些句号。不过连续两个句号等非法形式不包括在内。如果变量名为空就结束(例: 当使用 $| 时)，那么$相当于被转义，表达$字符本身的意思。给了一个机会简单的在字符串中表示$。
  
−
==== Literal Mode ====
+
==== 原义模式 ====
  
−
There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
+
存在一些场合你可以让代入不发生让文本像原先写的那样显示出来。如$在这里就可以直接写而不用$|形式。下面场合使用了原义模式:
−
* value of '''literal=''' inside [set_variable]
+
* '''literal属性值=''' 在[set_variable]内部
−
* contents of '''[literal]''' inside [set_variables]
+
* [set_variables]里[literal]里的内容
−
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
+
* 特殊[variables]标签，初始化时。
  
−
=== Automatically Stored Variables ===
+
=== 自动内建变量 ===
−
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)
+
* side_number:玩家当前在控制的方面的序号(在初始化时可能为空)。
−
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)
+
* turn_number:当前回合数(可能为空在初始化时)
−
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered
+
* x1:这个是最近触发事件的位置的x坐标
−
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered
+
* y1:这个是最近触发事件的位置的x坐标
−
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event
+
* x2:这个是最近协助事件触发的位置的x坐标
−
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event
+
* y2:x2:这个是最近协助事件触发的位置的y坐标
−
* '''unit''': inside an event, this is the unit at $x1,$y1
+
* unit:在事件内部,在x1,y1的单位
−
* '''second_unit''': inside an event, this is the unit at $x2,$y2
+
* second_unit:在事件内部,在x2,y2的单位
−
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match
+
* this_unit:在一个标准单位筛选器内部，当前那个符合筛选规则的单位。
−
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted
+
* damage_inflicted: 在attacker_hits 与defender_hits 事件内部, 造成的损伤的数量。
−
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].
+
* '''weapon''': 在attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die 以及 last_breath 事件内部, 这是一些关于在x1,y1的单位使用的装备的信息，它的属性来自[attack]表现,见 [[UnitTypeWML]].
−
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].
+
* '''second_weapon''': 在attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die 以及 last_breath 事件内部, 这是一些关于在x2,y2的单位使用的装备的信息，它的属性来自 [attack]表现,见  [[UnitTypeWML]].
  
−
Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.
+
注意:自动内建变量容器和数组变量只被保存一次到它们的属性之一被第一次访问时。这意味着有时会获得错误的结果，例如杀死一个单位在$x1,$y1作为一个moveto的第一个动作，然后取出$unit.something的值。这将造成一次虚假的取值，如增加0到HP上。
  
−
=== The [variables] tag ===
+
=== [variables]标签 ===
  
−
The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.
+
[variables]标签用来保存游戏,其描述当前变量的每个值。并且在剧本文件用于赋初值给变量在剧本初始化时。
  
−
A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.
+
一个标量变量可被赋值使用一个属性，这个属性的键是变量的名，这个属性的值时变量保存的值。
  
−
A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.
+
一个名为foo的容器变量被赋值使用一个[foo]标签，它包含其定义的变量。
  
−
An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...
+
一个名为foo的数组使用一系列[foo]标签，第一个叫foo[0],第二个叫foo[1]。。。
  
−
=== Storing variables inside units ===
+
=== 单位内部变量 ===
  
−
Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:
+
有时在一个单位里保存一个自定义的WML变量是有用的。使用[[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]]命令，可以为单位附加一个unit.variables自定义子容器变量，这个变量可以被保存。(记住 [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] 可以使变化被保存.) 使用这种方式的一个好处是可以使用基于值的筛选器 [[FilterWML|filtered]] .例如:
 
  [filter]
 
  [filter]
 
   [filter_wml]
 
   [filter_wml]
Line 190: Line 190:
 
  [/filter]
 
  [/filter]
  
−
=== Variable Usage Examples ===
+
=== 变量用法示例 ===
−
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)
+
考虑一个使用[variables]标签存档的游戏(或初始化剧本时使用这个标签)。
 
  [variables]
 
  [variables]
 
     attitude_of_elves=hate
 
     attitude_of_elves=hate
Line 199: Line 199:
 
  [/variables]
 
  [/variables]
  
−
Then,
+
然后
 
  [message]
 
  [message]
 
     message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
 
     message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
 
  [/message]
 
  [/message]
−
displays the message
+
打印出信息
 
  Oh, I see elves! They surely hate us!
 
  Oh, I see elves! They surely hate us!
  
−
Consider another game with variables
+
考虑其他游戏变量
 
  [variables]
 
  [variables]
 
     our_side=1
 
     our_side=1
 
     their_side=2
 
     their_side=2
 
  [/variables]
 
  [/variables]
−
where side 1 has 75 gold, and side 2 50 gold. Then,
+
side 1 有75金币，side 2有50金币。然后
 
  [store_side]
 
  [store_side]
 
     side=$our_side
 
     side=$our_side
Line 245: Line 245:
 
     name=they
 
     name=they
 
  [/clear_variable]
 
  [/clear_variable]
−
displays the messages
+
打印出这个信息:
−
We have 75 gold, they have 50 gold.
 
−
This should be easy!
 
−
If side 2 had 100 gold instead, the same code would display the messages
 
−
We have 75 gold, they have 100 gold.
 
−
This will not be easy!
 
  
−
The code
+
We have 75 gold, they have 50 gold.
 +
This should be easy!
 +
 
 +
如果side 2有100金币，类似的代码将打印出
 +
 
 +
We have 75 gold, they have 100 gold.
 +
This will not be easy!
 +
 
 +
代码
 
  [store_unit]
 
  [store_unit]
 
     [filter]
 
     [filter]
Line 266: Line 269:
 
     name=leader
 
     name=leader
 
  [/clear_variable]
 
  [/clear_variable]
−
always displays a true sentence.
+
将打印出一句正确的描述
  
−
You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.
+
你能找到更多复杂的变量例子使用方式在[[UsefulWMLFragments]] 章.
  
−
== Comments ==
+
== 注释 ==
  
−
Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.
+
注释用一个井号(#)开头。除非这行是一个预处理指令[[PreprocessorRef#Preprocessor_directives|preprocessor directive]], 所有这样的注释会被WML解释器无视。
  
−
== See Also ==
+
== 其他内容 ==
  
 
* [[PreprocessorRef]]
 
* [[PreprocessorRef]]

Revision as of 12:12, 10 November 2013

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D:

damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

韦诺标记语言 (WML)被用于编码几乎所有在韦诺里的事物，包括剧本，单位，存档文件以及用户交互接口，WML文件时简单，易读的文本文件，经常以.cfg后缀标出，与ini与XML文件非常类似。 关于如何使这些文件写的更易读,见 ConventionsWML.

标签和属性结构

WML有一个包含两个成员的语法结构: 标签 与 属性. 其中属性又由键(keys)与值(value)组成。作为例子: 

 [tag]
     key=value
 [/tag]

标签用于区分信息,直到一个数据被包含在属性里。键标出保存的数据的数据类型而值真正保存它们。当一个WML文件执行,标签识别成一些信息单元，如一个执行行动或一整个战役。这给了一个在一个标签内的属性一个上下文(context)。像每个在一个标签内的key=value行,其值被算进那个标签内。 标签也可以出现在另一个标签里，里面的标签被认为是包围它的标签的子标签，像下面的例子一样. 

 [parent_tag]
     key1=value1
     [child_tag]
         key2=value2
     [/child_tag]
 [/parent_tag]

每个标签介绍了一些不同的东西关于这个游戏;不同的标签以不同的方式发挥作用,但那些标签必须在上下文中有意义。这是一些 "top-level tags" ，这是一些不在任何其他标签内就可使用的标签，以及这些标签允许使用的子标签(以及键)。不能被理解的标签和键，如错别字，有些时候会产生错误信息，但是多数时候它们被无视掉。

键不能与变量混淆! 一个常见错误在初学者那里就是使用一个没有上下文意义的名字。相反，应使用在WML标准里能被找到的，具有上下文意义的，处于某个标签下的键名。所有这些标签下的键名字可以在这个文档AlphabeticalWML 中查到，或者WML Tags 导航框。

此外,对于标签和键的名遵循一个特殊形式。它们必须由字母数字与下划线组成，特别是不能有什么+ -之类的运算符(它们有特殊意义，见下)。不过，对于值来说它们可以包含任何它们需要的符号。


标签修正语法

插入一个加号(+)在一个标签前面名的标签形式允许追加到一个同名的（除去+后）较早的标签。这允许属性的增加或覆盖。 

 [tag]
     key=value
 [/tag]
 [+tag]
     key=value
 [/tag]
  • 所有在+tag(追加的标签代称)里的键必须设置一个给定的值。如果这个键不存在于想要追加的标签，则它们会被添加到要追加的那个标签里。其他情况下它们的值会替换老值在所追加的标签。
  • 任何在+tag里出现的子标签会被追加到对应标签子标签中。澄清一点:所追加标签的子标签不会因此被改变，这是一个追加(append)而不是一个合并(merge)
  • 还可以在一个标签外部修正这个标签的子标签，只要在修正子标签被修正父标签包围即可。这加强了修正的能力。

多行赋值语法

在一行内多次赋值是可行的。通过用等号分隔的几个键与几个值的形式。像这样: 

 [tag]
     key1,key2,key3=value1,value2,value3
 [/tag]

这等价于 

 [tag]
     key1=value1
     key2=value2
     key3=value3
 [/tag]
  • 允许两边项数不对称。当键更多时，从左数起没有对应值得键被赋空值。当值更多时，最后一个可对应的值以及后面所有的值作为一个表赋给最后一个键。

特殊属性值

一个属性值除了被赋予纯文本，也可以赋予其他形式，这些形式有不同的意义。

  • key = "value": 引用形式:引用形式无条件的将双引号包围的内容当做一个文本值。这提供了可写多行的值和转义能力(双引号自己的转义使用连双双引号，"" 见下)。不过在多数时候并不用写出这一形式，如果没有特殊情况，一段文本自动当做加上了双引号组。
  • key = _"value": translatable value 可翻译形式:使用一个下划线(_)与一个引用形式组合的形式。这一形式的文本可以被翻译comparisons to other values. ,自然它应该只用于会对外显示的文本而不是内部数据。除此以外它与引用形式工作方式一样。
  • key = "value1" + "value2": 字符串连接:这种形式下两个字符串将从左往右连接作为一个新字符串。显然，由于这种形式的存在，要想在文本里表示加号必须使用引用形式。
  • key = "quoted ""double quoted value"" value": 字符串转义:由于双引号表示引用，要想在文本里表示字符串必须使用两个双引号连在一起的形式。注意这并不需要成对使用。
  • key = $variable: 变量代入形式:键将被赋给所标示的WML变量所含有的值。变量通过美元符号($)标示,这种标示法只是一般的变量代入法的特殊情况。看之后的内容获得更多关于WML的信息。(注意:一些键需要的是变量的名字而不是变量的值，这时候不加$)。变量代入有一些支持文档，如IntroWML 与 EventWML.
  • key = "$(formula-expression)": 格式化表达式:格式化表达式是引用形式的特殊情况，这时有如上形式的表达式$(formula-expression)不会作为文本本身，而是代入对应变量所记录的字符串描述的表达式返回的字符串以生成新字符串。这有时可以理解为"string1"+$string-variable+"string2"的一种简写。更多关于formula的信息见FormulaAI.

变量

变量是WML用来暂时保存值延后再用的.每个变量被识别通过它的名字，这个名字只能包含字母数字和下画面。变量一建立就一直存在直到战役结束或被明确指出清空。

以下是三种简单的WML变量的操作方式，赋值，获取值与清空变量。

  • 变量赋值: 保存一个值到一个变量当中去的操作。这通过像 [set_variable]或宏 macros 像这样 {VARIABLE}.
  • 变量取值:返回最后被保存在变量的值(或空字符串值，如果这个变量还没创建)。需要使用美元号加变量名为标示出是哪个变量,如$variable，有时变量名后面会加竖线|,如$variable|.
  • 清空一个变量：让WML系统忘记一个变量。这在保存游戏时减少存档大小方面有用。 [clear_variable] 以及 {CLEAR_VARIABLE} macro.

变量类型

标量

一个标量变量可以存储一行文本或数字。 

 [set_variable]
     name=my_variable
     value="sample value"
 [/set_variable]

标量变量的全名就是给它的名字，如my_variable。注意变量的值可以是可翻译形式或是一个格式化表达式，见特殊属性值节。(Special Attribute Values).

数组

一个数组变量是一个由容器变量组成的序列。存在一些特殊的标签指派数组的信息。如[store_unit]和[store_location].创建一个数组使用[set_variable]像这样: 

 [set_variable]
     name=my_awesome_array[0].x
     value=10
 [/set_variable]
 [set_variable]
     name=my_awesome_array[1].x
     value=12
 [/set_variable]
 [set_variable]
     name=my_awesome_array[2].x
     value=14
 [/set_variable]

不过一般可以使用一种更简单的写法创建的一个数组如使用[set_variables]。这将可以写成这种形式: 

 [set_variables]
     name=my_awesome_array
     [value]
         x=10
     [/value]
     [value]
         x=12
     [/value]
     [value]
         x=14
     [/value]
 [/set_variables]

如果foo是数组的名字，那么foo[0]就是第一个容易变量的全名，foo[1]是第二个，以此类推、foo.length是一个特殊变量,它储存数组中的容器数目。比如若foo.length为18，则这个数组的最后一个容器就是foo[17].如果你想取一整个数组作为值，那么只要使用第一个索引[0]。一般的，$foo.bar 等价于$foo[0].bar.

注意：不要尝试像保存一个标量值一样保存数组容器变量值。如foo[3]并不是一个标量，不能直接赋值。而应使用foo[3].value形式。(虽然某些情况下可以使用那种形式，如果你无视这条规则，它将在更多时候出现不确定的行为。如载入一个文档存档文件时出现WML错误)

容器

一个容器变量可以保存任何数量的标量或数组变量。存在一些标签指派特殊信息，如[store_side]。若一个变量bar被保存到一个容器foo，你可以用foo.bar调用。一个数组加一个索引构成的项也被认为是一个容器变量而不是标量。

条件分支

变量可以被用在所谓的分支块内，如让[variable]在[if]或[while]标签里。更多信息请参考，ConditionalActionsWML.

变量代入

当使用一个有一个$号在变量名前的形式，那么这个形式将被"代入"，即将这个形式换成之前保存在变量名所代表的的变量里的内容。如: 

 [event]
     name=turn 1
     [set_variable]
         name=my_variable
         value= _ "Konrad"
     [/set_variable]
     [message]
         speaker=Delfador
         message= _ "Hello, $my_variable|... How are you?"
     [/message]
 [/event]

上面的WML代码导致德叔说:"你好，科纳德，最近过的怎么样"，在第一回合。

当写一个剧本事件(EventWML), 一个出现在赋值表达式(key=value形式)右边的变量可能被代入。如果值的任何部分前面有$，WML解释器会将其视为一个代入的申请，并分析出变量全名(通过空格或|)，找到变量的值，然后置换掉发出询问的形式。

在不引起歧义的情况下，|号可以省略。确切的规则是:如果没有|,被识别的变量名会跨过字母，数字，下划线，方括号和一些句号。不过连续两个句号等非法形式不包括在内。如果变量名为空就结束(例: 当使用 $| 时)，那么$相当于被转义，表达$字符本身的意思。给了一个机会简单的在字符串中表示$。

原义模式

存在一些场合你可以让代入不发生让文本像原先写的那样显示出来。如$在这里就可以直接写而不用$|形式。下面场合使用了原义模式:

  • literal属性值= 在[set_variable]内部
  • [set_variables]里[literal]里的内容
  • 特殊[variables]标签，初始化时。

自动内建变量

  • side_number:玩家当前在控制的方面的序号(在初始化时可能为空)。
  • turn_number:当前回合数(可能为空在初始化时)
  • x1:这个是最近触发事件的位置的x坐标
  • y1:这个是最近触发事件的位置的x坐标
  • x2:这个是最近协助事件触发的位置的x坐标
  • y2:x2:这个是最近协助事件触发的位置的y坐标
  • unit:在事件内部,在x1,y1的单位
  • second_unit:在事件内部,在x2,y2的单位
  • this_unit:在一个标准单位筛选器内部，当前那个符合筛选规则的单位。
  • damage_inflicted: 在attacker_hits 与defender_hits 事件内部, 造成的损伤的数量。
  • weapon: 在attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die 以及 last_breath 事件内部, 这是一些关于在x1,y1的单位使用的装备的信息，它的属性来自[attack]表现,见 UnitTypeWML.
  • second_weapon: 在attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die 以及 last_breath 事件内部, 这是一些关于在x2,y2的单位使用的装备的信息，它的属性来自 [attack]表现,见 UnitTypeWML.

注意:自动内建变量容器和数组变量只被保存一次到它们的属性之一被第一次访问时。这意味着有时会获得错误的结果，例如杀死一个单位在$x1,$y1作为一个moveto的第一个动作，然后取出$unit.something的值。这将造成一次虚假的取值，如增加0到HP上。

[variables]标签

[variables]标签用来保存游戏,其描述当前变量的每个值。并且在剧本文件用于赋初值给变量在剧本初始化时。

一个标量变量可被赋值使用一个属性，这个属性的键是变量的名，这个属性的值时变量保存的值。

一个名为foo的容器变量被赋值使用一个[foo]标签，它包含其定义的变量。

一个名为foo的数组使用一系列[foo]标签，第一个叫foo[0],第二个叫foo[1]。。。

单位内部变量

有时在一个单位里保存一个自定义的WML变量是有用的。使用[store_unit]命令，可以为单位附加一个unit.variables自定义子容器变量，这个变量可以被保存。(记住 [unstore_unit] 可以使变化被保存.) 使用这种方式的一个好处是可以使用基于值的筛选器 filtered .例如: 

[filter]
  [filter_wml]
    [variables]
      my_variable="test"
    [/variables]
  [/filter_wml]
[/filter]

变量用法示例

考虑一个使用[variables]标签存档的游戏(或初始化剧本时使用这个标签)。 

[variables]
    attitude_of_elves=hate
    attitude_of_dwarves=love
    attitude_of_humans=like
    current_opponent=elves
[/variables]

然后 

[message]
   message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"
[/message]

打印出信息 

Oh, I see elves! They surely hate us!

考虑其他游戏变量 

[variables]
    our_side=1
    their_side=2
[/variables]

side 1 有75金币，side 2有50金币。然后 

[store_side]
    side=$our_side
    variable=we
[/store_side]
[store_side]
    side=$their_side
    variable=they
[/store_side]
[message]
    message=We have $we.gold gold, they have $they.gold gold.
[/message]
[if]
    [variable]
        name=we.gold
        greater_than=$they.gold
    [/variable]
    [then]
        [message]
            message=This should be easy!
        [/message]
    [/then]
    [else]
        [message]
            message=This will not be easy!
        [/message]
    [/else]
[/if]
[clear_variable]
    name=we
[/clear_variable]
[clear_variable]
    name=they
[/clear_variable]

打印出这个信息:

We have 75 gold, they have 50 gold. This should be easy!

如果side 2有100金币，类似的代码将打印出

We have 75 gold, they have 100 gold. This will not be easy!

代码 

[store_unit]
    [filter]
        canrecruit=yes
        side=1
    [/filter]
    variable=leader
[/store_unit]
[message]
    message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.
[/message]
[clear_variable]
    name=leader
[/clear_variable]

将打印出一句正确的描述

你能找到更多复杂的变量例子使用方式在UsefulWMLFragments 章.

注释

注释用一个井号(#)开头。除非这行是一个预处理指令preprocessor directive, 所有这样的注释会被WML解释器无视。

其他内容

Retrieved from "https://wiki.wesnoth.org/index.php?title=WMLsyntax_ch&oldid=52376"