Authoring tools

From The Battle for Wesnoth Wiki
Revision as of 19:22, 18 July 2018 by Sapient (talk | contribs) (trackplacer bugs)

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

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)." Until it is fixed, you should 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