FIXME++

[omaha.git] / README

Omaha board game GUI
====================

Omaha is a (wannabe) GUI to play arbitrary board games, aiming to be
completely extensible by plugins.

Primary purpose is trying ideas about a tagua/kaya-like GUI suitable
for inclusion on OpenMoko devices (that meant, no ruby and not forcing
the use of kde), so that I can get a suitable goban to help in
studying games while in the train. And since Qt is not included by
default in om2009 or shr, not forcing qt either - so for now it is
using gtk, although it should be easy to add support for other GUI.

Secondary purpose is to experiment with various programing techniques
in python, like the component-oriented approach (others to come, like
design-by-contract).

Homepage: https://alioth.debian.org/projects/omaha/

Copyright and license
=====================

Omaha is Copyright (c) 2009-2015 by Yann Dirson <ydirson@free.fr>.

    This program and its libraries are free software; you can
    redistribute them and/or modify it under the terms of the GNU
    Lesser General Public License as published by the Free Software
    Foundation; either version 2.1 of the License.

    This program and these libraries are 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 Lesser General Public License for more
    details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
    02110-1301 USA

plugins/Games/Chess.png:
    32x32/apps/tagua.png from oxygen-icon-theme, LGPL v3
plugins/Games/Chess5x5.png:
    22x22/apps/tagua.png from oxygen-icon-theme, LGPL v3
plugins/Renderers/Pieces/FantasyChess:
    tagua FantasySVG theme from Maurizio Monge, GPL v2
plugins/Renderers/Pieces/SVGShogi/tile.svg:
    lib/plugins/shogi/pics/tile.svg from kaya, GPL v2


Dependencies
============

To use omaha, currently you will need at least:

- python 2.7, or 2.6 with argparse module (not python3 yet)
- distutils-extra (tested with v2.38)
- pyxdg (tested with v0.19)
   v0.15 (Debian lenny) seems to work once the DesktopEntry.__cmp__ method
   has been deleted from xdg/DesktopEntry.py (causes infinite recursion).
- flufl.enum (tested with v3.3.2 and v4.0.1)
- pygtk (tested with v2.14.1, but 2.4 may be sufficient)
- pygobject (tested with v2.20.0)
- pycairo (tested with v1.8.6)
- gnome-icon-theme (tested with v3.12.0) [Note for Ubuntu: this requires the
  gnome-icon-theme-full package)

For SVG rendering with gtk:
- python-rsvg (from gnome-python-desktop, tested with v2.26.0)

For Shogi tiles traditional rendering:
- a font with the suitable Kanji characters (eg. "WenQuanYi Zen Hei")

To read PGN files:
- pyparsing (tested with v2.0.1)

To play against the computer:
- gnuchess, fairy-max or another xboard-compliant Chess engine
- gnushogi
- gnugo or another GTP2-compliant Go engine
- hachu

For the experimental Qt4 support:
- pyqt4 (tested with v4.9.1)

To run the unit tests:
- nose (tested with v1.1.2)

To run the automated UI tests:
- dogtail (tested with v0.8.1)
- at-spi2-core 2.6.3 or 2.7.3 or better (tested with 2.7.91.  2.5.3 in
  Debian wheezy is known NOT to work)

Tested static analysis using pylint 1.3.1 (1.4.0 has a known bug
preventing full testing).  Before 1.2.1 commandline flags are required
to make use of the Overlord.pylintx plugin.


Implementation status of available games
========================================

Here is a (possibly incomplete) status for each game known to Omaha,
including a list of things each game lacks to be touted as "properly
supported".  Are considered "blockers" the problems which prevent some
legal moves to be made - when no blocker remains, some "missing
checks" may remain, when some illegal moves are accepted by the Omaha
implementation.

Checkers
--------

Blockers:
- a king capturing should be allowed to land on any free tile
Missing checks:
- forced captures (let alone "force longest capture")
- moves should be auto-finalized when detected as forced
- moves could be auto-finalized when detected as valid
Visual issues:
- feedback for move being composed
Game-file formats: none yet
AI: none yet

Shogi and MiniShogi
-------------------

Blockers: none known
Missing checks:
- drop checks
- forced promotion
- checkmate
- no-repeat rule
Visual issues:
- proper theme
Game-file formats: PGN (shogi only for now)
AI:
- XShogi protocol (gnu(mini)shogi)
- XBoard protocol (gnu(mini)shogi 1.5.x, SjaakII)

