https://wiki.wesnoth.org/api.php?action=feedcontributions&feedformat=atom&user=SigurdTheDragon 2026-06-07T09:33:49Z User contributions MediaWiki 1.31.16 https://wiki.wesnoth.org/index.php?title=LuaWML&diff=43802 2011-10-07T04:06:41Z

<p>SigurdTheDragon: /* Sides */ correction of match_sides to match_side</p> <hr /> <div>{{WML Tags}}<br /> <br /> == The '''[lua]''' tag ==<br /> <br /> This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.1] language.<br /> <br /> The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.<br /> <br /> [lua]<br /> code = &lt;&lt; wesnoth.message &quot;Hello World!&quot; &gt;&gt;<br /> [/lua]<br /> <br /> The Lua kernel can also be accessed from the [[CommandMode|command mode]]:<br /> <br /> :lua local u = wesnoth.get_units({ id = &quot;Konrad&quot; })[1]; u.moves = 5<br /> <br /> The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable &quot;'''...'''&quot;.<br /> <br /> [lua]<br /> code = &lt;&lt; local t = ...; wesnoth.message(tostring(t.text)) &gt;&gt;<br /> [args]<br /> text = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> <br /> == Global environment ==<br /> <br /> All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> function narrator(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/args]<br /> [/lua]<br /> [/event]<br /> <br /> In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> -- The function is now local, since its name does not have to be<br /> -- visible outside this Lua scripts.<br /> local function handler(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> -- Create a new tag named [narrator].<br /> wesnoth.register_wml_action(&quot;narrator&quot;, handler)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [narrator]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/narrator]<br /> [narrator]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/narrator]<br /> [/event]<br /> <br /> The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.<br /> <br /> The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. In {{DevFeature1.9}} the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library are also available. Keep in mind that they aren't multiplayer- and replay-save.<br /> <br /> At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.<br /> <br /> == Examples ==<br /> <br /> The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.<br /> <br /> # General catch for them moving to the wrong place.<br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [if]<br /> [variable]<br /> name=target_hex.is_set<br /> equals=yes<br /> [/variable]<br /> [then]<br /> [if]<br /> [variable]<br /> name=x1<br /> equals=$target_hex.x<br /> [/variable]<br /> [variable]<br /> name=y1<br /> equals=$target_hex.y<br /> [/variable]<br /> [then]<br /> [/then]<br /> [else]<br /> [redraw][/redraw]<br /> [message]<br /> speaker=narrator<br /> message=_ &quot;*Oops!<br /> You moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot; +<br /> _ &quot;<br /> *Left click or press spacebar to continue...&quot;<br /> [/message]<br /> [/else]<br /> [/if]<br /> [/then]<br /> [/if]<br /> [/event]<br /> <br /> A Lua script that performs the same action is presented below.<br /> <br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [lua]<br /> code = &lt;&lt;<br /> local event_data = wesnoth.current.event_context<br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> then<br /> W.redraw()<br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Here is a more detailed explanation of the Lua code. Its first line<br /> <br /> local event_data = wesnoth.current.event_context<br /> <br /> puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.<br /> <br /> The next two lines then test<br /> <br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> <br /> whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> -- skipping some other initializations<br /> -- ...<br /> H.set_wml_var_metatable(_G)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Without a prelude redirecting ''_G'', the conditional would have been written<br /> <br /> if wesnoth.get_variable(&quot;target_hex.is_set&quot;) and<br /> (event_data.x1 ~= wesnoth.get_variable(&quot;target_hex.x&quot;) or event_data.y1 ~= wesnoth.get_variable(&quot;target_hex.y&quot;)<br /> <br /> The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.<br /> <br /> W.redraw()<br /> <br /> Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.<br /> <br /> W = H.set_wml_action_metatable {}<br /> <br /> Without this shortcut, the first statement would have been written<br /> <br /> wesnoth.fire(&quot;redraw&quot;)<br /> <br /> Finally the script displays a message by<br /> <br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> <br /> The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is<br /> <br /> function narrator_says(m)<br /> W.message { speaker=&quot;narrator&quot;,<br /> message = m .. _ &quot;\n*Left click or press spacebar to continue...&quot; }<br /> end<br /> <br /> The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:<br /> <br /> _ = wesnoth.textdomain &quot;wesnoth-tutorial&quot;<br /> <br /> A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].<br /> <br /> == Interface to the engine and helper functions ==<br /> <br /> Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked &quot;read-only&quot; are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.<br /> <br /> Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].<br /> <br /> helper = wesnoth.require &quot;lua/helper.lua&quot;<br /> <br /> === WML variables ===<br /> <br /> * [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]<br /> * [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]<br /> * [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]<br /> * [[LuaWML:Variables#helper.get_child|helper.get_child]]<br /> * [[LuaWML:Variables#helper.child_range|helper.child_range]]<br /> * [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]<br /> * [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]<br /> * [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]<br /> <br /> === Events and WML actions ===<br /> <br /> * [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]<br /> * [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]<br /> * [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]<br /> * [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]<br /> * [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]<br /> * [[LuaWML:Events#helper.wml_error|helper.wml_error]]<br /> * [[LuaWML:Events#helper.literal|helper.literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.parsed|helper.parsed]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]] {{DevFeature1.9}}<br /> <br /> === User interface ===<br /> <br /> * [[LuaWML:Display#wesnoth.message|wesnoth.message]]<br /> * [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]<br /> * [[LuaWML:Display#wesnoth.delay|wesnoth.delay]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]<br /> * [[LuaWML:Display#wesnoth.highlight_hex|wesnoth.highlight_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]<br /> <br /> === Map and terrains ===<br /> <br /> * [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]<br /> * [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]<br /> * [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_image|items.place_image]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_halo|items.place_halo]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.remove|items.remove]] {{DevFeature1.9}}<br /> <br /> === Units ===<br /> <br /> * [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]<br /> * [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]<br /> * [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]<br /> * [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]<br /> * [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]<br /> * [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]<br /> * [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]<br /> * [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]<br /> * [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]<br /> * [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.races|wesnoth.races]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]<br /> * [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]] {{DevFeature1.9}}<br /> <br /> === Sides ===<br /> <br /> * [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]<br /> * [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#helper.all_teams|helper.all_teams]]<br /> <br /> === Pathfinder ===<br /> <br /> * [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]<br /> * [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]<br /> * [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]] {{DevFeature1.9}}<br /> <br /> === Lua files ===<br /> <br /> * [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]<br /> * [[LuaWML:Files#wesnoth.require|wesnoth.require]]<br /> <br /> === Location sets ===<br /> <br /> * [[LuaWML:Location_set#location_set.create|location_set.create]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:empty|location_set:empty]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:size|location_set:size]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:clear|location_set:clear]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:get|location_set:get]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:insert|location_set:insert]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:remove|location_set:remove]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union|location_set:union]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter|location_set:inter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:iter|location_set:iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:filter|location_set:filter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]] {{DevFeature1.9}}<br /> <br /> === Miscellaneous ===<br /> <br /> * [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]<br /> * [[LuaWML:Misc#wesnoth.current|wesnoth.current]]<br /> * [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]<br /> * [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]<br /> * [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]<br /> * [[LuaWML:Misc#helper.rand|helper.rand]] {{DevFeature1.9}}<br /> <br /> == Encoding WML objects into Lua tables ==<br /> <br /> Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.<br /> <br /> Scalar fields are transformed into WML attributes. For instance, the following Lua table<br /> <br /> {<br /> a_bool = true,<br /> an_int = 42,<br /> a_float = 1.25,<br /> a_string = &quot;scout&quot;,<br /> a_translation = _ &quot;Hello World!&quot;<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> a_bool = &quot;yes&quot;<br /> an_int = &quot;42&quot;<br /> a_float = &quot;1.25&quot;<br /> a_string = &quot;scout&quot;<br /> a_translation = _ &quot;Hello World!&quot;<br /> [/dummy]<br /> <br /> WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table &quot;layer&quot; in the corresponding WML table of the form {[1] = &quot;tag_name&quot;, [2] = {}} which is equivalent to {&quot;tag_name&quot;, {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table<br /> <br /> {<br /> foo = 42,<br /> { &quot;bar&quot;, { v = 1, w = 2 } },<br /> { &quot;foo&quot;, { x = false } },<br /> { &quot;bar&quot;, { y = &quot;foo&quot; } },<br /> { &quot;foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } } }<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> foo = 42<br /> [bar]<br /> v = 1<br /> w = 2<br /> [/bar]<br /> [foo]<br /> x = no<br /> [/foo]<br /> [bar]<br /> y = foo<br /> [bar]<br /> [foobar]<br /> z = 5<br /> [barfoo]<br /> [/barfoo]<br /> [/foobar]<br /> [/dummy]<br /> <br /> Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:<br /> {<br /> foo = 42,<br /> [1] = { [1] = &quot;bar&quot;, [2] = { v = 1, w = 2 } },<br /> [2] = { [1] = &quot;foo&quot;, [2] = { x = false } },<br /> [3] = { [1] = &quot;bar&quot;, [2] = { y = &quot;foo&quot; } },<br /> [4] = { [1] = &quot;foobar&quot;, [2] = { z = 5, [1] = { [1] = &quot;barfoo&quot;, [2] = {} } } }<br /> }<br /> <br /> So assuming ''cfg'' contains the above WML object, the following accesses are possible:<br /> <br /> a_int = cfg.foo -- &quot;dummy.foo&quot;, 42<br /> a_string = cfg[3][2].y -- &quot;dummy.bar[1].y&quot;, &quot;foo&quot;<br /> a_table = cfg[4][2] -- &quot;dummy.foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } }<br /> <br /> Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.<br /> <br /> Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.<br /> <br /> For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.<br /> <br /> local old_event_handler<br /> old_event_handler = register_wml_action(&quot;event&quot;,<br /> function(cfg)<br /> -- Get the plain text from the user.<br /> local new_cfg = cfg.__literal<br /> -- The expression below is equivalent to cfg.__parsed.first_time_only,<br /> -- only faster. It is needed, since the first_time_only attribute may<br /> -- reference variables.<br /> local first = cfg.first_time_only<br /> -- Modify the default behavior of first_time_only.<br /> if first == nil then first = false end<br /> new_cfg.first_time_only = first<br /> -- Call the engine handler.<br /> old_event_handler(new_cfg)<br /> end<br /> )<br /> <br /> Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:<br /> <br /> function get_child(cfg, name)<br /> for i = 1, #cfg do<br /> local v = cfg[i]<br /> if v[1] == name then return v[2] end<br /> end<br /> end<br /> <br /> Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:<br /> <br /> if getmetatable(cfg) == &quot;wml object&quot; then cfg = cfg.__parsed end<br /> <br /> The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal''' {{DevFeature1.9}}. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.<br /> <br /> == Skeleton of a preload event ==<br /> <br /> The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> W = H.set_wml_action_metatable {}<br /> _ = wesnoth.textdomain &quot;my-campaign&quot;<br /> <br /> -- Define your global constants here.<br /> -- ...<br /> <br /> H.set_wml_var_metatable(_G)<br /> <br /> -- Define your global functions here.<br /> -- ...<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt; wesnoth.dofile &quot;~add-ons/Whatever/file.lua&quot; &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> == Remarks ==<br /> <br /> The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.<br /> <br /> function random(min, max)<br /> if not max then min, max = 1, min end<br /> wesnoth.fire(&quot;set_variable&quot;, { name = &quot;LUA_random&quot;, rand = string.format(&quot;%d..%d&quot;, min, max) })<br /> local res = wesnoth.get_variable &quot;LUA_random&quot;<br /> wesnoth.set_variable &quot;LUA_random&quot;<br /> return res<br /> end<br /> <br /> [[Category: Lua Reference|*]]<br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=LuaWML&diff=43801 2011-10-07T04:05:45Z

