The Battle for Wesnoth Wiki - User contributions [en]

User:Iceiceice/Cross-compiling

2015-05-11T01:19:02Z

Iceiceice:

Here are some instructions I created the first time I managed to cross compile wesnoth. It's as much a "post-mortem" as a guide, I leave it here in case I ever want to do it again later, or if it might help someone.

These instructions refer to using mingw to cross-compile wesnoth 1.13.0-dev on Linux Mint Qiana 17 , targeted at 32-bit windows.

Last tested at commit: bce5fb22e59f467973ad27c22a6d8101e930f92b

== Get mingw32 ==

It might seem as simple as "sudo apt-get install mingw32", but after you do this, you need to make sure that you have a 32 bit compiler which is good enough to compile wesnoth. This required some trial and error, the version I got automatically from the distribution was only gcc 4.2, as you can see:

$ i586-mingw32msvc-g++ -v
Using built-in specs.
Target: i586-mingw32msvc
Configured with: /build/buildd/mingw32-4.2.1.dfsg/build_dir/src/gcc-4.2.1-2-dfsg/configure -v --prefix=/usr --target=i586-mingw32msvc --enable-languages=c,c++ --enable-threads --enable-sjlj-exceptions --disable-multilib --enable-version-specific-runtime-libs
Thread model: win32
gcc version 4.2.1-sjlj (mingw32-2)