Sho Shogi
---------

Blockers: none known
Missing checks:
- CrownPrince should be a royal piece (not a big problem because we lack
  "in-check" check, would become a blocker when we implement it)
- all other missing checks for Shogi
Game-file formats: none yet
AI:
- XBoard protocol (HaChu, SjaakII)

Tori Shogi
----------

Blockers: none known
Missing checks:
- drop checks
- forced promotion
- checkmate
- no-repeat rule
Visual issues:
- kanji tiles do not distinguish left- from right-quail
Game-file formats: none
AI: none

Chess and Chess5x5
------------------

Blockers: none known
Missing checks:
- checkmate, stalemate
- no-repeat rule
Visual issues: none
Game-file formats: PGN (Chess only, export not conformant with "PGN
  export", but with "PGN import)
AI: XBoard protocol (GNU Chess, Fairy-Max, SjaakII)

Go
--

Blockers:
- no territory counting
Missing checks:
- placed stone is not dead
- ko
Visual issues:
- rendering of captures
Game-file formats: SGF
AI: GTP2 (gnugo, etc.)

Gliński's hexagonal Chess
-------------------------

Blockers:
- different rule for startup boost
- promotion
- en-passant
Missing checks:
- checkmate, stalemate
- no-repeat rule
Visual issues: none known
Game-file formats: none yet
AI: none yet


Running tests
=============

Unit tests
----------

Run "nosetests" from the shell to run all tests expected to pass.
Run "nosetests -a known" to also run tests known to fail.

UI tests
--------

Make sure AT-SPI is activated on your desktop, by running "gconftool
--type bool --set /desktop/gnome/interface/accessibility"

First, run omaha, ensuring you have a single omaha instance running.
Make sure it uses the C locale, and make sure Gtk2 apps are starting
with accessibility support:

 LC_ALL=C LANGUAGE= GTK_MODULES=gail:atk-bridge ./scripts/omaha

Do not open any window besides the launcher; then run:

 ./scripts/uitest.py


Rough architectural overview
============================

Note that this description is still partial, and the architecture
itself is still a moving target.  Use "git blame" on this section to
identify the version of the code that it is supposed to describe.

All our classes are under the Omaha namespace, which we will omit in
this doc for the sake of readability.  Hence when we refer to
Core.Game, we really mean Omaha.Core.Game, and so on.

Game stuff
----------

The central class is the Core.Game class, tying together all other
parts.  Each type of game playable with Omaha (chess, checkers, etc)
is described by a subclass of Core.Game (eg. Games.Chess),
encapsulating all the knowledge of this particular game's mechanism.
To help sharing behaviour common to several games, several (abstract)
Game classes are provided (eg. Games.abstract.GenericChesslikeMoves,
Games.abstract.SingleBoardGame, Games.abstract.RectBoardGame), which
other Core.Game subclasses can reuse by (possibly multiple)
inheritance.

The games supported in Omaha make use of players (instances of
Core.Player created by the Game instance), game-specific pieces
(instances of a subclass of Core.Piece, available as class member "Piece"
inside the Core.Game subclass) and what we call "piece holders" for
lack of a better name (subclasses of Core.PieceHolder).  The latter includes
boards, bags, and other pools, in which pieces may be stored
(eg. Holders.RectBoard.RectBoard and Holders.Pool.PiecePool).

A game is a succession of moves (instances of a subclass of
Core.Move), done by each player on its turn.  All current Move
subclasses deal with moving pieces.  To allow dealing with the largest
set of games and to allow other plugins to be tied as little as
possible to specific games, the Omaha core provides very fine-grained
Move subclasses, such as moves where a piece is simply moved from one
location to another (Core.SimpleDisplaceMove), moves where pieces have
to go through other locations before reaching their target
(Core.WaypointDisplaceMove), moves where new pieces are just put on
the board (Core.PutOnlyMove) - and all those classes share behaviour
through more abstract classes.

Moves, like pieces, are game-specific, available as an attribute of
the Game subclass.  They are initiated by a Core.PlayerDriver instance
(eg. PlayerDrivers.MouseSingleClick for controlling a player through a
GUI, or Player.GnuShogi for controlling using an external gnushogi
program).

