wesnoth/RELEASE_NOTES

This file is here to allow devs to easily add stuff in the release notes for the next release, it allows easy syncing with the release team, since you don't have to be around when the release takes place...

Just dump whatever you want to have mentioned in the release notes here. Please take care that it is in a way that allows copy&paste to the release notes. That is making sure that spelling/grammar/whatever is usable and that you are using complete sentences, not just single words. Please do use forum syntax and do *NOT* split lines after 80 chars!

Stuff that belongs in here:
* groundbreaking changes (new campaigns, extremely new feature, ...)
* changed dependencies (new things, version bumps, stuff that was removed)
* known bugs

The release team should empty this file after each release.


=======
CHANGES
=======

[rasection="Example section title"]
Example contents.
[/rasection]

[rasection="New user files location on Windows by default"]
[b]Short version:[/b]

The installer no longer provides a choice between storing user files in the installation dir and [c]Documents\My Games\WesnothX.Y[/c], forcing the latter instead (which no longer requires a command-line switch to be added to the game shortcut).

[b]Long version:[/b]

Up to Windows XP, mostly owing to the lack of user and process access control facilities on the mainstream Windows 9x series, applications would freely write user data into their installation paths without restriction. NT-based versions of Windows (including Windows XP) still supported this when running processes as accounts with administrator privileges, albeit at the risk of breaking things horribly in a proper multi-user environment. However, since Windows Vista, this practice is no longer recommended (and rightly so). Because there are too many applications that rely on the aforementioned broken scheme, Vista introduces User Access Control Virtualization to support legacy applications, by redirecting their writes to restricted paths to a user-dependent Virtual Store location.

Until now, the official Wesnoth installer has included the option to store user files either in the user’s Documents folder, or in the installation dir; the latter option forces Wesnoth to rely on UAC Virtualization if Wesnoth has been installed system-wide and then is run with normal user privileges. This has resulted in confusing documentation and countless forum threads on the matter of finding the actual location of Wesnoth’s user files on disk, mostly due to people choosing the install dir option [u]without a real need to do so[/u].

From this version onwards, the installer no longer provides the option to store user files in the installation dir, and the game itself defaults to using the Documents folder (more specifically, [c]Documents\My Games\WesnothX.Y[/c] where [c]X.Y[/c] represents the major and minor version numbers, such as [c]1.13[/c]) unless specifically instructed to do otherwise with the [c]--config-dir[/c] option in the command line. Additionally, [c]--config-dir[/c] paths can be either absolute, relative to [c]Documents\My Games[/c] (to support the previous installer approach to storing files in Documents), or relative to the process current working dir (usually the install dir) if either . or .. are provided as the first path component; this latter option is provided so that people can still install and run Wesnoth from removable media if they wish.

See also bug [bug]23753[/bug].

[b]Command-line changes short version:[/b]

(For people who need to customize the game’s command-line for any reason.)

[b]Before 1.13.2:[/b]
[list]
  [*]Default: use [tt]<cwd>\userdata[/tt]
  [*]With [tt]--config-dir <path>[/tt]: [list]
    [*]use [tt]<Home dir>\Documents\My Games\<path>[/tt] (installer adds [c]--config-dir WesnothX.Y[/c]) if path does not begin with a drive spec
    [*]use absolute [tt]<path>[/tt] otherwise
  [/list]
[/list]

[b]After 1.13.2:/b]
[list]
  [*]Default: use [tt]<Home dir>\Documents\My Games\WesnothX.Y[/tt]
  [*]With [tt]--config-dir <path>[/tt]: [list]
    [*]use [tt]<cwd>\<path>[/tt] if path begins with . or ..
    [*]use [tt]<Home dir>\Documents\My Games\<path>[/tt] (installer adds [c]--config-dir WesnothX.Y[/c]) if path does not begin with a drive spec;
    [*]use absolute [tt]<path>[/tt] otherwise
  [/list]
[/list]
[/rasection]

