InternalActionsWML

Материал из Wesnoth Life Wiki
Перейти к: навигация, поиск

< Данная статья еще недопереведена! Английский оригинал можно прочесть тут >

Часть ActionWML. Включает различные внутренние WML-операции, не влияющие на игру напрямую, или по крайней не являющиеся очевидными для игрока. Например, ко внутренним операциям можно отнести работу с переменными.

Операции с переменными

These actions are focused, in one way or another, on variables. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

[set_variable]

Тег [set_variable] используется для создания и изменения переменных. Для простого объявления переменной также можно использовать макрос VARIABLE, а для математических операций — VARIABLE_OP.

  • name: имя рабочей переменной.
  • value: устанавливает переменной указанное значение (может быть числовым или текстовым).
  • literal: то же, что value, но с отключенной интерпретацией символа доллар (см. VariablesWML).
  • to_variable: устанавливает переменной значение, взятое из другой переменной, т.е. 'to_variable=temp' эквивалентно 'value=$temp'.
  • add: добавляет указанное число к значению переменной.
  • sub: вычитает указанное число из значения переменной.
  • multiply: умножает значение переменной на указанное число. The result is a float.
    To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.
  • divide: делит значение переменной на указанное число. Результатом является дробное значение. Начиная с версии 1.9 целочисленное деление больше не поддерживается. При необходимости можете использовать второй тег с round=floor.
  • modulo: получает остаток от деления переменной на указанное число.
  • rand: устанавливает случайное значение переменной.
    В виде параметров можно указать список допустимых значений (типа 'random=Bob,Bill,Bella'), целочисленный диаппазон (типа 'random=3..5'), либо сочетать диаппазоны со списками (например, 'random=100,1..9', где шанс выпадения сотни будет 1/10, как и у каждой из цифор 1-9).
    See BuildingMultiplayerExamples for more info on the MP case.
  • time=stamp: получает время в миллисекундах с момента запуска игры (не сценария, а вообще "Веснота"). Можно использовать для разных своих таймеров. Don't try to use this as random value in MP since it will cause an OOS.
  • string_length: получает количество символов в указанной строке, автоматически ее анализируя и подставляя значения переменных (см. VariablesWML).
  • [join] объединяет массив строк в текстовый список.
    • variable: имя исходного массива.
    • key: ключ для каждого элемента массива (array[$i].key), в котором расположены нужные строки.
    • separator: разделитель, вставляемый между исходными строками.
    • remove_empty: опция, определяющая, нужно ли игнорировать пустые элементы.
  • ipart: получает целую часть указанной переменной.
  • fpart: получает дробную часть указанной переменной.
  • round: Округляет значение переменной до указанного количества цифор после запятой. Можно использовать и отрицательные значения (округление 19517 до -2 = 19500). Специальные параметры:
    • round=floor: округление до ближайшего меньшего целого.
    • round=ceil: округление до ближайшего большего целого.

[set_variables]

Служит для манипуляций с массивами и контейнерами.

  • name: имя рабочего массива или контейнера.
  • mode: одно из следующих значений:
    • replace: will clean the array name and replace it with given data
    • append: will append given data to the current array
    • merge: will merge in the given data into name
    • insert: will insert the given data at the index specified in the name attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. Note: if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.
  • to_variable: data will be set to the given array
  • [value]: the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. (Пример)
  • [literal]: same as [value], but variables will not be substituted, [literal] and [value] can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of [value] and [literal] tags
  • [split] разбивает текстовый список на массив строк.
    • list: исходный список.
    • key: ключ для каждого элемента массива (array[$i].key), куда будут сохранены строки.
    • separator: используемый в списке разделитель.
    • remove_empty: опция, определяющая, нужно ли игнорировать пустые элементы.

Получение игровых данных

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

[store_gold]

Получает количество золота одной из игровых сторон.

  • StandardSideFilter: будет взято значение первой из сторон, соответствующих фильтру.
  • variable: (по умолчанию: 'gold') имя переменной, в которую нужно записать количество золота.

[store_locations]

Записывает в массив информацию о территориях на карте. Каждый элемент выходного массива содержит члены 'x' и 'y' (расположение), 'terrain' (тип местности) и 'owner_side' (только для деревень). The array will include any unreachable border hexes, if applicable.

  • StandardLocationFilter: область или области карты, определяющие сохраняемые территории. По умолчанию сохраняется вся карта.
  • variable: имя переменной (массива), куда будут сохранены данные о территориях.

