help.cfg

#textdomain wesnoth-help

[section]
    id=editor
    title= _ "Map and Scenario Editor"
    topics=..editor, editor_map_format, editor_separate_events_file
    sections=editor_mode_terrain, editor_mode_scenario
    sort_topics=no
[/section]

[section]
    id=editor_mode_terrain
    title= _ "Terrain Editor"
    topics=..editor_mode_terrain, editor_palette, editor_masks, editor_tool_paint, editor_tool_fill, editor_tool_select, editor_tool_paste, editor_tool_starting
    sort_topics=no
[/section]

[section]
    id=editor_mode_scenario
    title= _ "Scenario Editor"
    topics=..editor_mode_scenario, editor_tool_label, editor_tool_scenery, editor_tool_unit, editor_tool_village, editor_time_schedule, editor_playlist
    sort_topics=no
[/section]

# wmllint: markcheck off
[topic]
    id=editor_tool_paint
    title= _ "Paint Tool"
    text= "<img>src=icons/action/editor-tool-paint_60.png align=left box=yes</img>" + _ "Paint terrain tiles on the map.

The paint tool utilizes the brush sizes and the terrain palette.

<bold>text='Keyboard Modifiers'</bold>

• Shift+mouse click: If a base terrain is selected, change the base without changing the overlay. If an overlay is selected, change the overlay without changing the base.
• Control+mouse click: Select the terrain under the mouse cursor, as if it had been selected on the terrain palette (picks up both base and overlay).

<bold>text='Brush Sizes'</bold>

The selected brush changes the size of the tool:" +
        "<img>src=icons/action/editor-brush-1_30.png align=left box=yes</img>" + _ "Paint single hexes." +
        "<img>src=icons/action/editor-brush-2_30.png align=left box=yes</img>" + _ "Paint seven hexes at a time." +
        "<img>src=icons/action/editor-brush-3_30.png align=left box=yes</img>" + _ "Paint nineteen hexes at a time." +
        "<img>src=icons/action/editor-brush-nw-se_30.png align=left box=yes</img>" + _ "Paint three hexes in a line." +
        "<img>src=icons/action/editor-brush-sw-ne_30.png align=left box=yes</img>" + _ "Paint three hexes in a line."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_tool_fill
    title= _ "Fill Tool"
    text= "<img>src=icons/action/editor-tool-fill_60.png align=left box=yes</img>" + _ "Fill continuous regions of terrain with a different one.

The fill tool utilizes the terrain palette.

<bold>text='Keyboard Modifiers'</bold>

• Shift+mouse click: If a base terrain is selected, change the base without changing the overlay. If an overlay is selected, change the overlay without changing the base.
• Control+mouse click: Select the terrain under the mouse cursor, as if it had been selected on the terrain palette (picks up both base and overlay)."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_tool_select
    title= _ "Select Tool"
    text= "<img>src=icons/action/editor-tool-select_60.png align=left box=yes</img>" + _ "Selects a set of hex fields, for use with with the cut, copy and fill-selection buttons below the menu bar.

<bold>text='Keyboard Modifiers'</bold>

• Shift+mouse click: ‘Magic Wand’ mode, select the hex under the mouse cursor, and adjoining hexes of the same terrain type.
• Control+mouse click: Unselect hexes.

<bold>text='Brush Sizes'</bold>

The selected brush changes the size of the tool:" +
        "<img>src=icons/action/editor-brush-1_30.png align=left box=yes</img>" + _ "Select single hexes." +
        "<img>src=icons/action/editor-brush-2_30.png align=left box=yes</img>" + _ "Select seven hexes at a time." +
        "<img>src=icons/action/editor-brush-3_30.png align=left box=yes</img>" + _ "Select nineteen hexes at a time." +
        "<img>src=icons/action/editor-brush-nw-se_30.png align=left box=yes</img>" + _ "Select three hexes in a line." +
        "<img>src=icons/action/editor-brush-sw-ne_30.png align=left box=yes</img>" + _ "Select three hexes in a line."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_tool_paste
    title= _ "Clipboard and Paste Tool"
    text= "<img>src=icons/action/editor-paste_60.png align=left box=yes</img>" + _ "Rotate, flip and paste the terrain in the clipboard

Hexes can be cut or copied to the clipboard using the <ref>dst='editor_tool_select' text='Select Tool'</ref>.