Furthermore it was broken, and had some bugs about ::swprintf not defined, which caused boost iostreams to break... google this for some stories of pain. [http://www.gaia-gis.it/spatialite-2.4.0-3/mingw_how_to.html] [http://cboard.cprogramming.com/windows-programming/126629-error-'-swprintf'-has-not-been-declared.html] [http://qt-project.org/forums/viewthread/8055]

Therefore to get a more recent version of mingw I added a package from utopic universe :

$ sudo add-apt-repository -y "deb http://archive.ubuntu.com/ubuntu/ utopic main universe"

And I install

$ sudo apt-get install g++-mingw-w64-i686

(Launchpad page: http://packages.ubuntu.com/utopic/g++-mingw-w64-x86-64)

Now I get this instead

$ i686-w64-mingw32-g++ -v
Using built-in specs.
COLLECT_GCC=i686-w64-mingw32-g++
COLLECT_LTO_WRAPPER=/usr/lib/gcc/i686-w64-mingw32/4.9-win32/lto-wrapper
Target: i686-w64-mingw32
Configured with: ../../src/configure --build=x86_64-linux-gnu --prefix=/usr --includedir='/usr/include' --mandir='/usr/share/man' --infodir='/usr/share/info' --sysconfdir=/etc --localstatedir=/var --libexecdir='/usr/lib/gcc-mingw-w64' --disable-maintainer-mode --disable-dependency-tracking --prefix=/usr --enable-shared --enable-static --disable-multilib --with-system-zlib --libexecdir=/usr/lib --without-included-gettext --libdir=/usr/lib --enable-libstdcxx-time=yes --with-tune=generic --enable-version-specific-runtime-libs --enable-fully-dynamic-string --enable-libgomp --enable-languages=c,c++,fortran,objc,obj-c++ --enable-lto --with-plugin-ld --enable-threads=win32 --program-suffix=-win32 --program-prefix=i686-w64-mingw32- --target=i686-w64-mingw32 --with-as=/usr/bin/i686-w64-mingw32-as --with-ld=/usr/bin/i686-w64-mingw32-ld
Thread model: win32
gcc version 4.9.1 (GCC)

With gcc 4.9, now we are in business.

== Download loonycyborg's wesnoth deps collection ==

http://sourceforge.net/projects/wesnoth/files/SDK/wesnoth-deps-1.11.zip/download

I'm going to assume henceforth that you extract this to the folder "~/w-deps", and that inside is "include", "bin" etc. directories.

== Download boost ==

I wanted to test our stated boost dependencies, so I actually make a folder "~/old-boost/" where I hold several versions of boost. You can find any old version of boost at sourceforge, e.g.

http://sourceforge.net/projects/boost/files/boost/1.52.0/

http://sourceforge.net/projects/boost/files/boost/1.48.0/

http://sourceforge.net/projects/boost/files/boost/1.44.0/

etc.

Download one of these and extract it to ~/old-boost/, or take from w-deps folder.

I'm going to assume that you picked boost 1.52.0, so your boost directory is ~/old_boost/boost_1_52_0/.

== Make a boost config file (tell it what compiler you want to use) ==

In your home directory, make a text file called user_config.jam.

Here's some sample contents:

$ cat user-config.jam
using gcc ;
using gcc : 4.6 : g++-4.6 ;
using gcc : w64mingw32 : i586-mingw32msvc-g++ ;
using gcc : w64mingw64 : x86_64-w64-mingw32-g++ ;

When boost has a file like this, it means that e.g. "toolset=gcc-4.6" will cause it to use the compiler g++-4.6, and "toolset=gcc-w64mingw32" will cause it to use the compiler i586-mingw32msvc-g++.

Make a line like this:

using gcc : w64mingw32 : i686-w64-mingw32-g++ ;

To register our new compiler.

(And make sure its the only w64mingw32 line of course.)

== Compile boost ==

Navigate to your boost directory, ~/old_boost/boost_1_52_0/

First, run the "bootstrap" program,

./bootstrap.sh

You don't need to give it any arguments, it doesn't really matter what it builds with. It is just building the boost jam program which will actually orchestrate the boost build.

Now, run boost jam (called "b2"). I recommend to put the actual command in shell script, for ease of use in case you have to modify it (and so you don't forget it...)

I used the following recipe:

$ cat recipe
#!/bin/bash
./b2 toolset=gcc-w64mingw32 -d+2 -a --reconfigure --debug-configuration --with-iostreams --with-locale --with-regex --with-filesystem --with-system --with-program_options target-os=windows variant=release threading=multi threadapi=win32 address-model=32 architecture=x86 instruction-set=i686
link=static runtime-link=static -j 2 -sBZIP2_BINARY=libbz2 -sBZIP2_INCLUDE=/home/chris/w-deps/include -sBZIP2_LIBPATH=/home/chris/w-deps/bin -sZLIB_BINARY=zlib -sZLIB_INCLUDE=/home/chris/w-deps/include -sZLIB_LIBPATH=/home/chris/w-deps/bin

Discussion of flags
; toolset=gcc-w64mingw32
: Tells to use the compiler I choose for 32 bit windows. Could also have tried e.g. gcc-w64mingw64, for 64-bit windows, based on my user-config.jam, or gcc-4.6 for g++-4.6 compiler (see my user-config.jam above)
; -d+2
; --debug-configuration
: These are debugging output options that make boost tell you about the configuration, and show you what compiler commands it is running.
; -a
; --reconfigure
: -a makes sure that all targets are rebuilt, and reconfigure makes sure that it reconfigures based on new options. If you are changing things around these options prevent you from getting screwed over by stale options.
; --with-iostreams
; --with-locale
; --with-regex
; --with-filesystem
; --with-system
; --with-program_options
: Select what libraries you want. It's better to use --with than --without because otherwise you get a bunch of random crap. You can't use both kinds.
; target-os=windows
; threading=multi
; threadapi=win32
: You need these to make it build dll's, and that will work for you.
; address-model=32
; architecture=x86
; instruction-set=i686
: I added these out of paranoia at some point but they might not really be necessary
; link=static
; runtime-link=static
: This is the only reasonable option here
; -j 2
: Parallelize the build over 2 cores
; -sBZIP2_BINARY=libbz2
; -sBZIP2_INCLUDE=/home/chris/w-deps/include
; -sBZIP2_LIBPATH=/home/chris/w-deps/bin
: Tell boost exactly where to find bzip2 binary and header. I earlier tried to do this just with cxxflags and linker flags, but it got confused with my system-installed bzip2 and caused me a lot of pain. This fixed it.
; -sZLIB_BINARY=zlib
; -sZLIB_INCLUDE=/home/chris/w-deps/include
; -sZLIB_LIBPATH=/home/chris/w-deps/bin
: Tell boost exactly where to find zlib binary and header.

Now run the recipe (don't forget to "chmod +x" it):

$ ./recipe

If you would like to suppress the warnings, you can use cxxflags="-w" as an additional argument.

You should get this at the end:

The Boost C++ Libraries were successfully built!

The following directory should be added to compiler include paths:

/home/chris/old_boost/boost_1_52_0

The following directory should be added to linker library paths:

/home/chris/old_boost/boost_1_52_0/stage/lib

If you did not, check that all of your paths are matching correctly, that you actually have a libbz2.a and zlib.a in your ~/w-deps/bin, (and that they *match* the associated headers... if in doubt, try downloading again, or even compile the c libraries yourself, it doesn't matter what compiler you use for c libraries). Check that the compiler name is correct. You could use cxxflags to try to get additional diagnostics. The -d+2 command causes boost to output much additional diagnostics as well.

== Compile wesnoth ==

Now, you need to craft an scons command that will properly tell it to cross compile, to use the cross compiling compiler, and point it to your fresh boost compile, and all the deps. I prefer to in this case as well store the recipe in a shell script:

$ cat build_mingw_boost_1_52.sh
#!/bin/bash
rm .scons-option-cache
scons default_targets=wesnoth build=release extra_flags_config="-DBOOST_THREAD_USE_LIB -Wno-unused-local-typedefs" prefix=~/w-deps boostdir=~/old_boost/boost_1_52_0 boostlibdir=~/old_boost/boost_1_52_0/stage/lib gettextdir=~/w-deps gtkdir=~/w-deps host=i686-w64-mingw32

Some discussion
; rm .scons-option-cache
: So that stale settings can't screw up my build and confuse me
; default_targets=wesnoth
: This could also be wesnoth, wesnothd, campaignd. I think it can't include "test" atm because we didn't compile the boost unit testing system.
; build=release
: Unless you want to make a debug build
; extra_flags_config:
: Add -Wno-unused-local-typedefs or your log will be unreadable with pointless warnings.
: Add -DBOOST_THREAD_USE_LIB because loonycyborg said so
; prefix=~/w-deps
: This is pretty handy, this will cause scons to add ~/w-deps/include to be included as a cxx flag, and also to add ~/w-deps/bin to be linked. So it saves you some typing.
; boostdir=~/old_boost/boost_1_52_0
: First directory that boost reported to you above (or for whatever boost version you want to use)
; boostlibdir=~/old_boost/boost_1_52_0/stage/lib
: Second directory that boost reported to you above (Wherever the boost libraries ended up for you.)
; gettextdir=~/w-deps
; gtkdir=~/w-deps
: These point scons to find compiled versions of these, and not your system version (which will not be binary compatible in case of C++ libs).
: Note that I don't add sdldir=~/w-deps, because it shouldn't be necessary as SDL is a c lib, so my system version is fine. But if you get a problem finding or linking SDL, then add that in also.
; host=i686-w64-mingw32
: This is where we select the compiler, actually. scons will prepend the "host" followed by -, followed by g++, if no cxxtool argument is given. (I'm not sure how "host" and "cxxtool" arguments interact.) So this selection results in the compiler, i686-w64-mingw32-g++, as desired.

If you get configuration errors, a good way to trouble shoot is to check your /build/config.log

That's all there is to it. Good luck.

=== Note ===

When I finally compiled I get these warnings on linking:

/usr/bin/ccache i686-w64-mingw32-g++ -o wesnoth.exe -static-libgcc -static-libstdc++ -mwindows -mthreads build/release/wesnoth.o build/release/libwesnoth_extras.a build/release/lua/liblua.a build/release/libwesnoth_core.a build/release/libwesnoth.a build/release/libwesnoth_sdl.a build/release/libwesnoth_extras.a build/release/lua/liblua.a packaging/windows/wesnoth.o -L/home/chris/w-deps/lib -L/home/chris/w-deps/lib -L/home/chris/old_boost/boost_1_52_0/stage/lib -lmingw32 -lSDLmain -lSDL -lSDL_net -lboost_iostreams -lz -lbz2 -lboost_system -lboost_filesystem -lboost_locale -lSDL_ttf -lSDL_mixer -lSDL_image -lws2_32 -lpangocairo-1.0 -lcairo -lpangoft2-1.0 -lpangowin32-1.0 -lgdi32 -lfreetype -lpango-1.0 -lm -lgobject-2.0 -lglib-2.0 -lintl -lfontconfig -lboost_program_options -lboost_regex -lvorbisfile -lwsock32 -lintl -lz
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_9iostreams10gzip_errorEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_9iostreams10gzip_errorEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINSt8ios_base7failureEEE[__ZTSN5boost16exception_detail19error_info_injectorINSt8ios_base7failureEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_filesystem.a(operations.o): duplicate section `.rdata$_ZTSN5boost6detail17sp_counted_impl_pINS_10filesystem6detail11dir_itr_impEEE[__ZTSN5boost6detail17sp_counted_impl_pINS_10filesystem6detail11dir_itr_impEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_15program_options16validation_errorEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_15program_options16validation_errorEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_15program_options16validation_errorEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_15program_options16validation_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt13runtime_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt13runtime_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
scons: done building targets.

We don't know what these warnings are exactly but it seems they can be ignored.

== WINE ==

To get wine to run I did the following. You must make sure you are using a 32 bit environment.

env WINEPREFIX=~/prefix32 WINEARCH=win32 wine cmd

All the online instructions say that you need to update wine's path, using regedit, to point to your dll's. I couldn't actually get this to work, so I ended up putting symlinks in my prefix 32 C:\windows\system32 directory:

~/prefix32/drive_c/windows/system32 $ ln -s ~/w-deps/bin
~/prefix32/drive_c/windows/system32 $ ln -s /usr/lib/gcc/i686-w64-mingw32/4.9-win32/

Besides the libs like SDL, pango, etc., you also need a .dll specific to mingw (I guess this is the mingw run time library). I found that I needed this dll:

/usr/lib/gcc/i686-w64-mingw32/4.9-win32/libgcc_s_sjlj-1.dll

If I got errors like this:

$ env WINEPREFIX=~/prefix32 WINEARCH=win32 wine wesnoth
err:module:import_dll Library libpangoft2-1.0-0.dll (which is needed by L"C:\\windows\\system32\\libpangocairo-1.0-0.dll") not found
err:module:import_dll Library libpangocairo-1.0-0.dll (which is needed by L"Z:\\home\\chris\\wesnoth-src\\clone\\wesnoth\\wesnoth.exe") not found
err:module:LdrInitializeThunk Main exe initialization for L"Z:\\home\\chris\\wesnoth-src\\clone\\wesnoth\\wesnoth.exe" failed, status c0000135

I fixed it by adding a symlink to ~/w-deps/bin/libpangoft2-1.0-0.dll in the folder prefix32/drive_c/windows/system32.

And so on and so forth... Eventually it worked.

=== Tip ===

As I learned later, a better way to handle this is to just copy all of the .dll files you need into the root of your repo, next to wesnoth.exe. This will make wine find them first, for wesnoth only, and our .gitignore file includes *.dll so they won't get into the repo.

=== Troubleshooting ===

A helpful thing I found is, if you have problems running wesnoth with the DLL's, you can sanity check by running the little executables generated by scons for the configuration tests. E.g.

$ env WINEPREFIX=~/prefix32 WINEARCH=win32 wine build/sconf_temp/conftest_20.exe

If the test works it should give no output, otherwise if it's not linking right it should give you an error.

ImagePathFunctions

2015-04-17T10:23:22Z

Iceiceice: /* ADJUST_ALPHA */

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester'' from the 1.10 add-on server.

== Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

=== Syntax ===
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

== Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.
=== Syntax ===
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== Flip Function ==
May be used to flip an image horizontally and/or vertically.
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

== Rotate Function ==
May be used to rotate an image by a multiple of 90 degrees.
=== Syntax ===
'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Sepia Function ==
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).
=== Syntax ===
'''~SEPIA()'''

== Negative Function ==
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.
=== Syntax ===
'''~NEG( )'''

== Crop Function ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

== Blit Function ==
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)
=== Syntax ===
'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== Mask Function ==
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.
=== Syntax ===
'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

== Color-blend function ==
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.
=== Syntax ===
'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

== Lightmap color-shift function ==
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

=== Syntax ===
'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully gray image (RGB = 128,128,128) and any non-gray pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

== Image-scaling function ==
Scales a graphic up or down.
=== Syntax ===

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr.

== Opacity modifying function ==
Changes an image's opacity at render time.
=== Syntax ===

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== Blurring function ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.
=== Syntax ===

'''~BL( ''radius'' )'''

== Overlay function ==
Puts a time-of-day overlay on the image.
=== Syntax ===

'''~LIGHTEN()'''

'''~DARKEN()'''

== Background coloring function ==
Sets the color of all the (semi-)transparent pixels of the image.
=== Syntax ===

'''~BG(r,g,b)'''

== Null function ==
Does nothing.
=== Syntax ===

'''~NOP()'''

== XBRZ function ==
Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== SCALE_SHARP function ==
Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

== PLOT_ALPHA ==
At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

== WIPE_ALPHA ==
At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

== ADJUST_ALPHA ==

Scales the alpha value at each pixel down by a fixed factor. The argument is either a %, or an integer from 0 to 255, in which case it is divided by 255 and reinterpretted as a %.

'''~ADJUST_ALPHA(n)'''.

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

[[Category:WML Reference]]

ImagePathFunctions

2015-04-17T05:03:01Z

Iceiceice:

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester'' from the 1.10 add-on server.

== Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

=== Syntax ===
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

== Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.
=== Syntax ===
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== Flip Function ==
May be used to flip an image horizontally and/or vertically.
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

== Rotate Function ==
{{devfeature1.11}}
May be used to rotate an image by a multiple of 90 degrees.
=== Syntax ===
'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Sepia Function ==
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).
=== Syntax ===
'''~SEPIA()'''

== Negative Function ==
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.
=== Syntax ===
'''~NEG( )'''

== Crop Function ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

== Blit Function ==
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)
=== Syntax ===
'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== Mask Function ==
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.
=== Syntax ===
'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

== Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

== Color-blend function ==
{{DevFeature1.11}}
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.
=== Syntax ===
'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

== Lightmap color-shift function ==
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

=== Syntax ===
'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully gray image (RGB = 128,128,128) and any non-gray pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

== Image-scaling function ==
Scales a graphic up or down.
=== Syntax ===

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr.

== Opacity modifying function ==
Changes an image's opacity at render time.
=== Syntax ===

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== Blurring function ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.
=== Syntax ===

'''~BL( ''radius'' )'''

== Overlay function ==
Puts a time-of-day overlay on the image.
=== Syntax ===

'''~LIGHTEN()'''

'''~DARKEN()'''

== Background coloring function ==
Sets the color of all the (semi-)transparent pixels of the image.
=== Syntax ===

'''~BG(r,g,b)'''

== Null function ==
Does nothing.
=== Syntax ===

'''~NOP()'''

== XBRZ function ==
Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

== SCALE_SHARP function ==
Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

== PLOT_ALPHA ==
At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

== WIPE_ALPHA ==
At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

== ADJUST_ALPHA ==

Scales the alpha value at each pixel down by a fixed factor. The argument is a number from 0 to 255 -- the factor is ''n/255''.

'''~ADJUST_ALPHA(n)'''.

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

[[Category:WML Reference]]

LuaWML

2015-04-17T04:41:44Z

Iceiceice: /* Events and WML actions */

{{WML Tags}}

== The '''[lua]''' tag ==

This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.2] language.

It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immideately when the lua engine loads which is even before the scenario preload event is fired.

The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.

[lua]
code = << wesnoth.message "Hello World!" >>
[/lua]

The Lua kernel can also be accessed from the [[CommandMode|command mode]]:

:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5

The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".

[lua]
code = << local t = ...; wesnoth.message(tostring(t.text)) >>
[args]
text = _ "Hello world!"
[/args]
[/lua]

== Global environment ==

All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.

[event]
name = preload
first_time_only = no
[lua]
code = <<
function narrator(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
>>
[/lua]
[/event]

[event]
name = turn 1
[lua]
code = << narrator(...) >>
[args]
sentence = _ "Hello world!"
[/args]
[/lua]
[lua]
code = << narrator(...) >>
[args]
sentence = _ "How are you today?"
[/args]
[/lua]
[/event]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

[event]
name = preload
first_time_only = no
[lua]
code = <<
-- The function is now local, since its name does not have to be
-- visible outside this Lua scripts.
local function handler(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
-- Create a new tag named [narrator].
wesnoth.register_wml_action("narrator", handler)
>>
[/lua]
[/event]

[event]
name = turn 1
[narrator]
sentence = _ "Hello world!"
[/narrator]
[narrator]
sentence = _ "How are you today?"
[/narrator]
[/event]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. {{DevFeature1.13|0}} The [http://www.lua.org/manual/5.2/manual.html#6.7 bit32] library is supported as well. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Additionally, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.

At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.

== Examples ==

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.

# General catch for them moving to the wrong place.
[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[if]
[variable]
name=target_hex.is_set
equals=yes
[/variable]
[then]
[if]
[variable]
name=x1
equals=$target_hex.x
[/variable]
[variable]
name=y1
equals=$target_hex.y
[/variable]
[then]
[/then]
[else]
[redraw][/redraw]
[message]
speaker=narrator
message=_ "*Oops!
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
_ "
*Left click or press spacebar to continue..."
[/message]
[/else]
[/if]
[/then]
[/if]
[/event]

A Lua script that performs the same action is presented below.

[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[lua]
code = <<
local event_data = wesnoth.current.event_context
if V.target_hex.is_set and
(event_data.x1 ~= V.target_hex.x or event_data.y1 ~= V.target_hex.y)
then
W.redraw()
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
end
>>
[/lua]
[/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.

The next two lines then test

if V.target_hex.is_set and
(event_data.x1 ~= V.target_hex.x or event_data.y1 ~= V.target_hex.y)

whether the variable ''V.target_hex'' matches the event parameters. Since ''V'' is not a local variable, it is taken from the global environment. Usually, variables from the global environment are not persistent (they get lost on reloading), so it shouldn't be used to store data. In order to have an easy way to access the usual persistent Wml variables, the global variable ''V'' was mapped to the storage of WML variables by the following ''preload'' event.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
-- skipping some other initializations
-- ...
V = H.set_wml_var_metatable {}
>>
[/lua]
[/event]

Without a prelude redirecting ''V'', the conditional would have been written

if wesnoth.get_variable("target_hex.is_set") and
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")

The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.

W.redraw()

Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.

W = H.set_wml_action_metatable {}

Without this shortcut, the first statement would have been written

wesnoth.fire("redraw")

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
W.message { speaker="narrator",
message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"

A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].

== Interface to the engine and helper functions ==

Functionalities of the game engine are available through the functions contained in the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.

Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].

helper = wesnoth.require "lua/helper.lua"

=== WML variables ===

* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
* [[LuaWML:Variables#wesnoth.get_all_vars|wesnoth.get_all_vars]] {{DevFeature1.13|0}}
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]

=== Events and WML actions ===

* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
* [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_conditionals]]
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
* [[LuaWML:Events#helper.literal|helper.literal]]
* [[LuaWML:Events#helper.parsed|helper.parsed]]
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]]
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]
* [[LuaWML:Display#wesnoth.set_dialog_markup|wesnoth.set_dialog_markup]] {{DevFeature1.11|9}}
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]
* [[LuaWML:Display#wesnoth.add_dialog_tree_node|wesnoth.add_dialog_tree_node]] {{DevFeature1.13|0}}
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
* [[LuaWML:Display#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]

=== Map and terrains ===

* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]
* [[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]] {{DevFeature1.11}}
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]
* [[LuaWML:Tiles#items.place_image|items.place_image]]
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]
* [[LuaWML:Tiles#items.remove|items.remove]]

=== Units ===

* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]
* [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]
* [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]

=== Pathfinder ===

* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
* [[LuaWML:Pathfinder#wesnoth.find_cost_map|wesnoth.find_cost_map]]
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]

=== Lua files ===

* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]

=== Location sets ===

* [[LuaWML:Location_set#location_set.create|location_set.create]]
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]
* [[LuaWML:Location_set#location_set:size|location_set:size]]
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]
* [[LuaWML:Location_set#location_set:get|location_set:get]]
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]
* [[LuaWML:Location_set#location_set:union|location_set:union]]
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.get_era|wesnoth.get_era]] {{DevFeature1.11}}
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]
* [[LuaWML:Misc#wesnoth.have_file|wesnoth.have_file]] {{DevFeature1.11}}
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]
* [[LuaWML:Misc#wesnoth.get_time_stamp|wesnoth.get_time_stamp]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
* [[LuaWML:Misc#helper.rand|helper.rand]]
* [[LuaWML:Misc#helper.round|helper.round]] {{DevFeature1.11}}
* [[LuaWML:Misc#helper.shuffle|helper.shuffle]] {{DevFeature1.11}}

== Encoding WML objects into Lua tables ==

Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
a_bool = true,
an_int = 42,
a_float = 1.25,
a_string = "scout",
a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
a_bool = "yes"
an_int = "42"
a_float = "1.25"
a_string = "scout"
a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {[1] = "tag_name", [2] = {}} which is equivalent to {"tag_name", {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { z = 5, { "barfoo", {} } } }
}

is equivalent to the content of the following WML object

[dummy]
foo = 42
[bar]
v = 1
w = 2
[/bar]
[foo]
x = no
[/foo]
[bar]
y = foo
[bar]
[foobar]
z = 5
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
{
foo = 42,
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
[2] = { [1] = "foo", [2] = { x = false } },
[3] = { [1] = "bar", [2] = { y = "foo" } },
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
}

So assuming ''cfg'' contains the above WML object, the following accesses are possible:

a_int = cfg.foo -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.

Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.

For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler
old_event_handler = register_wml_action("event",
function(cfg)
-- Get the plain text from the user.
local new_cfg = cfg.__literal
-- The expression below is equivalent to cfg.__parsed.first_time_only,
-- only faster. It is needed, since the first_time_only attribute may
-- reference variables.
local first = cfg.first_time_only
-- Modify the default behavior of first_time_only.
if first == nil then first = false end
new_cfg.first_time_only = first
-- Call the engine handler.
old_event_handler(new_cfg)
end
)

Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:

function get_child(cfg, name)
for i = 1, #cfg do
local v = cfg[i]
if v[1] == name then return v[2] end
end
end

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:

if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end

The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal'''. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

== Skeleton of a preload event ==

The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It sets up a table ''T'' so be used for easier creation of valid WML tables. It also sets up a table ''V'' so that any access to it is redirected to the persistent WML storage.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
T = H.set_wml_tag_metatable {}
V = H.set_wml_var_metatable {}
_ = wesnoth.textdomain "my-campaign"

-- Define your global constants here.
-- ...

-- Define your global functions here.
-- ...
>>
[/lua]
[/event]

It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:

[event]
name=preload
first_time_only=no
[lua]
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
[/lua]
[/event]

== Remarks ==

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.

function random(min, max)
if not max then min, max = 1, min end
wesnoth.fire("set_variable", { name = "LUA_random", rand = string.format("%d..%d", min, max) })
local res = wesnoth.get_variable "LUA_random"
wesnoth.set_variable "LUA_random"
return res
end

[[Category: Lua Reference|*]]
[[Category: WML Reference]]

LuaWML/Events

2015-04-10T16:52:45Z

Iceiceice: /* wesnoth.wml_conditionals */

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====
{{DevFeature1.11}}: This function is deprecated; directly write into [[#wesnoth.wml_actions]] instead.

Registers the second argument as a handler for the given action tag. When the game encounters this tag when executing [[ActionWML]] (for example in an event), it fires the action handler and passes the content of the WML object as the first argument. Thus, this function creates new types of [[ActionWML]].

If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator",
"label", "lua", "menu_item", "music", "side", "sound_source", "story",
"terrain_graphics", "time", "time_area", "tunnel", "variables"

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

[[Category: Lua Reference]]

LuaWML/Events

2015-04-10T16:50:52Z

Iceiceice: /* wesnoth.wml_conditionals */

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====
{{DevFeature1.11}}: This function is deprecated; directly write into [[#wesnoth.wml_actions]] instead.

Registers the second argument as a handler for the given action tag. When the game encounters this tag when executing [[ActionWML]] (for example in an event), it fires the action handler and passes the content of the WML object as the first argument. Thus, this function creates new types of [[ActionWML]].

If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

function wesnoth.wml_conditionals.foo(cfg)
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end

If this lua code is placed in a preload event, it would make the following syntax be valid WML in your add-on:

[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator",
"label", "lua", "menu_item", "music", "side", "sound_source", "story",
"terrain_graphics", "time", "time_area", "tunnel", "variables"

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

[[Category: Lua Reference]]

LuaWML/Events

2015-04-10T16:50:26Z

Iceiceice:

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====
{{DevFeature1.11}}: This function is deprecated; directly write into [[#wesnoth.wml_actions]] instead.

Registers the second argument as a handler for the given action tag. When the game encounters this tag when executing [[ActionWML]] (for example in an event), it fires the action handler and passes the content of the WML object as the first argument. Thus, this function creates new types of [[ActionWML]].

If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

function wesnoth.wml_conditionals.foo(cfg
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end

If this lua code is placed in a preload event, it would make the following syntax be valid WML in your add-on:

[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator",
"label", "lua", "menu_item", "music", "side", "sound_source", "story",
"terrain_graphics", "time", "time_area", "tunnel", "variables"

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

[[Category: Lua Reference]]

LuaWML/Events

2015-04-10T16:50:03Z

Iceiceice:

This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

==== wesnoth.fire ====

Fires a [[ActionWML|WML action]]. Argument 1 is the name of the action. Argument 2 is the WML table describing the action. Note: WML variables are substituted.

wesnoth.fire("message", { speaker="narrator", message=_ "Hello World!" })

==== wesnoth.register_wml_action ====
{{DevFeature1.11}}: This function is deprecated; directly write into [[#wesnoth.wml_actions]] instead.

Registers the second argument as a handler for the given action tag. When the game encounters this tag when executing [[ActionWML]] (for example in an event), it fires the action handler and passes the content of the WML object as the first argument. Thus, this function creates new types of [[ActionWML]].

If the registered function raises an error with a message starting with ''~wml:'', it will not be displayed as a Lua error with a backtrace but as a standard WML error. (See also [[#helper.wml_error]].) The following script defines a [freeze_unit] tag that sets to 0 the move points of the unit with the given id.

wesnoth.register_wml_action("freeze_unit",
function(cfg)
local unit_id = cfg.id or error("~wml:[freeze_unit] expects an id= attribute.", 0)
helper.modify_unit({ id = unit_id }, { moves = 0 })
end
)

# The new tag can now be used in plain WML code.
[freeze_unit]
id=Delfador
[/freeze_unit]

The function returns the previous action handler. Its metatable appears as '''"wml action handler"'''. This handler can be called to delegate part of the action, if needed. For instance, the following script modifies the [[InterfaceActionsWML#Other interface tags|[print]]] tag so that messages are displayed with a bigger font.

local old_print_handler
old_print_handler = wesnoth.register_wml_action("print",
function(cfg)
-- Do not perform variable substitution.
local new_cfg = cfg.__literal
-- Modify the size field and call the previous handler.
new_cfg.size = (cfg.size or 12) + 10
old_print_handler(cfg)
end
)

Note that the data coming from the WML tag are stored in a read-only object and variable substitution happens on the fly when accessing attributes and children. The metatable of this proxy object appears as '''"wml object"'''. See [[LuaWML#Encoding WML objects into Lua tables]] for more details.

If the name of a tag starts as ''filter'', it is ignored when the actions of an event are executed. These names are indeed reserved for event filtering, e.g. [filter], [filter_weapon], and so on. It is therefore useless to define action tags with such names.

==== wesnoth.wml_actions ====

This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].

function wesnoth.wml_actions.freeze_unit(cfg)
local unit_id = cfg.id or helper.wml_error "[freeze_unit] expects an id= attribute."
helper.modify_unit({ id = unit_id }, { moves = 0 })
end

Note: When calling an action handler directly through its function stored in ''wesnoth.wml_actions'', the engine is not involved. As a consequence, whether variable substitution will happen is up to the handler. In particular, if the argument is a plain table, the caller should have substituted WML variables beforehand to be on the safe side. Moreover, table arguments might be modified by the action handler, so they should usually not be reused for consecutive calls. If variable substitution should happen and/or table content should be preserved, one can call [[#wesnoth.tovconfig]] and pass its result to the handler. Calling [[#wesnoth.fire]] is another possibility.

==== wesnoth.wml_conditionals ====

{{DevFeature1.13|0}}

This is an associative table like wesnoth.wml_actions. You can use it to define new conditional wml tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when '''wesnoth.eval_conditional''' is run.

Use it like

function wesnoth.wml_conditionals.foo(cfg
local bar = cfg.bar or error("[foo] tag did not have 'bar' attribute")

return (bar == "baz")
end

If this lua code is placed in a preload event, it would make the following syntax be valid WML in your add-on:

[if]
[foo]
bar = $X
[/foo]
[then]
[message]
...
[/message]
[/then]
[/if]

You cannot override the meaning of any core conditional tags.

==== wesnoth.game_events ====

This is not a function but an associative table indexed by engine action names. It contains function hooks the engine calls whenever it performs a particular action.

* '''on_save''': function called when the engine (auto)saves a scenario file; it should return a WML table and the children of this table are added to the savefile.
* '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
* '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].

The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

-- some value that survives save/load cycles, but that is not forwarded to the next level
local level_local_data = 0

local old_on_load = wesnoth.game_event.on_load
function wesnoth.game_event.on_load(cfg)
for i = 1,#cfg do
if cfg[i][1] == "my_data" then
-- recover the value stored in the savefile
level_local_data = cfg[i][2].value
-- erase the child, since it has been handled
table.remove(cfg, i)
break
end
end
-- call the previous hook, in case there are still some containers in the savefile
old_on_load(cfg)
end

local old_on_save = wesnoth.game_events.on_save
function wesnoth.game_events.on_save()
-- call the previous hook, in case it had some containers to store
local cfg = old_on_save()
-- add our own container to them
table.insert(cfg, { "my_data", { value = level_local_data } })
-- tell the engine to store them in the savefile
return cfg
end

Note: since the ''on_load'' hook is called very early in the scenario, it cannot be set inside a [lua] tag in an [event], not even a ''preload'' one. It has to be set inside a [lua] tag outside or at [scenario] level.

Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
"color_palette", "color_range", "era", "event", "generator",
"label", "lua", "menu_item", "music", "side", "sound_source", "story",
"terrain_graphics", "time", "time_area", "tunnel", "variables"

==== wesnoth.fire_event ====

Fires all the WML events with the given name. Optional parameters allow passing two locations and two tables. These parameters will be matched against the [filter], [filter_second], [filter_attack], and [filter_second_attack] of any event handler, and are used to fill the WML variables "unit", "second_unit", "weapon", and "second_weapon". These parameters can also be read through ''current.event_context''. The function returns a boolean indicating whether the game state was modified.

wesnoth.fire_event("explosion", 17, 42, { damage = "fire" })

==== wesnoth.eval_conditional ====

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wesnoth.eval_conditional {
{ "have_unit", { id = "hero" } },
{ "variable", { name = "counter", numerical_equals = "$old_counter" } }
}

==== wesnoth.tovconfig ====

Converts a WML table into a proxy object which performs variable substitution on the fly.

wesnoth.set_variable("varname", "to_be_deleted")
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" } -- correct
wesnoth.wml_actions.clear_variable { name = "$varname" } -- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable(wesnoth.tovconfig { name = "$varname" }) -- correct: "$varname" is replaced by "to_be_deleted" at the right time

==== helper.set_wml_action_metatable ====

Sets the metable of a table so that it can be used to fire WML actions. Returns the table. The fields of the table are then simple wrappers around a call to [[#wesnoth.fire]].

local W = helper.set_wml_action_metatable {}
W.message { speaker = "narrator", message = "?" }

==== helper.wml_error ====

Interrupts the current execution and displays a chat message that looks like a WML error.

local names = cfg.name or helper.wml_error("[clear_variable] missing required name= attribute.")

==== helper.literal ====

Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
cfg = helper.literal(cfg)
wesnoth.message(tostring(cfg.value))
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

==== helper.parsed ====

Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_literal ====

Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

==== helper.shallow_parsed ====

Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#helper.literal]].

[[Category: Lua Reference]]

ScenarioWML

2015-04-09T05:04:53Z

Iceiceice: /* The [scenario] tag */

{{WML Tags}}
== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==

The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios (without ''allow_new_game=no'') are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).

* The '''[test]''' scenario with the attribute '''id=test''' is an initial scenario. This test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test)

* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.

* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

The following keys and tags are recognized in '''[scenario]''' tags:

* '''id''': A unique identifier for this scenario. All scenarios must have an id. Can't clash with '''id''' used in '''[multiplayer]''' tags.

* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.

* '''description''': (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.

* '''name''': (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.

* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit (default). See also [[EventWML]]

* '''turn_at''': the turn to start on (default=1)

: Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn [[EventWML|WML events]] will still be fired, however.

* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default=no)

* '''music''': the music file relative to ''./music/'' to play during the scenario

* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].

* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''theme''': the name of the UI theme that should be used when playing this scenario.

* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) See Also [[SideWML]]. When this value is true the following keys can be used:
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''remove_from_carryover_on_leaders_loss''': {{DevFeature1.11}} when this is set to '''yes''' (default), for sides who lost all their leaders, carryover will be removed. {{DevFeature1.11|15}} this was renamed to '''remove_from_carryover_on_defeat'''

* '''remove_from_carryover_on_defeat''': {{DevFeature1.11|15}} when this is set to '''yes''' (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.

* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.

* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.

* '''[story]''': describes the intro screen. See [[IntroWML]]

* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label

* '''[item]''': places an item on map. See [[InterfaceActionsWML#.5Bitem.5D|InterfaceActionsWML]].

* '''[time]''': how a day should progress. See [[TimeWML]]
* '''current_tod''': The time of day slot number (starting from zero) active at scenario start.

* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag
** takes x and y coordinates.
** '''[time]''': how a day should progress in those locations. See [[TimeWML]]
** '''current_time''': The time slot number (starting with zero) active at the creation of the area.{{DevFeature1.11}}
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].

* '''[side]''': describes one player. See [[SideWML]]

* '''[event]''': describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]

* '''map_generation''': another way to generate a map. The map will be generated randomly
** '''default''': the default random map generator

* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]

The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:
* '''force_lock_settings''': {{DevFeature1.11}} provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=yes'' in [[SideWML]].
* '''new_game_title''': {{DevFeature1.11}} if provided will be used instead of '''name''' for campaign entry points.
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.
* '''allow_era''': {{DevFeature1.11}} a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.
* '''disallow_era''': {{DevFeature1.11}} a list of era ids. Only the eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.
* '''ignore_incompatible_era''': {{DevFeature1.11}} a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.
* '''allow_modification''': {{DevFeature1.11}} same as allow_era, but for modifications.
* '''disallow_modification''': {{DevFeature1.11}} same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': {{DevFeature1.11}} same as ignore_incompatible_era, but for modifications.
* '''force_modification''': {{DevFeature1.11}} a list of modification ids. The specified modifications must be enabled to play this scenario.
* '''[options]''': {{DevFeature1.11}} custom options. See [[OptionWML]] for details.
* '''require_scenario''': {{DevFeature1.13|0}} In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the '''addon_min_version''' attribute will control the minimum version number of your add-on which is compatible with this version.

== Scenario End Conditions ==

In this section we will give a more precise explanation of things that can cause a scenario to end. This information applies to {{DevFeature1.11|15}}.

* At the '''end of every turn''', the turn number will be compared with the turn limit.
** If we pass the limit, the ''time over'' event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. [[EventWML#The_.27name.27_Key_.28Mandatory.29]]
* At the '''beginning of any turn''', and at '''the end of any user or ai action''', the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:
** Every side will have its ''defeat_condition'' evaluated based on the units it currently has on the board. [[SideWML]]
*** At this time, villages of defeated sides will be unflagged, and if ''remove_from_carryover_on_defeat = yes'' then their carryover will be cleared as well.
** If any two not-defeated sides are enemies, the scenario will continue.
*** At this time, the ''enemies defeated'' event will fire.
** Furthermore, if ''victory_when_enemies_defated=no'' and there exists a human controlled side, then the scenario will continue.
*** The human controlled side may be local or remote, for networked mp play.
** If neither of these conditions is met then the scenario will end.
***In victory of defeat according to whether a local human-controlled side is not defeated.

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SideWML

2015-04-09T04:45:42Z

Iceiceice: /* the [side] tag */

{{WML Tags}}
== the [side] tag ==

The [side] tag is used to describe a side in a particular scenario.

The following keys are recognized:

* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides.

* '''controller''': how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves. This is the default setting.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.) Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.
** '''a number''': {{DevFeature1.11}} gives this side's control to a side with '''side''' matching the number (multiplayer only).

* '''no_leader''': if "no" (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using '''canrecruit=yes''') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are '''type''' (mandatory), '''id''', '''name''' and '''unrenamable=yes''', see [[SingleUnitWML]].

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.

* '''gold''': the starting gold for this side. Default 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side, default 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end. {{DevFeature1.11}}It is used in saved games.)

* '''[fog_override]''' {{DevFeature1.11}} With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[BuildingScenariosShroudData]].

* '''persistent''': whether the side exists in any other scenarios. If ''yes'', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to ''yes'' for sides with a human controller, and ''no'' for ai controlled sides.

* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username.

* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg.

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-1.png:250,misc/myflag-2.png:250,misc/myflag-3.png:250''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).

* '''village_support''': {{DevFeature1.11}} the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).

* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]).

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud.

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog).

* '''scroll_to_leader''': optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

* '''suppress_end_turn_confirmation''': {{DevFeature1.11}} If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* '''[village]''' describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

* <s>'''fight_on_without_leader'''</s>: {{DevFeature1.11|13}} this side will not be considered "defeated" until they have no units, for the purposes of determining whether the scenario ends or not. {{DevFeature1.11|15}} This attribute was replaced with defeat_condition

* '''defeat_condition''' {{DevFeature1.11|15}} Specifies when a side is considered ''defeated'' this is checked ''for all sides'', after every player action and at the beginning of every turn.
** '''no_leader_left''': (default) The side is considered defeated if it has no units with canrecruit=yes
** '''no_units_left''': The side is defeated as soon as it has no units left.
** '''never''': The side is never considered defeated.
** '''always''': The side is always considered defeated.

: For the meaning and significance of ''defeated'', see [[ScenarioWML#Scenario_End_Conditions]]

The following keys are multiplayer only:

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''disallow_shuffle''': {{DevFeature1.13|0}} do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (default: no)

* '''chose_random''': {{DevFeature1.13|0}} indicates if a side chose a random faction during creation

* '''controller_lock''': {{DevFeature1.11}} if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''color_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction_lock''': {{DevFeature1.11|16}} if true then this side's faction is not allowed to be modified.

* '''leader_lock''': {{DevFeature1.11|16}} if true then this side's leader (type or gender) is not allowed to be modified.

* '''faction''': if valid faction id is provided then this side's faction will default to it.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

{{DevFeature1.11}} N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SideWML

2015-04-09T04:44:45Z

Iceiceice: /* the [side] tag */

{{WML Tags}}
== the [side] tag ==

The [side] tag is used to describe a side in a particular scenario.

The following keys are recognized:

* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides.

* '''controller''': how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves. This is the default setting.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.) Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.
** '''a number''': {{DevFeature1.11}} gives this side's control to a side with '''side''' matching the number (multiplayer only).

* '''no_leader''': if "no" (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using '''canrecruit=yes''') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are '''type''' (mandatory), '''id''', '''name''' and '''unrenamable=yes''', see [[SingleUnitWML]].

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.

* '''gold''': the starting gold for this side. Default 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side, default 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end. {{DevFeature1.11}}It is used in saved games.)

* '''[fog_override]''' {{DevFeature1.11}} With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[BuildingScenariosShroudData]].

* '''persistent''': whether the side exists in any other scenarios. If ''yes'', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to ''yes'' for sides with a human controller, and ''no'' for ai controlled sides.

* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username.

* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg.

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-1.png:250,misc/myflag-2.png:250,misc/myflag-3.png:250''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).

* '''village_support''': {{DevFeature1.11}} the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).

* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]).

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud.

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog).

* '''scroll_to_leader''': optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

* '''suppress_end_turn_confirmation''': {{DevFeature1.11}} If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* '''[village]''' describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

* <s>'''fight_on_without_leader'''</s>: {{DevFeature1.11|13}} this side will not be considered "defeated" until they have no units, for the purposes of determining whether the scenario ends or not. {{DevFeature1.11|15}} This attribute was replaced with defeat_condition

* '''defeat_condition''' {{DevFeature1.11|15}} Specifies when a side is considered ''defeated'' this is checked ''for all sides'', after every player action and at the beginning of every turn.
** '''no_leader_left''': (default) The side is considered defeated if it has no units with canrecruit=yes
** '''no_units_left''': The side is defeated as soon as it has no units left.
** '''never''': The side is never considered defeated.
** '''always''': The side is always considered defeated.

: For the meaning and significance of ''defeated'', see [[ScenarioWML#Scenario_End_Conditions]]

The following keys are multiplayer only:

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''disallow_shuffle''': {{DevFeature1.13|0}} do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (deault: no)

* '''chose_random''': {{DevFeature1.13|0}} indicates if a side chose a random faction during creation

* '''controller_lock''': {{DevFeature1.11}} if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''color_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction_lock''': {{DevFeature1.11|16}} if true then this side's faction is not allowed to be modified.

* '''leader_lock''': {{DevFeature1.11|16}} if true then this side's leader (type or gender) is not allowed to be modified.

* '''faction''': if valid faction id is provided then this side's faction will default to it.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

{{DevFeature1.11}} N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EraWML

2015-03-15T18:08:29Z

Iceiceice: /* The [era] top level tag */

{{WML Tags}}
== The [era] top level tag ==

This tag describes one era. An era is a set of teams to play in multiplayer.

In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.

The following key/tags are recognized for '''[era]'''
* '''id''': ID of the era - must be unique. No gameplay effect
* '''name''': displayed name of the era.
* '''description''': {{DevFeature1.11}} a short description of the era.
* '''require_era''': whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
* '''allow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
* '''disallow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
* '''ignore_incompatible_scenario''': {{DevFeature1.11}} a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
* '''allow_modification''': {{DevFeature1.11}} same as allow_scenario, but for modifications.
* '''disallow_modification''': {{DevFeature1.11}} same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': {{DevFeature1.11}} same as ignore_incompatible_scenario, but for modifications.
* '''force_modification''': {{DevFeature1.11}} a list of modification ids. The specified modifications must be enabled to play this era.
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[multiplayer_side]''': a faction in the era. This tag contains many of the same keys as a [side] tag (A description of the [side] tag can be found in [[SideWML]]). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys(currently, not tags) of the [multiplayer_side] tag of the faction which the side chose.
** '''id''': faction ID - must be unique to your era. No gameplay effect
** '''name''': a description that Wesnoth displays as the option selecting that faction; see [[DescriptionWML]]. Any image in this description will ''not'' use the team color.
** '''image''': an image to display in the option. This image will use the team color.
** '''flag_rgb''': often set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]
** '''leader''': a list of unit types. Must be present. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
** '''random_leader''': if this list of types is present, it would use this list to instead to choose a random leader. If not it would use '''leader'''
** '''random_faction''': default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly.
** '''choices''': Empty by default. If non-empty and the faction has '''random_faction=yes''', it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
** '''except''': Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
** '''type''': the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default.
** '''recruit''': a comma-separated list of unit types this faction can recruit.
** '''extra_recruit''': a comma-separated list of unit types appended to the leader recruitlist (see [[SingleUnitWML]]).
** '''terrain_liked''': an unseparated list of terrains (see [[TerrainCodesWML]]). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
* '''[event]''': any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See [[EventWML]].
* '''[options]''': {{DevFeature1.11}} custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

== See Also ==

* [[ReferenceWML]]
* [[SideWML]]

[[Category: WML Reference]]

ModificationWML

2015-03-15T18:08:00Z

Iceiceice: /* The [modification] toplevel tag */

{{WML Tags}}
== The [modification] toplevel tag ==

{{DevFeature1.11}} This tag describes a multiplayer modification. A modification is practically a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''':

* '''id''': identifier for the modification. Must be unique.
* '''name''': the name of the modification, as displayed to the user.
* '''description''': a brief description for the modification.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this modification. Cannot be used in parallel with allow_scenario.
* '''allow_era''': same as allow_scenario, but for eras.
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.
* '''addon_min_version''': {{DevFeature1.13|0}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

ModificationWML

2015-03-15T18:07:41Z

Iceiceice: /* The [modification] toplevel tag */

{{WML Tags}}
== The [modification] toplevel tag ==

{{DevFeature1.11}} This tag describes a multiplayer modification. A modification is practically a bunch of events which get included into the scenario if the modification is enabled.

The following keys/tags are recognized for '''[modification]''':

* '''id''': identifier for the modification. Must be unique.
* '''name''': the name of the modification, as displayed to the user.
* '''description''': a brief description for the modification.
* '''allow_scenario''': a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this modification.
* '''disallow_scenario''': a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this modification. Cannot be used in parallel with allow_scenario.
* '''allow_era''': same as allow_scenario, but for eras.
* '''disallow_era''': same as disallow_scenario, but for eras. Can't be used with allow_era.
* '''allow_modification''': same as allow_scenario, but for modifications.
* '''disallow_modification''': same as disallow_scenario, but for modifications. Can't be used with allow_modification.
* '''ignore_incompatible_scenario''': a list of scenario ids. The scenarios with matching ids will be considered compatible with this modification regardless their dependencies.
* '''ignore_incompatible_era''': same as ignore_incompatible_scenario, but for eras.
* '''ignore_incompatible_modification''': same as ignore_incompatible_scenario, but for modifications.
* '''require_modification''': a boolean value; if set to yes, all players have to have this modification installed to join the game. Default no.
* '''addon_min_version''': {{DevFeature1.13}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PblWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[event]''': any [event] children written inside the [modification] tag will get included into scenarios that are played with this modification enabled. See [[EventWML]].
* '''[options]''': custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

EraWML

2015-03-15T18:05:19Z

Iceiceice: /* The [era] top level tag */

{{WML Tags}}
== The [era] top level tag ==

This tag describes one era. An era is a set of teams to play in multiplayer.

In the multiplayer game creation screen, an era is chosen by the host by the 'Era' option button.

The following key/tags are recognized for '''[era]'''
* '''id''': ID of the era - must be unique. No gameplay effect
* '''name''': displayed name of the era.
* '''description''': {{DevFeature1.11}} a short description of the era.
* '''require_era''': whether clients are required to have this era installed beforehand to be allowed join a game using this era. Possible values 'yes' (the default) and 'no'.
* '''allow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will be allowed to be played with this era.
* '''disallow_scenario''': {{DevFeature1.11}} a list of scenario ids. Only the scenarios with matching ids will not be allowed to be played with this era. Cannot be used in parallel with allow_scenario.
* '''ignore_incompatible_scenario''': {{DevFeature1.11}} a list of scenario ids. The scenarios with matching ids will be considered compatible with this era regardless their dependencies.
* '''allow_modification''': {{DevFeature1.11}} same as allow_scenario, but for modifications.
* '''disallow_modification''': {{DevFeature1.11}} same as disallow_scenario, but for modifications. Cannot be used in parallel with allow_modification.
* '''ignore_incompatible_modification''': {{DevFeature1.11}} same as ignore_incompatible_scenario, but for modifications.
* '''force_modification''': {{DevFeature1.11}} a list of modification ids. The specified modifications must be enabled to play this era.
* '''addon_min_version''': {{DevFeature1.13}} the minimum version of your add-on with which this content is backwards compatible. Compare with the version string given in [[PBLWML]]. Clients in multiplayer must have add-on versions agreeing with the ''addon_min_versions'' of eachothers content in order to play, and will be prompted to update otherwise.
* '''[multiplayer_side]''': a faction in the era. This tag contains many of the same keys as a [side] tag (A description of the [side] tag can be found in [[SideWML]]). When a multiplayer game is played, then the [side] tag for the scenario is merged with the keys(currently, not tags) of the [multiplayer_side] tag of the faction which the side chose.
** '''id''': faction ID - must be unique to your era. No gameplay effect
** '''name''': a description that Wesnoth displays as the option selecting that faction; see [[DescriptionWML]]. Any image in this description will ''not'' use the team color.
** '''image''': an image to display in the option. This image will use the team color.
** '''flag_rgb''': often set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]
** '''leader''': a list of unit types. Must be present. When this faction is chosen, the side can choose any of these unit types to be the side's leader (i.e. "Choose your Leader"). They will also have the option of having one of these types being chosen randomly.
** '''random_leader''': if this list of types is present, it would use this list to instead to choose a random leader. If not it would use '''leader'''
** '''random_faction''': default 'no'. If 'yes', then when this faction is chosen, another non random faction will be randomly chosen instead. The leader will also be chosen randomly.
** '''choices''': Empty by default. If non-empty and the faction has '''random_faction=yes''', it is the list of the IDs of the non random factions that will be choosen randomly. If empty, any faction can be chosen.
** '''except''': Empty by default. If the faction has random_faction=yes, it is the list of the IDs of the non random factions that will not be choosen randomly.
** '''type''': the unit type of the default leader for the side. This must be present. 'random' is a valid value here and will cause a random leader choice by default.
** '''recruit''': a comma-separated list of unit types this faction can recruit.
** '''extra_recruit''': a comma-separated list of unit types appended to the leader recruitlist (see [[SingleUnitWML]]).
** '''terrain_liked''': an unseparated list of terrains (see [[TerrainCodesWML]]). On random maps, these terrains will determine which keep the side is assigned, attempting to put it near the listed terrains.
* '''[event]''': any [event]s written inside the [era] tag will get included into scenarios that are played using this era. See [[EventWML]].
* '''[options]''': {{DevFeature1.11}} custom options. See [[OptionWML]] for details.
* '''[ai]''': See [[AiWML]] for details.

== See Also ==

* [[ReferenceWML]]
* [[SideWML]]

[[Category: WML Reference]]

CodingStandards

2014-12-17T03:48:52Z

Iceiceice: /* Destructors must not throw exceptions */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

In C++11, any destructor which throws an exception causes the program to be immediately terminated (except in special cases).

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

Similarly, avoid writing <tt>delete</tt> explicitly in your code. Oftentimes using a smart pointer or similar instead will improve the readability of your code, by making it obvious that you are managing memory correctly even if an exception is thrown. If you were deleting a pointer which is a member variable of an object, using a smart pointer instead may simplify your code by eliminating the need to write an explicit destructor in some cases.

For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

CodingStandards

2014-12-17T03:48:20Z

Iceiceice: /* Destructors must not throw exceptions */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

In C++11, any destructor which throws an exception causes the program to be immediately terminated. (Except in special cases.)

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

Similarly, avoid writing <tt>delete</tt> explicitly in your code. Oftentimes using a smart pointer or similar instead will improve the readability of your code, by making it obvious that you are managing memory correctly even if an exception is thrown. If you were deleting a pointer which is a member variable of an object, using a smart pointer instead may simplify your code by eliminating the need to write an explicit destructor in some cases.

For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

NotSoEasyCoding

2014-12-14T00:13:03Z

Iceiceice: /* Fix a longstanding bug concerning failure to initialize a side in networked mp */

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Game Engine ==
=== add a mode to improve OOS detection in MP ===
We really need an optional 'pedantic mode' for MP which detects OOSes immediately, by comparing all game state information after each action and printing any mismatches. This mode will be optional because of the extra overhead it adds, and it would be very useful for debugging.

=== Make a "replay actions since my last turn" button ===

It would be very convenient if there an ability to replay everything your opponents just did at the
start of your turn, since sometimes things go out of vision or are confusing.

The feature would be like a "replay since my last turn" menu option or button -- most likely, the best approach to implement it is to store a copy of the game_state object in playcontroller.cpp or even in resources, and to refactor the backlog object so that we can hold a "bookmark", i.e. a pointer, to the last position in the replay that we might look to jump back to. The replay process would work by swapping out for the old gamestate, then replaying through the actions since the bookmark until we get back up to speed. The difficult part would be making sure that scenarios with scripted WML events don't break when we do this. For debugging purposes, it might be good to check that at this point we have the same gamestate we did before we clicked the button. The bookmark should only be advanced when we end our turn, and there might be perhaps need to be multiple bookmarks, one for each side, to handle what happens when a side disconnects or is reassigned.

It would be especially helpful for MP play to have this, where special tactics with ambush units are quite common. Part of the design criteria of wesnoth is that it should be a high-level, thoughtful turn based strategy game, but you should be able to play asynchronously and not necessarily give attention to the game until your turn bell rings if you don't want to. Having ambush units and no ability to replay their movements during the opponents turn harms that goal.

For MP play, it will require special attention to make sure that events like "synchronize_choice" are handled correctly so as not to cause out of sync errors, and also that the timer is handled correctly.

Feature request: https://gna.org/bugs/?15334

=== Improve WML error reporting ===

There are many programming bugs that give very unclear or cryptic error messages when using WML. Here are some examples:

-- When calling a macro with the wrong number of arguments, wesnoth tells the number it expected, and the number it got, and at which line number it was instantiated. However, it would be helpful if it would also tell the line number of the definition of the macro. This might be helpful if someone is redefining macros.

-- For places where a standard unit filter is expected, if one is not found, the game should point out a problem. For places where such a filter is expected but [filter] child should not appear, if one does it should report an error and a line number. Many users have a hard time with this kind of thing.

-- When doing scenario transitions in a campaign, if the side definitions don't matchup exactly the game tends to give unintelligible error messages. For instance, if one is transitioning and there is an AI side which does not have a leader (but it has a starting location in the map) it must have "no_leader = yes" in its [side] tag, or else when the team_builder objects enter stage two, the game will try to create a unit with an empty type, and the constructor of class unit will fail giving the error message "game::game_error tried to create unit with empty type". This really needs to be much better. For instance, giving a line number of a problem, or suggesting that no_leader should be used. (Note that, it is often possible to debug problems like this by turning on --log-debug=team_construction at commandline but I doubt that there are any users that know about this, you would only learn from reading the C++... without such debug info, fixing things like this can literally take hours.) For that matter it's some question why the team_builder doesn't just stop trying to build a unit when it sees it doesn't have enough info...

-- Recursive macros break the game, and not by stack overflow but by exhausting the heap. It would be nice if we could catch this and report an error.

Many of the users of WML are students or beginners to programming, it is a big help to them to improve the error reporting of this nature -- not to mention that many veterans would appreciate as well. In part we need fixits here and there but more broadly we need a smarter system that can figure out what's really wrong when things go wrong and give helpful suggestions.

=== Map label "groups" which can be selectively turned on and off by the user ===

It would be nice if the user could have more control over how map labels are displayed, for instance to be able to check on / off labels made by certain players, and for custom scenarios, to be able to make custom classes which the use can turn on or off. This might be helpful for custom scenarios esp. which might have some technical info they want to show, but which it might be messy to display all of the time. The hard part of this is that there should ideally be a gui to work with the map labels, although maybe this need could be worked around or simplified somehow.

=== Add a new damage stats calculation mode to support scenarios with extremely high stats ===

Most players use the damage calculation window constantly when they play so that they can see what to expect from various attacks. The way the game is currently set up, when a unit is selected, as soon as another unit is moused over the stats for an attack will be calculated, whether or not the user actually brings up the window.

The probabilities for the various outcomes are calculated by explicitly calculating the distribution of attacker and defender hp / slowed status after each swing by either party, one swing at a time. Thus at the end we get exact probabilities of the possible outcomes.

However, this comes at a cost -- the running time of the calculation can in the worst case be something like O( attacker_hp * defender_hp * total_number_of_strikes). In default era wesnoth (and in much of UMC) this is fine because units don't get extremely high hp values. However in some UMC units do get extremely high hp, and many will also have specials like drain and berzerk, and may have many different weapons as well. At some point these scenarios become unplayable even on a machine of moderate specs because mousing over any unit causes > 10 seconds of lag during which the game becomes unresponsive, trying to calculate attack outcomes.

In these cases, it would be better to give an "inexact" damage prediction, based on just simulating a few thousand attacks and plotting the results. Since it's a monte carlo algorithm rather than an exact algorithm, there will be some error, but if it makes the game playable then it's clearly an improvement, and anyways for "extreme stats" battles with high strikes and damage, the outcome is in a sense less random anyways because the outcomes with inordinate amounts of hits and misses are more and more rare (law of large numbers), so the error shouldn't actually be terribly significant.

If there were an advanced preference that caused the predictions to use such an algorithm instead of the current one, so that the user could turn it on if they start to get problems, it would eliminate a significant headache for some UMC.

== MP Related ==

=== Automatically resolve add-on dependencies ===

In 1.11 add-ons may declare dependencies. A related easy coding task is to allow the user to force breaking dependencies.

A related goal which would be greatly beneficial would be that wesnoth can automatically resolve the dependencies by fetching the add-ons from the download server, when in the MP-lobby the user tries to join a game with a dependency they don't meet. A dialog would ideally be provided as well, or perhaps a preference.

https://gna.org/bugs/?21705

Even older: https://gna.org/bugs/?9683

=== Gold graph ===

Make a graph feature, presumably in a dialog, that helps depict the history of the game. For example it could display army value, army + bank value, number of villages tagged, luck swings... the purpose would be to assist spectators of a live game / spectators of a replay to understand the history of the game. It would be particularly helpful with AI development, by helping AI developers to identify key points where one of the AI is making a big mistake.

A possible nice feature for this purpose would be to allow the user to click on the graph at key points which would trigger the "back to turn" mechanism to jump back in the replay, or automatically play the replay forwards from the beginning to that point... etc.

Related email on dev-talk: https://mail.gna.org/public/wesnoth-dev/2014-02/msg00089.html

=== Automatically link up to wesnothd server on a local network ===

The feature request was to use ZeroConf technology, if available, to publish info of a running wesnothd instance to other machines on a local network. Then when they are searching to connect to an unofficial server, they won't have to learn the IP address.

The extra code should be guarded with preprocessor flags so that ZeroConf does not become a build dependency of wesnoth.

https://gna.org/bugs/?13703

=== Create a set of "common" mp messages which players can use when they don't share a language ===

Most users speak english, however, wesnoth also has large Polish and Hungarian communities, and many Brazilian players, not all of whom speak english. It would be nice we could have a set of messages that could be chatted, but which will be translated by our translators and displayed always in the current locale on each client, to make it easier to communicate in mp games / on the mp server.

The hard part is that if you don't already know about the gettext translation system, you will have to learn about it. The messages should be stored in a .cfg file in the data folder so that they can be easily modified and can be handled in the same way that other in-game text is translated -- they should perhaps go in their own gettext-domain however. Ideally there would be a gui dialog of some kind to select from them.

=== Improve server wml processing ===

The wesver uses an alternative implementation to store and process wml objects see http://wiki.wesnoth.org/WesnothdDesign#simple_wml. This is for performance. However, the simple_wml sometimes messes up translation for mp scenarios / campaigns, resulting in mp scenarios/campaigns beeing untranslated for non-hosts in networked mp (http://gna.org/bugs/?22989). Fixing this is not easy becasue of the performance requirements.

== Improvements to AI ==
=== Move and targeting phase ===
AI needs to move units which are not within range of the enemy. This is generally a sequence of moves (some interesting things like 'ambush!' or 'WML event' might happen as a result of those moves, which should interrupt this phase). The problem is that simply doing those moves 1-by-1 is very slow, for two reasons:

#movement maps are invalidated after each move, and are recalculated from the start. yet, if we are doing just a sequence of moves, we can just 'remove moved unit from moves' after each move and avoid expensive recalculation of the movement map.
#* Note that WML could mess with the game state at any time, so at the very least, movement will need to be recalculated after a WML event blocks undo (that is, indicates that it changed game state). --[[User:Brilliand|Brilliand]] 01:30, 28 May 2012 (UTC)
#most tasks need devoting more than one unit to execute (i.e., it's meaningless to go for the enemy position with just 1 unit). So, making individual decisions just does some repeating calculations, which is slow.

A practical demonstration of these concerns are LoW 2 (dwarf ai is slow due to large avoid aspect) and NR:Showdown (orc AIs there are slow because of huge number of units)

we need a fast and effective 'move and targeting stage' - both ideas and implementations are wanted.
Here's Sirp's idea (more in 2009-aug-15 irclog):

--

=== Eval-based AI ===
The AI system would be based around an 'eval' function -- a formula which is given a position, and returns a number saying how attractive that position is.

There would also be a 'candidate_moves' function -- a formula which is given a unit and returns a list of 'candidate moves' -- i.e. moves for that unit that the AI should consider making.

The aim of the system is to come up with the combination of candidate moves that gives the best possible evaluation. By doing this, the AI will work in a team, since the 'eval' function can give bonuses for units being close together, protecting each other, etc.

There are likely to be, of course, a very large combination of possible moves, and not every one can possibly be evaluated. Instead, we take a monte carlo approach.

If an AI has N units that it can move, that is an N-dimension matrix of possible moves. We would choose some cells in this matrix at random and then evaluate them. Then, of these cells evaluated we would choose cells that evaluated well, and discard those that did not evaluate well. Then, we would begin with those cells that evaluated well, and choose a scattering of 'close by' cells -- i.e. cells where we only vary some of the dimensions, at random. We would continue to evaluate cells at random, starting with those cells that evaluated well, and evaluating cells nearby. After several iterations, we would hope to arrive at a cell that evaluates very well, and we would use this as our set of moves.

Of course, this system will be made more complex by the uncertainty of attacks. There are a number of ways to handle attacks, probably the easiest being to consider attacks as types of moves, and then if a move combination involving an attack is chosen, perform the attack and then re-run the entire AI algorithm before moving again. (Something similar to what the current AI does).

This is effectively an AI framework, not an AI in itself. How well it performs will correlate strongly with how good an eval() function one can write, and is also based on the notion that generally certain combinations of moves are 'similar' to other combinations.

--

=== Village grabbing ===

Improve AI village grabbing algorithm to assign villages that are farther than one turn from current unit location.
Idea how to do would be value villages so that it can filter out villages that belongs to enemies/allies sides. Those villages are stored in memory and used in 2nd pass that determines how AI should dispatch units to get villages if it should at all in this turn. This should be close to optimal solution with currently available units but performance limits should be taken into account.
Good solution would be that village grabbing value could be calculated with attack ratings and if some village has high value it would make unit go for that village instead

This should help AI in begin of scenario. Currently AI might not grab all of villages that belong to its area which results quite large incoming loses.
In later game enemy might have large number of units in one part of map so village grabbing should be avoided in that are. Single unit would be easy pray for enemy so moving there would result just to loses.

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Config memory optimisation ===

Right now, most of the memory used by wesnoth when using '''low_memory''' configuration flag is used by the config object trees. It would be possible to drop unused "branches" of that trees by using boost smart pointers in the config structure

come and discuss that change on #wesnoth-dev. Sirp is the one that knows the most about that...

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063] (cjhopman has submitted a patch on that already)

=== Make the lua state persistent ===

Wesnoth is designed to make all data files as simple and human-readable as possible, including savefiles. WML is designed so that it is always very easy to write the entire WML state as plaintext and reload it correctly. There are many benefits of this, but especially

* It makes it easy for beginners / students to read the files and see what's going on
* It makes it easy for us to debug problems without needing special tools to read the savefiles
* It makes it easy to edit save files to work around any possible bugs. Users have even reported opening savefiles from version 1.10 in microsoft word (!) to correct minor bugs in mp and resaving them, as a policy for tournament games.

This was unfortunately somewhat lost when we added lua. If you use lua in your scenarios, things become more complicated because we can't save the lua state at all. If you rely on lua variables to save information, then when your scenario is saved and reloaded those variables will get wiped. The wesnoth engine provides places for lua to hook into "onsave" and "onload" so that the scenario developer can write their own serialization routines, but this is just punting the problem to scenario developers.

We also provide the "preload" event type specifically to work around the issue -- unlike all other events, preload is called exactly once for every time the scenario is loaded. The purpose is to give another way that lua users can initialize a table of lua functions used by their addon and guarantee that this happens before the functions are called. But to non-lua users this event is basically unsafe for normal use otherwise -- if there is a preload event which e.g. increments a WML variable, then the WML state now depends on how many times the scenario is saved or reloaded. In a normal scenario, save / reload events should be invisible, and normally if this isn't the case it indicates a bug similar to an OOS.

A nice solution to this would be if we properly serialized the lua state alongside the WML in a savefile. The most suitable solution is probably this library: https://github.com/fnuecke/eris
It would require significant additional work as well to find a good way to serialize the C functions that we expose to lua, and the userdata like units held by lua.

More info here: http://lua-users.org/wiki/PlutoLibrary

== See Also ==

=== Frequently Proposed Good Ideas ===

Check the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=9054&start=0&st=0&sk=t&sd=a B.W.H. list] in the Ideas Forum. Be aware that some entries there are old and have already been implemented, so you will need to investigate that before beginning work.

[[Category:Development]]
[[Category:Future]]

NotSoEasyCoding

2014-12-13T00:35:13Z

Iceiceice: /* Make a "replay actions since my last turn" button */

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Game Engine ==
=== add a mode to improve OOS detection in MP ===
We really need an optional 'pedantic mode' for MP which detects OOSes immediately, by comparing all game state information after each action and printing any mismatches. This mode will be optional because of the extra overhead it adds, and it would be very useful for debugging.

=== <s>Fix a longstanding bug concerning failure to initialize a side in networked mp</s> ===

(Actually we may have a fix for this now... will post reference)

https://gna.org/bugs/index.php?21397

The problem itself is quite simple -- when the server tells a client that their turn has begun, the client immediately broadcasts [init_side] to all the other players via the server, performing the initial upkeep, healing, and movement point reset actions. However, if this player disconnects / blocks the action by opening a dialog during the prior turn and never closing it, [init_side] is never broadcast. And if the game is then saved by one of the other clients, nothing in the current mechanism detects that this has been overlooked when the game is reloaded. The consequence is that in the reloaded game, that side's turn is *never* initialized -- they get no gold, their units don't heal, and they don't get full move points at the start of the turn.

Propose a mechanism to fix this -- perhaps games which have been loaded should be scanned to see if the current turn failed to initialize. Perhaps a flag in game_state could be used and saved. Perhaps a completely different approach. Check that your mechanism works whether the save is loaded from [snapshot] or [replay_start] and [replay].

This bug has existed since at least Wesnoth 1.8

=== Make a "replay actions since my last turn" button ===

It would be very convenient if there an ability to replay everything your opponents just did at the
start of your turn, since sometimes things go out of vision or are confusing.

The feature would be like a "replay since my last turn" menu option or button -- most likely, the best approach to implement it is to store a copy of the game_state object in playcontroller.cpp or even in resources, and to refactor the backlog object so that we can hold a "bookmark", i.e. a pointer, to the last position in the replay that we might look to jump back to. The replay process would work by swapping out for the old gamestate, then replaying through the actions since the bookmark until we get back up to speed. The difficult part would be making sure that scenarios with scripted WML events don't break when we do this. For debugging purposes, it might be good to check that at this point we have the same gamestate we did before we clicked the button. The bookmark should only be advanced when we end our turn, and there might be perhaps need to be multiple bookmarks, one for each side, to handle what happens when a side disconnects or is reassigned.

It would be especially helpful for MP play to have this, where special tactics with ambush units are quite common. Part of the design criteria of wesnoth is that it should be a high-level, thoughtful turn based strategy game, but you should be able to play asynchronously and not necessarily give attention to the game until your turn bell rings if you don't want to. Having ambush units and no ability to replay their movements during the opponents turn harms that goal.

For MP play, it will require special attention to make sure that events like "synchronize_choice" are handled correctly so as not to cause out of sync errors, and also that the timer is handled correctly.

Feature request: https://gna.org/bugs/?15334

=== Improve WML error reporting ===

There are many programming bugs that give very unclear or cryptic error messages when using WML. Here are some examples:

-- When calling a macro with the wrong number of arguments, wesnoth tells the number it expected, and the number it got, and at which line number it was instantiated. However, it would be helpful if it would also tell the line number of the definition of the macro. This might be helpful if someone is redefining macros.

-- For places where a standard unit filter is expected, if one is not found, the game should point out a problem. For places where such a filter is expected but [filter] child should not appear, if one does it should report an error and a line number. Many users have a hard time with this kind of thing.

-- When doing scenario transitions in a campaign, if the side definitions don't matchup exactly the game tends to give unintelligible error messages. For instance, if one is transitioning and there is an AI side which does not have a leader (but it has a starting location in the map) it must have "no_leader = yes" in its [side] tag, or else when the team_builder objects enter stage two, the game will try to create a unit with an empty type, and the constructor of class unit will fail giving the error message "game::game_error tried to create unit with empty type". This really needs to be much better. For instance, giving a line number of a problem, or suggesting that no_leader should be used. (Note that, it is often possible to debug problems like this by turning on --log-debug=team_construction at commandline but I doubt that there are any users that know about this, you would only learn from reading the C++... without such debug info, fixing things like this can literally take hours.) For that matter it's some question why the team_builder doesn't just stop trying to build a unit when it sees it doesn't have enough info...

-- Recursive macros break the game, and not by stack overflow but by exhausting the heap. It would be nice if we could catch this and report an error.

Many of the users of WML are students or beginners to programming, it is a big help to them to improve the error reporting of this nature -- not to mention that many veterans would appreciate as well. In part we need fixits here and there but more broadly we need a smarter system that can figure out what's really wrong when things go wrong and give helpful suggestions.

=== Map label "groups" which can be selectively turned on and off by the user ===

It would be nice if the user could have more control over how map labels are displayed, for instance to be able to check on / off labels made by certain players, and for custom scenarios, to be able to make custom classes which the use can turn on or off. This might be helpful for custom scenarios esp. which might have some technical info they want to show, but which it might be messy to display all of the time. The hard part of this is that there should ideally be a gui to work with the map labels, although maybe this need could be worked around or simplified somehow.

=== Add a new damage stats calculation mode to support scenarios with extremely high stats ===

Most players use the damage calculation window constantly when they play so that they can see what to expect from various attacks. The way the game is currently set up, when a unit is selected, as soon as another unit is moused over the stats for an attack will be calculated, whether or not the user actually brings up the window.

The probabilities for the various outcomes are calculated by explicitly calculating the distribution of attacker and defender hp / slowed status after each swing by either party, one swing at a time. Thus at the end we get exact probabilities of the possible outcomes.

However, this comes at a cost -- the running time of the calculation can in the worst case be something like O( attacker_hp * defender_hp * total_number_of_strikes). In default era wesnoth (and in much of UMC) this is fine because units don't get extremely high hp values. However in some UMC units do get extremely high hp, and many will also have specials like drain and berzerk, and may have many different weapons as well. At some point these scenarios become unplayable even on a machine of moderate specs because mousing over any unit causes > 10 seconds of lag during which the game becomes unresponsive, trying to calculate attack outcomes.

In these cases, it would be better to give an "inexact" damage prediction, based on just simulating a few thousand attacks and plotting the results. Since it's a monte carlo algorithm rather than an exact algorithm, there will be some error, but if it makes the game playable then it's clearly an improvement, and anyways for "extreme stats" battles with high strikes and damage, the outcome is in a sense less random anyways because the outcomes with inordinate amounts of hits and misses are more and more rare (law of large numbers), so the error shouldn't actually be terribly significant.

If there were an advanced preference that caused the predictions to use such an algorithm instead of the current one, so that the user could turn it on if they start to get problems, it would eliminate a significant headache for some UMC.

== MP Related ==

=== Automatically resolve add-on dependencies ===

In 1.11 add-ons may declare dependencies. A related easy coding task is to allow the user to force breaking dependencies.

A related goal which would be greatly beneficial would be that wesnoth can automatically resolve the dependencies by fetching the add-ons from the download server, when in the MP-lobby the user tries to join a game with a dependency they don't meet. A dialog would ideally be provided as well, or perhaps a preference.

https://gna.org/bugs/?21705

Even older: https://gna.org/bugs/?9683

=== Gold graph ===

Make a graph feature, presumably in a dialog, that helps depict the history of the game. For example it could display army value, army + bank value, number of villages tagged, luck swings... the purpose would be to assist spectators of a live game / spectators of a replay to understand the history of the game. It would be particularly helpful with AI development, by helping AI developers to identify key points where one of the AI is making a big mistake.

A possible nice feature for this purpose would be to allow the user to click on the graph at key points which would trigger the "back to turn" mechanism to jump back in the replay, or automatically play the replay forwards from the beginning to that point... etc.

Related email on dev-talk: https://mail.gna.org/public/wesnoth-dev/2014-02/msg00089.html

=== Automatically link up to wesnothd server on a local network ===

The feature request was to use ZeroConf technology, if available, to publish info of a running wesnothd instance to other machines on a local network. Then when they are searching to connect to an unofficial server, they won't have to learn the IP address.

The extra code should be guarded with preprocessor flags so that ZeroConf does not become a build dependency of wesnoth.

https://gna.org/bugs/?13703

=== Create a set of "common" mp messages which players can use when they don't share a language ===

Most users speak english, however, wesnoth also has large Polish and Hungarian communities, and many Brazilian players, not all of whom speak english. It would be nice we could have a set of messages that could be chatted, but which will be translated by our translators and displayed always in the current locale on each client, to make it easier to communicate in mp games / on the mp server.

The hard part is that if you don't already know about the gettext translation system, you will have to learn about it. The messages should be stored in a .cfg file in the data folder so that they can be easily modified and can be handled in the same way that other in-game text is translated -- they should perhaps go in their own gettext-domain however. Ideally there would be a gui dialog of some kind to select from them.

=== Improve server wml processing ===

The wesver uses an alternative implementation to store and process wml objects see http://wiki.wesnoth.org/WesnothdDesign#simple_wml. This is for performance. However, the simple_wml sometimes messes up translation for mp scenarios / campaigns, resulting in mp scenarios/campaigns beeing untranslated for non-hosts in networked mp (http://gna.org/bugs/?22989). Fixing this is not easy becasue of the performance requirements.

== Improvements to AI ==
=== Move and targeting phase ===
AI needs to move units which are not within range of the enemy. This is generally a sequence of moves (some interesting things like 'ambush!' or 'WML event' might happen as a result of those moves, which should interrupt this phase). The problem is that simply doing those moves 1-by-1 is very slow, for two reasons:

#movement maps are invalidated after each move, and are recalculated from the start. yet, if we are doing just a sequence of moves, we can just 'remove moved unit from moves' after each move and avoid expensive recalculation of the movement map.
#* Note that WML could mess with the game state at any time, so at the very least, movement will need to be recalculated after a WML event blocks undo (that is, indicates that it changed game state). --[[User:Brilliand|Brilliand]] 01:30, 28 May 2012 (UTC)
#most tasks need devoting more than one unit to execute (i.e., it's meaningless to go for the enemy position with just 1 unit). So, making individual decisions just does some repeating calculations, which is slow.

A practical demonstration of these concerns are LoW 2 (dwarf ai is slow due to large avoid aspect) and NR:Showdown (orc AIs there are slow because of huge number of units)

we need a fast and effective 'move and targeting stage' - both ideas and implementations are wanted.
Here's Sirp's idea (more in 2009-aug-15 irclog):

--

=== Eval-based AI ===
The AI system would be based around an 'eval' function -- a formula which is given a position, and returns a number saying how attractive that position is.

There would also be a 'candidate_moves' function -- a formula which is given a unit and returns a list of 'candidate moves' -- i.e. moves for that unit that the AI should consider making.

The aim of the system is to come up with the combination of candidate moves that gives the best possible evaluation. By doing this, the AI will work in a team, since the 'eval' function can give bonuses for units being close together, protecting each other, etc.

There are likely to be, of course, a very large combination of possible moves, and not every one can possibly be evaluated. Instead, we take a monte carlo approach.

If an AI has N units that it can move, that is an N-dimension matrix of possible moves. We would choose some cells in this matrix at random and then evaluate them. Then, of these cells evaluated we would choose cells that evaluated well, and discard those that did not evaluate well. Then, we would begin with those cells that evaluated well, and choose a scattering of 'close by' cells -- i.e. cells where we only vary some of the dimensions, at random. We would continue to evaluate cells at random, starting with those cells that evaluated well, and evaluating cells nearby. After several iterations, we would hope to arrive at a cell that evaluates very well, and we would use this as our set of moves.

Of course, this system will be made more complex by the uncertainty of attacks. There are a number of ways to handle attacks, probably the easiest being to consider attacks as types of moves, and then if a move combination involving an attack is chosen, perform the attack and then re-run the entire AI algorithm before moving again. (Something similar to what the current AI does).

This is effectively an AI framework, not an AI in itself. How well it performs will correlate strongly with how good an eval() function one can write, and is also based on the notion that generally certain combinations of moves are 'similar' to other combinations.

--

=== Village grabbing ===

Improve AI village grabbing algorithm to assign villages that are farther than one turn from current unit location.
Idea how to do would be value villages so that it can filter out villages that belongs to enemies/allies sides. Those villages are stored in memory and used in 2nd pass that determines how AI should dispatch units to get villages if it should at all in this turn. This should be close to optimal solution with currently available units but performance limits should be taken into account.
Good solution would be that village grabbing value could be calculated with attack ratings and if some village has high value it would make unit go for that village instead

This should help AI in begin of scenario. Currently AI might not grab all of villages that belong to its area which results quite large incoming loses.
In later game enemy might have large number of units in one part of map so village grabbing should be avoided in that are. Single unit would be easy pray for enemy so moving there would result just to loses.

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Config memory optimisation ===

Right now, most of the memory used by wesnoth when using '''low_memory''' configuration flag is used by the config object trees. It would be possible to drop unused "branches" of that trees by using boost smart pointers in the config structure

come and discuss that change on #wesnoth-dev. Sirp is the one that knows the most about that...

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063] (cjhopman has submitted a patch on that already)

=== Make the lua state persistent ===

Wesnoth is designed to make all data files as simple and human-readable as possible, including savefiles. WML is designed so that it is always very easy to write the entire WML state as plaintext and reload it correctly. There are many benefits of this, but especially

* It makes it easy for beginners / students to read the files and see what's going on
* It makes it easy for us to debug problems without needing special tools to read the savefiles
* It makes it easy to edit save files to work around any possible bugs. Users have even reported opening savefiles from version 1.10 in microsoft word (!) to correct minor bugs in mp and resaving them, as a policy for tournament games.

This was unfortunately somewhat lost when we added lua. If you use lua in your scenarios, things become more complicated because we can't save the lua state at all. If you rely on lua variables to save information, then when your scenario is saved and reloaded those variables will get wiped. The wesnoth engine provides places for lua to hook into "onsave" and "onload" so that the scenario developer can write their own serialization routines, but this is just punting the problem to scenario developers.

We also provide the "preload" event type specifically to work around the issue -- unlike all other events, preload is called exactly once for every time the scenario is loaded. The purpose is to give another way that lua users can initialize a table of lua functions used by their addon and guarantee that this happens before the functions are called. But to non-lua users this event is basically unsafe for normal use otherwise -- if there is a preload event which e.g. increments a WML variable, then the WML state now depends on how many times the scenario is saved or reloaded. In a normal scenario, save / reload events should be invisible, and normally if this isn't the case it indicates a bug similar to an OOS.

A nice solution to this would be if we properly serialized the lua state alongside the WML in a savefile. The most suitable solution is probably this library: https://github.com/fnuecke/eris
It would require significant additional work as well to find a good way to serialize the C functions that we expose to lua, and the userdata like units held by lua.

More info here: http://lua-users.org/wiki/PlutoLibrary

== See Also ==

=== Frequently Proposed Good Ideas ===

Check the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=9054&start=0&st=0&sk=t&sd=a B.W.H. list] in the Ideas Forum. Be aware that some entries there are old and have already been implemented, so you will need to investigate that before beginning work.

[[Category:Development]]
[[Category:Future]]

NotSoEasyCoding

2014-12-09T03:01:30Z

Iceiceice: /* Make the lua state persistent */

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Game Engine ==
=== add a mode to improve OOS detection in MP ===
We really need an optional 'pedantic mode' for MP which detects OOSes immediately, by comparing all game state information after each action and printing any mismatches. This mode will be optional because of the extra overhead it adds, and it would be very useful for debugging.

=== <s>Fix a longstanding bug concerning failure to initialize a side in networked mp</s> ===

(Actually we may have a fix for this now... will post reference)

https://gna.org/bugs/index.php?21397

The problem itself is quite simple -- when the server tells a client that their turn has begun, the client immediately broadcasts [init_side] to all the other players via the server, performing the initial upkeep, healing, and movement point reset actions. However, if this player disconnects / blocks the action by opening a dialog during the prior turn and never closing it, [init_side] is never broadcast. And if the game is then saved by one of the other clients, nothing in the current mechanism detects that this has been overlooked when the game is reloaded. The consequence is that in the reloaded game, that side's turn is *never* initialized -- they get no gold, their units don't heal, and they don't get full move points at the start of the turn.

Propose a mechanism to fix this -- perhaps games which have been loaded should be scanned to see if the current turn failed to initialize. Perhaps a flag in game_state could be used and saved. Perhaps a completely different approach. Check that your mechanism works whether the save is loaded from [snapshot] or [replay_start] and [replay].

This bug has existed since at least Wesnoth 1.8

=== <s>Make a "replay actions since my last turn" button</s> ===

It would be very convenient if there an ability to replay everything your opponents just did at the
start of your turn, since sometimes things go out of vision or are confusing.

The feature would be like a "replay since my last turn" menu option or button -- most likely, the best approach to implement it is to store a copy of the game_state object in playcontroller.cpp or even in resources, and to refactor the backlog object so that we can hold a "bookmark", i.e. a pointer, to the last position in the replay that we might look to jump back to. The replay process would work by swapping out for the old gamestate, then replaying through the actions since the bookmark until we get back up to speed. The difficult part would be making sure that scenarios with scripted WML events don't break when we do this. For debugging purposes, it might be good to check that at this point we have the same gamestate we did before we clicked the button. The bookmark should only be advanced when we end our turn, and there might be perhaps need to be multiple bookmarks, one for each side, to handle what happens when a side disconnects or is reassigned.

It would be especially helpful for MP play to have this, where special tactics with ambush units are quite common. Part of the design criteria of wesnoth is that it should be a high-level, thoughtful turn based strategy game, but you should be able to play asynchronously and not necessarily give attention to the game until your turn bell rings if you don't want to. Having ambush units and no ability to replay their movements during the opponents turn harms that goal.

For MP play, it will require special attention to make sure that events like "synchronize_choice" are handled correctly so as not to cause out of sync errors, and also that the timer is handled correctly.

Feature request: https://gna.org/bugs/?15334

Thanks to Zappaman for this. https://github.com/wesnoth/wesnoth/pull/270

=== Improve WML error reporting ===

There are many programming bugs that give very unclear or cryptic error messages when using WML. Here are some examples:

-- When calling a macro with the wrong number of arguments, wesnoth tells the number it expected, and the number it got, and at which line number it was instantiated. However, it would be helpful if it would also tell the line number of the definition of the macro. This might be helpful if someone is redefining macros.

-- For places where a standard unit filter is expected, if one is not found, the game should point out a problem. For places where such a filter is expected but [filter] child should not appear, if one does it should report an error and a line number. Many users have a hard time with this kind of thing.

-- When doing scenario transitions in a campaign, if the side definitions don't matchup exactly the game tends to give unintelligible error messages. For instance, if one is transitioning and there is an AI side which does not have a leader (but it has a starting location in the map) it must have "no_leader = yes" in its [side] tag, or else when the team_builder objects enter stage two, the game will try to create a unit with an empty type, and the constructor of class unit will fail giving the error message "game::game_error tried to create unit with empty type". This really needs to be much better. For instance, giving a line number of a problem, or suggesting that no_leader should be used. (Note that, it is often possible to debug problems like this by turning on --log-debug=team_construction at commandline but I doubt that there are any users that know about this, you would only learn from reading the C++... without such debug info, fixing things like this can literally take hours.) For that matter it's some question why the team_builder doesn't just stop trying to build a unit when it sees it doesn't have enough info...

-- Recursive macros break the game, and not by stack overflow but by exhausting the heap. It would be nice if we could catch this and report an error.

Many of the users of WML are students or beginners to programming, it is a big help to them to improve the error reporting of this nature -- not to mention that many veterans would appreciate as well. In part we need fixits here and there but more broadly we need a smarter system that can figure out what's really wrong when things go wrong and give helpful suggestions.

=== Map label "groups" which can be selectively turned on and off by the user ===

It would be nice if the user could have more control over how map labels are displayed, for instance to be able to check on / off labels made by certain players, and for custom scenarios, to be able to make custom classes which the use can turn on or off. This might be helpful for custom scenarios esp. which might have some technical info they want to show, but which it might be messy to display all of the time. The hard part of this is that there should ideally be a gui to work with the map labels, although maybe this need could be worked around or simplified somehow.

=== Add a new damage stats calculation mode to support scenarios with extremely high stats ===

Most players use the damage calculation window constantly when they play so that they can see what to expect from various attacks. The way the game is currently set up, when a unit is selected, as soon as another unit is moused over the stats for an attack will be calculated, whether or not the user actually brings up the window.

The probabilities for the various outcomes are calculated by explicitly calculating the distribution of attacker and defender hp / slowed status after each swing by either party, one swing at a time. Thus at the end we get exact probabilities of the possible outcomes.

However, this comes at a cost -- the running time of the calculation can in the worst case be something like O( attacker_hp * defender_hp * total_number_of_strikes). In default era wesnoth (and in much of UMC) this is fine because units don't get extremely high hp values. However in some UMC units do get extremely high hp, and many will also have specials like drain and berzerk, and may have many different weapons as well. At some point these scenarios become unplayable even on a machine of moderate specs because mousing over any unit causes > 10 seconds of lag during which the game becomes unresponsive, trying to calculate attack outcomes.

In these cases, it would be better to give an "inexact" damage prediction, based on just simulating a few thousand attacks and plotting the results. Since it's a monte carlo algorithm rather than an exact algorithm, there will be some error, but if it makes the game playable then it's clearly an improvement, and anyways for "extreme stats" battles with high strikes and damage, the outcome is in a sense less random anyways because the outcomes with inordinate amounts of hits and misses are more and more rare (law of large numbers), so the error shouldn't actually be terribly significant.

If there were an advanced preference that caused the predictions to use such an algorithm instead of the current one, so that the user could turn it on if they start to get problems, it would eliminate a significant headache for some UMC.

== MP Related ==

=== Automatically resolve add-on dependencies ===

In 1.11 add-ons may declare dependencies. A related easy coding task is to allow the user to force breaking dependencies.

A related goal which would be greatly beneficial would be that wesnoth can automatically resolve the dependencies by fetching the add-ons from the download server, when in the MP-lobby the user tries to join a game with a dependency they don't meet. A dialog would ideally be provided as well, or perhaps a preference.

https://gna.org/bugs/?21705

Even older: https://gna.org/bugs/?9683

=== Gold graph ===

Make a graph feature, presumably in a dialog, that helps depict the history of the game. For example it could display army value, army + bank value, number of villages tagged, luck swings... the purpose would be to assist spectators of a live game / spectators of a replay to understand the history of the game. It would be particularly helpful with AI development, by helping AI developers to identify key points where one of the AI is making a big mistake.

A possible nice feature for this purpose would be to allow the user to click on the graph at key points which would trigger the "back to turn" mechanism to jump back in the replay, or automatically play the replay forwards from the beginning to that point... etc.

Related email on dev-talk: https://mail.gna.org/public/wesnoth-dev/2014-02/msg00089.html

=== Automatically link up to wesnothd server on a local network ===

The feature request was to use ZeroConf technology, if available, to publish info of a running wesnothd instance to other machines on a local network. Then when they are searching to connect to an unofficial server, they won't have to learn the IP address.

The extra code should be guarded with preprocessor flags so that ZeroConf does not become a build dependency of wesnoth.

https://gna.org/bugs/?13703

=== Create a set of "common" mp messages which players can use when they don't share a language ===

Most users speak english, however, wesnoth also has large Polish and Hungarian communities, and many Brazilian players, not all of whom speak english. It would be nice we could have a set of messages that could be chatted, but which will be translated by our translators and displayed always in the current locale on each client, to make it easier to communicate in mp games / on the mp server.

The hard part is that if you don't already know about the gettext translation system, you will have to learn about it. The messages should be stored in a .cfg file in the data folder so that they can be easily modified and can be handled in the same way that other in-game text is translated -- they should perhaps go in their own gettext-domain however. Ideally there would be a gui dialog of some kind to select from them.

=== Improve server wml processing ===

The wesver uses an alternative implementation to store and process wml objects see http://wiki.wesnoth.org/WesnothdDesign#simple_wml. This is for performance. However, the simple_wml sometimes messes up translation for mp scenarios / campaigns, resulting in mp scenarios/campaigns beeing untranslated for non-hosts in networked mp (http://gna.org/bugs/?22989). Fixing this is not easy becasue of the performance requirements.

== Improvements to AI ==
=== Move and targeting phase ===
AI needs to move units which are not within range of the enemy. This is generally a sequence of moves (some interesting things like 'ambush!' or 'WML event' might happen as a result of those moves, which should interrupt this phase). The problem is that simply doing those moves 1-by-1 is very slow, for two reasons:

#movement maps are invalidated after each move, and are recalculated from the start. yet, if we are doing just a sequence of moves, we can just 'remove moved unit from moves' after each move and avoid expensive recalculation of the movement map.
#* Note that WML could mess with the game state at any time, so at the very least, movement will need to be recalculated after a WML event blocks undo (that is, indicates that it changed game state). --[[User:Brilliand|Brilliand]] 01:30, 28 May 2012 (UTC)
#most tasks need devoting more than one unit to execute (i.e., it's meaningless to go for the enemy position with just 1 unit). So, making individual decisions just does some repeating calculations, which is slow.

A practical demonstration of these concerns are LoW 2 (dwarf ai is slow due to large avoid aspect) and NR:Showdown (orc AIs there are slow because of huge number of units)

we need a fast and effective 'move and targeting stage' - both ideas and implementations are wanted.
Here's Sirp's idea (more in 2009-aug-15 irclog):

--

=== Eval-based AI ===
The AI system would be based around an 'eval' function -- a formula which is given a position, and returns a number saying how attractive that position is.

There would also be a 'candidate_moves' function -- a formula which is given a unit and returns a list of 'candidate moves' -- i.e. moves for that unit that the AI should consider making.

The aim of the system is to come up with the combination of candidate moves that gives the best possible evaluation. By doing this, the AI will work in a team, since the 'eval' function can give bonuses for units being close together, protecting each other, etc.

There are likely to be, of course, a very large combination of possible moves, and not every one can possibly be evaluated. Instead, we take a monte carlo approach.

If an AI has N units that it can move, that is an N-dimension matrix of possible moves. We would choose some cells in this matrix at random and then evaluate them. Then, of these cells evaluated we would choose cells that evaluated well, and discard those that did not evaluate well. Then, we would begin with those cells that evaluated well, and choose a scattering of 'close by' cells -- i.e. cells where we only vary some of the dimensions, at random. We would continue to evaluate cells at random, starting with those cells that evaluated well, and evaluating cells nearby. After several iterations, we would hope to arrive at a cell that evaluates very well, and we would use this as our set of moves.

Of course, this system will be made more complex by the uncertainty of attacks. There are a number of ways to handle attacks, probably the easiest being to consider attacks as types of moves, and then if a move combination involving an attack is chosen, perform the attack and then re-run the entire AI algorithm before moving again. (Something similar to what the current AI does).

This is effectively an AI framework, not an AI in itself. How well it performs will correlate strongly with how good an eval() function one can write, and is also based on the notion that generally certain combinations of moves are 'similar' to other combinations.

--

=== Village grabbing ===

Improve AI village grabbing algorithm to assign villages that are farther than one turn from current unit location.
Idea how to do would be value villages so that it can filter out villages that belongs to enemies/allies sides. Those villages are stored in memory and used in 2nd pass that determines how AI should dispatch units to get villages if it should at all in this turn. This should be close to optimal solution with currently available units but performance limits should be taken into account.
Good solution would be that village grabbing value could be calculated with attack ratings and if some village has high value it would make unit go for that village instead

This should help AI in begin of scenario. Currently AI might not grab all of villages that belong to its area which results quite large incoming loses.
In later game enemy might have large number of units in one part of map so village grabbing should be avoided in that are. Single unit would be easy pray for enemy so moving there would result just to loses.

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Config memory optimisation ===

Right now, most of the memory used by wesnoth when using '''low_memory''' configuration flag is used by the config object trees. It would be possible to drop unused "branches" of that trees by using boost smart pointers in the config structure

come and discuss that change on #wesnoth-dev. Sirp is the one that knows the most about that...

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063] (cjhopman has submitted a patch on that already)

=== Make the lua state persistent ===

Wesnoth is designed to make all data files as simple and human-readable as possible, including savefiles. WML is designed so that it is always very easy to write the entire WML state as plaintext and reload it correctly. There are many benefits of this, but especially

* It makes it easy for beginners / students to read the files and see what's going on
* It makes it easy for us to debug problems without needing special tools to read the savefiles
* It makes it easy to edit save files to work around any possible bugs. Users have even reported opening savefiles from version 1.10 in microsoft word (!) to correct minor bugs in mp and resaving them, as a policy for tournament games.

This was unfortunately somewhat lost when we added lua. If you use lua in your scenarios, things become more complicated because we can't save the lua state at all. If you rely on lua variables to save information, then when your scenario is saved and reloaded those variables will get wiped. The wesnoth engine provides places for lua to hook into "onsave" and "onload" so that the scenario developer can write their own serialization routines, but this is just punting the problem to scenario developers.

We also provide the "preload" event type specifically to work around the issue -- unlike all other events, preload is called exactly once for every time the scenario is loaded. The purpose is to give another way that lua users can initialize a table of lua functions used by their addon and guarantee that this happens before the functions are called. But to non-lua users this event is basically unsafe for normal use otherwise -- if there is a preload event which e.g. increments a WML variable, then the WML state now depends on how many times the scenario is saved or reloaded. In a normal scenario, save / reload events should be invisible, and normally if this isn't the case it indicates a bug similar to an OOS.

A nice solution to this would be if we properly serialized the lua state alongside the WML in a savefile. The most suitable solution is probably this library: https://github.com/fnuecke/eris
It would require significant additional work as well to find a good way to serialize the C functions that we expose to lua, and the userdata like units held by lua.

More info here: http://lua-users.org/wiki/PlutoLibrary

== See Also ==

=== Frequently Proposed Good Ideas ===

Check the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=9054&start=0&st=0&sk=t&sd=a B.W.H. list] in the Ideas Forum. Be aware that some entries there are old and have already been implemented, so you will need to investigate that before beginning work.

[[Category:Development]]
[[Category:Future]]

NotSoEasyCoding

2014-12-09T02:58:25Z

Iceiceice: /* Data Structures */

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Game Engine ==
=== add a mode to improve OOS detection in MP ===
We really need an optional 'pedantic mode' for MP which detects OOSes immediately, by comparing all game state information after each action and printing any mismatches. This mode will be optional because of the extra overhead it adds, and it would be very useful for debugging.

=== <s>Fix a longstanding bug concerning failure to initialize a side in networked mp</s> ===

(Actually we may have a fix for this now... will post reference)

https://gna.org/bugs/index.php?21397

The problem itself is quite simple -- when the server tells a client that their turn has begun, the client immediately broadcasts [init_side] to all the other players via the server, performing the initial upkeep, healing, and movement point reset actions. However, if this player disconnects / blocks the action by opening a dialog during the prior turn and never closing it, [init_side] is never broadcast. And if the game is then saved by one of the other clients, nothing in the current mechanism detects that this has been overlooked when the game is reloaded. The consequence is that in the reloaded game, that side's turn is *never* initialized -- they get no gold, their units don't heal, and they don't get full move points at the start of the turn.

Propose a mechanism to fix this -- perhaps games which have been loaded should be scanned to see if the current turn failed to initialize. Perhaps a flag in game_state could be used and saved. Perhaps a completely different approach. Check that your mechanism works whether the save is loaded from [snapshot] or [replay_start] and [replay].

This bug has existed since at least Wesnoth 1.8

=== <s>Make a "replay actions since my last turn" button</s> ===

It would be very convenient if there an ability to replay everything your opponents just did at the
start of your turn, since sometimes things go out of vision or are confusing.

The feature would be like a "replay since my last turn" menu option or button -- most likely, the best approach to implement it is to store a copy of the game_state object in playcontroller.cpp or even in resources, and to refactor the backlog object so that we can hold a "bookmark", i.e. a pointer, to the last position in the replay that we might look to jump back to. The replay process would work by swapping out for the old gamestate, then replaying through the actions since the bookmark until we get back up to speed. The difficult part would be making sure that scenarios with scripted WML events don't break when we do this. For debugging purposes, it might be good to check that at this point we have the same gamestate we did before we clicked the button. The bookmark should only be advanced when we end our turn, and there might be perhaps need to be multiple bookmarks, one for each side, to handle what happens when a side disconnects or is reassigned.

It would be especially helpful for MP play to have this, where special tactics with ambush units are quite common. Part of the design criteria of wesnoth is that it should be a high-level, thoughtful turn based strategy game, but you should be able to play asynchronously and not necessarily give attention to the game until your turn bell rings if you don't want to. Having ambush units and no ability to replay their movements during the opponents turn harms that goal.

For MP play, it will require special attention to make sure that events like "synchronize_choice" are handled correctly so as not to cause out of sync errors, and also that the timer is handled correctly.

Feature request: https://gna.org/bugs/?15334

Thanks to Zappaman for this. https://github.com/wesnoth/wesnoth/pull/270

=== Improve WML error reporting ===

There are many programming bugs that give very unclear or cryptic error messages when using WML. Here are some examples:

-- When calling a macro with the wrong number of arguments, wesnoth tells the number it expected, and the number it got, and at which line number it was instantiated. However, it would be helpful if it would also tell the line number of the definition of the macro. This might be helpful if someone is redefining macros.

-- For places where a standard unit filter is expected, if one is not found, the game should point out a problem. For places where such a filter is expected but [filter] child should not appear, if one does it should report an error and a line number. Many users have a hard time with this kind of thing.

-- When doing scenario transitions in a campaign, if the side definitions don't matchup exactly the game tends to give unintelligible error messages. For instance, if one is transitioning and there is an AI side which does not have a leader (but it has a starting location in the map) it must have "no_leader = yes" in its [side] tag, or else when the team_builder objects enter stage two, the game will try to create a unit with an empty type, and the constructor of class unit will fail giving the error message "game::game_error tried to create unit with empty type". This really needs to be much better. For instance, giving a line number of a problem, or suggesting that no_leader should be used. (Note that, it is often possible to debug problems like this by turning on --log-debug=team_construction at commandline but I doubt that there are any users that know about this, you would only learn from reading the C++... without such debug info, fixing things like this can literally take hours.) For that matter it's some question why the team_builder doesn't just stop trying to build a unit when it sees it doesn't have enough info...

-- Recursive macros break the game, and not by stack overflow but by exhausting the heap. It would be nice if we could catch this and report an error.

Many of the users of WML are students or beginners to programming, it is a big help to them to improve the error reporting of this nature -- not to mention that many veterans would appreciate as well. In part we need fixits here and there but more broadly we need a smarter system that can figure out what's really wrong when things go wrong and give helpful suggestions.

=== Map label "groups" which can be selectively turned on and off by the user ===

It would be nice if the user could have more control over how map labels are displayed, for instance to be able to check on / off labels made by certain players, and for custom scenarios, to be able to make custom classes which the use can turn on or off. This might be helpful for custom scenarios esp. which might have some technical info they want to show, but which it might be messy to display all of the time. The hard part of this is that there should ideally be a gui to work with the map labels, although maybe this need could be worked around or simplified somehow.

=== Add a new damage stats calculation mode to support scenarios with extremely high stats ===

Most players use the damage calculation window constantly when they play so that they can see what to expect from various attacks. The way the game is currently set up, when a unit is selected, as soon as another unit is moused over the stats for an attack will be calculated, whether or not the user actually brings up the window.

The probabilities for the various outcomes are calculated by explicitly calculating the distribution of attacker and defender hp / slowed status after each swing by either party, one swing at a time. Thus at the end we get exact probabilities of the possible outcomes.

However, this comes at a cost -- the running time of the calculation can in the worst case be something like O( attacker_hp * defender_hp * total_number_of_strikes). In default era wesnoth (and in much of UMC) this is fine because units don't get extremely high hp values. However in some UMC units do get extremely high hp, and many will also have specials like drain and berzerk, and may have many different weapons as well. At some point these scenarios become unplayable even on a machine of moderate specs because mousing over any unit causes > 10 seconds of lag during which the game becomes unresponsive, trying to calculate attack outcomes.

In these cases, it would be better to give an "inexact" damage prediction, based on just simulating a few thousand attacks and plotting the results. Since it's a monte carlo algorithm rather than an exact algorithm, there will be some error, but if it makes the game playable then it's clearly an improvement, and anyways for "extreme stats" battles with high strikes and damage, the outcome is in a sense less random anyways because the outcomes with inordinate amounts of hits and misses are more and more rare (law of large numbers), so the error shouldn't actually be terribly significant.

If there were an advanced preference that caused the predictions to use such an algorithm instead of the current one, so that the user could turn it on if they start to get problems, it would eliminate a significant headache for some UMC.

== MP Related ==

=== Automatically resolve add-on dependencies ===

In 1.11 add-ons may declare dependencies. A related easy coding task is to allow the user to force breaking dependencies.

A related goal which would be greatly beneficial would be that wesnoth can automatically resolve the dependencies by fetching the add-ons from the download server, when in the MP-lobby the user tries to join a game with a dependency they don't meet. A dialog would ideally be provided as well, or perhaps a preference.

https://gna.org/bugs/?21705

Even older: https://gna.org/bugs/?9683

=== Gold graph ===

Make a graph feature, presumably in a dialog, that helps depict the history of the game. For example it could display army value, army + bank value, number of villages tagged, luck swings... the purpose would be to assist spectators of a live game / spectators of a replay to understand the history of the game. It would be particularly helpful with AI development, by helping AI developers to identify key points where one of the AI is making a big mistake.

A possible nice feature for this purpose would be to allow the user to click on the graph at key points which would trigger the "back to turn" mechanism to jump back in the replay, or automatically play the replay forwards from the beginning to that point... etc.

Related email on dev-talk: https://mail.gna.org/public/wesnoth-dev/2014-02/msg00089.html

=== Automatically link up to wesnothd server on a local network ===

The feature request was to use ZeroConf technology, if available, to publish info of a running wesnothd instance to other machines on a local network. Then when they are searching to connect to an unofficial server, they won't have to learn the IP address.

The extra code should be guarded with preprocessor flags so that ZeroConf does not become a build dependency of wesnoth.

https://gna.org/bugs/?13703

=== Create a set of "common" mp messages which players can use when they don't share a language ===

Most users speak english, however, wesnoth also has large Polish and Hungarian communities, and many Brazilian players, not all of whom speak english. It would be nice we could have a set of messages that could be chatted, but which will be translated by our translators and displayed always in the current locale on each client, to make it easier to communicate in mp games / on the mp server.

The hard part is that if you don't already know about the gettext translation system, you will have to learn about it. The messages should be stored in a .cfg file in the data folder so that they can be easily modified and can be handled in the same way that other in-game text is translated -- they should perhaps go in their own gettext-domain however. Ideally there would be a gui dialog of some kind to select from them.

=== Improve server wml processing ===

The wesver uses an alternative implementation to store and process wml objects see http://wiki.wesnoth.org/WesnothdDesign#simple_wml. This is for performance. However, the simple_wml sometimes messes up translation for mp scenarios / campaigns, resulting in mp scenarios/campaigns beeing untranslated for non-hosts in networked mp (http://gna.org/bugs/?22989). Fixing this is not easy becasue of the performance requirements.

== Improvements to AI ==
=== Move and targeting phase ===
AI needs to move units which are not within range of the enemy. This is generally a sequence of moves (some interesting things like 'ambush!' or 'WML event' might happen as a result of those moves, which should interrupt this phase). The problem is that simply doing those moves 1-by-1 is very slow, for two reasons:

#movement maps are invalidated after each move, and are recalculated from the start. yet, if we are doing just a sequence of moves, we can just 'remove moved unit from moves' after each move and avoid expensive recalculation of the movement map.
#* Note that WML could mess with the game state at any time, so at the very least, movement will need to be recalculated after a WML event blocks undo (that is, indicates that it changed game state). --[[User:Brilliand|Brilliand]] 01:30, 28 May 2012 (UTC)
#most tasks need devoting more than one unit to execute (i.e., it's meaningless to go for the enemy position with just 1 unit). So, making individual decisions just does some repeating calculations, which is slow.

A practical demonstration of these concerns are LoW 2 (dwarf ai is slow due to large avoid aspect) and NR:Showdown (orc AIs there are slow because of huge number of units)

we need a fast and effective 'move and targeting stage' - both ideas and implementations are wanted.
Here's Sirp's idea (more in 2009-aug-15 irclog):

--

=== Eval-based AI ===
The AI system would be based around an 'eval' function -- a formula which is given a position, and returns a number saying how attractive that position is.

There would also be a 'candidate_moves' function -- a formula which is given a unit and returns a list of 'candidate moves' -- i.e. moves for that unit that the AI should consider making.

The aim of the system is to come up with the combination of candidate moves that gives the best possible evaluation. By doing this, the AI will work in a team, since the 'eval' function can give bonuses for units being close together, protecting each other, etc.

There are likely to be, of course, a very large combination of possible moves, and not every one can possibly be evaluated. Instead, we take a monte carlo approach.

If an AI has N units that it can move, that is an N-dimension matrix of possible moves. We would choose some cells in this matrix at random and then evaluate them. Then, of these cells evaluated we would choose cells that evaluated well, and discard those that did not evaluate well. Then, we would begin with those cells that evaluated well, and choose a scattering of 'close by' cells -- i.e. cells where we only vary some of the dimensions, at random. We would continue to evaluate cells at random, starting with those cells that evaluated well, and evaluating cells nearby. After several iterations, we would hope to arrive at a cell that evaluates very well, and we would use this as our set of moves.

Of course, this system will be made more complex by the uncertainty of attacks. There are a number of ways to handle attacks, probably the easiest being to consider attacks as types of moves, and then if a move combination involving an attack is chosen, perform the attack and then re-run the entire AI algorithm before moving again. (Something similar to what the current AI does).

This is effectively an AI framework, not an AI in itself. How well it performs will correlate strongly with how good an eval() function one can write, and is also based on the notion that generally certain combinations of moves are 'similar' to other combinations.

--

=== Village grabbing ===

Improve AI village grabbing algorithm to assign villages that are farther than one turn from current unit location.
Idea how to do would be value villages so that it can filter out villages that belongs to enemies/allies sides. Those villages are stored in memory and used in 2nd pass that determines how AI should dispatch units to get villages if it should at all in this turn. This should be close to optimal solution with currently available units but performance limits should be taken into account.
Good solution would be that village grabbing value could be calculated with attack ratings and if some village has high value it would make unit go for that village instead

This should help AI in begin of scenario. Currently AI might not grab all of villages that belong to its area which results quite large incoming loses.
In later game enemy might have large number of units in one part of map so village grabbing should be avoided in that are. Single unit would be easy pray for enemy so moving there would result just to loses.

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Config memory optimisation ===

Right now, most of the memory used by wesnoth when using '''low_memory''' configuration flag is used by the config object trees. It would be possible to drop unused "branches" of that trees by using boost smart pointers in the config structure

come and discuss that change on #wesnoth-dev. Sirp is the one that knows the most about that...

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063] (cjhopman has submitted a patch on that already)

=== Make the lua state persistent ===

Wesnoth is designed to make all data files as simple and human-readable as possible, including savefiles. WML is designed so that it is always very easy to write the entire WML state as plaintext and reload it correctly. There are many benefits of this, but especially

* It makes it easy for beginners / students to read the files and see what's going on
* It makes it easy for us to debug problems without needing special tools to read the savefiles
* It makes it easy to edit save files to work around any possible bugs. Users have even reported opening savefiles from version 1.10 in microsoft word (!) to correct minor bugs in mp and resaving them, as a policy for tournament games.

This was unfortunately somewhat lost when we added lua. If you use lua in your scenarios, things become more complicated because we can't save the lua state at all. If you rely on lua variables to save information, then when your scenario is saved and reloaded those variables will get wiped. The wesnoth engine provides places for lua to hook into "onsave" and "onload" so that the scenario developer can write their own serialization routines, but this is just punting the problem to scenario developers.

We also provide the "preload" event type specifically to work around the issue -- unlike all other events, preload is called exactly once for every time the scenario is loaded. The purpose is to give another way that lua users can initialize a table of lua functions used by their addon and guarantee that this happens before the functions are called. But to non-lua users this event is basically unsafe for normal use otherwise -- if there is a preload event which e.g. increments a WML variable, then the WML state now depends on how many times the scenario is saved or reloaded. In a normal scenario, save / reload events should be invisible, and normally if this isn't the case it indicates a bug similar to an OOS.

A nice solution to this would be if we properly serialized the lua state alongside the WML in a savefile. The most suitable solution is probably this library: https://github.com/fnuecke/eris
It would require significant additional work as well to find a good way to serialize the C functions that we expose to lua, and the userdata like units held by lua.

== See Also ==

=== Frequently Proposed Good Ideas ===

Check the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=9054&start=0&st=0&sk=t&sd=a B.W.H. list] in the Ideas Forum. Be aware that some entries there are old and have already been implemented, so you will need to investigate that before beginning work.

[[Category:Development]]
[[Category:Future]]

EasyCoding

2014-12-09T02:32:26Z

Iceiceice: /* GUI related features */

== Foreword ==

'''We are permanently updating this page. Parts marked by <s>strikeout</s> will likely be deleted shortly.

This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]]

If none of these are to your liking, feel free to check our [http://gna.org/bugs/?group=wesnoth bug tracker] with a broad spectrum of tasks.

== Engine related features ==

=== <s> Make a context menu option for command mode </s> ===

Make an alternate pathway to the command mode, normally activated with `:`. Some players have trouble getting used to this, a right click menu option may be easier for them.

See forum discussion here: http://forums.wesnoth.org/viewtopic.php?f=12&t=40300

Zappaman - 10/07/2014

=== <s> Make a preference to disable the "automatic moves" at the beginning of a turn </s> ===

There is already an option in the loadgame dialog to cancel all "planned" actions before loading your turn in SP. However it would also be nice esp. for MP to have a preference that would disable this behavior entirely, as for some players it can be quite frustrating.

See feature request here: https://gna.org/bugs/?9906
https://gna.org/bugs/?17195

Thanks to LovCAPONE for this.

=== <s> Make a "play single move" button in the replay viewer </s> ===

This is an often requested feature. The idea is to have a third `play` button which plays until a move or attack command appears, then stops again.

https://gna.org/bugs/?9354

Thanks to Zappaman for this.

=== Make a "map diff" tool to visualizes changes between two version of a map ===

Maintainers of maps often make small tweaks for balance purposes. For someone who doesn't know the map like the back of their hand it may be very difficult to spot exactly what changed. There isn't any really good way to do this right now -- using the 'diff' tool at command line doesn't give good results for .map files.

Such a tool would be helpful for someone who maintains a map pool containing maps made by others, also for someone who wants to browse a repository and examine balance changes on several maps, which could be instructive for someone who wants to make and balance their own maps.

There's any number of ways to actually do this, one might be to have a feature in the map editor that takes the name of another map and adds map labels to indicate what hexes changed. It could also be a command accessible in debug mode when playing the game, or it could be an additional command-line argument (--diff [map1] [map2] ?) for the game. (It could be a standalone application but that's probably going to end up with much more work for you.)

=== Make a GUI method to activate loggers ===

One of the tricks of the trade of wml programming is that you can turn on many helpful loggers to assist sometimes. For instance, there are many pitfalls related to carryover / transitioning scenarios that don't really generate sensible error messages, or give you a good idea of where to look to fix it. However, turning on ''--log-debug=engine/team_construction'' can provide you with the info that you need.

Unfortunately, this requires you to pass command-line arguments to the program, and is really most comfortable for linux users. For mac / windows it is of course possible but many users will end up modifying a shortcut to achieve this, if they even know how to do it, and it's fairly awkward.

It would be nice if we had a page of checkboxes or radiobuttons that could be reached from the main page, or from preferences, that could enable / disable the loggers for various channels, this would make it alot easier for the typical user to take advantage of the logger output.

== MP related features ==

=== Add possibility to switch off dependency checking ===
MP add-ons can define dependencies. Currently there's no way to force a "broken" configuration, although overzealous use of the system by UMC authors could make this feature useful. Add an option to the MP game creation screen to switch on/off dependency checking. Ask lipk (forum)/lipkab (IRC).

=== Make a header for the add-on when we organize scenarios by add-on in the mp create dialog ===

Using an established gui technique to signal when one block of scenarios for an add-on ends and the next begins would make it much easier to use this dialog, if the user has several add-ons.

See one proposal here:
https://gna.org/bugs/?21653

=== Make it possible to host a game which only registered players are allowed to join ===

See feature request here:
https://gna.org/bugs/?14138

=== Timer Pause Button ===

Longstanding feature request here:
https://gna.org/bugs/?16733

Request is for either a button, or a simple chat command like :pause, :unpause, to allow players to put the timer on hold if they are interrupted.

Ideally would be accompanied with a multiplayer-only scenario attribute "number_of_pauses" which decreases each time a client pauses the game. Pause should use a blindfold object to black out the screen, and send a chat message automatically when it occurs / resume occurs. For an example of how it might look, start a local hotseat mp game and enable the Preferences->General->Turn Dialog option. (This behavior introduced in this commit: https://github.com/wesnoth/wesnoth/commit/bab03d554bea92f1ce6f585ef1123202173a3491)

Wintermute also has other ideas about how the timer should / could work. For example, instead of their client ending their turn, the networked opponents could be required to "confirm" the time out. (This is probably a networked mp-only idea.)

A very fancy implementation might instead of a counter, allow the other players to vote on whether a pause request is granted.

Make sure that the paused client still responds to network commands, so that it is possible to kick a person who pauses and then doesn't ever unpause.

=== Add a "concede" button ===

Often times in mp, players concede the game before their leader is actually killed. When the game ends 'officially' the map is revealed, which can sometimes be instructive for the losing player. Additionally, it makes it easier to analyze the results of many games, for purposes of balancing, or for maintaining a ladder. So while it may seem small, this would actually be a pretty useful feature.

== WML related features ==

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== <s>Support for leaderless multiplayergames</s> ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

Actually this was solved... will put a reference soon.

=== Support variable village healing, variable poison properties ===

See a feature request here:

https://gna.org/bugs/index.php?20919

Suggested approach -- new read/writeable values in wesnoth.game_config:

http://wiki.wesnoth.org/LuaWML:Misc#wesnoth.game_config

=== <s> Support shuffled music playlist </s> ===

https://gna.org/bugs/?19653

Zappaman - 20/07/2014

=== Support variable recall cost in wml ===
see https://gna.org/bugs/?16538

the syntax needs to be discussed and refined, but the overall idea is good

make sure to update whiteboard to handle this correctly

Ask Boucman

Aishiko 5 Mar 2014

=== Support menu items available off turn ===

Add an attribute named something like "available_off_of_turn" to the [set_menu_item] tag, which allows the player to use the menu item at any time in an mp game. The action should contain only things like messages, if the scenario coder doesn't respect that then OOS is a reasonable outcome.

The main purpose of this is to allow players of umc scenarios to look at wml-defined info screens even when it's not their turn, which they currently can't do.

=== Allow umc to query the viewing player ===

Many theme / status items, for instance the gold and the countdown timer, display differently depending on whether the current player is also the viewing player. Using wesnoth.current we can determine the current player in lua, but we apparently can't determine the viewing player. Even though such info is not consistent across clients (and therefore can cause OOS if misused), it is useful for purposes of themes and status items.

=== Enhancements to Existing Actions ===

*[fire_event] id=X - allow firing an event by id instead of by name
*[allow_undo] {contents} - perform {contents} when move is undone.
''[allow_undo] will probably need a method to re-fire the event on redo.''

=== Events Manipulation ===

*[event] persistent="yes" - creates an event that lasts for the rest of the campaign
* [disable_event][/disable_event] disables the event within which it appears (useful with conditionals). A more complex take on first_time_only=yes/no.
''This is largely possible with event IDs, but could be useful when multiple copies of an event should be floating around''

=== Game Information ===

*[query_location] - queries a location from the user
**variable
**[filter_location]
''Regarding [query_location]: probably a better name would be choose_location. This is used when a wml event is running and needs to get a target location hex from the user. For example, you right click on a catapult unit and choose the menu item "fire Catapult." Now a [message] says to click on any target within 5 hexes. Now [choose_location] is encountered and the mouse cursor changes to a target sign (possibly customizable). If the user's mouse drifts outside of the allowed locations it changes to a cancel icon. If the operation is cancelled then the variable is cleared and no location stored. --Sapient''

==== Automatically stored variables ====

*$side_info - auto-stored side information
*$game_info - auto-stored game information
*$map_info - auto-stored map information

== Improvements to AI ==

Note: not all of these might be simple tasks. Talk to Crab or mattsc.

* Add a cost function to the C++ path finding code that takes avoided hexes into account, that is, hexes defined in an [ai][avoid] tag onto which the AI never moves. Also add an option to the Lua wesnoth.find_path() function with which using this cost functions can be turned on and off.
**The background behind this task is the way how the default AI's move-to-targets candidate action works. It does path finding for units without taking avoided hexes into account, and ''afterwards'' eliminates moves for which the end point falls onto an avoided hex. As a result, some units might not move at all, even if it is, in principle, easily possible to move around an avoided area. The inclusion of the new path-finding in the AI's move-to-targets phase could therefore be a follow-up task.

* Make the (old) simple aspect syntax work when the Lua engine is defined for a side. Setting aspects in the [side] tag like this:
[ai]
aggression=0.123
[/ai]
does not work if the Lua engine is defined. You either need to use the [aspect] tag in the [side] tag with 'engine=lua', or use the code above in a [modify_side] tag in an event. Making the above syntax available (as it is with the c++ engine) would be nice. The same also applies to the FAI engine and to aspects set for AI sides in MP games.

* Add a Lua function ai.get_individual_attacks() that returns all the single attacks the side can do (as opposed to attack combinations). This needs to include an option to recalculate and take the current situation on the map into account (making the function believe that the game state has changed).

* Set up an option the allows us to exclude units from the move-to-targets phase similar to [filter_own] for the combat phase (other than setting ai_special=guardian, which has a number of other side effects). Actually, having this option for all CA's would be nice.

* Change the aspects "passive_leader", "passive_leader_shares_keep", "leader_ignores_keep" to work with multiple leaders. The idea is to change the type of those aspects from yes/no to string so both "passive_leader=yes" and "passive_leader=leader_id_1,leader_id_2" is possible.

* ai.get_new_enemy_dst_src and related functions have several problems:
** They use the current moves of the enemy units, which generally are all zero.
** Hexes occupied by other enemy units count as not reachable.
**Units with zero moves are not listed at all, not even for the hex they are on.
**Working around this with a Lua wrapper makes this actually slower than ai_helper.get_enemy_dst_src, which makes the functions pretty much useless, as speed is the only thing speaking for them.

* Add new options (keys or tags) to the Micro AIs. As an example, some (but certainly not all) Micro AIs might benefit from taking some (but certainly not all) of the default AI aspects into account.

* Write a script that automatically changes WML from the deprecated [ai][target] to the new [ai][goal] syntax. Ideally, this would be part of wmllint.
** There are [http://wiki.wesnoth.org/AiWML#Deprecated_AI_Targeting_Aspects more deprecated AI aspect] which should eventually be added to this, but the [target] -> [goal] change would be a good and important start.

== GUI related features ==

Although Mordante developed the new GUI system GUI2, some dialogs still use the older GUI1 and could be improved or transferred. You should contact Mordante on IRC before starting to work on these.

=== Theme Changes ===

* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud) a GUI2 lobby is currently being developed, ask mordante whether this is still relevant
* input history (chat, commands, ..)

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

=== Port the random map generator dialog to GUI2 ===
The map generator currently doesn't use the GUI2 framework, but there's no reason why it couldn't. Ask lipk (forum)/lipkab (IRC).

== Miscellaneous ==

=== <s>More powerful village naming</s> ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow more powerful names to be generated.
Understanding how it works should be quite easy, and a few useful improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first syllabus" and "last syllabus" for naming. That's not really needed in English, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

Turns out this was already done, and should be removed.

=== Use friends list as a fallback for tab completion ===

Currently wesnoth will use the list of current players, lobby members, as candidates for tab completion of names when whispering. The OP requests that the friends list also be merged in, in case one of your friends whispered you. Even better, could also remember names of anyone who whispered you in the last hour.

https://gna.org/bugs/?9742

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== wesnoth-optipng ===
For lossless png compression we use wesnoth-optipng, a script using an external toolchain (ImageMagick, OptiPNG, Advdef). Perhaps the performance could be improved by using PNGOut instead of advdef. This task includes
* a quick profiling of compression ratio and decompression speed for both tools
* if it provides a higher compression while not significantly slowing down decompression, adapt wesnoth-optipng to use PNGOut

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

CodingStandards

2014-12-07T00:03:05Z

Iceiceice: /* Write exception-safe code */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

In C++11, any destructor which throws an exception causes the program to be immediately terminated.

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

Similarly, avoid writing <tt>delete</tt> explicitly in your code. Oftentimes using a smart pointer or similar instead will improve the readability of your code, by making it obvious that you are managing memory correctly even if an exception is thrown. If you were deleting a pointer which is a member variable of an object, using a smart pointer instead may simplify your code by eliminating the need to write an explicit destructor in some cases.

For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

CodingStandards

2014-12-06T23:22:52Z

Iceiceice: /* Write exception-safe code */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

In C++11, any destructor which throws an exception causes the program to be immediately terminated.

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

Similarly, avoid writing <tt>delete</tt> explicitly in your code. Oftentimes using a smart pointer or similar instead will improve the readability of your code, by making it obvious that you are managing memory correctly even if an exception is thrown. If you were deleting a pointer which is a member variable of an object, using a smart pointer instead may simplify your code by eliminating the need to write an explicit destructor in some cases.

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

CodingStandards

2014-12-05T02:36:17Z

Iceiceice: /* Destructors must not throw exceptions */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

In C++11, any destructor which throws an exception causes the program to be immediately terminated.

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

CodingStandards

2014-12-05T02:00:07Z

Iceiceice: /* Destructors must not throw exceptions */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes. In C++11, any destructor which throws an exception causes the program to be immediately terminated.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

CodingStandards

2014-12-05T01:58:23Z

Iceiceice: /* Destructors must not throw exceptions */

Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.

== C++ version ==

Wesnoth uses C++ conforming to C++98/03. At the moment C++11 compiler support is still not widely available, therefore C++11 is not allowed.

== Formatting ==

When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.

You may use long lines.

== Evil things to avoid ==

=== Avoid implicit conversions ===

Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.

Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:

t_string(const std::string&);

This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).

=== Do not declare class data members as non-private ===

It's okay to have a ''struct'' with only public members, if that's what you want.

However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.

=== Destructors must not throw exceptions ===

Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.

It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.

You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor

== Naming ==

=== End non-public class data members with an underscore ===

All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.

== Idioms ==

=== Use references when a value may not be NULL ===

If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:

void my_function(T& obj);

rather than

void my_function(T* obj);

This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.

=== Use the const keyword ===

The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects.
Always use <tt>const</tt> when you are not going to modify an object. For example:

void my_function(const T& obj);

This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:

void my_function(T& obj);

Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.

=== Know the behavior of const references when types differ ===

If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So

char c = 0;
const int& i = c;
c = 5;

will result in c == 5 and i == 0, which may not be what you expect.

=== Write exception-safe code ===

Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).

Code that uses a pattern like the following is bad:

{
SDL_Surface* image = IMG_Load("image.bmp");
...some code, which uses 'image'...
SDL_FreeSurface(image);
}

The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.

For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:

{
surface image(IMG_Load("image.bmp"));
...some code, which uses 'image'...
} ''the image is automatically freed here when 'image' is destroyed

Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.

=== Do not use sprintf ===

The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.

== Standard C++ to avoid ==

=== Do not use wstring ===

The standard C++ <tt>std::wstring</tt> class (defined as a <tt>std::basic_string< wchar_t ></tt>) does not exist in some platforms supported by Wesnoth. Use <tt>wide_string</tt> instead (defined in <tt>language.hpp</tt>). The <tt>wide_string</tt> type is actually defined as <tt>std::vector< wchar_t ></tt>.

You may use std::wstring in an #if that guarantees that wstring is supported on all supported plattforms that don't get filtered out by the #if.

=== Do not use 0 when you mean NULL ===

Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.

== C legacy to be avoided ==

=== Use util::array instead of C-style Arrays ===

C-style arrays are very efficient, but their interface is ugly. Use <tt>util::array</tt> defined in <tt>array.hpp</tt> instead. It is a wrapper for an array which has a C++ container-style interface. If you need to, extend it to make it fit your needs.

=== Do not use C-style casts ===

The following code,

if(i->second.side() == (size_t)player_number_) {

is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).

Good programming style is to use the least powerful tool available that does what you want. For example:

if(i->second.side() == static_cast<size_t>(player_number_)) {

Alternatively, a constructor call may be used for non-built-in types.

''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''

=== Do not use #define for constants ===

<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.

namespace {
const T foo = X;
}

== Documentation ==

=== Document config preconditions and postconditions ===

In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.

Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.

=== Doxygen ===

See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.

== See also ==

* [[HackingWesnoth]]

[[Category:Development]]

LuaWML/Display

2014-12-05T00:25:56Z

Iceiceice: /* wesnoth.theme_items */

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_time_of_day ====

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units and terrain (such as Mages of Light or lava) are taken into account (if the passed hex happens to be affected). The units' placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

The optional first parameter does not work if there is no turn limit in 1.11.0 and earlier.

==== wesnoth.select_hex ====

Selects the given location in the game map as if the player would have clicked onto it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false)

wesnoth.select_hex(14,6, true, true)

==== wesnoth.scroll_to_tile ====

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter {{DevFeature1.11}}, the view instantly warps to the location regardless of the scroll speed setting in Preferences.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

{{DevFeature1.11}} Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

{{DevFeature1.11}} Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_markup ====

{{DevFeature1.11|9}}

Sets the flag associated to a widget to enable or disable Pango markup. The new flag value is passed as the first argument (boolean), and the widget to modify is obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). Most widgets start with Pango markup disabled unless this function is used to set their flag to true.

wesnoth.set_dialog_markup(true, "notice_label")
wesnoth.set_dialog_value("<big>NOTICE!</big>", "notice_label")

==== wesnoth.set_dialog_canvas ====

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.get_displayed_unit ====

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

The following is a list of valid entries in wesnoth.theme_items which will have an effect in the game. Unfortunately when this feature was created the full range of capabilities of the feature was never properly documented. The following list is automatically generated. To find out what each entry will do, you will have to make guesses and experiment, or read the source code at src/reports.cpp. If you find out what an entry does, you are more than welcome to edit the wiki and give a proper description to any of these fields.

* '''unit_name'''
* '''selected_unit_name'''
* '''unit_type'''
* '''selected_unit_type'''
* '''unit_race'''
* '''selected_unit_race'''
* '''unit_side'''
* '''selected_unit_side'''
* '''unit_level'''
* '''selected_unit_level'''
* '''unit_amla'''
* '''unit_traits'''
* '''selected_unit_traits'''
* '''unit_status'''
* '''selected_unit_status'''
* '''unit_alignment'''
* '''selected_unit_alignment'''
* '''unit_abilities'''
* '''selected_unit_abilities'''
* '''unit_hp'''
* '''selected_unit_hp'''
* '''unit_xp'''
* '''selected_unit_xp'''
* '''unit_advancement_options'''
* '''selected_unit_advancement_options'''
* '''unit_defense'''
* '''selected_unit_defense'''
* '''unit_vision'''
* '''selected_unit_vision'''
* '''unit_moves'''
* '''selected_unit_moves'''
* '''unit_weapons'''
* '''highlighted_unit_weapons'''
* '''selected_unit_weapons'''
* '''unit_image'''
* '''selected_unit_image'''
* '''selected_unit_profile'''
* '''unit_profile'''
* '''tod_stats'''
* '''time_of_day'''
* '''unit_box'''
* '''turn'''
* '''gold'''
* '''villages'''
* '''num_units'''
* '''upkeep'''
* '''expenses'''
* '''income'''
* '''terrain_info'''
* '''terrain'''
* '''zoom_level'''
* '''position'''
* '''side_playing'''
* '''observers'''
* '''selected_terrain'''
* '''edit_left_button_function'''
* '''report_clock'''
* '''report_countdown'''

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

LuaWML/Display

2014-12-05T00:17:17Z

Iceiceice: /* wesnoth.theme_items */

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_time_of_day ====

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units and terrain (such as Mages of Light or lava) are taken into account (if the passed hex happens to be affected). The units' placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

The optional first parameter does not work if there is no turn limit in 1.11.0 and earlier.

==== wesnoth.select_hex ====

Selects the given location in the game map as if the player would have clicked onto it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false)

wesnoth.select_hex(14,6, true, true)

==== wesnoth.scroll_to_tile ====

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter {{DevFeature1.11}}, the view instantly warps to the location regardless of the scroll speed setting in Preferences.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

{{DevFeature1.11}} Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

{{DevFeature1.11}} Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_markup ====

{{DevFeature1.11|9}}

Sets the flag associated to a widget to enable or disable Pango markup. The new flag value is passed as the first argument (boolean), and the widget to modify is obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). Most widgets start with Pango markup disabled unless this function is used to set their flag to true.

wesnoth.set_dialog_markup(true, "notice_label")
wesnoth.set_dialog_value("<big>NOTICE!</big>", "notice_label")

==== wesnoth.set_dialog_canvas ====

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.get_displayed_unit ====

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

The following is a list of valid entries in wesnoth.theme_items which will have an effect in the game. Unfortunately when this feature was created the full range of capabilities of the feature was never properly documented. The following list is automatically generated. To find out what each entry will do, you will have to make guesses and experiment, or read the source code at src/reports.cpp

* '''unit_name'''
* '''selected_unit_name'''
* '''unit_type'''
* '''selected_unit_type'''
* '''unit_race'''
* '''selected_unit_race'''
* '''unit_side'''
* '''selected_unit_side'''
* '''unit_level'''
* '''selected_unit_level'''
* '''unit_amla'''
* '''unit_traits'''
* '''selected_unit_traits'''
* '''unit_status'''
* '''selected_unit_status'''
* '''unit_alignment'''
* '''selected_unit_alignment'''
* '''unit_abilities'''
* '''selected_unit_abilities'''
* '''unit_hp'''
* '''selected_unit_hp'''
* '''unit_xp'''
* '''selected_unit_xp'''
* '''unit_advancement_options'''
* '''selected_unit_advancement_options'''
* '''unit_defense'''
* '''selected_unit_defense'''
* '''unit_vision'''
* '''selected_unit_vision'''
* '''unit_moves'''
* '''selected_unit_moves'''
* '''unit_weapons'''
* '''highlighted_unit_weapons'''
* '''selected_unit_weapons'''
* '''unit_image'''
* '''selected_unit_image'''
* '''selected_unit_profile'''
* '''unit_profile'''
* '''tod_stats'''
* '''time_of_day'''
* '''unit_box'''
* '''turn'''
* '''gold'''
* '''villages'''
* '''num_units'''
* '''upkeep'''
* '''expenses'''
* '''income'''
* '''terrain_info'''
* '''terrain'''
* '''zoom_level'''
* '''position'''
* '''side_playing'''
* '''observers'''
* '''selected_terrain'''
* '''edit_left_button_function'''
* '''report_clock'''
* '''report_countdown'''

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

NotSoEasyCoding

2014-12-02T00:31:07Z

Iceiceice: remove stuff about random map generation, since the lua map generation is finished now

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Game Engine ==
=== add a mode to improve OOS detection in MP ===
We really need an optional 'pedantic mode' for MP which detects OOSes immediately, by comparing all game state information after each action and printing any mismatches. This mode will be optional because of the extra overhead it adds, and it would be very useful for debugging.

=== <s>Fix a longstanding bug concerning failure to initialize a side in networked mp</s> ===

(Actually we may have a fix for this now... will post reference)

https://gna.org/bugs/index.php?21397

The problem itself is quite simple -- when the server tells a client that their turn has begun, the client immediately broadcasts [init_side] to all the other players via the server, performing the initial upkeep, healing, and movement point reset actions. However, if this player disconnects / blocks the action by opening a dialog during the prior turn and never closing it, [init_side] is never broadcast. And if the game is then saved by one of the other clients, nothing in the current mechanism detects that this has been overlooked when the game is reloaded. The consequence is that in the reloaded game, that side's turn is *never* initialized -- they get no gold, their units don't heal, and they don't get full move points at the start of the turn.

Propose a mechanism to fix this -- perhaps games which have been loaded should be scanned to see if the current turn failed to initialize. Perhaps a flag in game_state could be used and saved. Perhaps a completely different approach. Check that your mechanism works whether the save is loaded from [snapshot] or [replay_start] and [replay].

This bug has existed since at least Wesnoth 1.8

=== <s>Make a "replay actions since my last turn" button</s> ===

It would be very convenient if there an ability to replay everything your opponents just did at the
start of your turn, since sometimes things go out of vision or are confusing.

The feature would be like a "replay since my last turn" menu option or button -- most likely, the best approach to implement it is to store a copy of the game_state object in playcontroller.cpp or even in resources, and to refactor the backlog object so that we can hold a "bookmark", i.e. a pointer, to the last position in the replay that we might look to jump back to. The replay process would work by swapping out for the old gamestate, then replaying through the actions since the bookmark until we get back up to speed. The difficult part would be making sure that scenarios with scripted WML events don't break when we do this. For debugging purposes, it might be good to check that at this point we have the same gamestate we did before we clicked the button. The bookmark should only be advanced when we end our turn, and there might be perhaps need to be multiple bookmarks, one for each side, to handle what happens when a side disconnects or is reassigned.

It would be especially helpful for MP play to have this, where special tactics with ambush units are quite common. Part of the design criteria of wesnoth is that it should be a high-level, thoughtful turn based strategy game, but you should be able to play asynchronously and not necessarily give attention to the game until your turn bell rings if you don't want to. Having ambush units and no ability to replay their movements during the opponents turn harms that goal.

For MP play, it will require special attention to make sure that events like "synchronize_choice" are handled correctly so as not to cause out of sync errors, and also that the timer is handled correctly.

Feature request: https://gna.org/bugs/?15334

Thanks to Zappaman for this. https://github.com/wesnoth/wesnoth/pull/270

=== Improve WML error reporting ===

There are many programming bugs that give very unclear or cryptic error messages when using WML. Here are some examples:

-- When calling a macro with the wrong number of arguments, wesnoth tells the number it expected, and the number it got, and at which line number it was instantiated. However, it would be helpful if it would also tell the line number of the definition of the macro. This might be helpful if someone is redefining macros.

-- For places where a standard unit filter is expected, if one is not found, the game should point out a problem. For places where such a filter is expected but [filter] child should not appear, if one does it should report an error and a line number. Many users have a hard time with this kind of thing.

-- When doing scenario transitions in a campaign, if the side definitions don't matchup exactly the game tends to give unintelligible error messages. For instance, if one is transitioning and there is an AI side which does not have a leader (but it has a starting location in the map) it must have "no_leader = yes" in its [side] tag, or else when the team_builder objects enter stage two, the game will try to create a unit with an empty type, and the constructor of class unit will fail giving the error message "game::game_error tried to create unit with empty type". This really needs to be much better. For instance, giving a line number of a problem, or suggesting that no_leader should be used. (Note that, it is often possible to debug problems like this by turning on --log-debug=team_construction at commandline but I doubt that there are any users that know about this, you would only learn from reading the C++... without such debug info, fixing things like this can literally take hours.) For that matter it's some question why the team_builder doesn't just stop trying to build a unit when it sees it doesn't have enough info...

-- Recursive macros break the game, and not by stack overflow but by exhausting the heap. It would be nice if we could catch this and report an error.

Many of the users of WML are students or beginners to programming, it is a big help to them to improve the error reporting of this nature -- not to mention that many veterans would appreciate as well. In part we need fixits here and there but more broadly we need a smarter system that can figure out what's really wrong when things go wrong and give helpful suggestions.

=== Map label "groups" which can be selectively turned on and off by the user ===

It would be nice if the user could have more control over how map labels are displayed, for instance to be able to check on / off labels made by certain players, and for custom scenarios, to be able to make custom classes which the use can turn on or off. This might be helpful for custom scenarios esp. which might have some technical info they want to show, but which it might be messy to display all of the time. The hard part of this is that there should ideally be a gui to work with the map labels, although maybe this need could be worked around or simplified somehow.

=== Add a new damage stats calculation mode to support scenarios with extremely high stats ===

Most players use the damage calculation window constantly when they play so that they can see what to expect from various attacks. The way the game is currently set up, when a unit is selected, as soon as another unit is moused over the stats for an attack will be calculated, whether or not the user actually brings up the window.

The probabilities for the various outcomes are calculated by explicitly calculating the distribution of attacker and defender hp / slowed status after each swing by either party, one swing at a time. Thus at the end we get exact probabilities of the possible outcomes.

However, this comes at a cost -- the running time of the calculation can in the worst case be something like O( attacker_hp * defender_hp * total_number_of_strikes). In default era wesnoth (and in much of UMC) this is fine because units don't get extremely high hp values. However in some UMC units do get extremely high hp, and many will also have specials like drain and berzerk, and may have many different weapons as well. At some point these scenarios become unplayable even on a machine of moderate specs because mousing over any unit causes > 10 seconds of lag during which the game becomes unresponsive, trying to calculate attack outcomes.

In these cases, it would be better to give an "inexact" damage prediction, based on just simulating a few thousand attacks and plotting the results. Since it's a monte carlo algorithm rather than an exact algorithm, there will be some error, but if it makes the game playable then it's clearly an improvement, and anyways for "extreme stats" battles with high strikes and damage, the outcome is in a sense less random anyways because the outcomes with inordinate amounts of hits and misses are more and more rare (law of large numbers), so the error shouldn't actually be terribly significant.

If there were an advanced preference that caused the predictions to use such an algorithm instead of the current one, so that the user could turn it on if they start to get problems, it would eliminate a significant headache for some UMC.

== MP Related ==

=== Automatically resolve add-on dependencies ===

In 1.11 add-ons may declare dependencies. A related easy coding task is to allow the user to force breaking dependencies.

A related goal which would be greatly beneficial would be that wesnoth can automatically resolve the dependencies by fetching the add-ons from the download server, when in the MP-lobby the user tries to join a game with a dependency they don't meet. A dialog would ideally be provided as well, or perhaps a preference.

https://gna.org/bugs/?21705

Even older: https://gna.org/bugs/?9683

=== Gold graph ===

Make a graph feature, presumably in a dialog, that helps depict the history of the game. For example it could display army value, army + bank value, number of villages tagged, luck swings... the purpose would be to assist spectators of a live game / spectators of a replay to understand the history of the game. It would be particularly helpful with AI development, by helping AI developers to identify key points where one of the AI is making a big mistake.

A possible nice feature for this purpose would be to allow the user to click on the graph at key points which would trigger the "back to turn" mechanism to jump back in the replay, or automatically play the replay forwards from the beginning to that point... etc.

Related email on dev-talk: https://mail.gna.org/public/wesnoth-dev/2014-02/msg00089.html

=== Automatically link up to wesnothd server on a local network ===

The feature request was to use ZeroConf technology, if available, to publish info of a running wesnothd instance to other machines on a local network. Then when they are searching to connect to an unofficial server, they won't have to learn the IP address.

The extra code should be guarded with preprocessor flags so that ZeroConf does not become a build dependency of wesnoth.

https://gna.org/bugs/?13703

=== Create a set of "common" mp messages which players can use when they don't share a language ===

Most users speak english, however, wesnoth also has large Polish and Hungarian communities, and many Brazilian players, not all of whom speak english. It would be nice we could have a set of messages that could be chatted, but which will be translated by our translators and displayed always in the current locale on each client, to make it easier to communicate in mp games / on the mp server.

The hard part is that if you don't already know about the gettext translation system, you will have to learn about it. The messages should be stored in a .cfg file in the data folder so that they can be easily modified and can be handled in the same way that other in-game text is translated -- they should perhaps go in their own gettext-domain however. Ideally there would be a gui dialog of some kind to select from them.

=== Improve server wml processing ===

The wesver uses an alternative implementation to store and process wml objects see http://wiki.wesnoth.org/WesnothdDesign#simple_wml. This is for performance. However, the simple_wml sometimes messes up translation for mp scenarios / campaigns, resulting in mp scenarios/campaigns beeing untranslated for non-hosts in networked mp (http://gna.org/bugs/?22989). Fixing this is not easy becasue of the performance requirements.

== Improvements to AI ==
=== Move and targeting phase ===
AI needs to move units which are not within range of the enemy. This is generally a sequence of moves (some interesting things like 'ambush!' or 'WML event' might happen as a result of those moves, which should interrupt this phase). The problem is that simply doing those moves 1-by-1 is very slow, for two reasons:

#movement maps are invalidated after each move, and are recalculated from the start. yet, if we are doing just a sequence of moves, we can just 'remove moved unit from moves' after each move and avoid expensive recalculation of the movement map.
#* Note that WML could mess with the game state at any time, so at the very least, movement will need to be recalculated after a WML event blocks undo (that is, indicates that it changed game state). --[[User:Brilliand|Brilliand]] 01:30, 28 May 2012 (UTC)
#most tasks need devoting more than one unit to execute (i.e., it's meaningless to go for the enemy position with just 1 unit). So, making individual decisions just does some repeating calculations, which is slow.

A practical demonstration of these concerns are LoW 2 (dwarf ai is slow due to large avoid aspect) and NR:Showdown (orc AIs there are slow because of huge number of units)

we need a fast and effective 'move and targeting stage' - both ideas and implementations are wanted.
Here's Sirp's idea (more in 2009-aug-15 irclog):

--

=== Eval-based AI ===
The AI system would be based around an 'eval' function -- a formula which is given a position, and returns a number saying how attractive that position is.

There would also be a 'candidate_moves' function -- a formula which is given a unit and returns a list of 'candidate moves' -- i.e. moves for that unit that the AI should consider making.

The aim of the system is to come up with the combination of candidate moves that gives the best possible evaluation. By doing this, the AI will work in a team, since the 'eval' function can give bonuses for units being close together, protecting each other, etc.

There are likely to be, of course, a very large combination of possible moves, and not every one can possibly be evaluated. Instead, we take a monte carlo approach.

If an AI has N units that it can move, that is an N-dimension matrix of possible moves. We would choose some cells in this matrix at random and then evaluate them. Then, of these cells evaluated we would choose cells that evaluated well, and discard those that did not evaluate well. Then, we would begin with those cells that evaluated well, and choose a scattering of 'close by' cells -- i.e. cells where we only vary some of the dimensions, at random. We would continue to evaluate cells at random, starting with those cells that evaluated well, and evaluating cells nearby. After several iterations, we would hope to arrive at a cell that evaluates very well, and we would use this as our set of moves.

Of course, this system will be made more complex by the uncertainty of attacks. There are a number of ways to handle attacks, probably the easiest being to consider attacks as types of moves, and then if a move combination involving an attack is chosen, perform the attack and then re-run the entire AI algorithm before moving again. (Something similar to what the current AI does).

This is effectively an AI framework, not an AI in itself. How well it performs will correlate strongly with how good an eval() function one can write, and is also based on the notion that generally certain combinations of moves are 'similar' to other combinations.

--

=== Village grabbing ===

Improve AI village grabbing algorithm to assign villages that are farther than one turn from current unit location.
Idea how to do would be value villages so that it can filter out villages that belongs to enemies/allies sides. Those villages are stored in memory and used in 2nd pass that determines how AI should dispatch units to get villages if it should at all in this turn. This should be close to optimal solution with currently available units but performance limits should be taken into account.
Good solution would be that village grabbing value could be calculated with attack ratings and if some village has high value it would make unit go for that village instead

This should help AI in begin of scenario. Currently AI might not grab all of villages that belong to its area which results quite large incoming loses.
In later game enemy might have large number of units in one part of map so village grabbing should be avoided in that are. Single unit would be easy pray for enemy so moving there would result just to loses.

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Config memory optimisation ===

Right now, most of the memory used by wesnoth when using '''low_memory''' configuration flag is used by the config object trees. It would be possible to drop unused "branches" of that trees by using boost smart pointers in the config structure

come and discuss that change on #wesnoth-dev. Sirp is the one that knows the most about that...

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063] (cjhopman has submitted a patch on that already)

== See Also ==

=== Frequently Proposed Good Ideas ===

Check the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=9054&start=0&st=0&sk=t&sd=a B.W.H. list] in the Ideas Forum. Be aware that some entries there are old and have already been implemented, so you will need to investigate that before beginning work.

[[Category:Development]]
[[Category:Future]]

Download

2014-11-09T21:09:38Z

Iceiceice:

{{Download/Translations}}
Welcome to the ''Battle for Wesnoth'' downloads page. The BfW project team officially releases the source code and builds for Windows, OS X, OpenPandora, and various Linux distros. Torrents are unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F|FAQ]].

Wesnoth is also available for OS X from [http://brew.sh/ Homebrew] and [http://www.macports.org/ Macports]. Macports carries only the stable version. Homebrew carries stable release, development release, and can also build the "bleeding edge" master branch.

__NOTOC__
== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{StableDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{DevDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]''

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==

This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x). Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2014-11-09T21:07:11Z

Iceiceice:

{{Download/Translations}}
Welcome to the ''Battle for Wesnoth'' downloads page. The BfW project team officially releases the source code and builds for Windows, OS X, OpenPandora, and various Linux distros. Torrents are unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F|FAQ]].

Wesnoth is also available for OS X from [[http://brew.sh|Homebrew]] and [[https://www.macports.org/|Macports]]. Macports carries only the stable version. Homebrew carries stable release, development release, and can also build the "bleeding edge" master branch.

__NOTOC__
== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{StableDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{DevDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]''

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==

This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x). Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2014-11-09T20:43:11Z

Iceiceice:

{{Download/Translations}}
Welcome to the ''Battle for Wesnoth'' downloads page. The BfW project team officially releases the source code and builds for Windows, OS X, OpenPandora, and various Linux distros. Torrents are unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS_X.2C_etc..5D.3F|FAQ]].
__NOTOC__
== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{StableDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code
{{DevDownload}}

==== GNU/Linux ====
* There are binaries for many different GNU/Linux distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your distribution.

==== Miscellaneous ====
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]''

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==

This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x). Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

MapGeneratorWML

2014-11-09T03:38:38Z

Iceiceice:

Map Generator WML is used to create scenarios which are randomly generated. Of course, any scenario may reconfigure itself during a start / prestart event as much as it likes, using randomness, but the Map Generator WML has the following advantages:

* Wesnoth has several built-in map generators which can be configured with options, and these are much better developed than any existing pure WML options.
* Map generation occurs before the scenario is even loaded, something which is not possible for WML events. In an mp game, the map generator code will run only on the host, side-stepping any synchronization issues, and keeping your scenario code as simple as possible.
* For scenarios with "allow_new_game=yes" and which use map generators, the generator may be reconfigured in the mp create screen (assuming that someone has coded a dialog for it). The user can also select to regenerate the map and get instant feedback from the minimap display.

== Scenario vs map generation ==

Every map generator can be used in either '''scenario_generation''' mode or '''map_generation''' mode. In map_generation mode, the generator is only used to replace the map_data of your scenario. In scenario_generation mode, the entire [scenario] tag is replaced.

To select a map generator and mode, in your [scenario] tag you must place '''one of'''
* '''scenario_generation=algorithm'''
* '''map_generation=algorithm'''
where '''algorithm''' is the generator algorithm you want to use. Note that not every algorithm is designed to be use with both of these options.

You must additionally place a [generator] tag in your scenario, which contains the options to the map generator.

== [generator] ==

The exact things that should be placed in [generator] depend on what algorithm you pick. There are three kinds of generators, `default`, `cave`, `lua` {DevFeature1.13|0}, and `yamg` {DevFeature1.13|0}.

For which key to use and what value, see the section for the generator you want to use.

===The lua generator===
The lua generator type specifies a custom map generator, which you provide via lua scripts.

The following keys are recognized for '''[generator]''' when the lua generator is used:
* '''create_map''' : A lua routine which returns a string containing the new map_data. The entire contents of the '''[generator]''' are passed to the script in a lua table (see [[LuaWML]]), via the argument '''...''' (see http://www.lua.org/pil/5.2.html).
* '''create_scenario''' : The same, but returning a '''[scenario]''' tag for the new scenario, as a lua table.

Any other keys are used only by the lua script.

The following keys of the output [scenario] are specifically watched by the mp create screen:
* '''id'''
* '''name'''
* '''description'''
* '''error_message'''

====Available Lua API====
The usual in-game API, in the table '''wesnoth''', is not available to lua scripts. However the usual standard lua libs are available, and a random number generator object is available from the Rng table. This is an instance of the Mersenne Twister 19937 random number generator from the C++11 standard.

* '''rng = Rng:create()''' : creates a new rng object
* '''rng:seed()''' : seed an rng, expects a string in hexadecimal format
* '''rng:draw()''' : draw a 32-bit random integer from the rng

===The Default Generator===
The default generator can be used to generate map data for any scenario. The data in this section is inferred from “data/multiplayer/scenarios/Random_Scenario.cfg”, usage in add-on content, and inspection of mapgen.cpp

'''Excerpt from mapgenerator comments:'''

* Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.

To use the default '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:
* '''scenario_generation=default'''
* '''map_generation=default'''
If ‘scenario_generation’ is used, the engine will expect for your entire '''[scenario]''' sub tags to be inside a '''[scenario]''' tag inside '''[generator]'''. Tags outside of this will be ignored. There may be value in this, but at this writing, it’s not clear.
‘map_generation=default’ is simpler and more commonly used. It is also necessary to use this key so that you can regenerate a map in MP game creation.
In its use only generator data is in the '''[generator]''' tag, all other '''[scenario]''' data is placed outside of it. The exception is if you are making an initial MP scenario available in MP game creation, for this a '''[scenario]''' tag must appear inside of '''[generator]''', containing the '''[scenario]''' subtags you want to use. See “data/multiplayer/scenarios/Random_Scenario.cfg” for an example.

The following key/tags are recognized for '''[generator]''' when the default generator is used:
* '''[scenario]''': See [[ScenarioWML]]
* '''name'''
** '''default'''
* '''map_width''','''map_height''': size of the map to generate
* '''iterations''': the number of times an attempt is being made to generate a hill
* '''hill_size''': hills will have a random size between 1 and ''hill_size''
* '''max_lakes''': the number of times an attempt is being made to generate a lake
* '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height
* '''lake_size''': the size of a lake still randomly generated
* '''river_frequency''': determine how much a river can run uphill and thus generate more rivers

* '''villages''': villages per 1,000 hexes
* '''players''': Number of starting locations for the map.
* '''castle_size''': Number of castle tiles (including the keep), per player.
* '''temperature_iterations''': Same as iterations, but for the temperature map.
* '''temperature_size''': Same as hill_size, but for the temperature map. (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)
* '''roads''': number of roads the generator will attempt to make
* '''road_windiness''': Use 1 for the road to be made using the cheapest path (based on [road_cost] tags), higher values introduce randomness to make the road wind a bit.
* '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)
* '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).
* '''[height]''': list of common terrain types that come in at different heights, from highest to lowest. Good WML will have the range of 1000-0 covered.
** '''height''': the terrain specified below will appear at this height and up.
** '''terrain''': 1 terrain code
* '''[convert]''': used to make terrain conversions. For example, water becomes ice at low temperatures, grass snow, etc. If the terrain is between the min_x and max_x it will be converted. If min_x is not defined it will default to a large negative number. If max_x is not defined it will default to a large positive number
** '''min_height'''
** '''max_height'''
** '''min_temperature'''
** '''max_temperature'''
** '''from''': a comma separated terrains to convert from
** '''to''': The terrain to convert these terrains to
* '''[road_cost]'''
** '''terrain''' 1 terrain code
** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road
** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.
** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)
* '''[village]''': The conversion of terrains to villages
** '''terrain''': 1 terrain code which will be converted to a village
** '''convert_to''': 1 terrain code for the village
** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.
** '''rating''': chance of appearing
* '''[castle]''': the conversion of castles
** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.
** '''min_distance''': all castles generated must be this number of hexes apart from each other
* '''[naming]''': The names used to label landscape features (forests, lakes, etc.). This controls, for example, the "Fox" part of "Foxwood". If this tag is empty, those labels should be suppressed. (Due to a bug, they are not suppressed prior to 1.11.1.) The predefined macro VILLAGE_NAMES is one option for the contents of this tag. If that macro is not used, this tag takes one key.
** '''male_names'''
* '''[village_naming]''': The names used to label villages. This controls, for example, the "Fox" part of "Foxham". If this tag is empty, those labels should be suppressed. (Due to a bug, they are not suppressed prior to 1.11.1.) The predefined macro VILLAGE_NAMES is one option for the contents of this tag. If that macro is not used, this tag takes one key.
** '''male_names'''

===The Cave Generator===
The cave generator does not appear to have been written for multiplayer scenario game creation like the default generator was. It is used in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg''' & '''campaigns\Heir_To_The_Throne\scenarios\ 17_Scepter_of_Fire.cfg '''. The data here is inferred from those scenarios and an inspection of cavegen.cpp

To use the cave '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:
* '''scenario_generation=cave'''
* '''map_generation=cave'''
Here it is recommend you use ‘scenario_generation’ as there are examples to follow, though it may be possible to use’ map_generation’.

The following key/tags are recognized for '''[generator]''' when the cave generator is used:
* '''[settings]''': behaves as if '''[scenario]''', See [[ScenarioWML]]
* '''map_width''','''map_height''': size of the map to generate
* '''village_density''': influences number of villages
* '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.
* '''flipy_chance''': Chance to flip y coordinates, that meens the map is mirrored at the horizontal axis in its midth.
* '''[chamber]''': for underground maps
** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.
** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)
** '''size''': circular radius of the chamber, including the center hex
** '''jagged''': a good value is probably between 0-50 (not sure exactly)
** '''chance''': chance for the chamber to be generated, between 0 and 100, 100 if key not present
** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.
** '''[passage]''': defines a pathway between chambers
*** '''destination''': the id key of the destination chamber
*** '''windiness''': a good value is probably between 1-10
*** '''laziness''':
*** '''width''': number of hexes
*** '''jagged''': a good value is probably between 1-10
*** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present

=== YAMG generator ===

*** Please document me! ***

== Infrastructure ==

* The default generator settings are loaded from a scenario file under data/multiplayer/scenarios.
* mapgen_dialog overwrites these values if necessary.
* The create_map / create_scenario function is called by one of the following
** multiplayer_create_engine.cpp:394
** context_manager.cpp:648
** map_create.cpp:56
* A map buffer is written to res["map_data"]
* the config res is passed to the calling function.

== See Also ==

* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

MapGeneratorWML

2014-11-09T03:28:16Z

Iceiceice:

Map Generator WML is used to create scenarios which are randomly generated. Of course, any scenario may reconfigure itself during a start / prestart event as much as it likes, using randomness, but the Map Generator WML has the following advantages:

* Wesnoth has several built-in map generators which can be configured with options, and these are much better developed than any existing pure WML options.
* Map generation occurs before the scenario is even loaded, something which is not possible for WML events. In an mp game, the map generator code will run only on the host, side-stepping any synchronization issues, and keeping your scenario code as simple as possible.
* For scenarios with "allow_new_game=yes" and which use map generators, the generator may be reconfigured in the mp create screen (assuming that someone has coded a dialog for it). The user can also select to regenerate the map and get instant feedback from the minimap display.

== Scenario vs map generation ==

Every map generator can be used in either '''scenario_generation''' mode or '''map_generation''' mode. In map_generation mode, the generator is only used to replace the map_data of your scenario. In scenario_generation mode, the entire [scenario] tag is replaced.

To select a map generator and mode, in your [scenario] tag you must place '''one of'''
* '''scenario_generation=algorithm'''
* '''map_generation=algorithm'''
where '''algorithm''' is the generator algorithm you want to use. Note that not every algorithm is designed to be use with both of these options.

You must additionally place a [generator] tag in your scenario, which contains the options to the map generator.

== [generator] ==

The exact things that should be placed in [generator] depend on what algorithm you pick. There are three kinds of generators, `default`, `cave`, `lua` {DevFeature1.13|0}, and `yamg` {DevFeature1.13|0}.

For which key to use and what value, see the section for the generator you want to use.

===The lua generator===
The lua generator type specifies a custom map generator, which you provide via lua scripts.

The following keys are recognized for '''[generator]''' when the lua generator is used:
* '''create_map''' : A lua routine which returns a string containing the new map_data. The entire contents of the '''[generator]''' are passed to the script in a lua table (see [[LuaWML]]), via the argument '''...''' (see http://www.lua.org/pil/5.2.html).
* '''create_scenario''' : The same, but returning a '''[scenario]''' tag for the new scenario, as a lua table.

Any other keys are used only by the lua script.

The following keys of the output [scenario] are specifically watched by the mp create screen:
* '''id'''
* '''name'''
* '''description'''
* '''error_message'''

====Available Lua API====
The usual in-game API, in the table '''wesnoth''', is not available to lua scripts. However the usual standard lua libs are available, and a random number generator object is available from the Rng table. This is an instance of the Mersenne Twister 19937 random number generator from the C++11 standard.

'''rng = Rng:create()''' : creates a new rng object
'''rng:seed()''' : seed an rng, expects a string in hexadecimal format
'''rng:draw()''' : draw a 32-bit random integer from the rng

===The Default Generator===
The default generator can be used to generate map data for any scenario. The data in this section is inferred from “data/multiplayer/scenarios/Random_Scenario.cfg”, usage in add-on content, and inspection of mapgen.cpp

'''Excerpt from mapgenerator comments:'''

* Basically we generate alot of hills, each hill being centered at a certain point, with a certain radius - being a half sphere. Hills are combined additively to form a bumpy surface. The size of each hill varies randomly from 1-hill_size. We generate 'iterations' hills in total. The range of heights is normalized to 0-1000. 'island_size' controls whether or not the map should tend toward an island shape, and if so, how large the island should be. Hills with centers that are more than 'island_size' away from the center of the map will be inverted (i.e. be valleys). 'island_size' as 0 indicates no island.

To use the default '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:
* '''scenario_generation=default'''
* '''map_generation=default'''
If ‘scenario_generation’ is used, the engine will expect for your entire '''[scenario]''' sub tags to be inside a '''[scenario]''' tag inside '''[generator]'''. Tags outside of this will be ignored. There may be value in this, but at this writing, it’s not clear.
‘map_generation=default’ is simpler and more commonly used. It is also necessary to use this key so that you can regenerate a map in MP game creation.
In its use only generator data is in the '''[generator]''' tag, all other '''[scenario]''' data is placed outside of it. The exception is if you are making an initial MP scenario available in MP game creation, for this a '''[scenario]''' tag must appear inside of '''[generator]''', containing the '''[scenario]''' subtags you want to use. See “data/multiplayer/scenarios/Random_Scenario.cfg” for an example.

The following key/tags are recognized for '''[generator]''' when the default generator is used:
* '''[scenario]''': See [[ScenarioWML]]
* '''name'''
** '''default'''
* '''map_width''','''map_height''': size of the map to generate
* '''iterations''': the number of times an attempt is being made to generate a hill
* '''hill_size''': hills will have a random size between 1 and ''hill_size''
* '''max_lakes''': the number of times an attempt is being made to generate a lake
* '''min_lake_height''': lakes are the starting point of rivers and need to start above a certain height
* '''lake_size''': the size of a lake still randomly generated
* '''river_frequency''': determine how much a river can run uphill and thus generate more rivers

* '''villages''': villages per 1,000 hexes
* '''players''': Number of starting locations for the map.
* '''castle_size''': Number of castle tiles (including the keep), per player.
* '''temperature_iterations''': Same as iterations, but for the temperature map.
* '''temperature_size''': Same as hill_size, but for the temperature map. (Temperature map is generated the same way as a hill map, but is hard coded with a island_size of 0.)
* '''roads''': number of roads the generator will attempt to make
* '''road_windiness''': Use 1 for the road to be made using the cheapest path (based on [road_cost] tags), higher values introduce randomness to make the road wind a bit.
* '''island_size''': Use 1-5 for coastal maps and 6-10 for island maps. Bigger values may crash map generation process. Bigger numbers makes more water (and less land)
* '''default_flatland''': If not specified, is Grassland. If your height tags don't go down to 0, the default_flatland will be used (possibly in other cases as well).
* '''[height]''': list of common terrain types that come in at different heights, from highest to lowest. Good WML will have the range of 1000-0 covered.
** '''height''': the terrain specified below will appear at this height and up.
** '''terrain''': 1 terrain code
* '''[convert]''': used to make terrain conversions. For example, water becomes ice at low temperatures, grass snow, etc. If the terrain is between the min_x and max_x it will be converted. If min_x is not defined it will default to a large negative number. If max_x is not defined it will default to a large positive number
** '''min_height'''
** '''max_height'''
** '''min_temperature'''
** '''max_temperature'''
** '''from''': a comma separated terrains to convert from
** '''to''': The terrain to convert these terrains to
* '''[road_cost]'''
** '''terrain''' 1 terrain code
** '''cost''': how expensive it is the create a road on this terrain, this influences the odds of this terrain getting a road
** '''convert_to_bridge''': a comma separated list of terrains; N/S, then NE/SW, then NW/SE.
** '''convert_to''': 1 terrain code (note using both ''convert_to_bridge'' and ''convert_to'' might result in unwanted results)
* '''[village]''': The conversion of terrains to villages
** '''terrain''': 1 terrain code which will be converted to a village
** '''convert_to''': 1 terrain code for the village
** '''adjacent_liked''': a comma separated terrain list. This list increases the rating for a certain location, every tile around the location will be tested against this list and for every match the rating of the location is increased. The same terrain twice in the list will double the rating increase for that location.
** '''rating''': chance of appearing
* '''[castle]''': the conversion of castles
** '''valid_terrain''': a comma-separated terrain list with terrains which are allowed to be converted to a castle.
** '''min_distance''': all castles generated must be this number of hexes apart from each other
* '''[naming]''': The names used to label landscape features (forests, lakes, etc.). This controls, for example, the "Fox" part of "Foxwood". If this tag is empty, those labels should be suppressed. (Due to a bug, they are not suppressed prior to 1.11.1.) The predefined macro VILLAGE_NAMES is one option for the contents of this tag. If that macro is not used, this tag takes one key.
** '''male_names'''
* '''[village_naming]''': The names used to label villages. This controls, for example, the "Fox" part of "Foxham". If this tag is empty, those labels should be suppressed. (Due to a bug, they are not suppressed prior to 1.11.1.) The predefined macro VILLAGE_NAMES is one option for the contents of this tag. If that macro is not used, this tag takes one key.
** '''male_names'''

===The Cave Generator===
The cave generator does not appear to have been written for multiplayer scenario game creation like the default generator was. It is used in '''campaigns\Sceptre_of_Fire\scenarios\4_Gathering_Materials.cfg''' & '''campaigns\Heir_To_The_Throne\scenarios\ 17_Scepter_of_Fire.cfg '''. The data here is inferred from those scenarios and an inspection of cavegen.cpp

To use the cave '''[generator]''' your '''[scenario]''' tag must contain one of the following keys:
* '''scenario_generation=cave'''
* '''map_generation=cave'''
Here it is recommend you use ‘scenario_generation’ as there are examples to follow, though it may be possible to use’ map_generation’.

The following key/tags are recognized for '''[generator]''' when the cave generator is used:
* '''[settings]''': behaves as if '''[scenario]''', See [[ScenarioWML]]
* '''map_width''','''map_height''': size of the map to generate
* '''village_density''': influences number of villages
* '''flipx_chance''': Chance to flip x coordinates, that meens the map is mirrored at the vertical axis in its midth.
* '''flipy_chance''': Chance to flip y coordinates, that meens the map is mirrored at the horizontal axis in its midth.
* '''[chamber]''': for underground maps
** '''id''': a name used to identify where the passages lead. See the [passage] tag, below.
** '''x''','''y''': approximate location of the center hex of the chamber. Unfortunately it isn't always exact. Can be a single number (x=5) or a range (x=10-20)
** '''size''': circular radius of the chamber, including the center hex
** '''jagged''': a good value is probably between 0-50 (not sure exactly)
** '''chance''': chance for the chamber to be generated, between 0 and 100, 100 if key not present
** '''[items]''': See [[ScenarioWML]]. This can contain tags normally found under [scenario] like [side], [item], and [event]. Moveto events definitely work here (using the same_location_as_previous key instead of a location filter). Other events can be placed in the [settings] tag, above. Locations of items will be generated randomly. The attribute '''same_location_as_previous=yes''' means that the filter for a moveto event (see [[EventWML]]) is the same as the location of the previous item.
** '''[passage]''': defines a pathway between chambers
*** '''destination''': the id key of the destination chamber
*** '''windiness''': a good value is probably between 1-10
*** '''laziness''':
*** '''width''': number of hexes
*** '''jagged''': a good value is probably between 1-10
*** '''chance''': chance for the passage to be generated, between 0 and 100, 100 if key not present

=== YAMG generator ===

*** Please document me! ***

== Infrastructure ==

* The default generator settings are loaded from a scenario file under data/multiplayer/scenarios.
* mapgen_dialog overwrites these values if necessary.
* The create_map / create_scenario function is called by one of the following
** multiplayer_create_engine.cpp:394
** context_manager.cpp:648
** map_create.cpp:56
* A map buffer is written to res["map_data"]
* the config res is passed to the calling function.

== See Also ==

* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

User:Iceiceice/Cross-compiling

2014-10-25T22:11:30Z

Iceiceice: /* Compile wesnoth */

Here are some instructions I created the first time I managed to cross compile wesnoth. It's as much a "post-mortem" as a guide, I leave it here in case I ever want to do it again later, or if it might help someone.

These instructions refer to using mingw to cross-compile wesnoth 1.13.0-dev on Linux Mint Qiana 17 , targeted at 32-bit windows.

Last tested at commit: 1385ab3791088d7c9bfa3bc439fcf49b23563535

== Get mingw32 ==

It might seem as simple as "sudo apt-get install mingw32", but after you do this, you need to make sure that you have a 32 bit compiler which is good enough to compile wesnoth. This required some trial and error, the version I got automatically from the distribution was only gcc 4.2, as you can see:

$ i586-mingw32msvc-g++ -v
Using built-in specs.
Target: i586-mingw32msvc
Configured with: /build/buildd/mingw32-4.2.1.dfsg/build_dir/src/gcc-4.2.1-2-dfsg/configure -v --prefix=/usr --target=i586-mingw32msvc --enable-languages=c,c++ --enable-threads --enable-sjlj-exceptions --disable-multilib --enable-version-specific-runtime-libs
Thread model: win32
gcc version 4.2.1-sjlj (mingw32-2)

Furthermore it was broken, and had some bugs about ::swprintf not defined, which caused boost iostreams to break... google this for some stories of pain. [http://www.gaia-gis.it/spatialite-2.4.0-3/mingw_how_to.html] [http://cboard.cprogramming.com/windows-programming/126629-error-'-swprintf'-has-not-been-declared.html] [http://qt-project.org/forums/viewthread/8055]

Therefore to get a more recent version of mingw I added a package from utopic universe :

$ sudo add-apt-repository -y "deb http://archive.ubuntu.com/ubuntu/ utopic main universe"

And I install

$ sudo apt-get install g++-mingw-w64-i686

(Launchpad page: http://packages.ubuntu.com/utopic/g++-mingw-w64-x86-64)

Now I get this instead

$ i686-w64-mingw32-g++ -v
Using built-in specs.
COLLECT_GCC=i686-w64-mingw32-g++
COLLECT_LTO_WRAPPER=/usr/lib/gcc/i686-w64-mingw32/4.9-win32/lto-wrapper
Target: i686-w64-mingw32
Configured with: ../../src/configure --build=x86_64-linux-gnu --prefix=/usr --includedir='/usr/include' --mandir='/usr/share/man' --infodir='/usr/share/info' --sysconfdir=/etc --localstatedir=/var --libexecdir='/usr/lib/gcc-mingw-w64' --disable-maintainer-mode --disable-dependency-tracking --prefix=/usr --enable-shared --enable-static --disable-multilib --with-system-zlib --libexecdir=/usr/lib --without-included-gettext --libdir=/usr/lib --enable-libstdcxx-time=yes --with-tune=generic --enable-version-specific-runtime-libs --enable-fully-dynamic-string --enable-libgomp --enable-languages=c,c++,fortran,objc,obj-c++ --enable-lto --with-plugin-ld --enable-threads=win32 --program-suffix=-win32 --program-prefix=i686-w64-mingw32- --target=i686-w64-mingw32 --with-as=/usr/bin/i686-w64-mingw32-as --with-ld=/usr/bin/i686-w64-mingw32-ld
Thread model: win32
gcc version 4.9.1 (GCC)

With gcc 4.9, now we are in business.

== Download loonycyborg's wesnoth deps collection ==

http://sourceforge.net/projects/wesnoth/files/SDK/wesnoth-deps-1.11.zip/download

I'm going to assume henceforth that you extract this to the folder "~/w-deps", and that inside is "include", "bin" etc. directories.

== Download boost ==

I wanted to test our stated boost dependencies, so I actually make a folder "~/old-boost/" where I hold several versions of boost. You can find any old version of boost at sourceforge, e.g.

http://sourceforge.net/projects/boost/files/boost/1.52.0/

http://sourceforge.net/projects/boost/files/boost/1.48.0/

http://sourceforge.net/projects/boost/files/boost/1.44.0/

etc.

Download one of these and extract it to ~/old-boost/, or take from w-deps folder.

I'm going to assume that you picked boost 1.52.0, so your boost directory is ~/old_boost/boost_1_52_0/.

== Make a boost config file (tell it what compiler you want to use) ==

In your home directory, make a text file called user_config.jam.

Here's some sample contents:

$ cat user-config.jam
using gcc ;
using gcc : 4.6 : g++-4.6 ;
using gcc : w64mingw32 : i586-mingw32msvc-g++ ;
using gcc : w64mingw64 : x86_64-w64-mingw32-g++ ;

When boost has a file like this, it means that e.g. "toolset=gcc-4.6" will cause it to use the compiler g++-4.6, and "toolset=gcc-w64mingw32" will cause it to use the compiler i586-mingw32msvc-g++.

Make a line like this:

using gcc : w64mingw32 : i686-w64-mingw32-g++ ;

To register our new compiler.

(And make sure its the only w64mingw32 line of course.)

== Compile boost ==

Navigate to your boost directory, ~/old_boost/boost_1_52_0/

First, run the "bootstrap" program,

./bootstrap.sh

You don't need to give it any arguments, it doesn't really matter what it builds with. It is just building the boost jam program which will actually orchestrate the boost build.

Now, run boost jam (called "b2"). I recommend to put the actual command in shell script, for ease of use in case you have to modify it (and so you don't forget it...)

I used the following recipe:

$ cat recipe
#!/bin/bash
./b2 toolset=gcc-w64mingw32 -d+2 -a --reconfigure --debug-configuration --with-iostreams --with-locale --with-regex --with-filesystem --with-system --with-program_options target-os=windows variant=release threading=multi threadapi=win32 address-model=32 architecture=x86 instruction-set=i686
link=static runtime-link=static -j 2 -sBZIP2_BINARY=libbz2 -sBZIP2_INCLUDE=/home/chris/w-deps/include -sBZIP2_LIBPATH=/home/chris/w-deps/bin -sZLIB_BINARY=zlib -sZLIB_INCLUDE=/home/chris/w-deps/include -sZLIB_LIBPATH=/home/chris/w-deps/bin

Discussion of flags
; toolset=gcc-w64mingw32
: Tells to use the compiler I choose for 32 bit windows. Could also have tried e.g. gcc-w64mingw64, for 64-bit windows, based on my user-config.jam, or gcc-4.6 for g++-4.6 compiler (see my user-config.jam above)
; -d+2
; --debug-configuration
: These are debugging output options that make boost tell you about the configuration, and show you what compiler commands it is running.
; -a
; --reconfigure
: -a makes sure that all targets are rebuilt, and reconfigure makes sure that it reconfigures based on new options. If you are changing things around these options prevent you from getting screwed over by stale options.
; --with-iostreams
; --with-locale
; --with-regex
; --with-filesystem
; --with-system
; --with-program_options
: Select what libraries you want. It's better to use --with than --without because otherwise you get a bunch of random crap. You can't use both kinds.
; target-os=windows
; threading=multi
; threadapi=win32
: You need these to make it build dll's, and that will work for you.
; address-model=32
; architecture=x86
; instruction-set=i686
: I added these out of paranoia at some point but they might not really be necessary
; link=static
; runtime-link=static
: This is the only reasonable option here
; -j 2
: Parallelize the build over 2 cores
; -sBZIP2_BINARY=libbz2
; -sBZIP2_INCLUDE=/home/chris/w-deps/include
; -sBZIP2_LIBPATH=/home/chris/w-deps/bin
: Tell boost exactly where to find bzip2 binary and header. I earlier tried to do this just with cxxflags and linker flags, but it got confused with my system-installed bzip2 and caused me a lot of pain. This fixed it.
; -sZLIB_BINARY=zlib
; -sZLIB_INCLUDE=/home/chris/w-deps/include
; -sZLIB_LIBPATH=/home/chris/w-deps/bin
: Tell boost exactly where to find zlib binary and header.

Now run the recipe (don't forget to "chmod +x" it):

$ ./recipe

If you would like to suppress the warnings, you can use cxxflags="-w" as an additional argument.

You should get this at the end:

The Boost C++ Libraries were successfully built!

The following directory should be added to compiler include paths:

/home/chris/old_boost/boost_1_52_0

The following directory should be added to linker library paths:

/home/chris/old_boost/boost_1_52_0/stage/lib

If you did not, check that all of your paths are matching correctly, that you actually have a libbz2.a and zlib.a in your ~/w-deps/bin, (and that they *match* the associated headers... if in doubt, try downloading again, or even compile the c libraries yourself, it doesn't matter what compiler you use for c libraries). Check that the compiler name is correct. You could use cxxflags to try to get additional diagnostics. The -d+2 command causes boost to output much additional diagnostics as well.

== Compile wesnoth ==

Now, you need to craft an scons command that will properly tell it to cross compile, to use the cross compiling compiler, and point it to your fresh boost compile, and all the deps. I prefer to in this case as well store the recipe in a shell script:

$ cat build_mingw_boost_1_52.sh
#!/bin/bash
rm .scons-option-cache
scons default_targets=wesnoth build=release extra_flags_config="-DBOOST_THREAD_USE_LIB -Wno-unused-local-typedefs" prefix=~/w-deps boostdir=~/old_boost/boost_1_52_0 boostlibdir=~/old_boost/boost_1_52_0/stage/lib gettextdir=~/w-deps gtkdir=~/w-deps host=i686-w64-mingw32

Some discussion
; rm .scons-option-cache
: So that stale settings can't screw up my build and confuse me
; default_targets=wesnoth
: This could also be wesnoth, wesnothd, campaignd. I think it can't include "test" atm because we didn't compile the boost unit testing system.
; build=release
: Unless you want to make a debug build
; extra_flags_config:
: Add -Wno-unused-local-typedefs or your log will be unreadable with pointless warnings.
: Add -DBOOST_THREAD_USE_LIB because loonycyborg said so
; prefix=~/w-deps
: This is pretty handy, this will cause scons to add ~/w-deps/include to be included as a cxx flag, and also to add ~/w-deps/bin to be linked. So it saves you some typing.
; boostdir=~/old_boost/boost_1_52_0
: First directory that boost reported to you above (or for whatever boost version you want to use)
; boostlibdir=~/old_boost/boost_1_52_0/stage/lib
: Second directory that boost reported to you above (Wherever the boost libraries ended up for you.)
; gettextdir=~/w-deps
; gtkdir=~/w-deps
: These point scons to find compiled versions of these, and not your system version (which will not be binary compatible in case of C++ libs).
: Note that I don't add sdldir=~/w-deps, because it shouldn't be necessary as SDL is a c lib, so my system version is fine. But if you get a problem finding or linking SDL, then add that in also.
; host=i686-w64-mingw32
: This is where we select the compiler, actually. scons will prepend the "host" followed by -, followed by g++, if no cxxtool argument is given. (I'm not sure how "host" and "cxxtool" arguments interact.) So this selection results in the compiler, i686-w64-mingw32-g++, as desired.

If you get configuration errors, a good way to trouble shoot is to check your /build/config.log

That's all there is to it. Good luck.

=== Note ===

When I finally compiled I get these warnings on linking:

/usr/bin/ccache i686-w64-mingw32-g++ -o wesnoth.exe -static-libgcc -static-libstdc++ -mwindows -mthreads build/release/wesnoth.o build/release/libwesnoth_extras.a build/release/lua/liblua.a build/release/libwesnoth_core.a build/release/libwesnoth.a build/release/libwesnoth_sdl.a build/release/libwesnoth_extras.a build/release/lua/liblua.a packaging/windows/wesnoth.o -L/home/chris/w-deps/lib -L/home/chris/w-deps/lib -L/home/chris/old_boost/boost_1_52_0/stage/lib -lmingw32 -lSDLmain -lSDL -lSDL_net -lboost_iostreams -lz -lbz2 -lboost_system -lboost_filesystem -lboost_locale -lSDL_ttf -lSDL_mixer -lSDL_image -lws2_32 -lpangocairo-1.0 -lcairo -lpangoft2-1.0 -lpangowin32-1.0 -lgdi32 -lfreetype -lpango-1.0 -lm -lgobject-2.0 -lglib-2.0 -lintl -lfontconfig -lboost_program_options -lboost_regex -lvorbisfile -lwsock32 -lintl -lz
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_9iostreams10gzip_errorEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_9iostreams10gzip_errorEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(gzip.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_9iostreams10gzip_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINSt8ios_base7failureEEE[__ZTSN5boost16exception_detail19error_info_injectorINSt8ios_base7failureEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_iostreams.a(file_descriptor.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINSt8ios_base7failureEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_filesystem.a(operations.o): duplicate section `.rdata$_ZTSN5boost6detail17sp_counted_impl_pINS_10filesystem6detail11dir_itr_impEEE[__ZTSN5boost6detail17sp_counted_impl_pINS_10filesystem6detail11dir_itr_impEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_locale.a(message.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_15program_options16validation_errorEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_15program_options16validation_errorEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(value_semantic.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_15program_options16validation_errorEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_15program_options16validation_errorEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(convert.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE[__ZTSN5boost16exception_detail19error_info_injectorINS_17bad_function_callEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_program_options.a(cmdline.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorINS_17bad_function_callEEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt13runtime_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt13runtime_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE[__ZTSN5boost16exception_detail19error_info_injectorISt11logic_errorEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTSN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt13runtime_errorEEEE]' has different size
/home/chris/old_boost/boost_1_52_0/stage/lib/libboost_regex.a(regex.o): duplicate section `.rdata$_ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE[__ZTVN5boost16exception_detail10clone_implINS0_19error_info_injectorISt11logic_errorEEEE]' has different size
scons: done building targets.

We don't know what these warnings are exactly but it seems they can be ignored.

== WINE ==

To get wine to run I did the following. You must make sure you are using a 32 bit environment.

env WINEPREFIX=~/prefix32 WINEARCH=win32 wine cmd

All the online instructions say that you need to update wine's path, using regedit, to point to your dll's. I couldn't actually get this to work, so I ended up putting symlinks in my prefix 32 C:\windows\system32 directory:

~/prefix32/drive_c/windows/system32 $ ln -s ~/w-deps/bin
~/prefix32/drive_c/windows/system32 $ ln -s /usr/lib/gcc/i686-w64-mingw32/4.9-win32/

Besides the libs like SDL, pango, etc., you also need a .dll specific to mingw (I guess this is the mingw run time library). I found that I needed this dll:

/usr/lib/gcc/i686-w64-mingw32/4.9-win32/libgcc_s_sjlj-1.dll

If I got errors like this:

$ env WINEPREFIX=~/prefix32 WINEARCH=win32 wine wesnoth
err:module:import_dll Library libpangoft2-1.0-0.dll (which is needed by L"C:\\windows\\system32\\libpangocairo-1.0-0.dll") not found
err:module:import_dll Library libpangocairo-1.0-0.dll (which is needed by L"Z:\\home\\chris\\wesnoth-src\\clone\\wesnoth\\wesnoth.exe") not found
err:module:LdrInitializeThunk Main exe initialization for L"Z:\\home\\chris\\wesnoth-src\\clone\\wesnoth\\wesnoth.exe" failed, status c0000135

I fixed it by adding a symlink to ~/w-deps/bin/libpangoft2-1.0-0.dll in the folder prefix32/drive_c/windows/system32.

And so on and so forth... Eventually it worked.

=== Tip ===

As I learned later, a better way to handle this is to just copy all of the .dll files you need into the root of your repo, next to wesnoth.exe. This will make wine find them first, for wesnoth only, and our .gitignore file includes *.dll so they won't get into the repo.

=== Troubleshooting ===

A helpful thing I found is, if you have problems running wesnoth with the DLL's, you can sanity check by running the little executables generated by scons for the configuration tests. E.g.

$ env WINEPREFIX=~/prefix32 WINEARCH=win32 wine build/sconf_temp/conftest_20.exe

If the test works it should give no output, otherwise if it's not linking right it should give you an error.

User:Iceiceice/Cross-compiling

2014-10-25T06:06:08Z

Iceiceice: /* WINE */

User:Iceiceice/Cross-compiling

2014-10-24T16:30:42Z

Iceiceice: /* Compile wesnoth */

User:Iceiceice/Cross-compiling

2014-10-24T16:29:49Z

Iceiceice: /* WINE */

User:Iceiceice/Cross-compiling

2014-10-24T16:14:21Z

Iceiceice: /* WINE */

User:Iceiceice/Cross-compiling

2014-10-24T16:07:13Z

Iceiceice: /* Download boost */

User:Iceiceice/Cross-compiling

2014-10-24T16:07:00Z

Iceiceice: /* Download boost */

User:Iceiceice/Cross-compiling

2014-10-24T16:06:13Z

Iceiceice: /* Get mingw */

User:Iceiceice/Cross-compiling

2014-10-24T16:05:01Z

Iceiceice: /* Compile wesnoth */

User:Iceiceice/Cross-compiling

2014-10-24T16:02:21Z

Iceiceice: /* Compile boost */

User:Iceiceice/Cross-compiling

2014-10-24T15:50:32Z

Iceiceice:

User:Iceiceice/Cross-compiling

2014-10-24T15:44:19Z

Iceiceice:

User:Iceiceice/Cross-compiling

2014-10-24T07:28:47Z

Iceiceice: /* Make a boost config file (tell it what compiler you want to use) */

User:Iceiceice/Cross-compiling

2014-10-24T07:23:15Z

Iceiceice: Created page with "Here are some instructions I created the first time I managed to cross compile wesnoth. It's as much a "post-mortem" as a guide, I leave it here in case I ever want to do it a..."

DeveloperGuide

2014-10-19T14:09:10Z

Iceiceice: /* Dependencies */

== Commits ==
* Setting up developer access to the repository: [[WesnothRepository#Commit_access]]
* Register to commit mailing list: https://mail.gna.org/listinfo/wesnoth-commits or get the list moderator to approve commit messages from you otherwise
* Trunk should compile and work after commit -- we use travis-ci, which will report any build failures on master to the irc channel. https://travis-ci.org/wesnoth/wesnoth
* All unit tests should pass after commit -- travis will also test this. To run the C++ unit tests, compile the "test" executable and run it. To run the WML unit tests, run "run_wml_tests -u" in the root of the repo.
** If a test times out spuriously on travis, you can restart the build by
*** clicking on the link posted to irc by the travis bot
***: 20141009 20:40:27-!- travis-ci [~travis-ci@ec2-184-73-55-78.compute-1.amazonaws.com] has joined #wesnoth-dev
***: 20141009 20:40:27< travis-ci> wesnoth/wesnoth#4154 (master - c91604a : Ignacio R. Morelle): The build was broken.
***: 20141009 20:40:27< travis-ci> Build details : http://travis-ci.org/wesnoth/wesnoth/builds/37536345
***: 20141009 20:40:27-!- travis-ci [~travis-ci@ec2-184-73-55-78.compute-1.amazonaws.com] has left #wesnoth-dev []
*** clicking on the [http://i.imgur.com/mxwVKJP.png restart button]
** Do not disable unit tests without a very good reason!
* Few small commits are better than a big one (hard to review), so when possible split it in working parts with info about where you are going
* Be on #wesnoth-dev IRC channel and coordinate with other developers. Bots report commits and some devs may ask you a question about it.
* Don't forget changelogs: ''changelog'' for any (significant enough) changes and ''player_changelog'' for changes visible to users.
* Always check your changes before commit (see [[WesnothRepository#Reviewing your changes]]).
* Commit message:
** Mention any change, especially if some are unrelated to the main one (but you should use separated commits for this).
** Mention "bug #1234" for automatic cc to that gna bug number
** Mention a developer's IRC name will ping him on IRC (when the bot report it), and if he's not there, he may see it on the IRC logs

== Bugs management ==
* Change status of fixed bugs to "Fixed" when committed
* Change status of fixed bugs to "Closed" when released, see [[ReportingBugs#Bug_protocol]] for details
* Check if there is new bugs relevant to your code and if any, assign them to you.

== Dependencies ==
* Any change in dependencies to build the project must be discussed on the mailing list (dev-talk).
* Update SConstruct (and ideally cmake recipe also) to check for the dependency.
* Note any change (added or removed deps, or increased version requirements) in the RELEASE_NOTES file. These will be announced in the forum announcement and in the emails to packagers.

== Tips ==

* If you build with scons, use clang rather than gcc, as it is 2-3x faster to compile wesnoth.
Set your choice permanently with

scons cxxtool=clang++

== See also ==
* [[Project#Developers]]
* [[WesnothRepository]]

[[Category:Development]]