[rasection="New log files location on Windows"]
From this release onwards, Wesnoth no longer writes its stdout/stderr logs to [tt]stdout.txt[/tt]/[tt]stderr.txt[/tt] in the installation path. Instead, a single combined log file is written to [tt]<user data dir>\logs\wesnoth-<TIMESTAMP>-<PID>.log[/tt] containing all stdout [b]and[/b] stderr output. Up to 8 older log files are kept around, the rest being automatically deleted at game startup. Note that if an early startup failure occurs, the log file will be found at [tt]%TEMP%\wesnoth-<TIMESTAMP>-<PID>.log[/tt] instead.

Since this replaces SDL 1.2's buggy built-in stdout/stderr redirection code with a Unicode-aware alternative, this also fixes bug [bug]22897[/bug].
[/rasection]

[rasection="New game version dialog"]
Describe how awesome the new game version dialog is and how it replaces the old game paths dialog from 1.12.x
[/rasection]

[rasection="Fixed OOS errors on random maps"]
Some people experienced OOS errors on random maps due to sides being placed in different castles in the beginning of the game. This has now been fixed.
[/rasection]

[rasection="Replay turns during mp games"]
It is now possible to load an autosave in an networked mp game: when an autosave is loaded the local gamestate will be reset to the gamestate at that point. Then the game will be replayed (using the replay UI) until the current gamestate. When the current gamestate is reached the replay ui is removed and the game continues normally.
[/rasection]

[rasection="Default values for variables"]
In variable substitution it's now possible to specify default values for example [tt]name="$player_name?Klaus|"[/tt] will evaluate to 'Klaus' in case the variable [tt]player_name[/tt] is not set.
[/rasection]

[rasection="Custom [effect]s"]
It is now possible to create custom effects with the [tt]wesnoth.effects[/tt] lua table.
[/rasection]

[rasection="New [resource] tag similar to mp [modification]s"]
A new tag [resource] was introduced which can contain [event] and [lua] similar to [modification] but its hidden from the user. 
[/rasection]

[rasection="New $other_unit variable for some filters"]
A new [tt]$other_unit[/tt] variable is accessible in some unit filters. This can be used in [tt][filter_adjacent][/tt] and similar contexts to create filters that are relative to the main unit. The backstab and leadership abilities have been rewritten to take advantage of this feature, which allows leadership to be implemented by a single macro, [tt]{ABILITY_LEADERSHIP}[/tt]. Although the old [tt]{ABILITY_LEADERSHIP_LEVEL_3}[/tt] etc macros are still available, they merely point to the new one. As a result, anyone who used a leadership level not matching the unit's level (for example, level 4 leadership on a level 3 unit) will find that this no longer works as expected.
[/rasection]

[rasection="New looping and flow control tags"]
A number of new WML tags have been added for different types of loops as well as loop flow control. The new looping tags are [tt][for][/tt], [tt][foreach][/tt], and [tt][repeat][/tt], while the flow control tags are [tt][continue][/tt], [tt][break][/tt], and [tt][return][/tt]. The [tt]{FOREACH}[/tt] and [tt]{REPEAT}[/tt] macros have been altered to make use of these new loops, which fixes an issue whereby the [tt]{REPEAT}[/tt] macro would not work correctly if nested in itself.
[/rasection]

[rasection="WML/Lua compatibility changes and deprecations"]
[list]
[*][tt][advance][/tt] was changed to [tt][advancement][/tt] in modifications; as a result, AMLA definition macros (such as [tt]{AMLA_DEFAULT}[/tt]) can now be used to create units that have already taken certain advancements
[*][tt]{FOREACH}[/tt] and [tt]{NEXT}[/tt] now use [tt][for][/tt] tags; this is only important for users who used one of these tags without the other, such as a custom loop macro closed by [tt]{NEXT}[/tt]
[*]The interface of [tt]wesnoth.synchronize_choice[/tt] for choices from multiple sides (which was introduced in wesnoth 1.13.0) has changed.
[*][tt]wesnoth.get_unit(underlying_id)[/tt] was removed; this was pretty useless since there was no reliable way to obtain the underlying_id
[*]Changed [tt]wesnoth.put_unit[/tt] so that the unit is passed as the first parameter; the original order is still supported, but is deprecated. In addition, calling [tt]wesnoth.put_unit[/tt] without a unit (ie, with just a location) is deprecated in favor of a new [tt]wesnoth.erase_unit[/tt] function.
[*][side] share_view=yes/no, share_maps=yes/no were replaced with share_vision=all/shroud/none
[*]The menu item syntax (eg [tt]&image.png=Peasant=Easy[/tt]) in campaign difficulty and in [message][option] is now deprecated
[/list]
[/rasection]