The paste tool shows an outline of the clipboard, which can be pasted with a mouse-click. Only the outline is shown, but mistakes can be corrected with the undo function, which is bound to both Control+Z and to the same key as the in-game undo function.

The paste tool also has some clipboard-manipulation functions:" +
        "<img>src=icons/action/editor-clipboard-rotate-cw_30.png align=left box=yes</img>" + _ "Rotate clockwise by 60°." +
        "<img>src=icons/action/editor-clipboard-rotate-ccw_30.png align=left box=yes</img>" + _ "Rotate counter-clockwise by 60°." +
        "<img>src=icons/action/editor-clipboard-flip-horizontal_30.png align=left box=yes</img>" + _ "Flip horizontally" +
        "<img>src=icons/action/editor-clipboard-flip-vertical_30.png align=left box=yes</img>" + _ "Flip vertically"
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_tool_starting
    title= _ "Starting Locations Tool"
    # po: the parts about "10" being shown as "Player 10" use the translatable string "Player $side_num" in the wesnoth-editor textdomain
    text= "<img>src=icons/action/editor-tool-starting-position_60.png align=left box=yes</img>" + _ "Defines the side leader starting position.

This tool sets the side leaders’ default starting locations, and named special locations. Both types of location are enabled in both <ref>dst='..editor_mode_terrain' text='Terrain Editor'</ref> and <ref>dst='..editor_mode_scenario' text='Scenario Editor'</ref> modes. The location names are shown as a list in the editor palette, clicking on the map will place that name on a hex, each location can only be placed on a single hex, and the editor will only allow one location per hex.

To add named special locations, click “Add” at the bottom of the editor palette, and enter the name. These names must start with a letter and may contain numbers and underscores.

More than nine teams can be added to a map, by clicking “Add” and entering a number, for example “10”. The UI will automatically show this as “Player 10”.

Named locations can be accessed from WML using the Standard Location Filter’s <italic>text='location_id='</italic>. Player starts can also be accessed from WML using <italic>text='location_id=1'</italic>, <italic>text='location_id=2'</italic>, etc — use only the number, without adding “Player ” in front of the number.

<bold>text='Keyboard Modifiers'</bold>

• Control+mouse click on a hex that already has a location: select that location for placing with a subsequent mouse click, as if it was selected in the editor palette."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_tool_label
    title= _ "Label Tool"
    text= "<img>src=icons/action/editor-tool-label_60.png align=left box=yes</img>" + _ "Put text labels on the map.

• Left-click will open a dialog box to create a new label or edit an existing one.
• Right-click deletes.
• Drag-and-drop with the left mouse button moves labels.

This tool is only available in Scenario Mode; the decorations are implemented in the scenario using WML’s <italic>text='[label]'</italic> tag."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_tool_scenery
    title= _ "Item Tool (Scenery Tool)"
    text= "<img>src=icons/action/editor-tool-item_60.png align=left box=yes</img>" + _ "The Item Tool allows placing decorations such as windmills, bookcases and monoliths. Multiple items can be placed on the same hex.

<bold>text='Note:'</bold> the tool doesn’t support deleting items once placed, nor does it support undo. Mistakes can currently only be fixed by editing the generated WML file.

This tool is only available in Scenario Mode; the decorations are not part of the terrain and are implemented in the scenario using WML’s <italic>text='[item]'</italic> tag."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_tool_village
    title= _ "Village Ownership Tool"
    text= "<img>src=icons/action/editor-tool-village_60.png align=left box=yes</img>" + _ "This tool assigns ownership of villages at the start of a scenario. The villages must first be placed on the terrain with the <ref>dst='editor_tool_paint' text='Paint Tool'</ref>.

• Left-click will assign the village to the currently-selected side.
• Right-click will set the village back to unowned.

This tool is only available in Scenario Mode; ownership information is stored by adding WML <italic>text='[village]'</italic> tags to the appropriate <italic>text='[side]'</italic>."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_tool_unit
    title= _ "Unit Tool"
    text= "<img>src=icons/action/editor-tool-unit_60.png align=left box=yes</img>" + _ "Place units belonging to the currently-selected side.

• Left-click will place a unit.
• Left drag-and-drop will move an already-placed unit.
• Various operations are added to the right-click menu when the hex contains a unit.