Plugability
-----------

Lots of things in Omaha can be added as plug-in without changing the
code.  At this time this include subclasses of the following Core classes:
 * Game
 * PlayerDriver
 * GameRenderer, HolderRenderer, PieceRenderer

Plugins can also define new types of plugins for their own use.
Eg. those that are subclasses of Renderers.Pieces.abstract.StackedVector
are skinable through the use of "PieceSkin" plugins.

A plugin is declared to Omaha using a Desktop Entry (.desktop) file as
defined by FreeDesktop.org.  For this we define our own set of
DesktopEntry types (eg. X-Omaha-Game, X-Omaha-GameRenderer,
X-Omaha-HolderRenderer), as well as a number of custom fields for our
purpose.

Plugin declaration files are looked for in
/usr/share/games/omaha/plugins/ (which is structured by plugin type
for convenience, although the location within that tree is ignored).
For developing, and for people wanting to run from the source tree, a
"plugins" directory in the current working directory is used instead
if it is found.

The following standard fields are used:

 Name, Name[xx]      : name displayed to the user
 Type                : type of plugin (X-Omaha-*)
 TryExec             : (optional) only enables the plugin if this program is found
 Icon                : (optional) may be displayed by the UI
 Comment, Comment[xx]: (optional) may be displayed by the UI

The following fields are defined for all Omaha plugins, unless
otherwise stated:

 X-Omaha-ID          : identifier for the plugin, should be unique

 X-Omaha-*-Categories: with which other plugins of given type this plugin is
                       compatible, see description of specific plugin types
                       for details.

Most plugins are implemented by a python class.  Those also provide:

 X-Omaha-Package     : python package holding the plugin implementation
 X-Omaha-Class       : name of the class inside the package specified by
                       X-Omaha-Package

Other specific fields are available for specific plugin types.
FIXME: to be written

Parameters
----------

Most plugins and instances of other Omaha classes can take parameters.
Classes whose instances may take parameters are subclasses of
Core.Parametrizable.  Values for those parameters can usually be
changed via the "preferences dialog".

Basically, the set of parameters taken by a Core.Parametrizable
instance are retrieved by the parameters_decl() class method (which
returns a dict of Overlord.ParamDecl keyed by string parameter
identifiers or "paramid"), and a specific set of parameters is applied
to an instance through the set_params() method.

The parameters_decl() method only has to add new parameters to the one
specified by parent classes.  Symetrically, the set_params() method
passes to the parent classes' set_params() only the parameters that it
did not use itself.

But indeed things are slightly complicated by the fact that some
parameters depend on others - eg. the "PieceRenderer" parameter in a
GameRenderer subclass is not the same for Chess and Go: they do not
allow to choose from the same set of choices, and must be stored
separately in the preferences.  So a given parameter
(Overlord.Param) is tied not only to its parameter declaration, but
also to a set of so-called "meta-parameters" ("metaparams" for short),
and set_params() expects as argument a dict of Param instances keyed
by a (metaparams, paramid) tuple.

The set of metaparams meaningful to a given Parametrizable is
available through the metaparams_set property.  It is a set object,
whose elements are frozendict objects (dict-like objects suitable for
inclusion in a set).  A commonly-used metaparam is the "gameclass"
one, whose value in the frozendict is as expected the class of the
game being played.

The parameters_decl() method takes a metaparams argument and only
returns the ParamDecl's which require compatible metaparams.  For this
reason, simple parameters which do not need any metaparams are tied to
an empty metaparams frozendict.

The Preferences system is naturally built on the Parametrizable stuff.
Omaha has a single Preferences repository (today only kept in memory,
but which is intended to be saved on disk for persistence once we are
sure it is adequate), which stores those parameters and the metaparams
they are related to, from one game to another.

UI stuff
--------

The Omaha UI is centered around Core.UI.App: a Core.Launcher App
allows to launch Core.GameApp subclasses.  Both Core.Launcher and
Core.GameApp are subclasses of Core.UI.App, which ties then to a
Core.UI.Toolkit implementation.

A GameApp creates a Game object, a GameRenderer object that usually
takes care of on-screen drawing, and PlayerDriver objects which send
their moves to the Game object.

