Authoring tools

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML.

tmx_trackplacer

(Version 1.15.3 and later only) tmx_trackplacer is a tool for editing journey tracks - the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

You'll need Tiled, a GPLv2 map editor:

• Debian / Ubuntu: install the "tiled" package
• other platforms: https://www.mapeditor.org/
• these instructions were written with version 1.2.4

Usage

Assume the campaign that we want to make a map for is Story of Wose, which is set on the Green Isle. Start by putting a copy of the map in the campaign:

   mkdir Story_of_Wose/images/maps
   cp WESNOTH_DIR/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Story_of_Wose/images/maps/

Create a template .tmx file with the tool:

   WESNOTH_DIR/data/tools/tmx_trackplacer Story_of_Wose/images/maps/green_isle.png -o temp.tmx

In Tiled

Start Tiled with the temp.tmx file. Expect to see the Green Isle map. On the right hand side of the screen there should be two windows:

• in the top, tabs Minimap, Objects and Layers. The Layers tab will have only background.
• in the bottom, tabs Terrains and Tilesets. The Tilesets tab should have wesnoth journey icons with the red dot, battle and rest markers.

In Layers, create a New Layer of type Object Layer. A typical name for this layer is JOURNEY. Ensure that this layer is selected. From the menu bar at the top, select Insert Tile. From the Tilesets tab, choose dots, battles or rests, and click on the map to add them. The first two items placed will define the start of the journey; every item placed after the first two will be inserted in to the sequence based on whether it appears to be at the end or in the middle.

For Story of Wose, the journey doubles back on itself. For this we'll split the journey in to two parts - rename JOURNEY to JOURNEY_PART1, and add a new layer JOURNEY_PART2. You can use the opacity control at the top of the layers window to see what's on each layer.

JOURNEY_PART1 starts with a battle, and ends with a battle:

JOURNEY_PART2 starts with dots, has a battle and then ends with another battle:

Save the .tmx file.

Creating the .cfg

Convert the .tmx file to a .cfg file:

   WESNOTH_DIR/data/tools/tmx_trackplacer temp.tmx -o Story_of_Wose/utils/bigmap.cfg

Expect to see:

   Read data: <Journey based on map file 'Story_of_Wose/images/maps/green_isle.png', with tracks {JOURNEY_PART1,JOURNEY_PART2}>
   Exporting as cfg

At the moment, tmx_trackplacer doesn't have a way to preview the animations, other than loading the .cfg with Wesnoth itself. For testing, let's put all of the journey in at the start of the first scenario, Story_of_Wose/scenarios/1_The_Oldwood.cfg

   #define STORY_BACKGROUND
       [background_layer]
           image=maps/background.jpg
           scale_vertically=yes
           scale_horizontally=no
           keep_aspect_ratio=yes
       [/background_layer]
       [background_layer]
           image=maps/green_isle.png
           scale_vertically=yes
           scale_horizontally=no
           keep_aspect_ratio=yes
           base_layer=yes
       [/background_layer]
   #enddef

   [story]
       [part]
           {STORY_BACKGROUND}
           {JOURNEY_PART1_STAGE1}
       [/part]
       [part]
           {STORY_BACKGROUND}
           {JOURNEY_PART1_STAGE2}
       [/part]
       [part]
           {STORY_BACKGROUND}
           {JOURNEY_PART1_COMPLETE}
           {JOURNEY_PART2_STAGE1}
       [/part]
       [part]
           {STORY_BACKGROUND}
           {JOURNEY_PART1_COMPLETE}
           {JOURNEY_PART2_STAGE2}
       [/part]
       [part]
           story= _ "Today I want to tell you another story, a mere footnote in the history books if it is even remembered at all."

This should now show at the start of the campaign. Remember to refresh Wesnoth's cache if it doesn't appear.

Could this be integrated as a Tiled plugin?

Yes it could. Implementing it as a file converter was the easier option for development, and the code is (hopefully) modular enough for reuse.

trackviewer