This tool is only available in Scenario Mode; it adds WML <italic>text='[unit]'</italic> tags to the appropriate <italic>text='[side]'</italic>."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_named_area
    title= _ "Named Areas"
    text= _ "This tool create sets of tiles that can be used in WML scripts’ Standard Location Filters (a concept explained in detail on the Wiki), by using the area’s id in the filter’s <italic>text='area='</italic> attribute. For example:

• assigning a local time zone to this set of hexes
• filtering the set of hexes which trigger an event when a unit moves on to them

To use the tool:

• select hexes using the <ref>dst='editor_tool_select' text='select tool'</ref>
• in the Areas menu, select Add New Area
• then in the Areas menu, select Save Selection to Area
• then in the Areas menu, select Rename Selected Area and choose a name for the area

This tool is only available in Scenario Mode; it adds WML <italic>text='[time_area]'</italic> tags to the scenario. Although the tag’s name implies time, it is now more generic and can be used for other purposes without needing to change the time-of-day schedule in the area."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_playlist
    title= _ "Playlist Manager"
    text= "<img>src=icons/action/playlist_30.png align=left box=yes</img>" + _ "Shows a list of music tracks known to the editor, with toggle-boxes to enable them.

This tool is only available in Scenario Mode; it adds WML <italic>text='[music]'</italic> tags to the scenario."
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=..editor
    title= _ "Map/Scenario Editor"
    text= "<img>src=icons/icon-editor.png align=left box=no float=yes</img>" + _ "Wesnoth’s Map and Scenario Editor allows users to create and edit the maps on which every Wesnoth scenario takes place. It also provides a limited set of features for setting up a basic scenario.

The editor can be launched from the <italic>text='Map Editor'</italic> option at the title screen.

<header>text='Editing Modes'</header>

The editor features two modes of operation: terrain mode and scenario mode.

The <ref>dst='..editor_mode_terrain' text='Terrain Mode'</ref> is similar to a simple paint application, with tools to <ref>dst='editor_tool_paint' text='paint'</ref>, <ref>dst='editor_tool_fill' text='fill'</ref>, <ref>dst='editor_tool_select' text='select (and copy)'</ref>, and <ref>dst='editor_tool_paste' text='paste'</ref>. It also has the tool for setting the leaders’ <ref>dst='editor_tool_starting' text='starting locations'</ref>.

The <ref>dst='..editor_mode_scenario' text='Scenario Mode'</ref>, in addition to the tools available in terrain mode, adds support for adding <ref>dst='editor_tool_label' text='labels'</ref>, <ref>dst='editor_tool_scenery' text='scenery items'</ref>, <ref>dst='editor_tool_unit' text='units'</ref> in addition to the leader, and assigning <ref>dst='editor_tool_village' text='village ownership'</ref> at the start of the scenario. There’s also a <ref>dst='editor_playlist' text='playlist manager'</ref> for the music.

<bold>text='Warning: the Scenario Mode is buggy in 1.14.'</bold> Improving it is one of the main blockers for the 1.16 release, however in 1.14 its quality is far below that of the game and the terrain mode." + "

" + _ "<header>text='What you do *not* get'</header>

• Exactly the same map rendering as in-game

The map won’t look exactly the same in the game as it does in the editor, because this depends on the terrain rules. For example, when many mountain hexes are clustered together the terrain rules will try to combine them into mountain ranges and large graphics spanning multiple hexes.

• Event handlers and scripting

The editor is not a tool to help you scripting the scenario’s event handlers.

• Infinite Backwards Compatibility

The editor can load most maps from older versions of Wesnoth, but not all. Maps from 1.3.2 and later will normally be supported, unless they use terrains which are no longer in mainline Wesnoth. Maps from add-ons which have their own terrains will need that add-on to tell the editor about their terrains."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=..editor_mode_terrain
    title= _ "Terrain Editor"
    text= _ "The terrain editor’s functionality is similar to a simple paint application.

The right-hand sidebar contains, from top to bottom, the mini-map, the toolkit (see the pages for each tool), tool options, and <ref>dst='editor_palette' text='Palette'</ref>.

When saved using “Save Map As” and saving to the default directory, the resulting map can be found in the “Custom Maps” game type of the multiplayer “Create Game” dialog."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=..editor_mode_scenario
    title= _ "Scenario Editor"
    text= _ "The scenario editor mode adds support for some map-related WML features, such as areas and scenery items. Most scenarios will still require additional WML to be written using a different tool; the scenario editor does not support scripting the scenario’s events." + "