A Game object usually has at least one Holder object - a board, and
board types may be shared by many games, the rendering of which is
usually delegated by a HolderRenderer, allowing to share board
rendering code among games.  This is handled by the
Core.HolderDelegatingGameRenderer class, from which are derived all
currently included game renderers.

Similarly, the Core.PieceDelegatingGameRenderer class allows to remove
that other game-specific aspect from GameRenderer, making it possible
to write really generic renderers suitable for many games
(eg. Renderers.FullscreenPieceDelegating).

On the graphical side, the idea is that renderers can be of several
types: plain and simple first for early implementation testing,
skinable 2D renderers (eg. reusing themes from tagua/kaya and other
GUIs out there), skinable 3D renderers, and whatever renderers one
would want to plug in.

Source organization
-------------------

TBW


HOWTO add a new UI Toolkit to Omaha
===================================

- for convenience, let's say you want to add support for a toolkit
  named Foo

- put a minimal launcher stub in place, which in turn requires a stub
  Toolkit implementation, so that "./scripts/omaha --toolkit=Foo" is
  minimally happy

- get an eventloop started, and a minimal window displayed

- add presentation of the available games, a "play" action, and a stub
  "play game" app

Most games have parameters, so the natural next step is to implement
toolkit widgets:

- the most common widgets used for game params is the IntWidget, but
  you will need to implement the Toolkit's open_params_dialog() and
  create_param_widget() methods to make them useful.

- the ChoiceWidget is used a lot too, and its basic functionnality of
  displaying choices and yielding corresponding value is quite easily
  implemented.  More complex behaviours (disabled choices and
  sub-parameters) can be left for later.

Now that we can start any game and switch settings at will, we can
go on to the canvas manipulation:

- let FooPlay._create_gui() instanciate a canvas, and teach
  Toolkit.Foo to find colors

- catch mouse events in the canvas.

  Event handlers are registered on mouse events (press, release,
  move), are called in turn in undefined order, and must return a true
  value when they have handled the event, to avoid propagating it to
  remaining handlers.

- let the canvas refresh handler call the renderer

  ... and deal with the parts the actual redraw relies on.  After
  fill_rectangle, draw_rectangle, draw_line, draw_ and fill_circle
  already allow to render some games.

  AsciiShogi renderer will help test implementations of draw_polygon
  and draw_centered_text.  Since we did not implement renderer
  switching yet, a local change to plugins/Games/Shogi.desktop will
  help.

- add SVG rendering: the default Chess renderer uses a StackedVector
  piece renderer, which renders SVG to a bitmap; we thus need to
  provide a BitmapImage on which we can draw, and a VectorImage
  implementation with a render_to_bitmap() implementation.  A
  Foo.draw_image() implementation is required to finish the work.

Other stuff to gradually implement:

 - icon support in launcher
 - disabled choices and sub-parameters in ChoiceWidget

- etc.; old guideslines read:
  - implement the required Omaha.GUI methods (UI itself, event-loop, and
    canvas drawing).
  - gradually add support for other features:
    - player driver setup


HOWTO add a new game to Omaha
=============================

TBW


Short term TODO list
====================

Bugs to report
--------------

- distutils-extra:
  - does not include MANIFEST.in
  - "unrecognized files" warning has:
    - false positives (files from MANIFEST.in, package_data)
    - false negatives (.coveragerc, .version, COPYING)
- distutils 2.7:
  - does not allow to use dotted notation in package_data
    (must use non-intuitive "/" instead)
- gnuchess issues "resign" after moving

Known bugs
----------

- setting up MultiplexerPlayerDriver gives "No sane default" warnings
- XBoard/CECP return error messages on unsupported commands, we should
  find a way to use them, eg. to stop an "edit" before we send edit
  instructions
- all royal pieces are reported as "king" when .checking_piece()
  returns non-None
- player controls like "resign" should only be active when there is a
  human player (currently we can make an AI resign)

- Linking class to desc through 'x-plugin-desc' is broken when using
  parameter specialization (several plugin descs for a single class).
  Causes a Go game launched after a Go19 game to get a window called
  "Go 19x19", since we use the plugin desc for the name; causes
  param-dialog defaults to be wrong because one class can only point to
  a single plugin; etc.
   => must instantiate a plugin subclass on parameter specialization