<p>SigurdTheDragon: /* Sides */ added listings for match_sides and get_starting_location</p> <hr /> <div>{{WML Tags}}<br /> <br /> == The '''[lua]''' tag ==<br /> <br /> This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.1] language.<br /> <br /> The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.<br /> <br /> [lua]<br /> code = &lt;&lt; wesnoth.message &quot;Hello World!&quot; &gt;&gt;<br /> [/lua]<br /> <br /> The Lua kernel can also be accessed from the [[CommandMode|command mode]]:<br /> <br /> :lua local u = wesnoth.get_units({ id = &quot;Konrad&quot; })[1]; u.moves = 5<br /> <br /> The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable &quot;'''...'''&quot;.<br /> <br /> [lua]<br /> code = &lt;&lt; local t = ...; wesnoth.message(tostring(t.text)) &gt;&gt;<br /> [args]<br /> text = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> <br /> == Global environment ==<br /> <br /> All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> function narrator(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/args]<br /> [/lua]<br /> [/event]<br /> <br /> In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> -- The function is now local, since its name does not have to be<br /> -- visible outside this Lua scripts.<br /> local function handler(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> -- Create a new tag named [narrator].<br /> wesnoth.register_wml_action(&quot;narrator&quot;, handler)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [narrator]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/narrator]<br /> [narrator]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/narrator]<br /> [/event]<br /> <br /> The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.<br /> <br /> The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. In {{DevFeature1.9}} the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library are also available. Keep in mind that they aren't multiplayer- and replay-save.<br /> <br /> At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.<br /> <br /> == Examples ==<br /> <br /> The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.<br /> <br /> # General catch for them moving to the wrong place.<br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [if]<br /> [variable]<br /> name=target_hex.is_set<br /> equals=yes<br /> [/variable]<br /> [then]<br /> [if]<br /> [variable]<br /> name=x1<br /> equals=$target_hex.x<br /> [/variable]<br /> [variable]<br /> name=y1<br /> equals=$target_hex.y<br /> [/variable]<br /> [then]<br /> [/then]<br /> [else]<br /> [redraw][/redraw]<br /> [message]<br /> speaker=narrator<br /> message=_ &quot;*Oops!<br /> You moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot; +<br /> _ &quot;<br /> *Left click or press spacebar to continue...&quot;<br /> [/message]<br /> [/else]<br /> [/if]<br /> [/then]<br /> [/if]<br /> [/event]<br /> <br /> A Lua script that performs the same action is presented below.<br /> <br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [lua]<br /> code = &lt;&lt;<br /> local event_data = wesnoth.current.event_context<br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> then<br /> W.redraw()<br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Here is a more detailed explanation of the Lua code. Its first line<br /> <br /> local event_data = wesnoth.current.event_context<br /> <br /> puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.<br /> <br /> The next two lines then test<br /> <br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> <br /> whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> -- skipping some other initializations<br /> -- ...<br /> H.set_wml_var_metatable(_G)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Without a prelude redirecting ''_G'', the conditional would have been written<br /> <br /> if wesnoth.get_variable(&quot;target_hex.is_set&quot;) and<br /> (event_data.x1 ~= wesnoth.get_variable(&quot;target_hex.x&quot;) or event_data.y1 ~= wesnoth.get_variable(&quot;target_hex.y&quot;)<br /> <br /> The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.<br /> <br /> W.redraw()<br /> <br /> Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.<br /> <br /> W = H.set_wml_action_metatable {}<br /> <br /> Without this shortcut, the first statement would have been written<br /> <br /> wesnoth.fire(&quot;redraw&quot;)<br /> <br /> Finally the script displays a message by<br /> <br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> <br /> The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is<br /> <br /> function narrator_says(m)<br /> W.message { speaker=&quot;narrator&quot;,<br /> message = m .. _ &quot;\n*Left click or press spacebar to continue...&quot; }<br /> end<br /> <br /> The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:<br /> <br /> _ = wesnoth.textdomain &quot;wesnoth-tutorial&quot;<br /> <br /> A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].<br /> <br /> == Interface to the engine and helper functions ==<br /> <br /> Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked &quot;read-only&quot; are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.<br /> <br /> Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].<br /> <br /> helper = wesnoth.require &quot;lua/helper.lua&quot;<br /> <br /> === WML variables ===<br /> <br /> * [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]<br /> * [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]<br /> * [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]<br /> * [[LuaWML:Variables#helper.get_child|helper.get_child]]<br /> * [[LuaWML:Variables#helper.child_range|helper.child_range]]<br /> * [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]<br /> * [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]<br /> * [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]<br /> <br /> === Events and WML actions ===<br /> <br /> * [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]<br /> * [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]<br /> * [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]<br /> * [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]<br /> * [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]<br /> * [[LuaWML:Events#helper.wml_error|helper.wml_error]]<br /> * [[LuaWML:Events#helper.literal|helper.literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.parsed|helper.parsed]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]] {{DevFeature1.9}}<br /> <br /> === User interface ===<br /> <br /> * [[LuaWML:Display#wesnoth.message|wesnoth.message]]<br /> * [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]<br /> * [[LuaWML:Display#wesnoth.delay|wesnoth.delay]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]<br /> * [[LuaWML:Display#wesnoth.highlight_hex|wesnoth.highlight_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]<br /> <br /> === Map and terrains ===<br /> <br /> * [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]<br /> * [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]<br /> * [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_image|items.place_image]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_halo|items.place_halo]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.remove|items.remove]] {{DevFeature1.9}}<br /> <br /> === Units ===<br /> <br /> * [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]<br /> * [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]<br /> * [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]<br /> * [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]<br /> * [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]<br /> * [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]<br /> * [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]<br /> * [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]<br /> * [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]<br /> * [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.races|wesnoth.races]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]<br /> * [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]] {{DevFeature1.9}}<br /> <br /> === Sides ===<br /> <br /> * [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]<br /> * [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.match_sides|wesnoth.match_sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#helper.all_teams|helper.all_teams]]<br /> <br /> === Pathfinder ===<br /> <br /> * [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]<br /> * [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]<br /> * [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]] {{DevFeature1.9}}<br /> <br /> === Lua files ===<br /> <br /> * [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]<br /> * [[LuaWML:Files#wesnoth.require|wesnoth.require]]<br /> <br /> === Location sets ===<br /> <br /> * [[LuaWML:Location_set#location_set.create|location_set.create]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:empty|location_set:empty]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:size|location_set:size]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:clear|location_set:clear]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:get|location_set:get]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:insert|location_set:insert]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:remove|location_set:remove]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union|location_set:union]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter|location_set:inter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:iter|location_set:iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:filter|location_set:filter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]] {{DevFeature1.9}}<br /> <br /> === Miscellaneous ===<br /> <br /> * [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]<br /> * [[LuaWML:Misc#wesnoth.current|wesnoth.current]]<br /> * [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]<br /> * [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]<br /> * [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]<br /> * [[LuaWML:Misc#helper.rand|helper.rand]] {{DevFeature1.9}}<br /> <br /> == Encoding WML objects into Lua tables ==<br /> <br /> Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.<br /> <br /> Scalar fields are transformed into WML attributes. For instance, the following Lua table<br /> <br /> {<br /> a_bool = true,<br /> an_int = 42,<br /> a_float = 1.25,<br /> a_string = &quot;scout&quot;,<br /> a_translation = _ &quot;Hello World!&quot;<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> a_bool = &quot;yes&quot;<br /> an_int = &quot;42&quot;<br /> a_float = &quot;1.25&quot;<br /> a_string = &quot;scout&quot;<br /> a_translation = _ &quot;Hello World!&quot;<br /> [/dummy]<br /> <br /> WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table &quot;layer&quot; in the corresponding WML table of the form {[1] = &quot;tag_name&quot;, [2] = {}} which is equivalent to {&quot;tag_name&quot;, {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table<br /> <br /> {<br /> foo = 42,<br /> { &quot;bar&quot;, { v = 1, w = 2 } },<br /> { &quot;foo&quot;, { x = false } },<br /> { &quot;bar&quot;, { y = &quot;foo&quot; } },<br /> { &quot;foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } } }<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> foo = 42<br /> [bar]<br /> v = 1<br /> w = 2<br /> [/bar]<br /> [foo]<br /> x = no<br /> [/foo]<br /> [bar]<br /> y = foo<br /> [bar]<br /> [foobar]<br /> z = 5<br /> [barfoo]<br /> [/barfoo]<br /> [/foobar]<br /> [/dummy]<br /> <br /> Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:<br /> {<br /> foo = 42,<br /> [1] = { [1] = &quot;bar&quot;, [2] = { v = 1, w = 2 } },<br /> [2] = { [1] = &quot;foo&quot;, [2] = { x = false } },<br /> [3] = { [1] = &quot;bar&quot;, [2] = { y = &quot;foo&quot; } },<br /> [4] = { [1] = &quot;foobar&quot;, [2] = { z = 5, [1] = { [1] = &quot;barfoo&quot;, [2] = {} } } }<br /> }<br /> <br /> So assuming ''cfg'' contains the above WML object, the following accesses are possible:<br /> <br /> a_int = cfg.foo -- &quot;dummy.foo&quot;, 42<br /> a_string = cfg[3][2].y -- &quot;dummy.bar[1].y&quot;, &quot;foo&quot;<br /> a_table = cfg[4][2] -- &quot;dummy.foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } }<br /> <br /> Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.<br /> <br /> Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.<br /> <br /> For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.<br /> <br /> local old_event_handler<br /> old_event_handler = register_wml_action(&quot;event&quot;,<br /> function(cfg)<br /> -- Get the plain text from the user.<br /> local new_cfg = cfg.__literal<br /> -- The expression below is equivalent to cfg.__parsed.first_time_only,<br /> -- only faster. It is needed, since the first_time_only attribute may<br /> -- reference variables.<br /> local first = cfg.first_time_only<br /> -- Modify the default behavior of first_time_only.<br /> if first == nil then first = false end<br /> new_cfg.first_time_only = first<br /> -- Call the engine handler.<br /> old_event_handler(new_cfg)<br /> end<br /> )<br /> <br /> Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:<br /> <br /> function get_child(cfg, name)<br /> for i = 1, #cfg do<br /> local v = cfg[i]<br /> if v[1] == name then return v[2] end<br /> end<br /> end<br /> <br /> Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:<br /> <br /> if getmetatable(cfg) == &quot;wml object&quot; then cfg = cfg.__parsed end<br /> <br /> The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal''' {{DevFeature1.9}}. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.<br /> <br /> == Skeleton of a preload event ==<br /> <br /> The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> W = H.set_wml_action_metatable {}<br /> _ = wesnoth.textdomain &quot;my-campaign&quot;<br /> <br /> -- Define your global constants here.<br /> -- ...<br /> <br /> H.set_wml_var_metatable(_G)<br /> <br /> -- Define your global functions here.<br /> -- ...<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt; wesnoth.dofile &quot;~add-ons/Whatever/file.lua&quot; &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> == Remarks ==<br /> <br /> The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.<br /> <br /> function random(min, max)<br /> if not max then min, max = 1, min end<br /> wesnoth.fire(&quot;set_variable&quot;, { name = &quot;LUA_random&quot;, rand = string.format(&quot;%d..%d&quot;, min, max) })<br /> local res = wesnoth.get_variable &quot;LUA_random&quot;<br /> wesnoth.set_variable &quot;LUA_random&quot;<br /> return res<br /> end<br /> <br /> [[Category: Lua Reference|*]]<br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=PersistenceWML&diff=43689 2011-09-15T20:07:26Z

