The Battle for Wesnoth Wiki - User contributions [en]

Talk:ReferencePythonAPI

2006-03-02T21:29:46Z

Ryo: /* Cheating */

== Feature Requests ==

* Path finder, something like: wesnoth.find_path(loc1, loc2), and it would return a list of all locations in between, or just the first step.. whatever the C++ API has
:Gonna wrap a_star_search (in pathfind.hpp) [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)
:Actually it's gonna be unit.find_path() since it depends on a unit. [[User:Ryo|Ryo]] 19:53, 8 December 2005 (CET)
:Done, experimental though :) [[User:Ryo|Ryo]] 20:09, 8 December 2005 (CET)

* Persistent variables. Right now, the script state isn't reset, so all variables are already persistent. But for the final version, there should be real persistent variables, which can also be stored to WML, and reloaded. An AI would use it to e.g. store a path, or some other state.
:Probably with the Object -> String Python conversion. Will look at that [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)

* Something like wesnoth.get_possible_moves(loc) - it would return all possible moves for the unit at the given location. It seems, right now, I make a lot of mistakes because the info of wesnoth.get_src_dst or wesnoth.get_units gets outdated after I move a unit. (Not really sure about this one, better planning out of the algorithm might make this function un-necessary.)
:Yes, you need to grab again the array after moving. What happens is that you get a "snapshot" copy, which isn't updated when you move a unit - thus your "obsolete" copy can contain now invalid destinations. I'm not sure of a fix for that apart getting again the array. [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)

* Having access to the properties 'HP' and 'Poisonned' of a unit. This would allow focussing on already damaged units when attacking and sending low HP units for rest. It could improve dramatically python AI efficiency. [[User:Viorc|Viorc]]

:added ''hitpoints'', ''max_hitpoints'' and ''poisoned'', thanks for the patch :)
:[[User:Ryo|Ryo]] 22:22, 2 March 2006 (CET)

== chance to kill ==

Can I get a chance_to_kill(wesnoth.location)? And it would tell me the chance to kill the unit at the given location, using terrain modifiers and everything.. I assume, the C++ AI has something like it available. [[User:Allefant|Allefant]] 22:39, 10 January 2006 (CET)

:I'll check what the C++ has, and export it. [[User:Ryo|Ryo]] 09:24, 11 January 2006 (CET)

:Ok, there is a structure/function associated, <code>attack_analysis</code>. Gonna try to export it, but may be a mess :)
:[[User:Ryo|Ryo]] 11:29, 15 January 2006 (CET)

== usage pattern ==

I'm not sure it would be really useful, since a good AI would probably derive the usage of a unit out of its properties - but maybe there could be a way to query the usage pattern of a unit? Like "scout" or "fighter".. --[[User:Allefant|Allefant]] 22:35, 13 January 2006 (CET)

== minor API cleanup ==

* properties or methods? E.g. why '''wesnoth.unit.type()''' but '''wesnoth.unit.name'''? Same or wesnoth.get_map() or wesnoth.get_gamestatus(), and others.. The rule behind it is not clear. One way could be, make everything that can change inside a turn a method, everything else a property. Or just make everything methods/properties, since it doesn't seem to matter much in the Python-C-API..

* '''unit.movement_cost''' - why does it need the wesnoth.gamemap parameter? Since you don't have a lot of choice what to pass there (or do I have it? could i modify the map returned by get_map?), I think the parameter could go. Same for defense_modifier.

* '''unit.movement_left''' - it seems that this data is not present in 'unit' interface. It should either be added or removed from ReferencePythonAPI (but could be useful later).

* '''wesnoth.attack_unit(attacker,defender,weapon)''' - how can we related the integer weapon with a attack as the one retrieved from unit.attacks() ? Couldn't we use this attack_type as parameter of attack_unit function ?

:You're right, property/method should be coherent. I'll do:
:*property => simple type, no argument
:*method => complex type or argument
:For the gamemap, I'm not sure, I merely mapped the function :) But I'll change the API to not use map anymore and use current one.
:movement_left does indeed exist in unit.
:Attack weapon is the index of the weapon in the list from attacks( ).
:[[User:Ryo|Ryo]] 22:27, 2 March 2006 (CET)

== Cheating ==

Should the Python AI be allowed to cheat? I'd like if it couldn't,
since then I could concentrate on the strategy in the AI script I'm
playing with, and wouldn't need to check for violated rules myself.
(So far, my AI attacks multiple times with one unit, and also moves
after capturing villages or attacking..)

OTOH, if the Python AI is meant to later allow scenario scripting,
it probably will be wanted to just modify things. But I think, that
could be done with an alternate API. Something like:
wesnoth.remove_unit(), wesnoth.place_unit().. and the current ones
still could have anti-cheat checks.

:I don't think AI should be able to cheat. AI is like a player (ok, maybe no fog of war, but still, unit moves should be legal).
:I'll check how to enforce the same rules than for players.
:[[User:Ryo|Ryo]] 22:29, 2 March 2006 (CET)

Talk:ReferencePythonAPI

2006-03-02T21:27:54Z

Ryo: /* minor API cleanup */

Talk:ReferencePythonAPI

2006-03-02T21:22:30Z

Ryo: /* Feature Requests */

== Feature Requests ==