- A player driver by GNU Chess gets a default of Fairy Max in the "player
  control" dialog (same problem ?)
- default playerdriver leaks from chess to chess5x5 if the former is
  added a X-Omaha-DefaultPlayerDriver and is used first (same problem ?)
- depends_on handling is broken when one param depends on several others,
  but luckily we do not need that yet (see pylint's cell-var-from-loop
  warning)

- Go: PASS moves in go trigger PutMove assert_locations to complain about
  self.__target
- Chess: castling moves are not forbidden when the king lands in check
- HorizontalHexDots does not implement point_to_location
- SquareDots does not catch IndexError when the cursor is on non-existent
  tiles
- prefs window is not closed when game window is
- Generic PlayerDrivers (XBoard, etc) support a fixed set of variants,
  plugin should reflect that
- castling not refused if it puts the king in check

- playerdriver params change of current field not validated on "OK" ?
- stray engines must be terminated
- overwriting file while saving requires confirmation
- PieceNotation should refer to a PieceSet, not to a Game
- an engine declaring the game is a draw without the other noticing
  blocks the game
  - AI/AI game gets stuck, UI should show a cue (eg. gnushogi vs. itself
    at low depth)
  - AI/human game : human should be presented proposed outcome
- engine init through game position should pass more game state
  (cf. setboard for xboard; ko status for go)
- stream-callback mechanism is deeply flawed:
  - cannot attach a handler to more than 1 stream
  - support for error conditions should be improved (cannot distinguish
    between error conditions, Gtk behaviour is strange)
- playerdrivers do not handle broken pipe on write
- Checkers with odd boardsize puts pieces on white squares instead of
  black ones
- Games.FreePlay has been broken since 5e66377cb (removal of
  Game.holder_classes had been necessary to fit this class into the
  existing framework).  OTOH, 74cdead67 and 0d9144a7e were made possible
  precisely by reintroducing them.  Sigh.

- closing the Gtk Launcher window quits without killing any running AI
- AI plugins not robust to missing program
- game setup should include initial playerdrivers choice (esp. because
  of handicap settings)
- assertion when looking at captured stones when feeding position to
  gtp engine

- the game window should have a minimum size
- using fullscreenpiecedelegating for go, or
  using fullscreenpoolpiecedelecating with chess etc causes
  exception
- holder renderer when openning prefs dialog is set to default, not
  current
- fullscreenpoolpiecedelegating does not display shogi pieces in
  correct orientation
- race condition at PlayerDriver init eg. causes problem when 2 gnushogi
  at low depth battle each other (not anymore?)
- events triggering PlayerDriver moves should be flushed when meaningful,
  to avoid them to be taken into account on next turns ?
- Should display warning for 2 plugins with same name.
- UI.PluginChoiceWidget() does not include Holder key in context

- uitest assumes that "Location:" field is always available, which is
  apparently not true by default

Milestone 0.1 (first public announcement)
-------------

* Short-term goals (including a number of things otherwise listed
  below)

- Go needs piece-stacking pool renderer
- Piece-stacking pool renderer requires Highlighter refactoring
- Highlighters (things done in t/highlight) requires a way to specify
  default colors for hl roles, or at least a persistent prefs system
- specifying default colors for hl roles is really close to a
  persistent prefs system
- persistent prefs system requires bare param values in preferences
- bare param values in preferences requires bare param values everywhere
  in set_params
- bare param values in set_params was done by leveraging @parameter, and
  the latter has to be generalized for HolderRenderer-*.  Possibly use
  a special form of parameter, where the value is a dict - need to think
  about how to deal with the dict's keys.

- full use of @parameter (proper override of boardwidth and
  boardheight) in SquareBoardGame requires pinning a parameter decl in
  a subclass
- pinning (or otherwise refining) a parameter decl in a subclass
  requires a way to clone a ParamDecl (done)
- parameter pinning works only by chance
  - pinned_value's should be set from X-Omaha-Parameter-* in Overlord.Plugin.Class()...
  - ...but a Parametrizable does not cache its parameter's decls
  - special-casing of pinned params should only occur in walk_action, not in
    walk_params or PluginChoiceWidget or GtkChoiceWidget, but in fact today only
    PluginChoiceWidget seems to matter

- split XBoard in CECP protocol and GnuChess support


* finish drawing context implementation