[store_reachable_locations]

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

  • [filter]: a StandardUnitFilter. The locations reachable by any of the matching units will be stored.
  • [filter_location]: (optional) a StandardLocationFilter. Only locations which also match this filter will be stored.
  • range: possible values movement (default), attack, vision. If movement, stores the locations within the movement range of the unit, taking Zone of Control into account. If attack, stores the attack range (movement range + 1 hex). If vision, stores the vision range (movement range ignoring Zone of Control + 1 hex).
  • moves: possible values current (default), max. Specifies whether to use the current or maximum movement points when calculating the range.
  • viewing_side: (optional) the side whose vision to use when calculating the reach. This only has meaning in the presence of fog, shroud, or units with the ambush ability. If left out, then fog, shroud and ambushers are ignored and the real reach of the units is stored.
  • variable: the name of the variable (array) into which to store the locations.

[store_map_dimensions]

Получает размер карты. Результат является контейнерной переменной с членами 'width' (ширина) и 'height' (высота).

  • variable: имя переменной, в которую будут сохранены данные о размере. Если аттрибут не указан, то будет использоваться переменная 'map_size' (если уже назначена, то ее значение будет перезаписано).

[store_side]

Получает подробную информацию о какой-либо игровой стороне. Целевой контейнер будет содержать следующие члены: 'name', 'team_name', 'gold', 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'color', 'controller', 'village_gold', 'recruit', и 'side' (the $side_number of the side belonging to this container).

  • StandardSideFilter: сохранены будут все соответствующие фильтру стороны (в случае нескольких вместо контейнера будет создан массив, к которому можно обращаться например так: side[2].team_name).
  • variable: имя переменной, куда будет записана информация (по умолчанию: 'side').

note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.

[store_starting_location]

Получает стартовую позицию лидера игровой стороны. Возвращает переменную составного типа (контейнер или массив) с членами'x', 'y', 'terrain' и 'owner_side' (villages only)

  • StandardSideFilter: будут сохранены позиции всех соответствующих фильтру сторон.
  • variable: (по умолчанию: 'location'): имя переменной, в которую будет записана информация.

[store_time_of_day]

Получает данные о времени суток. Целевой контейнер заполняется всеми аттрибутами тега [time].

  • turn: (по умолчанию: текущий ход) номер хода, для которого нужно узнать время суток.
  • variable: (по умолчанию: 'time_of_day') имя контейнера, куда будет записана информация.

[store_turns]

Получает установленный лимит ходов. Если же он не установлен, то значение -1.

  • variable: (по умолчанию: 'turns') имя переменной, в которую нужно записать лимит ходов.

[store_unit]

Захватывает детальную информацию о бойце в переменную типа контейнер. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [set_variable]. A sample list of these tags and keys can be found here. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the [unit] tag(s) in any save file).

Основное применение: сохраняете данные бойца в переменную через [store_unit], производите с ней различные манипуляции, а затем пересоздаете этого бойца с помощью тега [unstore_unit].

Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit] and FOREACH.

  • [filter] с параметрами StandardUnitFilter. Сохранены будут все бойцы, соответствующие данному фильтру (в случае нескольких бойцов вместо контейнера просто будет использован массив). The units will be stored in order of their internal underlying_id attribute, which is usually in creation order (but you normally should not depend on the order).
  • variable: имя переменной, в которую будет сохранены данные бойца (или бойцов).
  • mode: defaults to always_clear, which clears the variable, whether or not a match is found. If mode is set to replace, the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to append, the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.
  • kill: если установлено 'yes', то захватываемый боец будет удален из игры.
    Опция будет полезна в т.ч. для временного запрета призывать бойцов.