* Path finder, something like: wesnoth.find_path(loc1, loc2), and it would return a list of all locations in between, or just the first step.. whatever the C++ API has
:Gonna wrap a_star_search (in pathfind.hpp) [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)
:Actually it's gonna be unit.find_path() since it depends on a unit. [[User:Ryo|Ryo]] 19:53, 8 December 2005 (CET)
:Done, experimental though :) [[User:Ryo|Ryo]] 20:09, 8 December 2005 (CET)

* Persistent variables. Right now, the script state isn't reset, so all variables are already persistent. But for the final version, there should be real persistent variables, which can also be stored to WML, and reloaded. An AI would use it to e.g. store a path, or some other state.
:Probably with the Object -> String Python conversion. Will look at that [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)

* Something like wesnoth.get_possible_moves(loc) - it would return all possible moves for the unit at the given location. It seems, right now, I make a lot of mistakes because the info of wesnoth.get_src_dst or wesnoth.get_units gets outdated after I move a unit. (Not really sure about this one, better planning out of the algorithm might make this function un-necessary.)
:Yes, you need to grab again the array after moving. What happens is that you get a "snapshot" copy, which isn't updated when you move a unit - thus your "obsolete" copy can contain now invalid destinations. I'm not sure of a fix for that apart getting again the array. [[User:Ryo|Ryo]] 19:44, 8 December 2005 (CET)

* Having access to the properties 'HP' and 'Poisonned' of a unit. This would allow focussing on already damaged units when attacking and sending low HP units for rest. It could improve dramatically python AI efficiency. [[User:Viorc|Viorc]]

:added ''hitpoints'', ''max_hitpoints'' and ''poisoned'', thanks for the patch :)
:[[User:Ryo|Ryo]] 22:22, 2 March 2006 (CET)

== chance to kill ==

Can I get a chance_to_kill(wesnoth.location)? And it would tell me the chance to kill the unit at the given location, using terrain modifiers and everything.. I assume, the C++ AI has something like it available. [[User:Allefant|Allefant]] 22:39, 10 January 2006 (CET)

:I'll check what the C++ has, and export it. [[User:Ryo|Ryo]] 09:24, 11 January 2006 (CET)

:Ok, there is a structure/function associated, <code>attack_analysis</code>. Gonna try to export it, but may be a mess :)
:[[User:Ryo|Ryo]] 11:29, 15 January 2006 (CET)

== usage pattern ==

I'm not sure it would be really useful, since a good AI would probably derive the usage of a unit out of its properties - but maybe there could be a way to query the usage pattern of a unit? Like "scout" or "fighter".. --[[User:Allefant|Allefant]] 22:35, 13 January 2006 (CET)

== minor API cleanup ==

* properties or methods? E.g. why '''wesnoth.unit.type()''' but '''wesnoth.unit.name'''? Same or wesnoth.get_map() or wesnoth.get_gamestatus(), and others.. The rule behind it is not clear. One way could be, make everything that can change inside a turn a method, everything else a property. Or just make everything methods/properties, since it doesn't seem to matter much in the Python-C-API..

* '''unit.movement_cost''' - why does it need the wesnoth.gamemap parameter? Since you don't have a lot of choice what to pass there (or do I have it? could i modify the map returned by get_map?), I think the parameter could go. Same for defense_modifier.

* '''unit.movement_left''' - it seems that this data is not present in 'unit' interface. It should either be added or removed from ReferencePythonAPI (but could be useful later).

* '''wesnoth.attack_unit(attacker,defender,weapon)''' - how can we related the integer weapon with a attack as the one retrieved from unit.attacks() ? Couldn't we use this attack_type as parameter of attack_unit function ?

== Cheating ==

Should the Python AI be allowed to cheat? I'd like if it couldn't,
since then I could concentrate on the strategy in the AI script I'm
playing with, and wouldn't need to check for violated rules myself.
(So far, my AI attacks multiple times with one unit, and also moves
after capturing villages or attacking..)

OTOH, if the Python AI is meant to later allow scenario scripting,
it probably will be wanted to just modify things. But I think, that
could be done with an alternate API. Something like:
wesnoth.remove_unit(), wesnoth.place_unit().. and the current ones
still could have anti-cheat checks.

Talk:ReferencePythonAPI

2006-01-15T10:29:08Z

Ryo: /* chance to kill */

Talk:ReferencePythonAPI

2006-01-11T08:24:18Z

Ryo: /* chance to kill */

Credits

2005-12-27T21:19:00Z

Ryo: /* Developers */ add myself

In July 2003, '''David White''' released the first version of Wesnoth. Since then, many people have joined the project, contributing in very different ways.