<p>SigurdTheDragon: /* WML Syntax */ Edited set and get examples to match description under immediate section</p> <hr /> <div>{{DevFeature1.9}}<br /> {{WML Tags}}<br /> <br /> == Purpose ==<br /> Persistent Variables are used to record information that can be accessed across savegames and session instances. <br /> <br /> For instance, assume that completing a campaign on hard mode should unlock a special item in subsequent playthroughs of this campaign. With a persistent variable, that can be recorded, and made available to the campaign on later plays.<br /> <br /> This can also be used to allow two or more related campaigns to communicate with each other about what has happened in each, allowing the player's choices in one campaign to influence the state of another.<br /> <br /> == Overview ==<br /> Persistent Variables work like [[VariablesWML|normal Variables]], with a few differences.<br /> <br /> {| align=&quot;center&quot; border=&quot;1&quot; style=&quot;text-align:center; color:red; font-size: larger&quot;<br /> <br /> | WARNING: in multiplayer, do not use persistent variables in '''prestart''', '''start''', and other non-synchronized events.<br /> |}<br /> <br /> * During multiplayer, Persistent Variables '''''cannot''''' be used in events that occur before side 1 turn 1, and will force a quit if they occur there.<br /> * Persistent Variables may be assigned, retrieved, or cleared, but not directly queried.<br /> * Persistent Variables may only be assigned from an existing variable, not directly from a constant<br /> * In addition to a name, each Persistent Variable must have a namespace<br /> * In multiplayer campaigns, each Persistent Variable also requires a side<br /> * Persistent Variables will retain their values after wesnoth is closed, until they are cleared or the file containing their namespace is erased or lost.<br /> <br /> == Transactions ==<br /> For the purposes of efficiency, and gameplay consistency, persistent variables are usually not written out to file immediately. Instead, they are grouped into transactions which are sets of changes that are either all written at once, or not written at all. &lt;br/&gt;<br /> The policy regarding persistent variables will be written is as follows:<br /> *Transactions will be committed (written to permanent file) whenever the game autosaves, whenever the player saves the game manually, or whenever a scenario is completed in either victory or defeat.<br /> *Transactions will be cancelled (ignored and wiped from memory) whenever the player loads an earlier savegame, or quits without saving.<br /> *A WML author can mark a change as an exception to a transaction, to be committed immediately by itself, by using setting the attribute &quot;immediate&quot; to &quot;yes&quot; in a [set_global_variable] or [clear_global_variable] tag. Such operations will be written immediately, regardless of the transaction status, without committing any waiting transactions.<br /> <br /> {| align=&quot;center&quot; border=&quot;1&quot; style=&quot;text-align:center;&quot;<br /> <br /> | NOTE: Because of the interaction between persistent variable transactions and user loading/saving of games, it is suggested that any variables a WML author wants to remain consistent for a single playthrough of a scenario should be read in immediately at the beginning of the scenario (side 1 turn 1), and set or cleared only in the victory and/or defeat events.<br /> <br /> |}<br /> <br /> == WML Syntax ==<br /> The following WML Tags are provided.<br /> [set_global_variable]<br /> namespace=my_addon<br /> from_local=foo<br /> to_global=my_variable_name<br /> side=1<br /> immediate=no<br /> [/set_global_variable]<br /> Assigns a persistent variable with the contents of a standard variable<br /> <br /> [get_global_variable]<br /> namespace=my_addon<br /> from_global=my_variable_name<br /> to_local=foo<br /> side=1<br /> [/get_global_variable]<br /> Retrieves the contents of a persistent variable and stores them in a standard variable.<br /> and<br /> [clear_global_variable]<br /> namespace=my_addon<br /> global=my_variable_name<br /> side=1<br /> immediate=no<br /> [/clear_global_variable]<br /> Clears a persistent variable entirely.<br /> === Attribute information ===<br /> ==== namespace ====<br /> This atribute specifies the name of the namespace that the persistent variable resides in.<br /> <br /> *In this attribute, the character &quot;.&quot; means &quot;child of&quot;, <br /> **A namespace equal to &quot;foo.bar&quot; will access a &quot;bar&quot; namespace inside &quot;foo&quot;, creating it if it doesn't already exist, and store the peristent variable inside &quot;bar&quot;.<br /> **If this attribute begins with &quot;.&quot; it will access a child namespace of the default namespace.<br /> ***A namespace equal to &quot;.bar&quot; with the default namespace of &quot;foo&quot; will access a &quot;bar&quot; namespace inside the &quot;foo&quot; namespace.<br /> *In this attribute, the character &quot;^&quot; means &quot;parent of&quot;, must follow a namespace and may only be directly followed by a &quot;.&quot; or another &quot;^&quot;. And is provided so that content creators can easily use macros to eliminate data repitition for the most frequently used namespaces.<br /> **a namespace equal to &quot;{def}^&quot; with the def macro &quot;foo&quot; will access the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^&quot; with the def macro &quot;foo.bar&quot; will access the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^&quot; with the def macro &quot;foo.bar.test&quot; will access the &quot;bar&quot; namespace. inside the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^^&quot; with the def macro &quot;foo.bar.test&quot; will access the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^.rod&quot; with the def macro of &quot;foo.bar&quot; will access the &quot;rod&quot; namespace within the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^^.rod&quot; with the def macro &quot;foo.bar.test&quot; will access the &quot;rod&quot; namespace within the &quot;foo&quot; namespace.<br /> **a namespace equal to &quot;{def}^.quiz&quot; with the def macro &quot;foo.bar.test&quot; will access the &quot;quiz&quot; namespace within the &quot;rod&quot; namespace within the &quot;foo&quot; namespace.<br /> **a namespace beginning with &quot;^&quot; is invalid and will generate a WML error, because it is impossible to determine the parent of nothing.<br /> <br /> ==== *global ====<br /> These attributes (from_global, to_global, and global) specify the name of the persistent variable to be worked with.&lt;br/&gt;<br /> The name of the persistent variable must be a valid variable name, as defined in [[VariablesWML]]<br /> <br /> ==== *local ====<br /> These attributes (from_local, to_local) specify the name of the standard variable to be worked with.<br /> <br /> ==== side ====<br /> This attribute specifies which player client's persistence data should read from or written to in multiplayer.&lt;br/&gt;<br /> This attribute is not used in single player, and may be omitted in single-player only scenarios.&lt;br/&gt;<br /> If this attribute is equal to &quot;global&quot;, the currently active player's data will be read in [get_global_variable] operations, and all player's data will be written to in [set_global_variable] and [clear_global_variable] operations.<br /> <br /> ==== immediate ====<br /> This attribute is an optional boolean value that specifies whether the changes made by the [set_global_variable] or [clear_global_variable] should be stored permanently at the moment they occur.&lt;br/&gt;<br /> If it is set to yes, the namespace's permanent storage will be updated with the change that occurred in the marked tag immediately.&lt;br/&gt;<br /> The default value is no.&lt;br/&gt;<br /> This attribute does not apply to [get_global_variable], which always occurs immediately.<br /> <br /> == About Namespaces ==<br /> Namespaces exist in order to prevent variable collisions from occuring when two or more unrelated campaigns use the same name for some of their persistent variables.<br /> A namespace is simply a name that identifies one set of variables. A namespace may contain only alphabetic characters, digits, and underscores.<br /> <br /> === Internal Separation ===<br /> Just as variables can contain other variables, namespaces may contain other namespaces. The syntax for this works just like container variables: to refer to a namespace &quot;bar&quot; contained within a namespace &quot;foo&quot;, use namespace=&quot;foo.bar&quot;<br /> <br /> === Uniqueness ===<br /> Because situations may arise where persistent variables from campaigns that are not installed concurrently have to coexist, a namespace should be unique per-context. This means that two unrelated campaigns with the same name should use different namespaces, but two or more related campaigns with different names may use the same namespace.<br /> <br /> The following guidelines are provided in order to facilitate this:<br /> ==== Single Standalone Campaign ====<br /> For a single campaign which is not intended to interact with other campaigns, the format &quot;(author_handle)_(campaign_name)&quot; is suggested for namespaces.<br /> As an example, if an author going by &quot;upthorn&quot; in the community were to create a campaign named &quot;foo&quot;, the suggested namespace would be &quot;upthorn_foo&quot;.<br /> <br /> In cases where the author wishes to remain anonymous, or there are many contributing authors (more than say, two or three), the alternate format &quot;(campaign_name)_(month)(year)&quot; is suggested.<br /> Using the above example, assuming that upthorn began work on the campaign on the day this wiki page was created, the resulting namespace would be &quot;foo_may2010&quot;<br /> <br /> ==== Multiple Related Campaigns ====<br /> For multiple related campaigns, there are a few different suggested namespace options depending on order of development and the intended level of interaction.<br /> <br /> ===== Developed or Conceived Concurrently =====<br /> If a campaign is intended from the beginning to be part of a larger world of related campaigns, it is recommended that a namespace be created for the overall world, using the format &quot;(author_handle)_(world_name)&quot; for a named author, or &quot;(world_name)_(month)(year)&quot; for an unnamed author.<br /> As an example, if an author going by &quot;upthorn&quot; were to begin development on a &quot;hypothetical&quot; world the day this page was created, this would result in a namespace of either &quot;upthorn_hypothetical&quot; or &quot;hypothetical_may2010&quot;<br /> <br /> If a campaign in this world is intended to have a high level of interaction, it is recommended that the campaign simply uses the world's namespace as default, and stores any information that it needs to be kept separate in a child namespace of the format &quot;(campaign_name)&quot;.<br /> Building on the above example, if upthorn made a &quot;foo&quot; campaign in the &quot;hypothetical&quot; world, with high level of intended interactivity with the world, it would use &quot;upthorn_hypothetical&quot; as its default namespace, perhaps occasionally storing information in &quot;upthorn_hypothetical.foo&quot;.<br /> <br /> If a campaign in this world is intended to have a medium level of interaction, it is recommended that the campaign creates a child namespace of the format &quot;(campaign_name)&quot; in the world's overall namespace, and uses it as default, accessing the parent namespace when it needs to get information from the overall world.<br /> Continuing with the above examples, if upthorn made a &quot;bar&quot; campaign in the &quot;hypothetical&quot; world, with mid level of intended interactivity with the world, it would use &quot;upthorn_hypothetical.bar&quot; as its default namespace, and somewhat frequently access information in &quot;upthorn_hypothetical&quot;, by using the namespace &quot;^&quot; or explicitly naming &quot;upthorn_hypothetical&quot;.<br /> <br /> If a campaign in this world is intended to have a low level of interaction, it is recommended that the campaign uses an entirely separate namespace, of the format &quot;(world_namespace)_(campaign)&quot; as its default, and accesses the overall world's namespace when it needs to communicate with the world.<br /> Continuing with the above examples, if upthorn made a &quot;fnord&quot; campaign in the &quot;hypothetical&quot; world, with a low level of intended interactivity with the world, it would use &quot;upthorn_hypothetical_fnord&quot; as its default namespace, and occasionally access information in &quot;upthorn_hypothetical&quot;, by explicitly naming &quot;upthorn_hypothetical&quot;.<br /> <br /> ===== Developed Sequentially =====<br /> In cases where the first campaign is intended as a standalone, but some time after its release the same author, or other authors decide to make other campaigns in the same overall continuity, the first campaign's namespace cannot be changed.<br /> <br /> If campaigns are intended to have a high level of interaction, it is recommended that the later campaign uses the namespace of the prior campaign, and makes a child namespace for itself 'if' it needs to save any of its variables separately.<br /> As an example, if an author going by &quot;upthorn&quot; developed a campaign &quot;foo&quot; and later developed a related campaign &quot;bar&quot;, the &quot;bar&quot; campaign would use &quot;upthorn_foo&quot; as its default namespace, and perhaps occasionally store information in &quot;upthorn_foo.bar&quot;<br /> <br /> If campaigns are intended to have a medium level of interaction, it is recommended that the later campaign makes its default namespace a child inside the namespace of the prior campaign that it is most heavily realted to, and accesses the parent namespace when it needs to work with variables from the prior campaign(s).<br /> Working from the above example, upthorn's &quot;bar&quot; campaign would use &quot;upthorn_foo.bar&quot; as its default namespace, and somewhat frequently access the &quot;foo&quot; campaign's information in &quot;upthorn_foo&quot;, either by setting the namespace attribute to &quot;upthorn_foo&quot; explicitly, or by using &quot;^&quot; to get &quot;upthorn_foo.bar&quot;'s parent.<br /> <br /> If campaigns are intended to have a low level of interaction, it is recommended that the later campaign(s) has its own separate namespace using the &quot;Single Standalone Campaign&quot; guideline format, and explicitly name the prior campaign(s)'s namespace(s) for the few times it needs to access them.<br /> Working from the above examples, upthorn's &quot;bar&quot; campaign would use &quot;upthorn_bar&quot; as its default namespace, and occasionally access the &quot;foo&quot; campaign's information in &quot;upthorn_foo&quot;, by explicitly naming &quot;upthorn_foo&quot; as the namespace.</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=LuaWML&diff=43639 2011-09-07T19:33:14Z

<p>SigurdTheDragon: /* Units */ added wesnoth.races and wesnoth.get_traits links</p> <hr /> <div>{{WML Tags}}<br /> <br /> == The '''[lua]''' tag ==<br /> <br /> This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.1] language.<br /> <br /> The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.<br /> <br /> [lua]<br /> code = &lt;&lt; wesnoth.message &quot;Hello World!&quot; &gt;&gt;<br /> [/lua]<br /> <br /> The Lua kernel can also be accessed from the [[CommandMode|command mode]]:<br /> <br /> :lua local u = wesnoth.get_units({ id = &quot;Konrad&quot; })[1]; u.moves = 5<br /> <br /> The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable &quot;'''...'''&quot;.<br /> <br /> [lua]<br /> code = &lt;&lt; local t = ...; wesnoth.message(tostring(t.text)) &gt;&gt;<br /> [args]<br /> text = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> <br /> == Global environment ==<br /> <br /> All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> function narrator(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/args]<br /> [/lua]<br /> [lua]<br /> code = &lt;&lt; narrator(...) &gt;&gt;<br /> [args]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/args]<br /> [/lua]<br /> [/event]<br /> <br /> In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.<br /> <br /> [event]<br /> name = preload<br /> first_time_only = no<br /> [lua]<br /> code = &lt;&lt;<br /> -- The function is now local, since its name does not have to be<br /> -- visible outside this Lua scripts.<br /> local function handler(t)<br /> -- Behave like the [message] tag.<br /> wesnoth.fire(&quot;message&quot;,<br /> { speaker = &quot;narrator&quot;, message = t.sentence })<br /> end<br /> -- Create a new tag named [narrator].<br /> wesnoth.register_wml_action(&quot;narrator&quot;, handler)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> [event]<br /> name = turn 1<br /> [narrator]<br /> sentence = _ &quot;Hello world!&quot;<br /> [/narrator]<br /> [narrator]<br /> sentence = _ &quot;How are you today?&quot;<br /> [/narrator]<br /> [/event]<br /> <br /> The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.<br /> <br /> The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. In {{DevFeature1.9}} the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library are also available. Keep in mind that they aren't multiplayer- and replay-save.<br /> <br /> At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.<br /> <br /> == Examples ==<br /> <br /> The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.<br /> <br /> # General catch for them moving to the wrong place.<br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [if]<br /> [variable]<br /> name=target_hex.is_set<br /> equals=yes<br /> [/variable]<br /> [then]<br /> [if]<br /> [variable]<br /> name=x1<br /> equals=$target_hex.x<br /> [/variable]<br /> [variable]<br /> name=y1<br /> equals=$target_hex.y<br /> [/variable]<br /> [then]<br /> [/then]<br /> [else]<br /> [redraw][/redraw]<br /> [message]<br /> speaker=narrator<br /> message=_ &quot;*Oops!<br /> You moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot; +<br /> _ &quot;<br /> *Left click or press spacebar to continue...&quot;<br /> [/message]<br /> [/else]<br /> [/if]<br /> [/then]<br /> [/if]<br /> [/event]<br /> <br /> A Lua script that performs the same action is presented below.<br /> <br /> [event]<br /> name=moveto<br /> first_time_only=no<br /> [allow_undo][/allow_undo]<br /> [filter]<br /> side=1<br /> [/filter]<br /> <br /> [lua]<br /> code = &lt;&lt;<br /> local event_data = wesnoth.current.event_context<br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> then<br /> W.redraw()<br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> end<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Here is a more detailed explanation of the Lua code. Its first line<br /> <br /> local event_data = wesnoth.current.event_context<br /> <br /> puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.<br /> <br /> The next two lines then test<br /> <br /> if target_hex.is_set and<br /> (event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)<br /> <br /> whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> -- skipping some other initializations<br /> -- ...<br /> H.set_wml_var_metatable(_G)<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> Without a prelude redirecting ''_G'', the conditional would have been written<br /> <br /> if wesnoth.get_variable(&quot;target_hex.is_set&quot;) and<br /> (event_data.x1 ~= wesnoth.get_variable(&quot;target_hex.x&quot;) or event_data.y1 ~= wesnoth.get_variable(&quot;target_hex.y&quot;)<br /> <br /> The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.<br /> <br /> W.redraw()<br /> <br /> Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.<br /> <br /> W = H.set_wml_action_metatable {}<br /> <br /> Without this shortcut, the first statement would have been written<br /> <br /> wesnoth.fire(&quot;redraw&quot;)<br /> <br /> Finally the script displays a message by<br /> <br /> narrator_says(_ &quot;*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.&quot;)<br /> <br /> The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is<br /> <br /> function narrator_says(m)<br /> W.message { speaker=&quot;narrator&quot;,<br /> message = m .. _ &quot;\n*Left click or press spacebar to continue...&quot; }<br /> end<br /> <br /> The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:<br /> <br /> _ = wesnoth.textdomain &quot;wesnoth-tutorial&quot;<br /> <br /> A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].<br /> <br /> == Interface to the engine and helper functions ==<br /> <br /> Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked &quot;read-only&quot; are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.<br /> <br /> Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].<br /> <br /> helper = wesnoth.require &quot;lua/helper.lua&quot;<br /> <br /> === WML variables ===<br /> <br /> * [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]<br /> * [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]<br /> * [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]<br /> * [[LuaWML:Variables#helper.get_child|helper.get_child]]<br /> * [[LuaWML:Variables#helper.child_range|helper.child_range]]<br /> * [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]<br /> * [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]<br /> * [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]<br /> <br /> === Events and WML actions ===<br /> <br /> * [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]<br /> * [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]<br /> * [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]<br /> * [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]<br /> * [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]<br /> * [[LuaWML:Events#helper.wml_error|helper.wml_error]]<br /> * [[LuaWML:Events#helper.literal|helper.literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.parsed|helper.parsed]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]] {{DevFeature1.9}}<br /> * [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]] {{DevFeature1.9}}<br /> <br /> === User interface ===<br /> <br /> * [[LuaWML:Display#wesnoth.message|wesnoth.message]]<br /> * [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]<br /> * [[LuaWML:Display#wesnoth.delay|wesnoth.delay]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]<br /> * [[LuaWML:Display#wesnoth.hilight_hex|wesnoth.hilight_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]] {{DevFeature1.9}}<br /> * [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]<br /> <br /> === Map and terrains ===<br /> <br /> * [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]<br /> * [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]<br /> * [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]<br /> * [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_image|items.place_image]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.place_halo|items.place_halo]] {{DevFeature1.9}}<br /> * [[LuaWML:Tiles#items.remove|items.remove]] {{DevFeature1.9}}<br /> <br /> === Units ===<br /> <br /> * [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]<br /> * [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]<br /> * [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]<br /> * [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]<br /> * [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]<br /> * [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]<br /> * [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]<br /> * [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]<br /> * [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]<br /> * [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.races|wesnoth.races]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]] {{DevFeature1.9}}<br /> * [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]<br /> * [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]] {{DevFeature1.9}}<br /> <br /> === Sides ===<br /> <br /> * [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]<br /> * [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]<br /> * [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]] {{DevFeature1.9}}<br /> * [[LuaWML:Sides#helper.all_teams|helper.all_teams]]<br /> <br /> === Pathfinder ===<br /> <br /> * [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]<br /> * [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]<br /> * [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]<br /> * [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]] {{DevFeature1.9}}<br /> <br /> === Lua files ===<br /> <br /> * [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]<br /> * [[LuaWML:Files#wesnoth.require|wesnoth.require]]<br /> <br /> === Location sets ===<br /> <br /> * [[LuaWML:Location_set#location_set.create|location_set.create]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:empty|location_set:empty]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:size|location_set:size]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:clear|location_set:clear]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:get|location_set:get]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:insert|location_set:insert]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:remove|location_set:remove]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union|location_set:union]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter|location_set:inter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:iter|location_set:iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:filter|location_set:filter]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]] {{DevFeature1.9}}<br /> * [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]] {{DevFeature1.9}}<br /> <br /> === Miscellaneous ===<br /> <br /> * [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]<br /> * [[LuaWML:Misc#wesnoth.current|wesnoth.current]]<br /> * [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]] {{DevFeature1.9}}<br /> * [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]<br /> * [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]<br /> * [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]<br /> * [[LuaWML:Misc#helper.rand|helper.rand]] {{DevFeature1.9}}<br /> <br /> == Encoding WML objects into Lua tables ==<br /> <br /> Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.<br /> <br /> Scalar fields are transformed into WML attributes. For instance, the following Lua table<br /> <br /> {<br /> a_bool = true,<br /> an_int = 42,<br /> a_float = 1.25,<br /> a_string = &quot;scout&quot;,<br /> a_translation = _ &quot;Hello World!&quot;<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> a_bool = &quot;yes&quot;<br /> an_int = &quot;42&quot;<br /> a_float = &quot;1.25&quot;<br /> a_string = &quot;scout&quot;<br /> a_translation = _ &quot;Hello World!&quot;<br /> [/dummy]<br /> <br /> WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table &quot;layer&quot; in the corresponding WML table of the form {[1] = &quot;tag_name&quot;, [2] = {}} which is equivalent to {&quot;tag_name&quot;, {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table<br /> <br /> {<br /> foo = 42,<br /> { &quot;bar&quot;, { v = 1, w = 2 } },<br /> { &quot;foo&quot;, { x = false } },<br /> { &quot;bar&quot;, { y = &quot;foo&quot; } },<br /> { &quot;foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } } }<br /> }<br /> <br /> is equivalent to the content of the following WML object<br /> <br /> [dummy]<br /> foo = 42<br /> [bar]<br /> v = 1<br /> w = 2<br /> [/bar]<br /> [foo]<br /> x = no<br /> [/foo]<br /> [bar]<br /> y = foo<br /> [bar]<br /> [foobar]<br /> z = 5<br /> [barfoo]<br /> [/barfoo]<br /> [/foobar]<br /> [/dummy]<br /> <br /> Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:<br /> {<br /> foo = 42,<br /> [1] = { [1] = &quot;bar&quot;, [2] = { v = 1, w = 2 } },<br /> [2] = { [1] = &quot;foo&quot;, [2] = { x = false } },<br /> [3] = { [1] = &quot;bar&quot;, [2] = { y = &quot;foo&quot; } },<br /> [4] = { [1] = &quot;foobar&quot;, [2] = { z = 5, [1] = { [1] = &quot;barfoo&quot;, [2] = {} } } }<br /> }<br /> <br /> So assuming ''cfg'' contains the above WML object, the following accesses are possible:<br /> <br /> a_int = cfg.foo -- &quot;dummy.foo&quot;, 42<br /> a_string = cfg[3][2].y -- &quot;dummy.bar[1].y&quot;, &quot;foo&quot;<br /> a_table = cfg[4][2] -- &quot;dummy.foobar&quot;, { z = 5, { &quot;barfoo&quot;, {} } }<br /> <br /> Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.<br /> <br /> Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.<br /> <br /> For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.<br /> <br /> local old_event_handler<br /> old_event_handler = register_wml_action(&quot;event&quot;,<br /> function(cfg)<br /> -- Get the plain text from the user.<br /> local new_cfg = cfg.__literal<br /> -- The expression below is equivalent to cfg.__parsed.first_time_only,<br /> -- only faster. It is needed, since the first_time_only attribute may<br /> -- reference variables.<br /> local first = cfg.first_time_only<br /> -- Modify the default behavior of first_time_only.<br /> if first == nil then first = false end<br /> new_cfg.first_time_only = first<br /> -- Call the engine handler.<br /> old_event_handler(new_cfg)<br /> end<br /> )<br /> <br /> Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:<br /> <br /> function get_child(cfg, name)<br /> for i = 1, #cfg do<br /> local v = cfg[i]<br /> if v[1] == name then return v[2] end<br /> end<br /> end<br /> <br /> Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:<br /> <br /> if getmetatable(cfg) == &quot;wml object&quot; then cfg = cfg.__parsed end<br /> <br /> The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal''' {{DevFeature1.9}}. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.<br /> <br /> == Skeleton of a preload event ==<br /> <br /> The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt;<br /> H = wesnoth.require &quot;lua/helper.lua&quot;<br /> W = H.set_wml_action_metatable {}<br /> _ = wesnoth.textdomain &quot;my-campaign&quot;<br /> <br /> -- Define your global constants here.<br /> -- ...<br /> <br /> H.set_wml_var_metatable(_G)<br /> <br /> -- Define your global functions here.<br /> -- ...<br /> &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:<br /> <br /> [event]<br /> name=preload<br /> first_time_only=no<br /> [lua]<br /> code = &lt;&lt; wesnoth.dofile &quot;~add-ons/Whatever/file.lua&quot; &gt;&gt;<br /> [/lua]<br /> [/event]<br /> <br /> == Remarks ==<br /> <br /> The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.<br /> <br /> function random(min, max)<br /> if not max then min, max = 1, min end<br /> wesnoth.fire(&quot;set_variable&quot;, { name = &quot;LUA_random&quot;, rand = string.format(&quot;%d..%d&quot;, min, max) })<br /> local res = wesnoth.get_variable &quot;LUA_random&quot;<br /> wesnoth.set_variable &quot;LUA_random&quot;<br /> return res<br /> end<br /> <br /> [[Category: Lua Reference|*]]<br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=LuaWML/Misc&diff=43636 2011-09-07T18:37:57Z