==========
KNOWN BUGS
==========

[raissue="Newly introduced in 1.13.x"]
[b]General bugs:[/b]

[list]
[*]The MP server has trouble with Local player types in campaigns (bug [bug]21965[/bug]). We have decided to postpone dealing with this. In the meantime, you might try assigning such sides to the host, or running multiple instances of Wesnoth.
[*]Replaying turns during MP games with the new feature causes OOS in multiplayer games if side controllers changed during the game.
[*]The game can crash when planning recruits in Planning Mode.
[*][tt][event][/tt] in [tt][unit][/tt], [tt][unit_type][/tt] or [tt][side][/tt] does not work as expected.
[*]Using [tt][set_menu_item][/tt] to change an existing menu items fails in some cases.
[/list]
[/raissue]

[raissue="Carried over from 1.12.x"]
[b]General bugs:[/b]

[list]
[*]It’s not possible to clear some default hotkeys with the Clear Hotkey option (bug [bug]21983[/bug]).
[*]Attempting to assign hotkeys including both the Ctrl and Alt modifiers does not work (bug [bug]22219[/bug]).
[/list]

[b]Bugs specific to Microsoft Windows:[/b]

[list]
[*]ClearType font rendering is disabled as it causes glitches (bug [bug]21648[/bug]).
This is likely caused by outdated libraries in the packaging process.
[*]Consecutive line breaks (paragraph breaks) are not rendered as expected (bug [bug]21649[/bug]).
This is likely caused by outdated libraries in the packaging process. There is no built-in workaround available yet.
[/list]

[b]Bugs specific to Apple OS X:[/b]

The following issues affecting Wesnoth on Apple OS X are known and they are pending fixes. Many of them require significant re-engineering that can only be done in 1.13.x development releases later, or cannot be properly addressed due to a lack of experienced OS X coders in our team. Thus, unless someone can contribute patches to address them, it is unlikely that these bugs will be fixed.

[list]
[*]Color cursors are forcibly disabled on this platform due to severe performance issues (bug [bug]18112[/bug]).
[*]The default variable-width font is used instead of a monospace font even where a monospace font is required (bug [bug]23628[/bug]).
[*]Helvetica is used as the default variable-width font instead of DejaVu Sans (bug [bug]23560[/bug]).
[*]Fullscreen mode does not fill the entire screen when maximum resolution is selected in Preferences → Display, and user interface elements are scaled and distorted.
[*]System commands do not work while Wesnoth is running in fullscreen mode (bug [bug]21943[/bug]).
[*]The mouse cursor is not mapped correctly to the game screen contents on Retina displays due to problems with detected vs. real screen resolution mismatches (bug [bug]20332[/bug]).
A workaround is in place making Wesnoth default to 800x600 on OS X regardless of the incorrectly-detected maximum resolution.
[*]Trackpad tap clicking is sometimes not recognized ([url=http://forums.wesnoth.org/viewtopic.php?f=4&t=39788]forum post[/url]).
[*]Unofficial builds  with OpenMP support enabled randomly freeze (bug [bug]18144[/bug]).
[*]Consecutive line breaks (paragraph breaks) are not rendered as expected (bug [bug]21649[/bug]).
This is likely caused by outdated libraries in the packaging process. There is no built-in workaround available yet.
[/list]
[/raissue]