Authoring tools

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML. At present there is only one such tool: trackplacer.

trackplacer

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.

Note that this tool is distributed in the Template:DevFeature. However, it is a Python script with no external dependencies other than pygtk, so it will probably work fine in a 1.4 tree providing you have pygtk installed on your system.

When you run trackplacer, it will pop up a file selection dialogue asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new journey track on that map. If you select a .cfg, the .cfg will be scanned for macros describing a journey track. 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 track for it), you can add journey markers to the track by clicking the left mouse button; they will appear on the screen. 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 icons will remove them.

You can click on and drag a marker to move it. Note that when you add an icon, it is always appended to the end of the track, but moving a marker preserves its place in 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.

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 on .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 if you need to write a couple of different track .cfg files, say for a campaign with branches.

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 propery: map, which records the name of the mapfile on which your track is laid.

'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, slow down.