<p>SigurdTheDragon: /* wesnoth.game_config */ changed poison_amount example to reflect reality</p> <hr /> <div>This page describes miscellaneous [[LuaWML]] objects and helpers.<br /> <br /> ==== wesnoth.game_config ====<br /> <br /> Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:<br /> <br /> * '''version''': string (read only)<br /> * '''base_income''': integer (read/write)<br /> * '''village_income''': integer (read/write)<br /> * '''poison_amount''': integer (read/write)<br /> * '''rest_heal_amount''': integer (read/write)<br /> * '''recall_cost''': integer (read/write)<br /> * '''kill_experience''': integer (read/write)<br /> * '''debug''': boolean (read only)<br /> <br /> -- Poison a bit weak? Let's boost it!<br /> wesnoth.game_config.poison_amount = 15<br /> <br /> ==== wesnoth.current ====<br /> <br /> As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:<br /> <br /> * '''side''': integer (read only)<br /> * '''turn''': integer (read only)<br /> * '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.<br /> <br /> wesnoth.message(string.format(&quot;Turn %d, side %d is playing.&quot;, wesnoth.current.turn, wesnoth.current.side))<br /> <br /> ==== wesnoth.synchronize_choice ====<br /> <br /> {{DevFeature1.9}}<br /> <br /> Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called. An optional second function can be passed; if present, it will be used instead of the first one when the client happens to be an AI (hence not enable to interact with a user interface).<br /> <br /> local result = wesnoth.synchronize_choice(function()<br /> -- Called only on the client handling the current side, if it is a human.<br /> local choice = 0<br /> wesnoth.show_dialog(some_dialog_cfg, nil, function() choice = wesnoth.get_dialog_value &quot;some_list&quot; end)<br /> return { value = choice }<br /> end, function()<br /> -- Called only on the client handling the current side, if it is an AI.<br /> return { value = math.random(some_list_size) }<br /> end)<br /> wesnoth.message(string.format(&quot;Selected item: %d&quot;, result.value))<br /> <br /> ==== wesnoth.get_image_size ====<br /> <br /> {{DevFeature1.9}}<br /> <br /> Returns the width and height of an image.<br /> <br /> local w, h = wesnoth.get_image_size &quot;units/transport/galleon.png&quot;<br /> <br /> ==== wesnoth.compare_versions ====<br /> <br /> {{DevFeature1.9}}<br /> <br /> Takes two versions strings and an operator, returns whether the comparison yields true.<br /> Follows the same rules like the #ifver preprocessor statement.<br /> <br /> local function version_is_sufficient(required)<br /> if not wesnoth.compare_versions then return false end<br /> return wesnoth.compare_versions(wesnoth.game_config.version, &quot;&gt;=&quot;, required)<br /> end<br /> local required = &quot;1.9.6+svn&quot;<br /> if not version_is_sufficient(required) then wesnoth.message(string.format(<br /> &quot;Your BfW version is insufficient, please get BfW %s or greater!&quot;, required)) end<br /> <br /> ==== helper.set_wml_tag_metatable ====<br /> <br /> Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.<br /> <br /> T = helper.set_wml_tag_metatable {}<br /> W.event { name = &quot;new turn&quot;, T.message { speaker = &quot;narrator&quot;, message = &quot;?&quot; } }<br /> <br /> ==== helper.modify_unit ====<br /> <br /> Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.<br /> <br /> helper.modify_unit({ id=&quot;Delfador&quot; }, { moves=0 })<br /> <br /> ==== helper.move_unit_fake ====<br /> <br /> Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.<br /> <br /> helper.move_unit_fake({ id=&quot;Delfador&quot; }, 14, 8)<br /> <br /> ==== helper.rand ====<br /> {{DevFeature1.9}}<br /> <br /> (A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.<br /> <br /> create a random unit at (1, 1) on side=1 :<br /> wesnoth.put_unit(1, 1, { type = helper.rand(&quot;Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout&quot;) })<br /> <br /> [[Category: Lua Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=GameConfigWML&diff=43635 2011-09-07T17:57:34Z

<p>SigurdTheDragon: /* The [game_config] tag */ added poison_amount</p> <hr /> <div>{{WML Tags}}<br /> == The [game_config] tag ==<br /> <br /> This tag is a top level WML tag which can only be used once because<br /> it defines basic settings that are used everywhere in the game.<br /> In official versions of Wesnoth it is in ''game_config.cfg''; values used there are labeled 'standard'.<br /> <br /> <br /> The following keys are recognised<br /> * '''base_income''': (standard 2) how much your leader earns without any villages<br /> * '''village_income''': (standard 1) how much your leader earns for each village you control<br /> * '''poison_amount''': (standard 8) the amount of damage poison deals to a unit<br /> * '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests<br /> * '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.<br /> * '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.<br /> <br /> * '''icon''': (standard 'wesnoth-icon.png') the game icon file<br /> * '''title''': (standard 'misc/title.png') the title screen image<br /> * '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image<br /> * '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario<br /> * '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario<br /> * '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen<br /> * '''logo_x''': (standard 292) the x position of the logo on the title screen<br /> * '''logo_y''': (standard 120) the y position of the logo on the title screen<br /> * '''buttons_x''': (standard 760) the x position of the buttons on the title screen<br /> * '''buttons_y''': (standard 330) the y position of the buttons on the title screen<br /> * '''buttons_padding''': (standard 20) space between buttons, and border in main menu<br /> * '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge<br /> * '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)<br /> * '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.<br /> * '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel<br /> <br /> * '''map_image''': (standard 'maps/wesnoth.png') the background image for the &quot;About&quot; screen<br /> * '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics<br /> * '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics<br /> * '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.<br /> * '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]<br /> * '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units<br /> * ''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units<br /> * '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied. <br /> * '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied. <br /> <br /> * '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]<br /> * '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios<br /> <br /> * '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.<br /> The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;<br /> the second for ones which would take more.<br /> The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].<br /> The 'left' and 'right' designations are used alternately throughout the path;<br /> however, the standard values are the same for 'left' and 'right'.<br /> <br /> * '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.<br /> * '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option <br /> * '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations<br /> <br /> * '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)<br /> * '''download_campaign_image''': (standard no image) the icon for the &quot;Download more Campaigns&quot; campaign menu option.<br /> <br /> == See Also ==<br /> <br /> * [[ReferenceWML]]<br /> <br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=GameConfigWML&diff=43634 2011-09-07T17:47:58Z

<p>SigurdTheDragon: /* The [game_config] tag */ corrected game.cfg to game_config.cfg</p> <hr /> <div>{{WML Tags}}<br /> == The [game_config] tag ==<br /> <br /> This tag is a top level WML tag which can only be used once because<br /> it defines basic settings that are used everywhere in the game.<br /> In official versions of Wesnoth it is in ''game_config.cfg''; values used there are labeled 'standard'.<br /> <br /> <br /> The following keys are recognised<br /> * '''base_income''': (standard 2) how much your leader earns without any villages<br /> * '''village_income''': (standard 1) how much your leader earns for each village you control<br /> * '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests<br /> * '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.<br /> * '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.<br /> <br /> * '''icon''': (standard 'wesnoth-icon.png') the game icon file<br /> * '''title''': (standard 'misc/title.png') the title screen image<br /> * '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image<br /> * '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario<br /> * '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario<br /> * '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen<br /> * '''logo_x''': (standard 292) the x position of the logo on the title screen<br /> * '''logo_y''': (standard 120) the y position of the logo on the title screen<br /> * '''buttons_x''': (standard 760) the x position of the buttons on the title screen<br /> * '''buttons_y''': (standard 330) the y position of the buttons on the title screen<br /> * '''buttons_padding''': (standard 20) space between buttons, and border in main menu<br /> * '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge<br /> * '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)<br /> * '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.<br /> * '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel<br /> <br /> * '''map_image''': (standard 'maps/wesnoth.png') the background image for the &quot;About&quot; screen<br /> * '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics<br /> * '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics<br /> * '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.<br /> * '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]<br /> * '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units<br /> * ''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units<br /> * '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied. <br /> * '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied. <br /> <br /> * '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]<br /> * '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios<br /> <br /> * '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.<br /> The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;<br /> the second for ones which would take more.<br /> The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].<br /> The 'left' and 'right' designations are used alternately throughout the path;<br /> however, the standard values are the same for 'left' and 'right'.<br /> <br /> * '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.<br /> * '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option <br /> * '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations<br /> <br /> * '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)<br /> * '''download_campaign_image''': (standard no image) the icon for the &quot;Download more Campaigns&quot; campaign menu option.<br /> <br /> == See Also ==<br /> <br /> * [[ReferenceWML]]<br /> <br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=GameConfigWML&diff=43633 2011-09-07T17:46:48Z

<p>SigurdTheDragon: /* The [game_config] tag */ added village_income entry</p> <hr /> <div>{{WML Tags}}<br /> == The [game_config] tag ==<br /> <br /> This tag is a top level WML tag which can only be used once because<br /> it defines basic settings that are used everywhere in the game.<br /> In official versions of Wesnoth it is in ''game.cfg''; values used there are labeled 'standard'.<br /> <br /> <br /> The following keys are recognised<br /> * '''base_income''': (standard 2) how much your leader earns without any villages<br /> * '''village_income''': (standard 1) how much your leader earns for each village you control<br /> * '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests<br /> * '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.<br /> * '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.<br /> <br /> * '''icon''': (standard 'wesnoth-icon.png') the game icon file<br /> * '''title''': (standard 'misc/title.png') the title screen image<br /> * '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image<br /> * '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario<br /> * '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario<br /> * '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen<br /> * '''logo_x''': (standard 292) the x position of the logo on the title screen<br /> * '''logo_y''': (standard 120) the y position of the logo on the title screen<br /> * '''buttons_x''': (standard 760) the x position of the buttons on the title screen<br /> * '''buttons_y''': (standard 330) the y position of the buttons on the title screen<br /> * '''buttons_padding''': (standard 20) space between buttons, and border in main menu<br /> * '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge<br /> * '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)<br /> * '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.<br /> * '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel<br /> <br /> * '''map_image''': (standard 'maps/wesnoth.png') the background image for the &quot;About&quot; screen<br /> * '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics<br /> * '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics<br /> * '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.<br /> * '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]<br /> * '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units<br /> * ''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units<br /> * '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied. <br /> * '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied. <br /> <br /> * '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]<br /> * '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios<br /> <br /> * '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.<br /> The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;<br /> the second for ones which would take more.<br /> The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].<br /> The 'left' and 'right' designations are used alternately throughout the path;<br /> however, the standard values are the same for 'left' and 'right'.<br /> <br /> * '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.<br /> * '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option <br /> * '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations<br /> <br /> * '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]<br /> * '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)<br /> * '''download_campaign_image''': (standard no image) the icon for the &quot;Download more Campaigns&quot; campaign menu option.<br /> <br /> == See Also ==<br /> <br /> * [[ReferenceWML]]<br /> <br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=43343 2011-08-08T18:45:45Z

<p>SigurdTheDragon: /* [modify_turns] */ added clarification</p> <hr /> <div>{{WML Tags}}<br /> == Direct actions ==<br /> <br /> Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br /> <br /> The following tags are actions:<br /> <br /> === [endlevel] ===<br /> Ends the scenario.<br /> * '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a &quot;Victory&quot; message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. {{DevFeature}}: All values for result=... except victory and defeat are being discarded in favor of modifying '''[endlevel]''' behaviour with single keys.<br /> Unless ''result=defeat'', the following keys can also be used:<br /> * '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.<br /> * '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br /> * '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.<br /> * '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay. {{DevFeature1.9}}<br /> * '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.<br /> * '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended. {{DevFeature1.9}}<br /> * '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.<br /> <br /> When the result is &quot;victory&quot; the following keys can be used:<br /> * '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br /> * '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.<br /> * '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.<br /> * '''end_text''': Text that is shown centered in a black screen at the end of a campaign. Defaults to &quot;The End&quot;. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br /> * '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br /> <br /> === [unit] ===<br /> Places a unit on the map. For syntax see [[SingleUnitWML]].<br /> * {{Short Note:Predefined Macro|GENERIC_UNIT}}<br /> * '''to_variable''': spawn directly into a variable instead of on the map.<br /> <br /> === [recall] ===<br /> Recalls a unit. The unit is recalled free of charge, and is placed near the leader.<br /> * [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).<br /> * '''x,y''': the unit is placed here instead of next to the leader.<br /> * '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br /> * '''fire_event''': {{DevFeature1.9}} boolean yes|no (default no); whether any according prerecall or recall events shall be fired. In pre-1.9.3 these events are all automatically fired and it can't be turned off.<br /> * '''check_passability''': {{DevFeature1.9}} (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen). Before 1.9 this key is always &quot;no&quot;.<br /> <br /> === [teleport] ===<br /> Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br /> * '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br /> * '''x,y''': the position to teleport to.<br /> * '''clear_shroud''': should shroud be cleared on arrival<br /> * '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br /> * '''ignore_passability''': {{DevFeature}} normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to &quot;yes&quot; permits it. {{DevFeature1.9}}Renamed to check_passability (default yes).<br /> <br /> (Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br /> <br /> === [terrain_mask] ===<br /> Changes the terrain on the map. See [[TerrainMaskWML]].<br /> <br /> === [terrain] ===<br /> Changes the terrain on the map.<br /> * '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br /> * '''x,y''': the position (or range of positions) to change. {{DevFeature1.9}}: [terrain] accepts a [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.<br /> * '''layer''': (overlay|base|both, default=both) only change the specified layer.<br /> * '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.<br /> <br /> === [gold] ===<br /> Gives one side gold.<br /> * '''amount''': the amount of gold to give.<br /> * '''side''': (default=1) the number of the side to give the gold to; {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> <br /> === [unstore_unit] ===<br /> Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.<br /> * '''variable''': the name of the variable.<br /> * '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. <br /> * '''check_passability''': {{DevFeature1.9}} (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always &quot;no&quot;.<br /> * '''text''': (translatable) floating text to display above the unit, such as a damage amount<br /> * '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br /> * '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.<br /> * '''fire_event''': {{DevFeature1.9}}(boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise. Before 1.9 this is always &quot;yes&quot;.<br /> * '''x''' ,'''y''': override unit location, &quot;x,y=recall, recall&quot; will put the unit on the unit's side's recall list.<br /> <br /> === [allow_recruit] ===<br /> Allows a side to recruit units it couldn't previously recruit.<br /> * '''type''': the types of units that the side can now recruit.<br /> * '''side''': (default=1) the number of the side that is being allowed to recruit the units {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [allow_extra_recruit] ===<br /> {{DevFeature1.9}}; Allows a leader to recruit units it couldn't previously recruit.<br /> These types add to the types the leader can recruit because of [side]recruit=.<br /> * '''extra_recruit''': the types of units that the unit can now recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [disallow_recruit] ===<br /> Prevents a side from recruiting units it could previously recruit.<br /> * '''type''': the types of units that the side can no longer recruit.<br /> * '''side''': (default=1) the number of the side that may no longer recruit the units. {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [disallow_extra_recruit] ===<br /> {{DevFeature1.9}}; Prevents a leader from recruiting units it could previously recruit.<br /> * '''extra_recruit''': the types of units that the side can no longer recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [set_recruit] ===<br /> Sets the units a side can recruit.<br /> * '''recruit''': the types of units that the side can now recruit.<br /> * '''side''': (default=1) the number of the side that is having its recruitment set. {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [set_extra_recruit] === <br /> {{DevFeature1.9}}; Sets the units a leader can recruit.<br /> * '''extra_recruit''': the types of units that the leader can now recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [modify_side] ===<br /> Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''<br /> * '''side''': (default=1) the number of the side that is to be changed.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * '''income''': the income given at the begining of each turn.<br /> * '''team_name''': the team in which the side plays the scenario.<br /> * '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br /> * '''gold''': the amount of gold the side owns.<br /> * '''village_gold''': the income setting per village for the side.<br /> * '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.<br /> * '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br /> * '''shroud''': a boolean string describing the status of Shroud for the side.<br /> * '''hidden''': a boolean string specifying whether side is shown in status table.<br /> * '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].<br /> * '''switch_ai''': {{DevFeature}} replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.<br /> * '''share_maps''': {{DevFeature}} change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br /> * '''share_view''': {{DevFeature}} change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br /> <br /> === [modify_turns] ===<br /> Modifies the turn limit in the middle of a scenario.<br /> * '''value''': the new turn limit.<br /> * '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br /> * '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only, cannot be changed to lesser one; also, it is not possible to change the turn number to exceed the turn limit.<br /> <br /> === [capture_village] ===<br /> Changes the ownership of a village.<br /> * '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral.<br /> * '''x, y''': the location of the village. Can be a comma-separated list and/or location ranges. {{DevFeature1.9}}: [capture_village] accepts a full SLF; all village locations matching the filter are affected.<br /> <br /> === [kill] ===<br /> Removes all units (including units in a recall list) that match the filter from the game.<br /> * [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br /> * '''animate''': if 'yes', displays the unit dying (fading away).<br /> * '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'last breath' and 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. In the stable version, the variable second_unit in each of these die and last breath events is always the same as the variable unit (the dying unit). Note that events are only fired for killed units that have been on the map (as opposed to recall list).<br /> * '''[secondary_unit]''' {{DevFeature1.9}} with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).<br /> <br /> === [move_unit] ===<br /> {{DevFeature1.9}}; works like the MOVE_UNIT macro.<br /> * [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.<br /> * '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.<br /> * '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br /> * '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br /> * '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)<br /> <br /> === [modify_ai] ===<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]<br /> <br /> === [modify_unit] ===<br /> {{DevFeature1.9}}; works similar to the MODIFY_UNIT macro.<br /> * '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br /> * Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the :inspect command. Can add traits with immediate effect. Cannot remove things. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.<br /> example usage (see also the test scenario):<br /> [modify_unit]<br /> [filter]<br /> type=Troll Rocklobber<br /> [/filter]<br /> hitpoints=10<br /> [modifications]<br /> [trait]<br /> # first trait is unmodified<br /> [/trait]<br /> {TRAIT_HEALTHY}# second trait is replaced with the healthy trait<br /> [/modifications]<br /> [/modify_unit]<br /> <br /> The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = &quot;$($this_unit.hitpoints / 2)&quot; to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).<br /> <br /> note: The syntax allowed is somehow vague. Just try things and possibly correct/add/modify this documentation. (a [http://forums.wesnoth.org/viewtopic.php?f=21&amp;t=31676&amp; forum thread] discusses some related issues).<br /> <br /> === [transform_unit] ===<br /> {{DevFeature1.9}}; transforms every unit matching the filter to the given unit type. Keeps intact hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.<br /> * [[StandardUnitFilter]]: do not use a [filter] tag.<br /> * '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.<br /> <br /> === [petrify] ===<br /> {{DevFeature1.9}}(This tag never existed until r47553 (from 1.9.3 on), although it was already documented.)<br /> <br /> * [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br /> <br /> === [unpetrify] ===<br /> * [[StandardUnitFilter]] as an argument. {{DevFeature1.9}}: Do not use a [filter] tag. All units matching this filter are unpetrified {{DevFeature1.9}}: recall list units included.<br /> <br /> === [object] ===<br /> Gives some unit an object and removes all items on the tile the unit is on.<br /> * '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.<br /> * '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br /> * '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).<br /> * '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.<br /> * '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.<br /> * '''silent''': whether or not messages should be suppressed. Default is &quot;no&quot;.<br /> * '''image''': the displayed image of the object.<br /> * '''name''': (translatable) displayed as a caption of the image.<br /> <br /> * '''description''': (translatable) displayed as a message of the image.<br /> * '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br /> * If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.<br /> * The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.<br /> <br /> === [remove_shroud] ===<br /> Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br /> * '''side''': (default=1) the side for which to remove shroud. {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br /> <br /> === [place_shroud] ===<br /> Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br /> * '''side''': (default=1) the side for which to place shroud. {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br /> <br /> === [allow_undo] ===<br /> Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.<br /> * Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.<br /> <br /> === [heal_unit] ===<br /> Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). {{DevFeature1.9}} $heal_amount contains only the number of hitpoints the first unit that was found got healed (no change, actually).<br /> * '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed. If no filter is supplied, it is tried to take the unit at $x1, $y1. {{DevFeature1.9}} All matching on-map units are healed.<br /> * '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) {{DevFeature1.9}}...for each of the units healed.<br /> * '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If &quot;full&quot;, sets hitpoints to max_hitpoints. Before 1.9 the default is 0.<br /> * '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br /> * '''moves''': {{DevFeature1.9}} (integer, default 0) The maximum current movement points the units will be &quot;healed&quot;. Can't set below 0 or above max_moves. If &quot;full&quot;, sets moves to max_moves.<br /> * '''restore_attacks''': {{DevFeature1.9}} (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br /> * '''restore_statuses''': {{DevFeature1.9}} (boolean, default yes) Whether standard statuses should be reset to &quot;no&quot;. This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always &quot;no&quot;.<br /> <br /> === [harm_unit] ===<br /> {{DevFeature1.9}}Harms every unit matching the filter, for the specific damage amount.<br /> * '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br /> * '''amount''': the amount of damage that will be done (required).<br /> * '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.<br /> * '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br /> * '''kill''': (default yes) if yes, when an harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.<br /> * '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired.<br /> * '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense and death animations.<br /> * '''[secondary_attack]''': sets the weapon against which the unit harmed will defend, to allow playing specific defense animations. Takes a weapon filter as argument, see [[FilterWML]].<br /> * '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br /> * '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the &quot;harm_amount&quot; key.<br /> * '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br /> <br /> === [time_area] ===<br /> How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag.<br /> * [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br /> * [[TimeWML]]: the new schedule.<br /> * '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br /> * '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.<br /> <br /> === [end_turn] ===<br /> End the current side's turn. {{DevFeature}} The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).<br /> <br /> === [replace_map] ===<br /> <br /> Replaces the entire map.<br /> * '''map''': Content of a wesnoth map file. example:<br /> map=&quot;{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}&quot;<br /> * '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br /> * '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.<br /> <br /> === [replace_schedule] ===<br /> Replace the time of day schedule of the entire scenario. {{DevFeature1.9}}<br /> * [[TimeWML]]: the new schedule.<br /> <br /> === [tunnel] ===<br /> <br /> {{DevFeature1.9}}<br /> <br /> Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain). ([http://forums.wesnoth.org/viewtopic.php?f=21&amp;t=14749&amp;p=405667&amp;hilit=tunnel#p405667 source])<br /> <br /> * '''id''' identifier for the tunnel, to allow removing (optional).<br /> * '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)<br /> * '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)<br /> * '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)<br /> * '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).<br /> * '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).<br /> * '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for &quot;all units&quot;.<br /> <br /> (Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br /> <br /> == Useful Macros ==<br /> There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br /> * '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br /> * '''{FULL_HEAL}''': Brings a unit to full HP<br /> * '''{LOYAL_UNIT}''': Create a loyal unit<br /> * '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br /> <br /> == See Also ==<br /> <br /> * [[InternalActionsWML]]<br /> * [[InterfaceActionsWML]]<br /> * [[EventWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]<br /> [[Category: ActionsWML]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=43342 2011-08-08T16:45:24Z

<p>SigurdTheDragon: /* [endlevel] */ addition of replay_save key</p> <hr /> <div>{{WML Tags}}<br /> == Direct actions ==<br /> <br /> Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br /> <br /> The following tags are actions:<br /> <br /> === [endlevel] ===<br /> Ends the scenario.<br /> * '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a &quot;Victory&quot; message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. {{DevFeature}}: All values for result=... except victory and defeat are being discarded in favor of modifying '''[endlevel]''' behaviour with single keys.<br /> Unless ''result=defeat'', the following keys can also be used:<br /> * '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.<br /> * '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br /> * '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.<br /> * '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay. {{DevFeature1.9}}<br /> * '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.<br /> * '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended. {{DevFeature1.9}}<br /> * '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.<br /> <br /> When the result is &quot;victory&quot; the following keys can be used:<br /> * '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br /> * '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.<br /> * '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.<br /> * '''end_text''': Text that is shown centered in a black screen at the end of a campaign. Defaults to &quot;The End&quot;. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br /> * '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br /> <br /> === [unit] ===<br /> Places a unit on the map. For syntax see [[SingleUnitWML]].<br /> * {{Short Note:Predefined Macro|GENERIC_UNIT}}<br /> * '''to_variable''': spawn directly into a variable instead of on the map.<br /> <br /> === [recall] ===<br /> Recalls a unit. The unit is recalled free of charge, and is placed near the leader.<br /> * [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).<br /> * '''x,y''': the unit is placed here instead of next to the leader.<br /> * '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br /> * '''fire_event''': {{DevFeature1.9}} boolean yes|no (default no); whether any according prerecall or recall events shall be fired. In pre-1.9.3 these events are all automatically fired and it can't be turned off.<br /> * '''check_passability''': {{DevFeature1.9}} (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen). Before 1.9 this key is always &quot;no&quot;.<br /> <br /> === [teleport] ===<br /> Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br /> * '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br /> * '''x,y''': the position to teleport to.<br /> * '''clear_shroud''': should shroud be cleared on arrival<br /> * '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br /> * '''ignore_passability''': {{DevFeature}} normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to &quot;yes&quot; permits it. {{DevFeature1.9}}Renamed to check_passability (default yes).<br /> <br /> (Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br /> <br /> === [terrain_mask] ===<br /> Changes the terrain on the map. See [[TerrainMaskWML]].<br /> <br /> === [terrain] ===<br /> Changes the terrain on the map.<br /> * '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br /> * '''x,y''': the position (or range of positions) to change. {{DevFeature1.9}}: [terrain] accepts a [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.<br /> * '''layer''': (overlay|base|both, default=both) only change the specified layer.<br /> * '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.<br /> <br /> === [gold] ===<br /> Gives one side gold.<br /> * '''amount''': the amount of gold to give.<br /> * '''side''': (default=1) the number of the side to give the gold to; {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> <br /> === [unstore_unit] ===<br /> Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.<br /> * '''variable''': the name of the variable.<br /> * '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. <br /> * '''check_passability''': {{DevFeature1.9}} (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always &quot;no&quot;.<br /> * '''text''': (translatable) floating text to display above the unit, such as a damage amount<br /> * '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br /> * '''advance''': (default=true) if true the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.<br /> * '''fire_event''': {{DevFeature1.9}}(boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise. Before 1.9 this is always &quot;yes&quot;.<br /> * '''x''' ,'''y''': override unit location, &quot;x,y=recall, recall&quot; will put the unit on the unit's side's recall list.<br /> <br /> === [allow_recruit] ===<br /> Allows a side to recruit units it couldn't previously recruit.<br /> * '''type''': the types of units that the side can now recruit.<br /> * '''side''': (default=1) the number of the side that is being allowed to recruit the units {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [allow_extra_recruit] ===<br /> {{DevFeature1.9}}; Allows a leader to recruit units it couldn't previously recruit.<br /> These types add to the types the leader can recruit because of [side]recruit=.<br /> * '''extra_recruit''': the types of units that the unit can now recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [disallow_recruit] ===<br /> Prevents a side from recruiting units it could previously recruit.<br /> * '''type''': the types of units that the side can no longer recruit.<br /> * '''side''': (default=1) the number of the side that may no longer recruit the units. {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [disallow_extra_recruit] ===<br /> {{DevFeature1.9}}; Prevents a leader from recruiting units it could previously recruit.<br /> * '''extra_recruit''': the types of units that the side can no longer recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [set_recruit] ===<br /> Sets the units a side can recruit.<br /> * '''recruit''': the types of units that the side can now recruit.<br /> * '''side''': (default=1) the number of the side that is having its recruitment set. {{DevFeature1.9}} side= can be a comma-separated list<br /> <br /> === [set_extra_recruit] === <br /> {{DevFeature1.9}}; Sets the units a leader can recruit.<br /> * '''extra_recruit''': the types of units that the leader can now recruit.<br /> * '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br /> <br /> === [modify_side] ===<br /> Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''<br /> * '''side''': (default=1) the number of the side that is to be changed.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * '''income''': the income given at the begining of each turn.<br /> * '''team_name''': the team in which the side plays the scenario.<br /> * '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br /> * '''gold''': the amount of gold the side owns.<br /> * '''village_gold''': the income setting per village for the side.<br /> * '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.<br /> * '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br /> * '''shroud''': a boolean string describing the status of Shroud for the side.<br /> * '''hidden''': a boolean string specifying whether side is shown in status table.<br /> * '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].<br /> * '''switch_ai''': {{DevFeature}} replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.<br /> * '''share_maps''': {{DevFeature}} change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br /> * '''share_view''': {{DevFeature}} change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br /> <br /> === [modify_turns] ===<br /> Modifies the turn limit in the middle of a scenario.<br /> * '''value''': the new turn limit.<br /> * '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br /> * '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.<br /> <br /> === [capture_village] ===<br /> Changes the ownership of a village.<br /> * '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral.<br /> * '''x, y''': the location of the village. Can be a comma-separated list and/or location ranges. {{DevFeature1.9}}: [capture_village] accepts a full SLF; all village locations matching the filter are affected.<br /> <br /> === [kill] ===<br /> Removes all units (including units in a recall list) that match the filter from the game.<br /> * [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br /> * '''animate''': if 'yes', displays the unit dying (fading away).<br /> * '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'last breath' and 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. In the stable version, the variable second_unit in each of these die and last breath events is always the same as the variable unit (the dying unit). Note that events are only fired for killed units that have been on the map (as opposed to recall list).<br /> * '''[secondary_unit]''' {{DevFeature1.9}} with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes. The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).<br /> <br /> === [move_unit] ===<br /> {{DevFeature1.9}}; works like the MOVE_UNIT macro.<br /> * [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free passable location is chosen. All target locations passed (see below) need to be passable hexes for the particular moved units.<br /> * '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.<br /> * '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br /> * '''fire_event''' (optional, boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br /> * '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)<br /> <br /> === [modify_ai] ===<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> Changes the AI for a specified side. See [[Customizing_AI_in_Wesnoth_1.8#.5Bmodify_ai.5D_tag]]<br /> <br /> === [modify_unit] ===<br /> {{DevFeature1.9}}; works similar to the MODIFY_UNIT macro.<br /> * '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br /> * Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the :inspect command. Can add traits with immediate effect. Cannot remove things. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.<br /> example usage (see also the test scenario):<br /> [modify_unit]<br /> [filter]<br /> type=Troll Rocklobber<br /> [/filter]<br /> hitpoints=10<br /> [modifications]<br /> [trait]<br /> # first trait is unmodified<br /> [/trait]<br /> {TRAIT_HEALTHY}# second trait is replaced with the healthy trait<br /> [/modifications]<br /> [/modify_unit]<br /> <br /> The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = &quot;$($this_unit.hitpoints / 2)&quot; to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).<br /> <br /> note: The syntax allowed is somehow vague. Just try things and possibly correct/add/modify this documentation. (a [http://forums.wesnoth.org/viewtopic.php?f=21&amp;t=31676&amp; forum thread] discusses some related issues).<br /> <br /> === [transform_unit] ===<br /> {{DevFeature1.9}}; transforms every unit matching the filter to the given unit type. Keeps intact hitpoints, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned.<br /> * [[StandardUnitFilter]]: do not use a [filter] tag.<br /> * '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.<br /> <br /> === [petrify] ===<br /> {{DevFeature1.9}}(This tag never existed until r47553 (from 1.9.3 on), although it was already documented.)<br /> <br /> * [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br /> <br /> === [unpetrify] ===<br /> * [[StandardUnitFilter]] as an argument. {{DevFeature1.9}}: Do not use a [filter] tag. All units matching this filter are unpetrified {{DevFeature1.9}}: recall list units included.<br /> <br /> === [object] ===<br /> Gives some unit an object and removes all items on the tile the unit is on.<br /> * '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.<br /> * '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br /> * '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).<br /> * '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.<br /> * '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.<br /> * '''silent''': whether or not messages should be suppressed. Default is &quot;no&quot;.<br /> * '''image''': the displayed image of the object.<br /> * '''name''': (translatable) displayed as a caption of the image.<br /> <br /> * '''description''': (translatable) displayed as a message of the image.<br /> * '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br /> * If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.<br /> * The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.<br /> <br /> === [remove_shroud] ===<br /> Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br /> * '''side''': (default=1) the side for which to remove shroud. {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br /> <br /> === [place_shroud] ===<br /> Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br /> * '''side''': (default=1) the side for which to place shroud. {{DevFeature1.9}} takes a comma-separated list as of 1.9.5.<br /> * '''[filter_side]''' {{DevFeature1.9}} with a [[StandardSideFilter]] as argument<br /> * [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br /> <br /> === [allow_undo] ===<br /> Allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.<br /> * Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.<br /> <br /> === [heal_unit] ===<br /> Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed). {{DevFeature1.9}} $heal_amount contains only the number of hitpoints the first unit that was found got healed (no change, actually).<br /> * '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed. If no filter is supplied, it is tried to take the unit at $x1, $y1. {{DevFeature1.9}} All matching on-map units are healed.<br /> * '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true) {{DevFeature1.9}}...for each of the units healed.<br /> * '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If &quot;full&quot;, sets hitpoints to max_hitpoints. Before 1.9 the default is 0.<br /> * '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br /> * '''moves''': {{DevFeature1.9}} (integer, default 0) The maximum current movement points the units will be &quot;healed&quot;. Can't set below 0 or above max_moves. If &quot;full&quot;, sets moves to max_moves.<br /> * '''restore_attacks''': {{DevFeature1.9}} (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br /> * '''restore_statuses''': {{DevFeature1.9}} (boolean, default yes) Whether standard statuses should be reset to &quot;no&quot;. This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always &quot;no&quot;.<br /> <br /> === [harm_unit] ===<br /> {{DevFeature1.9}}Harms every unit matching the filter, for the specific damage amount.<br /> * '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br /> * '''amount''': the amount of damage that will be done (required).<br /> * '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.<br /> * '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br /> * '''kill''': (default yes) if yes, when an harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.<br /> * '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired.<br /> * '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense and death animations.<br /> * '''[secondary_attack]''': sets the weapon against which the unit harmed will defend, to allow playing specific defense animations. Takes a weapon filter as argument, see [[FilterWML]].<br /> * '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br /> * '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the &quot;harm_amount&quot; key.<br /> * '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br /> <br /> === [time_area] ===<br /> How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag.<br /> * [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br /> * [[TimeWML]]: the new schedule.<br /> * '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br /> * '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.<br /> <br /> === [end_turn] ===<br /> End the current side's turn. {{DevFeature}} The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).<br /> <br /> === [replace_map] ===<br /> <br /> Replaces the entire map.<br /> * '''map''': Content of a wesnoth map file. example:<br /> map=&quot;{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}&quot;<br /> * '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br /> * '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.<br /> <br /> === [replace_schedule] ===<br /> Replace the time of day schedule of the entire scenario. {{DevFeature1.9}}<br /> * [[TimeWML]]: the new schedule.<br /> <br /> === [tunnel] ===<br /> <br /> {{DevFeature1.9}}<br /> <br /> Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain). ([http://forums.wesnoth.org/viewtopic.php?f=21&amp;t=14749&amp;p=405667&amp;hilit=tunnel#p405667 source])<br /> <br /> * '''id''' identifier for the tunnel, to allow removing (optional).<br /> * '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)<br /> * '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)<br /> * '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)<br /> * '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).<br /> * '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).<br /> * '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for &quot;all units&quot;.<br /> <br /> (Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br /> <br /> == Useful Macros ==<br /> There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br /> * '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br /> * '''{FULL_HEAL}''': Brings a unit to full HP<br /> * '''{LOYAL_UNIT}''': Create a loyal unit<br /> * '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br /> <br /> == See Also ==<br /> <br /> * [[InternalActionsWML]]<br /> * [[InterfaceActionsWML]]<br /> * [[EventWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]<br /> [[Category: ActionsWML]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=41408 2011-03-31T18:49:26Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The '''[generator]''' tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> The map generator function is not very well documented. This rewrite is an attempt to remedy that.<br /> <br /> There are only two kinds of generators, ‘default’ and ‘cave’. As each behaves differently, a section for each has been made.<br /> To use '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:<br /> * '''scenario_generation''': (This is used in the cave examples below)<br /> * '''map_generation''': (This is used in the multiplayer Random Map.)<br /> For which key to use and what value, see the section for the generator you want to use.<br /> <br /> ===The Default Generator===<br /> The default generator can be used to generate map data for any scenario. The data in this section is inferred from “data/multiplayer/scenarios/Random_Scenario.cfg”, usage in add-on content, and inspection of mapgen.cpp<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> To use the default '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:<br /> * '''scenario_generation=default'''<br /> * '''map_generation=default'''<br /> If ‘scenario_generation’ is used, the engine will expect for your entire '''[scenario]''' sub tags to be inside a '''[scenario]''' tag inside '''[generator]'''. Tags outside of this will be ignored. There may be value in this, but at this writing, it’s not clear.<br /> ‘map_generation=default’ is simpler and more commonly used. It is also necessary to use this key so that you can regenerate a map in MP game creation.<br /> In its use only generator data is in the '''[generator]''' tag, all other '''[scenario]''' data is placed outside of it. The exception is if you are making an initial MP scenario available in MP game creation, for this a '''[scenario]''' tag must appear inside of '''[generator]''', containing the '''[scenario]''' subtags you want to use. See “data/multiplayer/scenarios/Random_Scenario.cfg” for an example.<br /> <br /> The following key/tags are recognized for '''[generator]''' when the default generator is used:<br /> * '''[scenario]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size''<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height<br /> * '''lake_size''': the size of a lake still randomly generated<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers<br /> <br /> * '''villages''': villages per 1,000 hexes<br /> * '''players''': Number of starting locations for the map.<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads''': number of roads the generator will attempt to make<br /> * '''road_windiness''': Use 1 for the road to be made using the cheapest path (based on [road_cost] tags), higher values introduce randomness to make the road wind a bit.<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance''': all castles generated must be this number of hexes apart from each other<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> <br /> ===The Cave Generator===<br /> The cave generator does not appear to have been written for multiplayer scenario game creation like the default generator was. It is used in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg''' &amp; '''campaigns\Heir_To_The_Throne\scenarios\ 17_Scepter_of_Fire.cfg '''. The data here is inferred from those scenarios and an inspection of cavegen.cpp<br /> <br /> To use the cave '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:<br /> * '''scenario_generation=cave'''<br /> * '''map_generation=cave'''<br /> Here it is recommend you use ‘scenario_generation’ as there are examples to follow, though it may be possible to use’ map_generation’.<br /> <br /> <br /> The following key/tags are recognized for '''[generator]''' when the cave generator is used:<br /> * '''[settings]''': behaves as if '''[scenario]''', See [[ScenarioWML]]<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''village_density''': influences number of villages<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.<br /> * '''flipy_chance''': Chance to flip y coordinates, that meens the map is mirrored at the horizontal axis in its midth.<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''laziness''':<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=41351 2011-03-31T04:33:20Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The [generator] tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> <br /> The map generator function is not very well documented. The data on this page are inferred from '''scenarios/multiplayer/Random_Map.cfg''' and '''scenarios/Heir_To_The_Throne/Sceptre.cfg'''.<br /> An example for a random underground map that is less complex can be found in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg'''.<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> Updated with some more info and the changes with the new terrain system<br /> <br /> The following keys are recognized for '''[scenario]'''/'''[multiplayer]''' (Use one of them.)<br /> * '''scenario_generation''': (This is used is the cave examples mentioned above.)<br /> * '''map_generation''': (This is used in the multiplayer Random Map.)<br /> &quot;empty&quot; or &quot;default&quot; will use the default generator, &quot;cave&quot; used the cave generator. Other values are not valid.<br /> <br /> The following key/tags are recognized for '''[generator]''':<br /> * '''[scenario]'''/'''[settings]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill (default only)<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size'' (default only)<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake (default only)<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height (default only)<br /> * '''lake_size''': the size of a lake still randomly generated (default only)<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers (default only)<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth. (cave only)<br /> * '''flipy_chance''': Chance to flip y coordinates, that meens the map is mirrored at the horizontal axis in its midth. (cave only)<br /> <br /> * '''villages''': villages per 1,000 hexes (default only)<br /> * '''village_density''': influences number of villages (cave only)<br /> * '''players'''<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads'''<br /> * '''road_windiness'''<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest (default only)<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions (default only).<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages (default only)<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles (default only)<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance'''<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=41350 2011-03-31T04:19:53Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The [generator] tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> <br /> The map generator function is not very well documented. The data on this page are inferred from '''scenarios/multiplayer/Random_Map.cfg''' and '''scenarios/Heir_To_The_Throne/Sceptre.cfg'''.<br /> An example for a random underground map that is less complex can be found in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg'''.<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> Updated with some more info and the changes with the new terrain system<br /> <br /> The following keys are recognized for '''[scenario]'''/'''[multiplayer]''' (Use one of them.)<br /> * '''scenario_generation''': (This is used is the cave examples mentioned above.)<br /> * '''map_generation''': (This is used in the multiplayer Random Map.)<br /> &quot;empty&quot; or &quot;default&quot; will use the default generator, &quot;cave&quot; used the cave generator. Other values are not valid.<br /> <br /> The following key/tags are recognized for '''[generator]''':<br /> * '''[scenario]'''/'''[settings]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill (default only)<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size'' (default only)<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake (default only)<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height (default only)<br /> * '''lake_size''': the size of a lake still randomly generated (default only)<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers (default only)<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth. (cave only)<br /> * '''villages''': villages per 1,000 hexes (default only)<br /> * '''village_density''': influences number of villages (cave only)<br /> * '''players'''<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads'''<br /> * '''road_windiness'''<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest (default only)<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions (default only).<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages (default only)<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles (default only)<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance'''<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=PblWML&diff=41290 2011-03-30T04:00:30Z

<p>SigurdTheDragon: /* author */</p> <hr /> <div>{{WML Tags}}<br /> <br /> To upload an add-on you have made, you need a .pbl file.<br /> <br /> This is a file with name '''data/add-ons/''_add_on_name.pbl'' '''(On Wesnoth 1.8+, it is &quot;_server.pbl&quot;)'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]<br /> <br /> When you upload a add-on, the file '''data/add-ons/''addon-name''.cfg'''<br /> and the directory '''data/add-ons/''addon-name''/''' will be published. Alternatively, '''data/add-ons/''addon-name''.cfg''' can be replaced with '''data/add-ons/''addon-name''/_main.cfg'''. Your add-on must be based entirely on these paths.<br /> <br /> Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.<br /> <br /> == What goes into a .pbl file? ==<br /> <br /> '''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''<br /> <br /> The following keys are recognized for .pbl files:<br /> <br /> === icon ===<br /> : An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and not a custom one. A custom file will work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.<br /> <br /> : If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.<br /> <br /> === title ===<br /> : Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.<br /> <br /> === version ===<br /> : Displayed to the right of the title, it is just text. However, starting with Wesnoth 1.6, the ''required'' format is x.y.z where x, y and z are numbers and a value for x greater than 0 implies the add-on is complete feature-wise. Trailing non-numeric elements are allowed, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])<br /> <br /> === author ===<br /> : Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.<br /> <br /> === passphrase ===<br /> : Not displayed, it prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.<br /> <br /> === description ===<br /> : This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.<br /> <br /> === dependencies ===<br /> : An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])<br /> <br /> === translate ===<br /> : If set to '''true''', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)<br /> <br /> : You should make sure your add-on complies with some very specific [[WesCamp#How_to_contribute_to_this_Project|conventions]] required to ease the process for translators.<br /> <br /> === type ===<br /> : Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:<br /> <br /> :* ''campaign'': single player campaign.<br /> :* ''scenario'': single player scenario.<br /> :* ''era'': multiplayer era.<br /> :* ''faction'': multiplayer stand-alone faction, or add-on for other available era.<br /> :* ''map_pack'': multiplayer map-pack.<br /> :* ''campaign_mp'': multiplayer campaign.<br /> :* ''scenario_mp'': multiplayer scenario. (See the note below.)<br /> :* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.<br /> :* ''other'': The type to use when no other type fits.<br /> <br /> '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.<br /> <br /> === email ===<br /> : Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is ''highly'' recommended that you provide one in case you need to be contacted about your add-on.<br /> <br /> <br /> The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].<br /> <br /> == Examples ==<br /> <br /> === Dependency Key Example ===<br /> <br /> The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:<br /> <br /> dependencies=Imperial_Era,Era_of_Myths<br /> <br /> === Version Key Examples ===<br /> <br /> The following are examples of '''good''' version values:<br /> <br /> version=&quot;1.5&quot;<br /> <br /> version=&quot;0.11.4&quot;<br /> <br /> version=&quot;0.1.4beta&quot;<br /> <br /> version=&quot;1.5c&quot;<br /> <br /> <br /> The following are examples of '''bad''' version values:<br /> <br /> version=&quot;Beta1.5&quot;<br /> <br /> version=&quot;Incomplete (0.3.4)&quot;<br /> <br /> In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.<br /> <br /> <br /> Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.<br /> <br /> 0.5 &lt; 1.0<br /> <br /> 1.5 &lt; 1.5c<br /> <br /> 1.0 &lt; 1.0.1<br /> <br /> 1.0c &lt; 1.0.1a<br /> <br /> 1.0.1a &lt; 1.0.1c<br /> <br /> 1.0 Final &lt; 1.0.1 Beta<br /> <br /> === Example .pbl File ===<br /> <br /> title=&quot;My Campaign&quot;<br /> type=&quot;campaign&quot;<br /> icon=&quot;misc/ball.png&quot;<br /> version=&quot;0.1.2&quot;<br /> author=&quot;Me, artwork by myself&quot;<br /> passphrase=&quot;This is like a password&quot;<br /> description=&quot;You get to kill a lot of bad guys. But only the first map is done.&quot;<br /> email=&quot;name@example.com&quot;<br /> <br /> == See Also ==<br /> <br /> * [[ReferenceWML]]<br /> * [[BuildingCampaignsThePBLFile]]<br /> * [[CampaignServerWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=41125 2011-03-24T17:00:18Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The [generator] tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> <br /> The map generator function is not very well documented. The data on this page are inferred from '''scenarios/multiplayer/Random_Map.cfg''' and '''scenarios/Heir_To_The_Throne/Sceptre.cfg'''.<br /> An example for a random underground map that is less complex can be found in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg'''.<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> Updated with some more info and the changes with the new terrain system<br /> <br /> The following keys are recognized for '''[scenario]'''/'''[multiplayer]''' (Use one of them.)<br /> * '''scenario_generation''': (This is used is the cave examples mentioned above.)<br /> * '''map_generation''': (This is used in the multiplayer Random Map.)<br /> &quot;empty&quot; or &quot;default&quot; will use the default generator, &quot;cave&quot; used the cave generator. Other values are not valid.<br /> <br /> The following key/tags are recognized for '''[generator]''':<br /> * '''[scenario]'''/'''[settings]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill (default only)<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size'' (default only)<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake (default only)<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height (default only)<br /> * '''lake_size''': the size of a lake still randomly generated (default only)<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers (default only)<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.<br /> * '''villages'''<br /> * '''village_density''': tiles per village ???<br /> * '''players'''<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads'''<br /> * '''road_windiness'''<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest (default only)<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions (default only).<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages (default only)<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles (default only)<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance'''<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=41124 2011-03-24T16:58:41Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The [generator] tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> <br /> The map generator function is not very well documented. The data on this page are inferred from '''scenarios/multiplayer/Random_Map.cfg''' and '''scenarios/Heir_To_The_Throne/Sceptre.cfg'''.<br /> An example for a random underground map that is less complex can be found in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg'''.<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> Updated with some more info and the changes with the new terrain system<br /> <br /> The following keys are recognized for '''[scenario]'''/'''[multiplayer]'''<br /> * '''scenario_generation''': (This is used is the cave examples mentioned above.)<br /> * '''map_generation''': (This is used in the multiplayer Random Map.)<br /> &quot;empty&quot; or &quot;default&quot; will use the default generator, &quot;cave&quot; used the cave generator. Other values are not valid.<br /> <br /> The following key/tags are recognized for '''[generator]''':<br /> * '''[scenario]'''/'''[settings]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill (default only)<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size'' (default only)<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake (default only)<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height (default only)<br /> * '''lake_size''': the size of a lake still randomly generated (default only)<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers (default only)<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.<br /> * '''villages'''<br /> * '''village_density''': tiles per village ???<br /> * '''players'''<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads'''<br /> * '''road_windiness'''<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest (default only)<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions (default only).<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages (default only)<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles (default only)<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance'''<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon https://wiki.wesnoth.org/index.php?title=MapGeneratorWML&diff=40718 2011-03-09T20:40:59Z

<p>SigurdTheDragon: /* [generator] */</p> <hr /> <div>== [generator] ==<br /> <br /> The [generator] tag replaces a scenario's map data;<br /> in fact its whole purpose is to generate the map data given a set of configuration parameters.<br /> <br /> The map generator function is not very well documented. The data on this page are inferred from '''scenarios/multiplayer/Random_Map.cfg''' and '''scenarios/Heir_To_The_Throne/Sceptre.cfg'''.<br /> An example for a random underground map that is less complex can be found in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg'''.<br /> <br /> '''Excerpt from mapgenerator comments:'''<br /> <br /> * Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.<br /> <br /> Updated with some more info and the changes with the new terrain system<br /> <br /> The following key is recognized for '''[scenario]'''/'''[multiplayer]'''<br /> * '''map_generation''': &quot;empty&quot; or &quot;default&quot; will use the default generator, &quot;cave&quot; used the cave generator. Other values are not valid. <br /> <br /> The following key/tags are recognized for '''[generator]''':<br /> * '''[scenario]'''/'''[settings]''': See [[ScenarioWML]]<br /> * '''name'''<br /> ** '''default''''<br /> * '''map_width''','''map_height''': size of the map to generate<br /> * '''iterations''': the number of times an attempt is being made to generate a hill (default only)<br /> * '''hill_size''': hills will have a random size between 1 and ''hill_size'' (default only)<br /> * '''max_lakes''': the number of times an attempt is being made to generate a lake (default only)<br /> * '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height (default only)<br /> * '''lake_size''': the size of a lake still randomly generated (default only)<br /> * '''river_frequency''': determine how much a river can run uphill and thus generate more rivers (default only)<br /> * '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.<br /> * '''villages'''<br /> * '''village_density''': tiles per village ???<br /> * '''players'''<br /> * '''castle_size''': Number of castle tiles (including the keep), per player.<br /> * '''temperature_iterations''': Same as iterations, but for the temperature map.<br /> * '''temperature_size''': Same as hill_size, but for the temperature map.<br /> (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)<br /> * '''roads'''<br /> * '''road_windiness'''<br /> * '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)<br /> * '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).<br /> * '''[height]''': list of common terrain types<br /> which come in at different heights, from highest to lowest (default only)<br /> Good WML will have the range of 1000-0 covered.<br /> ** '''height''': the terrain specified below will appear at this height and up.<br /> ** '''terrain''': 1 terrain code<br /> * '''[convert]''': used to make terrain conversions (default only).<br /> For example water becomes ice at low temperatures, grass snow, etc.<br /> If the terrain is between the min_x and max_x it will be converted<br /> if min_x is not defined it will default to a large negative number<br /> if max_x is not defined it will default to a large positive number<br /> ** '''min_height'''<br /> ** '''max_height'''<br /> ** '''min_temperature'''<br /> ** '''max_temperature'''<br /> ** '''from''': a comma separated terrains to convert from<br /> ** '''to''': The terrain to convert these terrains to<br /> * '''[road_cost]'''<br /> ** '''terrain''' 1 terrain code<br /> ** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road<br /> ** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.<br /> ** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)<br /> * '''[village]''': The conversion of terrains to villages (default only)<br /> ** '''terrain''': 1 terrain code which will be converted to a village<br /> ** '''convert_to''': 1 terrain code for the village<br /> ** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.<br /> ** '''rating''': chance of appearing<br /> * '''[castle]''': the conversion of castles (default only)<br /> ** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.<br /> ** '''min_distance'''<br /> * '''[naming]'''<br /> ** '''male_names'''<br /> * '''[village_naming]'''<br /> ** '''male_names'''<br /> * '''[chamber]''': for underground maps<br /> ** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.<br /> ** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)<br /> ** '''size''': circular radius of the chamber, including the center hex<br /> ** '''jagged''': a good value is probably between 0-50 (not sure exactly)<br /> ** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.<br /> ** '''[passage]''': defines a pathway between chambers<br /> *** '''destination''': the id key of the destination chamber<br /> *** '''windiness''': a good value is probably between 1-10<br /> *** '''width''': number of hexes<br /> *** '''jagged''': a good value is probably between 1-10<br /> *** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present<br /> <br /> == See Also ==<br /> <br /> * [[ScenarioWML]]<br /> * [[ReferenceWML]]<br /> <br /> [[Category: WML Reference]]</div>

SigurdTheDragon