" + _ "<header>text='Checking whether the editor is in scenario mode'</header>

You can check which mode the editor is in by looking at the menu bar.

• In scenario mode the “Areas” and “Side” menus are enabled.
• In terrain-only mode the “Areas” and “Side” menus are grayed-out." + "

" + _ "<header>text='Entering scenario mode'</header>

To start a new map in scenario mode, choose “New Scenario” from the “File” menu.

If you’re already editing a map in terrain mode, use “Save Scenario As” from the “File” menu; this will switch to scenario mode." + "

To load a map that was created in the scenario editor, use “Load Map” from the “File” menu, and select the .cfg file (not a .map file)." + "

" + _ "<header>text='The files: .map and .cfg'</header>

The map editor saves exactly one file, either a .map (for terrain mode) or a .cfg (for scenario mode). In scenario mode the terrain map is saved inside the .cfg file; there is no separate .map file. If you start editing in terrain mode and then switch to scenaro mode then an old .map file might remain, but this is not updated by the scenario editor.

Loading a .cfg file has different results depending on the contents of the .cfg file. For .cfg files that were created by the scenario editor, it will open the .cfg in the scenario editor. However, for .cfg files that use a separate .map file (which can't be created by the scenario editor), the editor may follow the link and open the corresponding .map in terrain-only mode, as if the .map file was chosen in the file selector."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
[topic]
    id=editor_separate_events_file
    title= _ "Using a separate file for WML events"
    text= _ <<When loading a .cfg file, the scenario editor understands files created by the scenario editor, but is likely to have difficulty with files that have been edited by hand.

Files created by the scenario editor omit the opening [scenario] and closing [/scenario] tags. If you are creating a campaign (or other add-on), then those tags need to be added; there is more detail about this in the <ref>dst='editor_map_format' text='map file format'</ref> documentation.

One workflow is to create a separate WML file, also with the .cfg extension, which uses the WML preprocessor to include the editor-created file. This separate file contains both the [scenario] tag and any hand-edited WML such as events. With this workflow, the add-on’s file structure could look like this:

<header>text='For Wesnoth 1.14'</header>

• _main.cfg:
  ◦ use “{./scenarios}” to include the “scenarios” directory
• maps/map_from_01.cfg
  ◦ this is the file created by the scenario editor
• scenarios/01_Forest.cfg, instead of the opening [scenario] tag put in these four lines:
  ◦ [scenario]
  ◦     {~add-ons/NAME_OF_ADD_ON/maps/map_from_01.cfg}
  ◦ [/scenario]
  ◦ [+scenario]

The first three of those lines insert the scenario-generated file inside a [scenario] tag. The ‘+’ sign on the fourth line means that two scenario tags will be combined, with attributes in the second one overriding attributes in the first one.

<header>text='1.16 and later'</header>

If your add-on will only be used on 1.16 and later, there are new features to load .cfg files via map_file, and to avoid repeating the add-on’s name within the .cfg files.

• _main.cfg:
  ◦ use “[binary_path]” to add add-on’s directories to the binary path, which makes “map_file” search the “maps” directory.
  ◦ use “{./scenarios}” to include the “scenarios” directory
• maps/map_from_01.cfg
  ◦ this is the file created by the scenario editor
• scenarios/01_Forest.cfg
  ◦ inside the [scenario] element, use “map_file="map_from_01.cfg"” to load that file>>
[/topic]
# wmllint: unbalanced-off
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_masks
    title= _ "Editor Mask Usage"
    text= _ "Masks can be applied to a base map for reusal in several scenarios playing at the same locations."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_time_schedule
    # po: Time of Day and Schedule Editor, please use a short string as it will be used in the left-hand pane of the help browser
    title= _ "ToD and Schedule Editor"
    text= "<img>src='icons/action/editor-switch-time_30.png' align=left box=yes</img>" + _ "This button at the top-right of the screen accesses the time-of-day preview and the schedule editor.

In terrain mode, this displays the map as it will be recolored at different times of day.

In scenario mode, the button accesses an editor for individual schedules for <ref>dst='editor_named_area' text='time areas'</ref>."
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
[topic]
    id=editor_palette
    title= _ "Editor Palette"
    # po: the “Player 1”, “Player 2”, ... list is translated using "Player $side_num" in the wesnoth-editor textdomain
    text= _ "The editor palette contains the applicable items you may use with the currently selected tool. For example, the Paint tool will display a full list of all available terrains, and the unit tool will provide a list of available units. When using the Starting Locations Tool, the palette changes to a list of “Player 1”, “Player 2”, etc.

<bold>text='Filter'</bold>

There is a filter function to show only a subset of the available items — this is the leftmost of the four buttons at the top of the palette, and the graphic changes depending on what is selected. Examples:" +
        "<img>src=icons/terrain/terrain_group_all_30.png align=left box=yes</img>" + _ "Show all kinds of terrain" +
        "<img>src=icons/terrain/terrain_group_water_deep_30.png align=left box=yes</img>" + _ "Show only water terrains" +
        "<img>src=icons/terrain/terrain_group_village_30.png align=left box=yes</img>" + _ "Show only villages"
[/topic]
# wmllint: markcheck on

# wmllint: markcheck off
# wmllint: unbalanced-on
# wmlindent: start ignoring
# This section uses << >> quotes so that curly brackets can be used without being interpreted by the preprocessor
# Note: If you change the following description string or this comment line, run wmllint on this file afterwards and make sure wmllint doesn't "improve" the map_data={...} lines.
[topic]
    id=editor_map_format
    title= _ "Wesnoth Map Format"
    text= _ "Wesnoth stores its maps in human readable plain text files." + "

" + _ <<<header>text='Native'</header>

A map file consists of rows with comma separated terrain code strings. The only non-terrain information provided by the map syntax is the set of locations created by the <ref>dst='editor_tool_starting' text='Starting Locations Tool'</ref>. The files can be edited with a general purpose text editor like notepad.

These files can be used directly for multiplayer games, the number of players is automatically determined by the number of starting positions. When saved in the default directory, the map can be found in the “Custom Maps” game type of the multiplayer “Create Game” dialog; you may need to refresh the cache (press F5 on the title screen) before a newly-created map appears.

These files can be used in a scenario’s .cfg file, with the scenario’s WML providing additional information such as teams, custom events, and complex side setups. The .cfg file loads the map file with either of:

• map_file=maps/01_First_Map.map <italic>text='— supported since Wesnoth 1.14'</italic>
• map_data="{maps/01_First_Map.map}" <italic>text='— a WML preprocessor include'</italic>

The <italic>text='map_file'</italic> method is preferred over using a preprocessor include.>> + "

" + _ <<<header>text='Embedded'</header>

The map data can stored as part of a scenario’s .cfg file, directly in the <italic>text='map_data'</italic> attribute. In other words, in the place that the preprocessor would include it when using the preprocessor-include method.

<header>text='Using Embedded Format in Terrain Mode'</header>

If you are editing the map and not using the Scenario Mode support, then it’s trivial to move the data to a native map file before opening it in the editor. This conversion is recommended — the editor supports editing the content of map_data while leaving everything else in the file untouched, but this is rarely-used code. Maps opened this way are marked (E) in the Window menu.>> + "

" + _ <<<header>text='Files created by the Scenario Editor'</header>

In scenario mode, the editor saves the data as a .cfg file with embedded map data. When loading a .cfg file, the scenario editor understands files created by the scenario editor itself, but is likely to have difficulty with files that have been edited by hand; problems can be avoided by <ref>dst='editor_separate_events_file' text='using a separate .cfg file'</ref> for the hand-edited parts.>> + "

" + _ <<<header>text='Which scenario files use the [scenario] tag'</header>

Files created by the scenario editor have the contents of a WML scenario element, but don’t include the opening [scenario] and closing [/scenario] tags. For each .cfg file in the userdata folder’s editor/scenarios subfolder, the game will automatically try to load a scenario from it to include in the “Custom Scenarios” list (files that fail to load are ignored). In this folder each file is a separate item - files that fail to parse as a scenario are ignored, and files must not contain the [scenario][/scenario] tags.

The opposite applies when a scenario is part of a campaign or other add-on. Typically each scenario has its own .cfg file, however this is unnecessary - all of the WML in an add-on will be combined by the preprocessor, it doesn’t matter whether the add-on is written as separate files or not. The engine needs the [scenario]...[/scenario] (or [multiplayer]...[/multiplayer]) tags to know which WML is part of each scenario.>>
[/topic]
# wmlindent: stop ignoring
# wmllint: unbalanced-off
# wmllint: markcheck on