- make DrawingContext a standalone class ?
- add a GameRenderer.rotation parameter
  - layout computation
  - inverse transformation for mouse
- per-holder rotation
  - draw pieces in a per-holder fashion,
  - draw pieces relative to holder, use drawing context for the board offset
  - demonstrate with a 3-player game made of 3 2-player games
- fix the issue of drawing_context for move highlighting


* essential user-visible features:

- finer expose events to avoid the need to always redraw everything
- Toolkit support for asynchronous notifications

- Add more filter types
  - MoveHighlighters may depend on a Game and a HolderRenderer

- go: use GTP2 final_score to get engine's opinion about score
- draw letters/numbers on boards in renderers
- move (de)serialization for chess/checkers
- (gtk) use a double-buffer to get get rid of flickering
- undo support for checkers
- undo support in engine playerdrivers
- distinguish reasons for a draw (Chess: stalemate, repetition...)
- a problem in _iconview_hook() and other hooks should abort game
  launch (currently causes unexpected behaviours in other places)
- rework parameter mechanism:
  - change parameters with variable names to be dicts of parameters instead ?
  - get rid of ParamDecl subclasses, use real types instead to encapsulate
    the static constraints, use a Parameter/TypedProperty class instead ?
    - ability to further restrict type of a parameter in subclasses
  - use the changed_listeners mechanism to implement depends_on, for
    dynamic constraints
  - turn params into ctor args, moving default values there, and allowing
    default-less params
- finalize preferences mechanism:
  - factorize set_param call for plugin subparams
  - add "color", and "multichoice-plugin" parameter types
  - move playerdrivers to UI subparams ?
  - use "multichoice-plugin" parameter type for playerdriver multiplexer
  - multilevel prefs (current level = "all instances" (general default);
    lacks "this instance", "default for game X", others depending
    on the Parametrizable class)
  - holder prefs in GameRenderer's are key'd to __name__ and not fullname
    of game and holder
  - parameters should be kept in an odict when available
  - allow setting param values from plugin decl
- display message to user when parameters are refused
- let integer parameter have standard/preferred values for quick
  selection (eg. 9/13/19 for go boardsize, 8/10 for checkers)
- display game description in launcher, add a "play" button
- MouseWaypoint should discard current path if an invalid waypoint is
  selected (or maybe it is just Checkers not giving correct info ?)
- UI "Pause" support (cooperative suspend; get time to change playerdriver, etc)
- use icons in gtk toolbar
- move quit/save/prefs/players into a "game" menu
- either have dialogs disable the game window, or:
  - optionally auto-pause game on dialog popup
  - limit prefs/driver dialogs to one instance each
- promotion dialogs should not be fully modal, but that seems to
  require: 1) surgery on PlayerDriver's click handling to get
  __reset_move called at the correct time, and 2) a way to avoid
  breaking UserCancel propagation
- notify dialogs should not be modal
- shogi PSN format

- let user react to opponent refusing move:
  - "Protest" (threatening game stop) / "Ack refusal"
  - if protest: "Insist and stop game" / "Retract refusal"

- make margin a parameter of fullscreen renderer

- alert on opponent move (phone buzzer)
- hourglass on app launch
- make plugins of read/write file formats

* code improvements:

- find a way to specify a __check_parameters__() method to be called after
  set_params().  Using an Aspect Programming framework ?

- abstract event-loop handling from UI.Toolkit (look at twisted.internet.reactor)

- use better enums

- switch SimpleDrawnStones from hardcoded games to skinnability

- improve structuring for location highlighting
  - pluginify
  - allow highlighter parameters (color, etc)
  - highlight last opponent move
  - MoveHighlighter and PieceHighlighter classes
  - WaypointMoveHighlighter classes
  - SingleBoard mixes hl types in __highlights
  - allow highlights to be draw above pieces in addition as below them
    - "modifier" thingies for use a stateful vector canvas ?
    - different kinds of hl actions ? (sort of layers: board, pre-location,
      post-location, post-piece...)
  - include captured pieces in last-move highlight ?  last-captured ?

- let new_piece_on_board call player_relative_pos itself

- move Move.piece into GenericChesslikeMoves

- make move-checking accept pre-composed special moves
  (in chess: validate or fill source/target as needed)