== Developers ==
* Alfredo Beaumont (ziberpunk) - autotools
* András Salamon ([[User:Ott|ott]]) - general QA and bug fixing, subediting
* [mailto:dragonking_AT_o2.pl Bartek Waresiak] (Dragonking) - multiplayer developer
* Benjamin Drieu - scenario designer
* Benoît Timbert (Noyga) - coder
* Bram Ridder (Morloth) - editor improvements
* [[User:bruno|Bruno Wolff III]] - Campaign web interface, [[MainlineScenarios#The_Dark_Hordes|The Dark Hordes]] maintainer, bug fixing, minor coder
* Cédric Duval - coder, internationalization manager
* Crossbow/Miyo - administrator, release manager
* David Philippi (Torangan) - internationalization manager, wescamp
* [mailto:davidnwhite_AT_verizon.net David White] (Sirp) - founder, lead developer, scenario designer
* Francisco Muñoz (fmunoz) - artwork manager, original units, scenario designer
* Guillaume Melquiond (silene) -
* Hogne Håskjold (frame) - terrain designer
* [mailto:isaac_AT_sindominio.net Isaac Clerencia] - administrator, release manager
* [mailto:Crazy-Ivanovic_AT_gmx.net Nils Kneuper] (Ivanovic) - internationalization manager
* James Spencer (Shade) - scenario designer
* Jan Zvánovec (jaz) -
* Jérémy Rosen (Boucman) - coder
* John B. Messerly -
* [mailto:forcemaster_AT_gmx.net Jon Daniel] (forcemstr) -
* [mailto:jorda_AT_ettin.org Jordà Polo] (ettin) -
* Joseph Simmons (Turin) - scenario designer, graphics
* Jörg Hinrichs (Yogi Bear/YogiHH) - coder
* J.R. Blain (Cowboy) -
* [mailto:mcnabb_AT_gravity.psu.edu J.W.C. McNabb] (Darth Fool) - coder, graphics
* Justin Zaun (jzaun) - coder, scenario designer
* [mailto:erl_AT_erl.se Kristoffer Erlandsson] (erl) - help system, editor
* Maksim Orlovich (SadEagle) -
* Mark Michelsen (skovbaer) - internationalization manager
* Nicolas Weeger (ryo) - Python API
* [mailto:philippe.plantier_AT_naema.org Philippe Plantier] ([[User:Ayin|Ayin]]) - several parts of the code, notably terrain graphics code
* Richard Kettering (Jetryl) - artwork coordinator, several graphics
* Richard S. (Noy) - multiplayer developer
* Scott Klempner - campaign maintainer
* Soliton - multiplayer developer
* [mailto:susanna.bjorverud_AT_telia.com Susanna Björverud] (sanna) - internationalization manager
* [mailto:ydirson_AT_altern.org Yann Dirson] - gettext support, tinygui
* Zas -

== Artists ==
* Aleksi - music coordinator
* Alex Jarocha-Ernst (Jormungandr) - portraits
* Andrew James Patterson (Kamahawk) - sprites
* antwerp - sprites
* Christophe Anjard - sprites
* Diego Brea (Cobretti) - sprites
* Eli Dupree (Elvish Pillager) - sprites
* Fredrik Lindroth - music
* Gareth Miller (Gafgarion) - sprites
* James Barton (Sangel) - sprites
* James Woo (Pickslide) - portraits
* Jason Lutes - portraits
* Jimmy Olsson (Azlan) - icons
* Johanna Manninen (lohari) - tiles
* John Muccigrosso (Eponymous Archon) - sprites
* John-Robert Funck (XJaPaN) - sprites
* Jonatan Alamà (tin) - logo
* Joseph Toscano (zhaymusic.com) - music
* J.W. Bjerk (Eleazar) - tiles, graphics
* Michael Gil de Muro (grp21) - portraits
* Neorice - sprites
* Pau Congost - music
* Pekka Aikio - tiles
* Peter Geinitz (Shadow) - sprites
* Robert Bolin (Zebulon) - tiles
* Slainte - sprites
* Stephen Stone - [graphics]
* Svetac - [graphics]

== Translators ==
* adson - hungarian translation
* İhsan Akın - turkish translation
* Alessio D'Ascanio (otaku) - italian translation
* Alexander Alexiou (Santi) - greek translation
* Alexander Kjäll (capitol) - swedish translation
* Alexandr Menovchicov - russian translation
* Alfredo Beaumont (ziberpunk) - basque translation
* Ambra Viviani Loos - brazilian portuguese translation
* Americo Iacovizzi (DarkAmex) - italian translation
* Anders K. Madsen (madsen) - danish translation
* András Salamon ([[User:Ott|ott]]) - afrikaans, english and hungarian translation
* Andre Schmidt (schmidta) - german translation
* Anežka Bubeníčková (Bubu) - czech translation
* Ankka - finnish translation
* Anton Tsigularov (Atilla) - bulgarian translation
* Arkadiusz Danilecki (szopen) - polish translation
* Arne Deprez - dutch translation
* Artur R. Czechowski - polish translation
* Aurélien Brevers (Breversa) - french translation
* Azamat Hackimov - russian translation
* Bartek Waresiak (Dragonking) - polish translation
* Beer (Eddi) - hungarian translation
* Benoit Astruc - french translation
* Bjarke Sørensen (basher) - danish translation
* Boris Stumm (quijote_) - german translation
* BOrsuk - polish translation
* Cédric Duval - french translation
* Carles Company (brrr) - catalan translation
* Celso Goya - brazilian portuguese translation
* Christoph Berg (chrber) - german translation
* Claus Aranha - brazilian portuguese translation
* crys0000 - italian translation
* Dan Rosàs Garcia (focks) - catalan translation
* Daniel López (Azazelo) - catalan translation
* DaringTremayne - french translation
* David Martínez Moreno - spanish translation
* David Nečas (Yeti) - czech translation
* dentro - hungarian translation
* Enes Akın (yekialem) - turkish translation
* Erik J. Mesoy (Circon) - norwegian translation
* Eugenio Favalli (ElvenProgrammer) - italian translation
* Federico Tomassetti - italian translation
* Flamma - spanish translation
* Franciso Muñoz (fmunoz) - spanish translation
* François Orieux - french translation
* Gabriel Rodríguez (Chewie) - spanish translation
* Georgi Dimitrov (oblak)- bulgarian translation
* Gerfried Fuchs (Alfie) - german translation
* Gilluin - hungarian translation
* Guillaume Duwelz-Rebert - french translation
* [mailto:massart.guillaume_AT_wanadoo.fr Guillaume Massart (Piou2fois)] - french translation
* Guillaume Melquiond (silene) - french translation
* Hallvard Norheim Bø (Lysander) - norwegian translation
* Håvard Korsvoll - norwegian translation
* Huang huan (unicon) - chinese translation
* Ilya Kaznacheev - russian translation
* isazi - italian translation
* Iván Herrero (navitux) - spanish translator
* Jaka Kranjc (lynx) - slovenian translation
* Jan Greve (Jan) - german translation
* Jan-Heiner Laberenz (jan-heiner) - german translation
* Jean Privat (Tout) - french translation
* Jean-Luc Richard (Le Gnome) - french translation
* Jérémy Rosen (Boucman) - french translation
* Jesper Fuglsang Wolff (ulven) - danish translation
* Jonatan Alamà (tin) - catalan translation
* [mailto:jorda_AT_ettin.org Jordà Polo] (ettin) - catalan translation coordinator
* Jose Gordillo (kilder) - spanish and catalan translation
* Jose Manuel Gomez (joseg) - spanish translation
* Julien Moncel - french translation
* Julien Tailleur - french translation
* Julen Landa (genars) - basque translation
* Kai Ensenbach (Pingu) - german translation
* Kékkői László (BlackEvil) - hungarian translation
* Karol Nowak (grzywacz) - polish translation
* Katerina Sykioti - greek translation
* Kertész Csaba - hungarian translation
* Khiraly - hungarian translation
* kko - finnish translation
* Konstantinos Karasavvas - greek translation
* Kosif - turkish translation
* Kovács Dániel - hungarian translation
* krix - hungarian translation
* Lala - dutch translation
* Leo Danielson (Lugo Moll) - swedish translation
* Lim Choon Kiat - 林俊杰 - chinese translation
* Lukáš Faltýnek - czech translation
* Maarten Albrecht - dutch translation
* Mark Michelsen (skovbaer) - danish translation
* Mark Polo (mpolo) - latin translation
* Mark Recasens - catalan translation
* Mart Tõnso - estonian translation
* Martin Šín - czech translation
* Mathias Bundgaard Svensson (freaken) - danish translation
* Matias Parmala - finnish translation
* methinks - polish translation
* Michał Jedynak (Artanis) - polish translation
* Michel Loos - brazilian portuguese translation
* Mikel Olasagasti (Hey_neken) - basque translation
* Mintaka - czech translation
* Naoki Iimura - japanese translation
* Nico Oliver - afrikaans translation
* Nicolas Boudin (Blurgk) - french translation
* [mailto:Crazy-Ivanovic_AT_gmx.net Nils Kneuper] (Ivanovic) - german translation
* Nobuhito Okada - japanese translation
* [mailto:tapik_AT_buchtovi.cz Oto Buchta] ([[User:Tapik|tapik]]) - czech translation
* Pau Rul·lan Ferragut - catalan translation
* Paweł Stradomski - polish translation
* Paweł Tomak - polish translation
* paxed - finnish translation
* Petr Kopač (Ferda) - czech translation
* Petr Kovár (Juans) - czech translation
* [mailto:philippe.plantier_AT_naema.org Philippe Plantier] ([[User:Ayin|Ayin]]) - french translation
* Pieter Vermeylen (Onne) - dutch translation
* Pınar Yanardağ (moonquelle) - turkish translation
* Renato Cunha - brazilian portuguese translation
* Roel Thijs (Roel) - dutch translation
* RokStar - italian translation
* Roman Tuchin (Sankt) - russian translation
* Rudolf Orság - czech translation
* Ruben Philipp Wickenhäuser (The Very Uhu) - german translation
* Sérgio de Miranda Costa - brazilian portuguese translation
* Selim Farsakoğlu - turkish translation
* Sofronius - czech translation
* Spiros, Giorgis - greek translation
* Srecko Toroman (FreeCraft) - serbian translation
* Stefan Bergström (tephlon) - swedish translation
* Stephan Grochtmann (Schattenstephan) - german translation
* [mailto:susanna.bjorverud_AT_telia.com Susanna Björverud] (sanna) - swedish translation
* Susanne Mesoy (Rarlgland) - norwegian translation
* Széll Tamás (TomJoad) - hungarian translation
* Tiago Souza (Salvador) - brazilian portuguese translation
* Tobe Deprez - dutch translation
* Vít Komárek - czech translation
* Vít Krčál - czech translation
* Viliam Bur - slovak translation
* wint3r - swedish translation
* [mailto:ydirson_AT_altern.org Yann Dirson] - french translation
* Yuji Matsumoto - japanese translation
* Zas - french translation

== Other Contributions ==
* Ben Anderman (crimson_penguin) - unit list
* Dacyn - scenario designer
* Cyril Bouthors (CyrilB) - debian packager, patron
* Darryl Dixon - packager
* edge - packager
* Francesco Gigli (Jaramir) - wiki, wesnoth.slack.it
* Frédéric Wagner
* Jay Hopping - packager
* Jeff Breidenbach (Jab) - Bilinear interpolation
* Marcin Konicki (ahwayakchih) - BeOS packager
* Marcus Phillips (Sithrandel) - Mac OS X packager
* Mark Michelsen (skovbaer) - slackware packager
* Mike Quinones (Doc Paterson) - multiplayer maps
* Peter Groen (pg) - multiplayer maps
* Ruben Philipp Wickenhäuser (The Very Uhu) - multiplayer maps
* Tom Chance (telex4) - multiplayer maps, scenario balancing
* Sam Phillips (dark172) - creation of campains and multiplayer maps

{{Home}}

Talk:ReferencePythonAPI

2005-12-08T19:09:22Z

Ryo: /* Feature Requests */

Talk:ReferencePythonAPI

2005-12-08T18:53:09Z

Ryo: /* Feature Requests */

Talk:ReferencePythonAPI

2005-12-08T18:44:21Z

Ryo: /* Feature Requests */

WritingYourOwnAI

2005-11-28T19:13:30Z

Ryo: + PythonTestScript

== Writing your own AI ==

Wesnoth supports a pluggable AI system that allows programmers to write their own AIs in C++.

To write an AI, you need to derive a class from ''ai_interface''
(defined in '''ai.hpp'''), and implement the function ''play_turn()'' which will be called every time your AI is expected to play a turn.

Class ''ai_interface'' contains three important functions
which allow you to execute the three basic types of move available in the game:

* ''attack_enemy()'', which is used to order an attack on an enemy unit,
* ''move_unit()'', which is used to order a unit to move from one location to another, and
* ''recruit()'', which is used to recruit a new unit.

Of course, to decide where units are to move and attack, you must have information about the state of the game - the dimensions and layout of the map, the locations and type of units on the map, the types of units your side can recruit, and information about your allies and enemies.

Firstly, a type ''location'' is defined, which defines any location on the map. It has members ''x'' and ''y''. In '''pathfind.hpp''' there are a number of functions which will tell you useful things about locations -- whether two locations
are adjacent, all the locations adjacent to a certain location,
and the distance between locations.

A type ''move_map'' is defined as a ''std::multimap<location,location>''. Note that ''std::multimap'' is of course a standard C++ container, and cannot be documented here. http://www.sgi.com/tech/stl/ is a good reference on standard C++ containers. The purpose of a ''move_map'' is to show all the possible moves for a side. It can either be a ''source -> destination'' map, which associates the locations of all the units a side has to all the possible places they can move to, or a ''destination -> source'' map, which associates all the locations all the units a side has can get to, to all the places they are now.

The function ''calculate_possible_moves()'' is provided
as a useful utility function. It can give you maps for where all
your units can move, or where all your enemy's movements
can move when it's their turn. This is a very important
function to use to work out all the possible places your units can move to.

''ai_interface'' also defines an ''info'' type. This type contains a number of references to various game objects which you
will need access to in order to make moves. The two most important of these objects are the unit map (unit_map units)
and the game map (gamemap map).

The unit map is of type ''std::map<location,unit>''
and associates locations with units. This object can be used to find the location of, and information about, every unit on the board. See '''unit.hpp''' for a definition of the ''unit'' object.

The game map allows you to inspect the dimensions and layout of the playing board. Given a location, it can tell you the
terrain type at that location. See '''map.hpp''' for a definition of this object. You can combine this class with use of the functions in '''pathfind.hpp''' to find various
information about where units can move to.

The team class (defined in '''team.hpp''') is also very important. Each side is represented by a ''team'' object. The team object can tell you the gold balance of a team, which villages (note that internally, villages are often called 'towers') the team owns, what units the team can recruit,
and which other teams are this teams friends or enemies.

The utility function ''current_team()'' can be used to get a reference to the team that your AI is in control of, but you
can also use the vector ''teams'' inside the info object to get a list of all teams.

If you want to make your AI customizable within the configuration file, you can gain access to any parameters passed to your AI using ''team::ai_parameters()''. This returns an object of type ''config'' (see '''config.hpp'''). These ''config'' objects are representations of WML document fragments. When the user defines your side, if they put an [ai] tag inside it, everything inside the [ai] tag will be returned by ''team::ai_parameters()''.

== Using your AI ==

Finally, when you have your AI ready to go, you can add it to the ''create_ai()'' function in '''ai.cpp'''. Suppose you called your class ''killer_ai'', you could add it like so:

if(name == "killer_ai")
return new killer_ai(info);

Then, you can define a side to use your AI in [[ReferenceWML|WML]]:

ai_algorithm=killer_ai

and when that side is created, it'll use your AI!

== An example ==

Let us conclude with a small sample AI, called ''sample_ai''. How should this AI behave?

* First it should detect if there are any enemies in range,
and if there are it should attack them by moving onto the
best defensive terrain next to them. Attacks should be made with the weapon for which damage*strikes*chance to hit is
the highest.
* If there are no enemies in range, it should move units onto villages that don't already belong to it.
* If there are no enemies or villages in range, it should move toward the enemy leader along the shortest possible route.
* At the end of its turn, it should recruit random units until it runs out of money or doesn't have any space.

In the following example, I will place all functions in-line
rather than in the cpp file. To do this properly, of course you should put them in the cpp file. The entire definition of this AI can be found in '''ai.cpp''' and '''ai.hpp''' in the source distribution.

We start the definition,

class sample_ai : public ai_interface {
public:
sample_ai(info& i) : ai_interface(i) {}

We have defined the constructor which takes an ''info'' object
and passes it straight onto ai_interface. We don't need to
store anything ourselves in this simple AI. (Although it would be fine to have data members if we wanted them.)

Next we define the main function, ''play_turn()'':

void play_turn() {
do_attacks();
get_villages();
do_moves();
do_recruitment();
}

Just a series of calls to functions we are about to write which do the actual work. Firstly, ''do_attacks()''. We start by
calculating all the moves our units can make:

private:
void do_attacks() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Note that the ''possible_moves'' thing is of little direct interest. It contains details of exactly which tiles the unit
moves along to get from one tile to another. This is useful for the display to know about when it draws the unit moving, but as an AI programmer, it's not likely you'll ever care about
what it contains. Just pass it along to the ''move_unit()'' function so it can draw the unit moving along the correct path.

The things we're interested in are ''srcdst'', and especially ''dstsrc'', which will tell us all the hexes our units can reach.
We want to check if any of these hexes are next to an enemy unit. Let's walk over the units and see if we can reach any of them:

for(unit_map::const_iterator i = get_info().units.begin(); i != get_info().units.end(); ++i) {
if(current_team().is_enemy(i->second.side()) {

We're iterating over all units, but we're only interested in units that are enemies of our side. So, we access our team object, and ask if the side the unit is on is an enemy. If it is, then we're interested in seeing if any of our units can move to a hex that's adjacent to the enemy unit. We do this by getting the six locations around the enemy unit:

location adjacent_tiles[6];
get_adjacent_tiles(i->first,adjacent_tiles);

This kind of call is very common in the game's code -- make an array of 6 locations, and fill them up with the locations adjacent to a certain location. We actually want to find the position to attack from which gives our unit the best possible defense. So, we initialize some variables to find the best possible defense:

int best_defense = -1;
std::pair<location,location> best_movement;

The value of ''best_defense'' will of course be between 1 and 100, but we give it a value of -1 to mean 'not initialized', since we haven't found any possible attacks at all yet. Variable ''best_movement'' will contain the destination/source pair that gives the best possible defense for our attacking unit.

for(size_t n = 0; n != 6; ++n) {
typedef move_map::const_iterator Itor;
std::pair<Itor,Itor> range = dstsrc.equal_range(adjacent_tiles[n]);

If you don't understand how ''equal_range'' works, then look up documentation on how the standard container multimap works. ''range'' now refers to all the possible movements that can end
with our unit being at ''adjacent_tiles[n]''. Let's iterate over all those movements, and find if any of them give a better defensive rating than our current best defense. We'll start our iteration by creating some aliases that ensure we don't go crazy ;)

while(range.first != range.second) {
const location& dst = range.first->first;
const location& src = range.first->second;

Now let's find out about the unit that we're planning to send to this destination:

const unit_map::const_iterator un = get_info().units.find(src);
assert(un != get_info().units.end());

We can assume that the unit is in that location (hence the assert), because ''calculate_possible_moves()'' said that it's the possible source of a move. Let's find out the type of terrain we're planning to move to:

const gamemap::TERRAIN terrain = get_info().map.get_terrain(dst);

Okay, so we have the unit, and we have the terrain, now we should be able to find out the unit's defensive rating on this terrain.
The ''unit'' class has a convenient ''defense_modifier()'' function which will tell us the chance of hitting that unit on a certain terrain.

const int chance_to_hit = un->second.defense_modifier(get_info().map,terrain);

So, now we have all that, if it's the best chance to hit we've seen so far, or we haven't seen any other chances to hit at all, then we add it as our best option seen.

if(best_defense == -1 || chance_to_hit < best_defense) {
best_defense = chance_to_hit;
best_movement = *range.first;
}

That's it for these two loops. Iterate and close:

++range.first;
}
}

Now if we found a possible move, best_defense will not be -1,
and the movement will be stored in ''best_movement''. So, if ''best_defense'' is -1, we want to move from ''best_movement.second'' to ''best_movement.first''.

if(best_defense != -1) {
move_unit(best_movement.second,best_movement.first,possible_moves);

Remember that ''possible_moves'' thing? That comes in useful here, where we have to give it to the display object so it can know the path to move the unit along. This is the only time we need to touch it.

Immediately after moving, we want to attack. First we need to know which weapon to use. We'll write a ''choose_weapon()''
function later which will choose our weapon. It'll have to take the location of the attacker and the location of the defender, and it'll return an int referring to our weapon of choice. For now we'll just make use of this function:

const int weapon = choose_weapon(best_movement.first,i->first);
attack_enemy(best_movement.first,i->first,weapon);

This will implement our attack. What now? We've attacked once, but we want to attack with as many units as we can attack with, right? We can't use the same move_maps again, because they'll be invalid now that we've moved and attacked. What we'll do is we'll call ''do_attacks()'' all over again, recursively, and return immediately. This way all our maps will be recalculated.

do_attacks();
return;
}
}
}
}

That's the entire function done. It'll keep attacking while it finds attacks, and when it finally runs out of attacks to execute, it'll return nicely. Let's write that ''choose_weapon()'' function now:

int choose_weapon(const location& attacker, const location& defender) {
const unit_map::const_iterator att = get_info().units.find(attacker);
assert(att != get_info().units.end());

const std::vector<a ttack_type>& attacks = att->second.attacks();

unit contains a convenient ''attacks()'' function which returns a vector of all a unit's possible attacks. We'll store the
best attack found so far, and iterate over all attacks:

int best_attack_rating = -1;
int best_attack = -1;
for(int n = 0; n != attacks.size(); ++n) {

There is a nice function called ''evaluate_battle_stats()'' in '''actions.hpp''' which will give us all sorts of information about a potential battle. We make use of it here:

const battle_stats stats = evaluate_battle_stats(get_info().map,
attacker, defender, n, get_info().units,
get_info().state, get_info().gameinfo, 0, false);

A rather complicated function call, but most of the parameters can be pulled straight from ''get_info()''. The last two parameters are a little confusing. The first one of these, ''attacker_terrain_override'', is used if we wanted to know what the combat would look like if the attacker was on different terrain to what it is on now. If this is non-0, the function will assume the attacker is on the type of terrain given. This is useful if you want to test the possibility of moving to many different hexes without actually moving there. The last parameter is false, meaning that strings won't be included in the results. Strings are useful for showing to a player in a dialog,
but not useful for an AI, and are expensive to calculate, so this should always be false from within AI algorithms.

Let's use our stats to come up with a rating for this attack:

const int attack_rating = stats.damage_defender_takes*stats.nattacks*stats.chance_to_hit_defender;

Now if this is the best attack, we can use it,

if(best_attack == -1 || attack_rating > best_attack_rating) {
best_attack = n;
best_attack_rating = attack_rating;
}
}

return best_attack;
}

Now we're done with that, we can move onto our ''get_villages()'' function. We start off by calculating possible moves,

void get_villages() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Now it's a simple matter of iterating over possible destinations,
and seeing if they are villages not controlled by us:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
if(get_info().map.is_village(i->first) &&
current_team().owns_village(i->first) == false) {

First it checks whether the destination is a village. The right side of the ''&&'' simply sees if our team owns the village at that location or not. If we don't own the village, we've found the movement we want to make, and we recurse and return.

move_unit(i->second,i->first,possible_moves);
get_villages();
return;
}
}
}

Just a couple more functions now. Firstly, ''do_moves()'' is meant to move our units toward the enemy leader. Well, there may be multiple enemies and thus more than one leader, so we'll just go for the first enemy leader we can find. We start off by trying to find the enemy leader:

void move_units() {
unit_map::const_iterator leader;
for(leader = get_info().units.begin(); leader != get_info().units.end(); ++leader) {

A unit is a leader if it can recruit -- so we use the ''can_recruit()'' function to test if it's a leader.

if(leader->second.can_recruit() && current_team().is_enemy(leader->second.side())) {
break;
}
}

We better have found an enemy leader, otherwise we'll just return...

if(leader == get_info().units.end())
return;

Now, let's find all our unit's possible moves:

std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

We want to find the move that'll take us as close as possible to the enemy leader. Let's make our variables to show us the best move so far,

int closest_distance = -1;
std::pair<location,location> closest_move;

Now iterate and find the destination closest to the enemy leader:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
const int distance = distance_between(i->first,leader->first);
if(closest_distance == -1 || distance < closest_distance) {
closest_distance = distance;
closest_move = *i;
}
}

If ''closest_distance'' is not -1, we've found a valid move that'll take one of our units toward the enemy leader. We can make the move and recurse

if(closest_distance != -1) {
move_unit(closest_move.second,closest_move.first,possible_moves);
do_moves();
}
}

