Authoring tools

From The Battle for Wesnoth Wiki
Revision as of 13:51, 14 October 2008 by Esr (talk | contribs) (Document smart insertion.)

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 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.

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 to move it. Moving a marker preserves its place in the track order.

The Animate button erases all icon, then redisplays the 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.

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 property: map, which records the name of the mapfile on which your track is laid. Don't remove this comment, trackplacer needs it.

Remember: when you edit a .cfg file with this tool all data other than the track and the properties are discarded. It is strongly recommended that you never modify a journey .cfg by hand.

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.

trackplacer has a help button that will supply you with a reminder of how the controls work. It also has tooltips on each of its controls.