- allow displaying captured pieces (eg. in Chess)
  - change support no-drop shogi variants to allow this

- rework GUI Toolkit API to allow drawing onto image or canvas without
  duplicating all methods.
- setup a unit-test system

- factorize all current gamerenderers into a single FullScreenBoard
  one.

- Gtk: canvas mask is in Gtk.Play, while handling is in Toolkit.Gtk

Milestone 0.2
-------------

- code cleanups/refactorings
  - privatization of all members, with property accessors
  - audit for missing abstract method declarations

- Reduce the number of standalone renderers
  - need a pool-enabled FullScreen
  - TextOnSVGShogiRenderer should use FullScreen with pools
    - requires a more generic FullScreen (not only SinglePieceSetGameRenderer)

- find a way to separate Judge/Referee (checks) from Game, while still
  allowing eg. promotions in Chess/Shogi

- more games: crazyhouse, tablut, other hexagonal
  chess variants, bridg-it (and 3-player hex variation), hex, GIPF
  - asymetric games with different Move class for each player (eg. entropy)
  - triangle board, support for Atride (3 players)
- history display

- add a shogi SVG renderer and skins
- multi-kanji character rendering

- capabilities for plugins (eg. svg, various UI support for player
  drivers)
- restore PlayerDriver sub-parameters when reopening setup dialog
- make PlayerDriver default dependant on movetype and UI, not on game
- display PlayerDriver grayed-out when disabled because of TryExec check
- introduce Good/Experimental tags
- PlayerDrivers should only start to play when the game starts

- implement move checking in go
- add free-handicap support to go
- finish move checking in shogi
- finalize support for go (territory counting)
  - use GTP2 command final_status

- integrate special-move code into movetype decl
- improve support for enforcing rules

- add GUIs for Qt (PyQt/PySide), E17 (elementary)
- make Location.board a possibly-computed attribute (eg. for go)
- make toolbar part of the game renderer
- handle captures as side-effects ?
- multiplexer player driver should filter choices

- implement a way to avoid AI or dumb PlayerDrivers to be selected by
  default (would supercede X-Omaha-DefaultPlayerDriver)

- change of PlayerDriver (and their settings) should be kept and
  recorded.  Right now we even have no means of storing the value
  (data loss bug according to PGN spec)

Milestone 0.4 ?
-------------

- endgame detection
- implement move checking by AI
- i18n
- make AI engines portable
  - look at wisted.internet.reactor.spawnProcess in twisted for
    portable async process communication

Milestone 0.5 ?
-------------

- deal with the case of PieceHolder and Location, whose descendants'
  __init__() have different prototypes, and thus can hardly use super()
- replace relevant assertions with some design-by-contract mechanism
  (not sure how much zope.interface would fit, and python-contract looks
   old, unmaintained and awkward)
- review method scopes

- replace relevant assertions with nice user feedback
- trap RuntimeError's and get them displayed as well
- robustness of plugin selection: open preferences when the selected
  choice does not load (eg. missing python-rsvg)
- use a more generic mechanism than X-Omaha-RendererCompat ?
- distinguish LauncherGUI from GameGUI, allowing simultaneous games ?
- clock support in game and GUI
- arr/spacebar piece selection in HumanPlayer
- board rotations
  - HolderRenderer parameter for orientation (unit vector?)
  - GameRenderer parameter for general orientation
    - preset values depending on orientations available in holders
- display messages with the suitable orientation for the target player
- 3D OpenGL board rendering
- support for 3D-board games (3DChess, etc)

- avoid destroying/creating new PlayerDriver when a choice did not change
- GUI.Gtk does not let the user specify arguments to multiplexed
  PlayerDriver's:
 - find a correct way to filter out those with arguments
 - find a way to allow arguments there

- allow disambiguation of short serializations
- audit/fix lifecycle of objects (eg. locations)
- support for "bag" holders (for eg. entropy, scrabble)
- support for "hidden hand" holders (for eg. scrabble, possibly card games)
- support for games with mutable boards (isola, zizanie beach)
- support for multiple pieces per location (eg. Troke)
- pieces mutating on each turn (micro- and nano-shogi)
- add GUIs for Android, HTTP, text
- incremental board update, move animation
- chesslike-moves themes with arrows for moves
- golike-moves themes with numbers
- unconstrained position editing
  - palette holder
  - "set game" or "multiple moves/edits without an order" as part of history
  - special input modes for (eg. for go, allow cycling white/black/empty)
  - tools to allow reconstructing full history from game snapshots