Okay, all our movement functions are done! Now all we've got left is the recruitment function. We start by getting the units that we can recruit.

void do_recruitment() {
const std::set<std::string>& options = current_team().recruits();

We can choose the number of a unit to recruit at random:

const int choice = (rand()%options.size());
std::set<std::string>::const_iterator i = options.begin();
std::advance(i,choice);
const bool res = recruit(*i);

And if the recruitment succeeds, we will try to recruit another unit,

if(res) {
do_recruitment();
}
}
};

That's it! We've made our ''sample_ai''. All we have to do is add it to ''create_ai'' in '''ai.cpp''' and we're done!

== AI - specific parameters ==

wesnoth --multiplayer --controller1=ai --controller2=ai --algorithm1=z_ai --algorithm2=sample_ai

Use the ''--nogui'' switch before ''--multiplayer'' to make the game run without displaying a GUI. The winner will be reported on stdout.

== See Also ==

* [[DeveloperResources]]
* [[PythonTestScript]]

StartingPoints

2005-11-01T15:23:22Z

Ryo: /* Tweaking the Game (Create) */ add Python API

__NOTOC__
Battle for Wesnoth is a turn-based fantasy strategy game.

Defeat all enemy leaders using a well-chosen cadre of troops,
taking care to manage your resources of gold and villages.
All units have their own strengths and weaknesses; to win,
deploy your forces to their best advantage while
denying your foes the chance to do the same. As units gain
experience, they acquire new abilities and become more
powerful. Play in your own language and test your skill
against a smart computer opponent, or join Wesnoth's large
community of on-line players.
Create your own custom units, scenarios or campaigns,
and share them with others.