(Version 1.15.3 and later only) Map journey track animation preview tool, shows the journey without needing to start Wesnoth and refresh the cache. It’s a support program which assumes you’re either editing the .cfg file with a text editor or using Tiled with tmx_trackplacer; in other words, it's the part of the old trackplacer that wasn't covered by tmx_trackplacer.

At least on Linux you can have both Tiled and this open on the same file. Save the file in Tiled, alt+tab to this, and press enter to reload the file.

Keys:

• Escape quits
• Return or Enter reloads the .cfg or .tmx file, and restarts the animation
• Space pauses/unpauses

trackplacer

UPDATE: per Elvish_Hunter in this thread: "trackplacer is outdated (it requires the obsolete PyGTK toolkit, which doesn't run on Python 3) and terribly bugged (it doesn't run at all on Windows, for example)." You should either use tmx_trackplacer, or use image editing software to find the X and Y coordinates to create each dot or cross manually.

---

trackplacer is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run trackplacer, it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by trackplacer (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the trackplacer window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, trackplacer looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The Animate button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The Save button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The Properties button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of trackplacer. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to JOURNEY).

The Tracks button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like JOURNEY_STAGE_1, JOURNEY_STAGE_2 and so on. JOURNEY_STAGE_1 will draw the first stage in the 'new' color parts. JOURNEY_STAGE_2 will draw the first stage in the 'old' color and the second stage in the 'new' one; JOURNEY_STAGE_3 will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro JOURNEY_COMPLETE that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments that look like this:

   # trackplacer: tracks begin
   # trackplacer: tracks end

trackplacer will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your journey.cfg, looking like this:

    # trackplacer: <property>=<value>

These set properties that trackplacer may use. At present there is only one such property: map, which records the name of the mapfile on which your track is laid. Don't remove this comment, trackplacer needs it.

trackplacer has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click Animate to refresh and slow down.

CampSynt

CampSynt is a tool to create a not so skeletal campaign as you can view in the help:

       camp-synt -c -n -s [-s] -h [-h] -u [-u] -f -w

       Warning: put underscores instead of spaces or include in double quotes (eg: a_string or "a string")
       Warning: you can use long or short notations for options:
       -c A_str  is the same of -c "A str" and of --campaign=A_str and --campaign="A str"

       OPTIONS:
       -c Name_with_underscores or  "Name in quotes". This option is mandatory.
       -n Number of scenarios if not provided scenario's names via -s option
       -s First_scenario [-s Second_scenario -s Third_scenario -s End]
          one or more scenario names provided in sequential order
       -h Hero_Name [-h Best_Friend -h My_Dog.Wolf]
          one or more hero names to create and use in the story.
          If the name contains a '.' (dot sign) everything following it is considerd as the type of that unit.
       -u new_Unit [-u Another_one -u Last]
          one or more new unit types to be included in the private units folder.
          If the name contains two dot signs it will be splitted this way: new_unit_name, race, copied_from
          like in: Farm_rebel.humans.Peasant
          This need -w option properly set.
       -f Force the rewrite of an existing file.
       -w Wesnoth path (in double quotes if containing spaces) to access original units.
          If this option is set and the path match 1.6 then the directory 'campaigns' is used instead of 'add-ons'.

       EXAMPLES:
       -c Camp_Name  -n  3
       -c Camp_Name  -n  3 -f
       -c Camp_Name  -s Scenario_One  -s Scenario_Two
       -c Camp_Name  -s Scenario_One  -s Scenario_Two -h Hero_Name -u New_unit
       -c Camp_Name  -s One -s Two -h Hero_Name -h His_Friend -u New_unit -u New_Bowman
       -c Camp_Name  -s One -s Two -h Hero -h Friend.New_Bowman -u New_Bowman
       -c Camp_Name  -s One -s Two -h Hero.New_Bowman -u New_Bowman.humans.Peasant

campsynth is a perl script (with core modules usage only, suitable for most Linux systems and packed as exe for the enjoy of some other OS users). It was written based on 1.8.5 version of the game but can be also used with 1.6.x versions and was successfully tested with 1.9.5 (12 apr 2011). campsynth is located at the forum http://forum.wesnoth.org/viewtopic.php?f=8&t=29010