- generic undo support by full-replay for game not providing specific
  undo implementation ?
- "refuse" should not be so close to "undo"

Milestone 1.0 ?
-------------

- move history display, forking history
- editing history
- DnD moves
- UI playerdriver for PutMove with visual cues on "touch" and validate
  on "release"
- network play
  - using existing standard protocols for supported games
  - generic protocol
    - check whether fedmsg or another generic messenging framework could
      be leveraged (http://fedmsg.com/)
    - over chat channels (irc/xmpp/whatever - use libpurple or similar ?)
    - p2p protocol for serverless operation
    - use of advertize/discovery protocol (avahi ?) for finding nearby
      network opponents
- free position editing / problem solving support
- global themes to tie renderers and skins all together
- easy installation for plugins / additional packages (packagekit,
  sessioninstaller ?
- the current design makes it so that multiplexed player drivers send
  signal_ready() to the game even when they are attached to a
  Multiplexer.  It is not known to cause any problem today, but that's not
  clean and will eventually cause problems.

Post 1.0 ?
--------

- sandboxed plugins (RestrictedPython looks like the best candidate,
  but zope is told to be moving away from it, investigate)
- investigate alternative (preexisting) plugin systems (eg. ethos)
- support for Phalanx game (en: http://www.boardgamegeek.com/boardgame/4554
  fr: http://jeuxstrategieter.free.fr/Phalanx_presentation.php)
- support for Ploy game (possible moves depending on piece orientation)
- support for game-analysis engines
- other common (?) notations for chess ? (initials in native language,
  ICCF numeric notation)
- voice annotation, speech-to-text support
- world domination

Other ideas of games to add
---------------------------

- classical ones: hip, gomoku, chinese checkers, halma
- seen in "les jeux de table pour tous": jumpin, "blocus maritime"

About the name
==============

- it starts with "om", which sounds nice for an OpenMoko-enabled app
- it ends with "a", much like tagua and kaya, to whom it owes much
- I was on Omaha Beach when I thought it was cool to use this name :)
- a couple of days before, we played Beach Go with my son on that very
beach :)


Useful sites for game rules
===========================

http://en.wikipedia.org/wiki/Category:Abstract_strategy_games
http://www.boardgamegeek.com/boardgamecategory/1009
[fr] http://jeuxstrategie.free.fr/
http://www.boardspace.net/ [+ SGF game archives]


File formats references
=======================

- PGN
  http://en.wikipedia.org/wiki/Portable_Game_Notation
- PSN
  http://japanesechess.org/psn_white_sheet.php
- SGF
  http://www.red-bean.com/sgf/


Additional standalone AIs we may want to support
================================================

xboard-compatible (chess and variants)
 (phalanx, crafty, sjeng, fairymax, stockfish, hoichess)
UCI-compatible chess engines (natively or through polyglot)
 (fruit, toga2, glaurung, stockfish)
orego, pachi, fuego, amigogtp (go)
grhino (othello, amazons?)
eleeye, hoichess (xiangqi)
GPSshogi


GUI programs with builtin AI (from which AI would need to be split)
============================

gf1 (gipf) - http://repo.or.cz/w/gf1.git
3Dchess


Other programs we may want to interface with
============================================

http://remi.coulom.free.fr/Bayesian-Elo/ to produce ratings from
  tournament matches


Sources for game art
====================

http://mucho.girly.jp/bona/ (CC, includes some vector shogi pieces)
http://www.kiseido.com/shogi/shogi_equipment.htm (info on traditional
 calligraphy used for shogi tiles)
xboard has a nice SVG theme, for standard shogio only


Other UI programs (possibly steal themes/ideas)
=================

(for playing)
tagua
kaya
knights
eboard
gnome-chess
fltk-chess
quarry
gmchess
gogui
xistrat
pychess
brutalchess, dreamchess, pouetchess (3D/animated)
tofu
cgoban
cgoban3(KGS)
qgo
gpe-go
android apps (go droid, gobandroid, ...)
pidgin-gmchess
http://www.playwitharena.com/

(for other tasks)
scid
uligo
mgt
cutechess