Battle for Wesnoth is released under the
[http://www.gnu.org/licenses/licenses.html#GPL GPL].
Prebuilt packages are available for most operating systems,
including Windows, Mac OS X, and GNU/Linux, or you can build
your own from source code.

== Getting the Game ==
==== Downloading ====
* [[Download]] - get the most recent source-files and many binaries
** [[WesnothBinaries]] - precompiled for GNU/Linux, BeOS, PDAs, ...
** [[WesnothBinariesLinux]] - precompiled for many GNU/Linux distributions

==== Compiling ====
* [[CompilingWesnoth]] - on Unix, Mac, Windows, GNU/Linux, PDAs, ...
* [[DebuggingWesnoth]] - on GNU/Linux and Unix-like systems
* [[WesnothOnLinuxPDAs]] - on the Qtopia/OPIE and thepdaXrom/Zaurus C series

== Playing the Game ([[Play]]) ==

==== For New Players ====
* [[GettingStarted]] - read me first!
* [[WesnothManual]] - the rules
* [[MainlineScenarios]] - walkthroughs for the game-supplied campaigns

==== For Not-So-New Players ====
* [[AdvancedTactics]] - beating the AI and other people
* [[MultiplayerServers]] - where to play against other people online

==== Reference ====
* [[HotKeysSystem]] - keyboard shortcuts
* [[CommandMode]] - commands you can use in-game
* [[ServerAdministration]] - commands that authenticated users can use to administer the server
* [http://wesnoth.slack.it/units.cgi Units] - Units stats and advance trees
** [http://wesnoth.slack.it/units.cgi?page=frames Wesnoth Unit List]
** ([http://wesnoth.slack.it/units.cgi?page=list without frames])
** [http://wesnoth.slack.it/units.cgi Experience Tree]
** [http://wesnoth.slack.it/units.cgi?factions Factions]
** [http://wesnoth.slack.it/units.cgi?movetypes Movement, defense and resistance tables]
* [[RaceDescriptions]] - Elves, Humans, Dwarves, Orcs, Drakes, Undead, Others
* [[GraphicLibrary]] - unit and terrain images posted on the forums
**[[UnsortedContrib]] - Unsorted Contributions
**[[GameArt]] - Art for the main game
* [[WesnothAcronyms|Wesnoth Acronyms (by category)]] - common wesnothian acronyms explained
* [[WesnothAcronyms(alphabetic)|WesnothAcronyms (alphabetic)]] - common wesnothian acronyms explained

== Tweaking the Game ([[Create]]) ==

* [[UserScenarios]] - user-written scenarios, campaigns and game modifications
* [[ReferenceWML]] - all about Wesnoth Markup Language
* [[ReferencePythonAPI]] - upcoming Python interface for AI
* [[BuildingCampaigns]] - how to make your own campaigns
* [[BuildingScenarios]] - how to make your own scenarios
*[[BuildingUnits]] - how to make your own units
* [[WesnothMapEditor]] - summary of controls
* [[CastleTutorial]] - how to create tileable castles and other castle-like tilesets
* [[ExternalUtilities]] - scripts to help create scenarios, campaigns, and graphics
* [[UnitAnalysis]] - tool to analyze units

== Improving the Game ==
* [[ReportingBugs]] - use Gna
==== Developer information ====
* [[DeveloperResources]] - useful links
* [http://changelog.wesnoth.org Changelog] - the most recent changes made to the game
* [[WesnothCVS]] - accessing the source code
* [[HackingWesnoth]] - guide for programmers
* [[CodingStandards]] - for programmers
* [[UnitDescriptionRewriting]] - coordinating the revision
* [http://wesnoth.slack.it/missing.cgi Missing unit animations and sounds] - what's available and what's missing
* [[WritingYourOwnAI]] - write a C++ plugin
* [[ThemeSystem]] - customizing the screen layout for the game and the editor
* [[ReleasingWesnoth]] - steps to follow to release a new version
* [[WesnothPackagersGuide]] - guidelines for packaging Wesnoth for different platforms
* [[WesnothPreferences]]

==== Game translations ====
* [[GettextForTranslators]] - how to translate Wesnoth under [[GetText]]
* [[WesnothTranslations]] - 11 complete, 2 almost complete, 7 more than halfway, 10 partial
* [[WesCamp]] - a project for translating user-made campaigns

==== Ideas ====
* [[FrequentlyProposedIdeas]] - before you propose an idea, check here!
* [[NewUnits]] - units that exist only in theory
* [[NewTerrains]] - tile status
* To submit a feature request, use http://bugs.wesnoth.org

== About the Game ==
* [[WesnothPhilosophy]] - Dave on Wesnoth
* [[WesnothHistory]] - the Ages of Wesnoth
* [[WesnothGeography]] - description of Wesnoth and surrounding lands
* [[WesnothReviews]] - third party reviews of Wesnoth
* [irc://irc.wesnoth.org/wesnoth #wesnoth] - our IRC channel

== Other ==
* [[UsefulLinks]]
* [[WesnothLSM]] - presentation at LSM
* [http://wesnoth.slack.it/?WesnothPlayerMap Wesnoth player's map] - add yourself to the map!
* [http://en.wikipedia.org/wiki/Battle_for_Wesnoth Wikipedia entry for Wesnoth]
* [[WikiMigration]] - we are looking for a replacement

== About this Wiki ==
* [[Help:Editing|Editing]] - learn how to edit pages
* [[Sandbox]] - experiment with the wiki