[store_unit_type]

  • type: (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.
  • variable: the name of the variable into which to store the unit type information (default "unit_type")

[store_unit_type_ids]

  • variable: the name of the variable into which to store a comma-separated list of all unit type IDs

[store_villages]

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'. note: The only advantage/difference this tag has, in comparison to using [store_locations]terrain=*^V*, is that the amount of hexes which are considered for a possible match is previously restricted to those with villages.

  • variable: the name of the variable (array) into which to store the locations (default: "location")
  • StandardLocationFilter tags and keys as arguments

[store_items]

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [item] (depending on what was set during creating the item).

[find_path]

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path.

  • [traveler]: StandardUnitFilter, only the first matching unit will be used for calculation
  • [destination]: StandardLocationFilter, only the first matching nearest hex will be used
  • variable: the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
  • allow_multiple_turns: default no, if yes also moves that require more than one turn will be calculated.
  • check_visibility: default no, if yes the path will not be computed if some hexes are not visible due to shroud.
  • check_teleport: default yes, if no teleport won't be taken in account while computing path.
  • check_zoc: default yes, if no unit ZOCs won't be considered while calculating the path.

This is the structure of the variable returned by [find_path]:

[path]
	length = the total length of the path
		if the path is calculated to an impassable hex, or the move requires multiple turns
		and allow_multiple_turns is no, its value will be 0.
	hexes = in 1.11, this will replace the length key above
	from_x, from_y = location of the unit
	to_x, to_y = destination
	movement_cost = total movement cost required by unit to reach that hex
	required_turns = total turns required by unit to reach that hex
	[step]
		x, y = location of the step
		terrain = terrain of the step
		movement_cost = movement cost required by unit to reach that hex
		required_turns = turns required by unit to reach that hex
	[/step]
[/path]

To read the total length of the path on 1.10, use path.step.length.
(версия 1.11 и выше) length is replaced by hexes in the output array.

[clear_variable]

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro CLEAR_VARIABLE is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

  • name: the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
    • If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, {CLEAR_VARIABLE my_awesome_array[2]} deletes my_awesome_array[2], but then moves my_awesome_array[3] to my_awesome_array[2], moves my_awesome_array[4] to my_awesome_array[3], and so on until the end of the array.
    • Note that {CLEAR_VARIABLE my_awesome_array} deletes the entire array, but {CLEAR_VARIABLE my_awesome_array[0]} deletes only the first container.

Прочие внутренние операции

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

[fire_event]

Trigger a WML event

  • name: the name of event to trigger
  • [primary_unit]: (Optional) Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
  • [secondary_unit]: (Optional) Same as [primary_unit] except for the secondary unit.
  • [primary_attack]: Information passed to the primary attack filter and $weapon variable on the new event.
  • [secondary_attack]: Information passed to the second attack filter and $second_weapon variable on the new event.

[insert_tag]

Inserts a variable as WML. In other words, the value of the passed container variable will be injected into the game as if they had been written out in WML form. (See Example).

Tag insertion is a special case in that it can be used in places where other ActionWML cannot be used. The basic rule is that anywhere that $variable syntax works, tag insertion will also work. In practice this means pretty much everywhere except directly within top-level scenario tags.

  • name: The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a ActionWML tag name, and it may be a recognized subtag such as "option" when used within a [message]).
  • variable: Name of the container variable which will have its value inserted into the tag.

[role]

Tries to find a unit to assign a role to.
This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use role= in a unit filter to identify the unit with that role (See FilterWML).
However, there is no guarantee that roles will ever be assigned. You can use [have_unit] (see Condition Tags) to see whether a role was assigned. This tag uses a StandardUnitFilter (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a side attribute to force the unit to be on a particular side.

  • role: the value to store as the unit's role. This role is not used in the StandardUnitFilter when doing the search for the unit to assign this role to.
  • type: a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.
  • StandardUnitFilter, do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

Примеры

Создание массива с помощью [set_variables]

[set_variables]
    name=arr
    mode=replace
    [value]
        foo=bar
    [/value]
    [value]
       foo=more
    [/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}

This will produce two output messages, first one saying bar and next one saying more.

Пример использования [insert_tag]

[event]
    name=moveto
    
    [set_variable]
        name=temp.speaker
        value=Konrad
    [/set_variable]
    
    [set_variable]
        name=temp.message
        value= _ "Yo Kalenz!"
    [/set_variable]
    
    [insert_tag]
        name=message
        variable=temp
    [/insert_tag]
[/event]

Такая конструкция даст тот же эффект, что и следующая:

[event]
    name=moveto
    
    [message]
        speaker=Konrad
        message= _ "Yo Kalenz!"
    [/message]
[/event]

Смотрите также