{"id":13765140,"url":"https://github.com/peterosterlund2/droidfish","last_synced_at":"2025-05-10T20:31:59.131Z","repository":{"id":28661704,"uuid":"32181228","full_name":"peterosterlund2/droidfish","owner":"peterosterlund2","description":"DroidFish Android Chess App","archived":false,"fork":false,"pushed_at":"2024-06-04T10:28:03.000Z","size":212434,"stargazers_count":327,"open_issues_count":19,"forks_count":108,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-11-17T01:32:43.333Z","etag":null,"topics":["android-app","android-studio","chess","cpp11","java"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterosterlund2.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-13T21:14:20.000Z","updated_at":"2024-11-11T17:25:32.000Z","dependencies_parsed_at":"2024-02-25T20:43:31.180Z","dependency_job_id":"cc153f97-24fc-46c2-9e4d-3ce14fe4f094","html_url":"https://github.com/peterosterlund2/droidfish","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterosterlund2%2Fdroidfish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterosterlund2%2Fdroidfish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterosterlund2%2Fdroidfish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterosterlund2%2Fdroidfish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterosterlund2","download_url":"https://codeload.github.com/peterosterlund2/droidfish/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253480676,"owners_count":21915249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android-app","android-studio","chess","cpp11","java"],"created_at":"2024-08-03T16:00:34.498Z","updated_at":"2025-05-10T20:31:54.114Z","avatar_url":"https://github.com/peterosterlund2.png","language":"Java","funding_links":[],"categories":["Games"],"sub_categories":["Other"],"readme":"# Introduction\n\n*DroidFish* is a feature-rich graphical chess user interface, combined with\nthe very strong *Stockfish* chess engine.\n\n*DroidFish* is primarily designed for engine analysis of chess positions and\nviewing and editing of chess games. It can also be used for playing games, either\nagainst a chess engine or against another human player. Both players must play\non the same device though.\n\nA much weaker chess engine called *CuckooChess* is also included in\n*DroidFish*. Its primary feature is that it can be made to play very weakly so\nthat even beginners have a reasonable chance to beat it.\n\n\u003ca href=\"https://f-droid.org/repository/browse/?fdid=org.petero.droidfish\" target=\"_blank\"\u003e\n\u003cimg src=\"https://f-droid.org/badge/get-it-on.png\" alt=\"Get it on F-Droid\" height=\"80\"/\u003e\u003c/a\u003e\n\n\n# Using the user interface\n\n* Many common actions are invoked by tapping on user interface elements such as\n  buttons, chess pieces and text.\n\n* A context menu can often be opened by long pressing (tap and hold) on an\n  element such as the chess board, the move list text area or a button.\n\n* The *Left drawer menu* contains command actions and is opened by swiping from\n  the left side of the screen towards the middle. The *right drawer menu*\n  contains less common actions and is opened by swiping from the right side of\n  the screen towards the middle.  \n  It is also possible to open the left/right drawer menu by tapping on the\n  left/right half of the app title bar.\n\n* To play a move on the board first tap the piece to move, then tap the\n  destination square. Alternatively, touch the piece to move, drag it to the\n  destination square and release the piece. For pawn promotion moves a context\n  menu is opened that lets the user select the piece to promote to. For castling\n  moves, first tap on the king and then tap on the king destination square. The\n  rook is moved automatically.  \n  **Note!** Castling is only allowed if the king and rook have not previously\n  been moved. When setting up a position manually (see below), make sure to also\n  set the castling right flags appropriately.\n\n\n# Permissions\n\n*DroidFish* requests the *Storage* permission when it is first started. This\npermission is used to read/write data in the `DroidFish` directory on the\nexternal storage. *DroidFish* does not read/write any file outside of the\n`DroidFish` directory, except when explicitly requested to save/load a PGN\n(portable game notation) or FEN/EPD (Forsyth-Edwards notation / extended\nposition description) file in a different directory.\n\nThe `DroidFish` directory is used to store opening books, PGN files, FEN/EPD\nfiles, third party chess engines and tablebase files. It is also used to store\nsome settings, such as UCI parameter values.\n\nIt is possible to use *DroidFish* without granting the *Storage* permission, but\nfunctionality will be rather limited.\n\n\n# Default buttons\n\nBy default the following buttons are displayed next to the chess board, from\nleft to right:\n\n* The folder button (Custom Button 3). This button opens the last used file to\n  let you select a PGN game or a FEN/EPD position. This button only has an\n  effect if you have previously opened a file.\n\n* The light bulb button (Custom Button 2). This button toggles engine\n  analysis. See the **Game mode** section below for details.\n\n* The rotate board button (Custom Button 1). This button rotates the chess board\n  180 degrees.\n\n* The game mode button. See the **Game mode** section below for details.\n\n* The left arrow button. This button moves to an earlier position in the\n  game. See the note in the **Game mode** section below for details.  \n\n* The right arrow button. This button moves to a later position in the game. See\n  the note in the **Game mode** section below for details.  \n\nTap and hold a button to display a menu with additional actions.\n\nSee the **Button configuration** section below for information about how to\nconfigure button actions.\n\n\n# Game mode\n\nChange the *game mode* by tapping the `M` button. There are three types of game\nmodes:\n\n1. To view and/or edit a game, use the *Edit/re-play Game* game mode. In this\n   mode there are no chess clocks and no chess engine that will make moves for\n   any side.\n\n1. To make the chess engine analyze the position on the chess board, use the\n   *Analysis mode* game mode. In this mode the engine will continuously analyze\n   the current position. During analysis it is possible to step back/forward in\n   the game and/or add/remove moves to explore possible variations. All moves\n   played on the board are automatically added to the game tree.\n\n1. To play games, use one of the modes *Play white*, *Play black*, *Two\n   players*, *Computer vs computer*. In these modes chess clocks are used and\n   when a computer engine is playing it will limit its thinking time to respect\n   the time available on the clock.\n\n**Note!** When the left/right arrow buttons are used to move back/forward in a\ngame, the position will move one or two half-moves depending on the game mode\nand current position. If a human player is playing against a computer player,\nthe buttons will move to the next/previous position where it is the human's turn\nto make a move. To make the buttons move only one half-move, change the game\nmode to *Edit/re-play game* or *analysis mode*.\n\n**Hint!** Since enabling and disabling analysis mode can be a very common\noperation while analyzing a game, there is a special button (the one with the\nlight bulb image) that toggles analysis mode. When analysis mode is disabled the\ngame mode that was used before analysis mode was enabled is restored.\n\n\n# Playing strength\n\nFor engines that can reduce their playing strength using the UCI_LimitStrength\nand UCI_Elo options, it is possible to specify the engine playing strength by\nopening the *Left drawer menu* and selecting *Set Engine Strength*. Both\nbuilt-in engines (*Stockfish* and *CuckooChess*) can reduce their playing\nstrength.\n\nThe available Elo range can be different for different engines. If *Stockfish*\nis playing too strong even on the lowest setting, consider switching to the\n*CuckooChess* engine which is able to play at a much weaker level. At the lowest\nsetting, *CuckooChess* plays random legal moves so it should be usable also for\nan absolute beginner.\n\nThe selected playing strength is shown in the title bar after the engine name.\n\nPlaying strength changes take effect the next time the engine starts to think\nabout a move.\n\nThe playing strength setting is only used in game playing mode. When the engine\nis in analysis mode, full strength is always used.\n\n\n# The move list text area\n\nThe move list keeps a record of moves played during a game and during analysis.\nTap on a move in the move list to move to the corresponding point in the game.\n\nThe behavior of the move list can be configured in several ways by settings\navailable in *Left drawer menu* -\u003e *Settings* -\u003e *Other* -\u003e *PGN Settings*. You\ncan specify if variations, comments and annotations should be used when viewing,\nimporting and exporting PGN data.\n\nBy default the move list is automatically scrolled to make the current move\nvisible at the top of the move list text area. To disable this behavior change\nthe setting *Left drawer menu* -\u003e *Settings* -\u003e *Behavior* -\u003e *Auto scroll move\nlist*.\n\nIf you do not want any variations to be used while playing or analyzing a game,\nenable the setting *Left drawer menu* -\u003e *Settings* -\u003e *Behavior* -\u003e *Discard\nvariations*.  \n**Note!** In this mode any move played on the board immediately becomes the\nmainline and the previously played move (if different from the just played move)\nand all following moves and variations are immediately removed from the game\ntree.\n\nTap and hold the move text area to open a menu with the following actions:\n\n* *Edit Headers*: Opens a dialog where the standard PGN headers can be edited.\n\n* *Edit comments*: Opens a dialog where comments and annotations for the current\n  move can be edited. The following fields are available:\n  * *Before*: Edit the comment before the current move.\n  * *After*: Edit the comment after the current move.\n  * *Move*: The move itself cannot be edited but the annotation for the move can\n    be edited. Valid annotations are:\n    * `!  ` : Good move\n    * `?  ` : Poor move\n    * `!! ` : Very good move\n    * `?? ` : Very poor move\n    * `!? ` : Speculative move\n    * `?! ` : Questionable move\n    * `=  ` : Equal chances, quiet position\n    * `∞  ` : Unclear position\n    * `+/=` : White has a slight advantage\n    * `=/+` : Black has a slight advantage\n    * `+/-` : White has a moderate advantage\n    * `-/+` : Black has a moderate advantage\n    * `+- ` : White has a decisive advantage\n    * `-+ ` : Black has a decisive advantage\n\n* *Add opening name*: Adds or updates the `ECO` and `Opening` PGN headers based\n  on information from the ECO (Encyclopedia of Chess Openings) database and the\n  main line in the current game.\n\n* *Truncate Game Tree*: Removes the current move and all following moves and\n  variations from the game tree.\n\n* *Move Variation Up/Down*: Rearrange the order of variations in the game tree.\n  Note that you may have to move a variation up several times to make it become\n  the main line.\n\n* *Add Null Move*: Adds a null move to the game tree. A null move does not move\n  any piece but passes the turn to the other side. Adding a null move can be\n  useful to perform threat analysis.  \n  **Note!** A null move is not a legal move in chess.\n\n\n# Hints about the current position\n\n*DroidFish* can display different kinds of hints to improve the user's\nunderstanding of the current position on the board.\n\n## Engine analysis\n\nWhen the engine is analyzing a position, information about the current position\nis displayed at the bottom of the screen. Information is also displayed while\nthe engine is thinking about what move to play in a game, if *Left drawer menu*\n-\u003e *Settings* -\u003e *Hints* -\u003e *Show Computer Thinking* is enabled.\n\nThe first line of information has the following format:\n\n[*depth*] *score* *principal_variation*\n\n* *Depth* is the search depth the engine used when it calculated the score and\n  the principal variation. Search depth is measured in number of half-moves.\n\n* The *score* is a measure of how good the engine thinks the current position is\n  from the white player's point of view. A positive number means white is better\n  and a negative number means black is better.\n\n  The score is either a numerical value, where 1.00 is roughly equal to a one\n  pawn advantage, or a mate score in the form m*value*, where *value* is the\n  number of moves to mate. If black is winning *value* is a negative number.\n\n  In some cases the engine has not calculated an exact score, only an upper or\n  lower bound for the score. In this case the score is prepended with either\n  `\u003c=` or `\u003e=` to show that the score is not exact.\n\n  **Hint!** To instead show scores from the perspective of the side to move, go\n  to *Left Drawer Menu* -\u003e *Settings* -\u003e *Hints* and disable *White-based\n  scores*.\n\n* The *principal variation* shows the best game continuation for both sides\n  according to the engine.\n\nThe last line of information has the following format:\n\nd:*depth*[/*selDepth*] *i*:*move* t:*time* n:*nodes* nps:*speed* h:*hashfull* tb:*tbhits*\n\n* *depth* The search depth to which the engine is searching the current move.\n\n* *selDepth* The selective search depth, if reported by the engine.\n\n* *i* is the move number the engine is currently searching. An engine generally\n  starts searching the move it thinks is best, then continues with the second,\n  third, etc best moves until all moves have been searched. Then it starts over\n  with a larger search depth.\n\n* *move* The move the engine is currently searching.\n\n* *time* The amount of time in seconds the engine has been searching in the\n  current position.\n\n* *nodes* The number of nodes the engine has searched for the current position.\n\n* *speed* The search speed measured in number of nodes per second.\n\n* *hashfull* How full the engine hash (transposition) table is. This is\n  displayed as a percentage value between 0 and 100.\n\n* *tbhits* How many successful tablebase lookups the engine has performed for\n  the current position. This is only displayed if the value is larger than 0.\n\nThe displayed information can be configured in different ways by long pressing\non the analysis text area when it is visible. A context menu appears with the\nfollowing choices:\n\n### Add Analysis\n\nSelect *Add Analysis* to add the moves from the principal variation to the\ncurrent game.\n\n### Number of Variations\n\nSelect *Number of Variations* to control how many best lines the engine will\ncalculate. By default only the best line of play is calculated. Change this to a\nlarger number to show information about the N best lines of play. This option is\nnot displayed if not supported by the currently used engine.\n\n**Note!** This setting is only used during analysis, not when the engine is\nplaying a game. During game play only the best line of play is calculated to\navoid a speed loss that would make the engine play weaker.\n\n### Show whole variations / Truncate variations\n\nSelect this option to enable or disable the display of the full PV the engine\nhas computed. The default (*Truncate variations*) is to only display the first\nfew moves that fit on a single line on the screen.\n\n### Hide statistics / Show statistics\n\nIf you are not interested in the last line that displays statistics about the\nengine (as opposed to the other lines that display information about the chess\nposition), select *Hide statistics* to hide that information.\n\n## Opening book moves\n\nIf the current board position is included in the currently used opening book,\ninformation about all book moves for the position is displayed at the bottom of\nthe screen. Each move is displayed as *move*:*percentage* where *percentage*\nshows how often the computer player would play that move in games.\n\nOpening book hints can be enabled/disabled from *Left Drawer Menu* -\u003e *Settings*\n-\u003e *Hints* -\u003e *Show Book Hints*. Note that the chess engine will use the opening\nbook even if opening book hints are disabled.\n\n## Opening name (ECO codes)\n\nThe setting *Show ECO codes* controls when ECO codes and opening names are\ndisplayed. There are three options:\n\n* `Off`: ECO codes and opening names are never displayed.\n* `Auto`: ECO codes and opening names are displayed in the opening phase\n  up to 5 moves after the last move in the ECO database.\n* `Always`: ECO codes and opening names are displayed during the whole game.\n\n## Arrows\n\n*DroidFish* sometimes draws arrows on the chess board to give information about\nthe current position.\n\nGo to *Left Drawer Menu* -\u003e *Settings* -\u003e *Hints* -\u003e *Use Arrows* to control how\nmany arrows to display.\n\nGo to *Left Drawer Menu* -\u003e *Settings* -\u003e *Appearance* -\u003e *Color Settings* to\nchange the arrow colors. Note that manually made color changes are overwritten\nif you set a new color theme using *Left Drawer Menu* -\u003e *Set Color Theme*.\n\nThe arrows have different meanings in different circumstances. The first that\napplies from the following list defines what the arrows mean:\n\n1. If *DroidFish* is in analysis mode or if it is *DroidFish's* turn to move and\n   *Show Computer Thinking* is enabled, engine search information is\n   displayed. If *Number of Variations* is 1, the first N half-moves from the\n   principal variation is displayed. If *Number of Variations* is larger than 1,\n   the best N moves are displayed. (To change *Number of Variations*, tap and\n   hold on the analysis output area while the engine is thinking.)\n\n1. If *Left Drawer Menu* -\u003e *Settings* -\u003e *Hints* -\u003e *Show Book Hints* is\n   enabled and the current position is included in the opening book, the arrows\n   display the N best moves from the opening book.\n\n1. If there are variations recorded in the current game for the current\n   position, the arrows display the first N variations. Variations appear for\n   example if you undo a move and play a different move instead.\n\n## Endgame tablebase information\n\nTo change how endgame tablebase hints are displayed, go to *Left drawer menu* -\u003e\n*Settings* -\u003e *Endgame Tablebases* and change *Show Hints* and/or *Edit Board\nHints*.\n\nWhen *Show Hints* is enabled and the position on the board is included in an\nendgame tablebase, if you tap on a piece, information about all legal moves for\nthat piece is displayed. For each square the piece can move to, the tablebase\nscore is displayed on that square. The score is positive if the side to move has\nthe advantage.\n\nWhen *Edit Board Hints* is enabled, you are using the board editor to set up a\nposition, and the position is included in an endgame tablebase, if you select a\npiece on the board, information about alternative positions for that piece is\ndisplayed. For each square the piece can be placed on, the tablebase score for\nthe corresponding position is displayed on that square. The score is positive if\nwhite has the advantage.\n\nA tablebase probe can produce one of three different types of scores, depending\non what tablebase file was probed:\n\n* Distance to mate. This is displayed as +*score* or -*score*, where `+` is used\n  for winning scores and `-` is used for losing scores. The *score* value is the\n  number of moves (not half-moves) to mate. A drawn position is displayed as\n  `0`.\n  * A Gaviota tablebase probe produces a distance to mate score.\n\n* Distance to zeroing move. This is displayed as W*score* or L*score*, where `W`\n  is used for winning scores and `L` is used for losing scores. The *score*\n  value is the number of moves (not half-moves) to the next zeroing move. A\n  drawn position is displayed as `0`.\n  * A Syzygy `.rtbz` tablebase probe produces a distance to zeroing move score.\n  * A zeroing move is a move that resets the 50-move draw counter, that is a\n    pawn move or a capture.\n\n* Win/draw/loss. This is displayed as `W`, `0` or `L`.\n  * A Syzygy `.rtbw` tablebase probe produces a win/draw/loss score.\n\n\n# Claim/Offer/Accept Draw\n\n*DroidFish* does not automatically end a game when the 50-move rule or the\n3-fold repetition rule is triggered. According to FIDE (International Chess\nFederation) rules, these conditions do not automatically end a game, they just\nallow a player to claim a draw if the player wants to.\n\nTo request a draw action, select *Right drawer menu* -\u003e *Claim/Offer/Accept\nDraw*. The following happens:\n\n* If the current position allows a draw to be claimed, the game immediately ends\n  with a draw result.\n\n* If the other player offered a draw in the previous move, the draw offer is\n  accepted and the game immediately ends with a draw result.\n\n* Otherwise, play a move on the board as usual.\n\n* If the resulting position allows a draw to be claimed, the game immediately\n  ends with a draw result.\n\n* Otherwise the move is played on the board and a draw offer is given to the\n  opponent. The opponent is free to accept or ignore the offer.\n\n**Note!** It is not possible to offer a draw without also playing a move.\n\nThe chess engine never offers a draw, but it can accept a draw offer made by the\nuser and it can claim a draw if allowed by the rules of chess.\n\n**Note!** *DroidFish* does not implement the relatively new 75-move draw rule\nand 5-fold repetition rule. Those rules are primarily meant to prevent very long\ngames where neither player would want to claim a draw. *DroidFish* does not mind\nif the players want to play very long games so it does not have to implement\nthese rules.\n\n\n# Saving and loading games and positions\n\n## PGN\n\nTo load a game from a PGN file, go to *Left drawer menu* -\u003e *File* -\u003e *Load game\nfrom PGN file*. Select the file to read, then select the game to load from the\nlist of available games.\n\nTo save a game to a PGN file, go to *Left drawer menu* -\u003e *File* -\u003e *Save game\nto PGN file*. Select the file to save to. If the file is empty, the game is\ndirectly saved in the file. If the file is not empty, a list of existing games\nis displayed. To decide where the current game should be saved in the file,\nselect an existing game from the list. A menu is opened where you can decide if\nthe current game should be saved before, after or replace the selected game.\n\nThere is a search field above the game list. If a string is entered in the\nsearch field, the game list is filtered to only show games matching the search\nstring. The matching is case insensitive and by default matches a substring in\nthe game list. It is possible to enable matching using [Java regular expression\nsyntax](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html)\nby enabling *Regular Expression Search* in the menu.\n\n**Hint!** In the game list, tap and hold a game to delete that game from the PGN\nfile.\n\n**Hint!** To delete the whole file, select *Delete File* from the menu.\n\n## FEN/EPD\n\nTo load a position from a FEN/EPD file, go to *Left drawer menu* -\u003e *File* -\u003e\n*Load position from file*. Select the file to read, then select the position to\nload from the list of available positions in the file. A preview of the position\nis displayed on the small chess board. Click the `OK` button to replace the\ncurrent game with the selected position. Click the `CANCEL` button or the device\nback button to return to the current game.\n\n**Hint!** Tap and hold a position in the list to immediately replace the current\ngame with the selected position.\n\nSaving a position to a FEN/EPD file has not been implemented.\n\n## Autosave\n\nWhen an action is performed that causes the current game to be discarded, the\ngame is automatically saved in the file `DroidFish/pgn/.autosave.pgn` before\nbeing discarded. The autosave file has a maximum size of 20 games and the most\nrecently autosaved game is stored first in the file. If the number of games\nbecomes too large, the oldest stored game is removed from the file.\n\n\n## OI File Manager\n\nIf the [*OI File Manager*](https://play.google.com/store/apps/details?id=org.openintents.filemanager)\napp (or a compatible file manager) is installed *DroidFish* will use the app to\nselect files when loading/saving PGN/FEN/EPD files. This makes it possible to\nread files in any directory on the device where the user has read\naccess. Removable storage like USB hard disks and SD cards do not typically\nallow write access from apps using normal file system operations, so *DroidFish*\nwill only be able to read files from such locations.\n\n**Hint!** If the OI File Manager is installed, it can also be used to copy, move\nand delete existing files when invoked to load/save a PGN/FEN/EPD file.\n\n## Character encoding\n\n*DroidFish* assumes that PGN/FEN/EPD files are encoded in UTF-8 format. ASCII is\na subset of UTF-8 so that will work too. Other encodings will likely cause at\nleast some characters to be displayed incorrectly.\n\n## Setting up a position\n\nTo set up a position, open the *Left drawer menu* and select *Edit Board*. A\nchess board editor is opened where you can move pieces around freely and\nadd/remove pieces. If a piece is selected in the area next to the chess board,\nclick a square on the chess board to change the piece on that square.\n\n* If the square is empty or contains a different piece type, the selected piece\n  is placed on the square.\n\n* If the square contains the selected piece, the same piece but with opposite\n  color is placed on the square.\n\n* If the square contains the selected piece but with opposite color, the square\n  is cleared.\n\nIf an empty square is selected in the area next to the chess board, click a\nsquare on the chess board to clear that square.\n\nIf nothing is selected in the area next to the chess board you can move pieces\non the chess board by first clicking on the from square, then clicking on the\ndestination square. This works even if the from square is empty, which has the\neffect of clearing the destination square.\n\nThe board editor has its own *Left drawer menu* where you can change the side to\nmove, castling flags, en passant file and move counters. The menu also contains\nshortcuts to set up the initial position and to clear the board.\n\nTo use the set up position, click the `OK` button or the device back\nbutton. This replaces the current game with the set up position. Click the\n`CANCEL` button to discard the set up position and return to the current game.\n\n**Note!** It is not possible to set up illegal positions since this could\npotentially cause the chess engine to crash. UCI engines usually assume that\nthey are only asked to analyze legal positions. If the position being edited is\nillegal, a warning message is displayed. If you click the `OK` button when the\nposition is illegal, the illegal position is discarded and the current game is\nrestored.\n\n\n# Opening books\n\n## Pre-installed books\n\n*DroidFish* includes three pre-installed opening books:\n\n1. \u0026lt;Internal Book\u003e: This is a small opening book that is also the default\n   book.\n\n1. \u0026lt;ECO Book\u003e: This opening book contains all book lines that define the ECO\n   codes.\n\n1. \u0026lt;No Book\u003e: This is an empty opening book that can be used when no\n   opening book is wanted.\n\n## Installing additional opening books\n\nTo use *polyglot*, *CTG* or *ABK* book files:\n\n1. Copy one or more opening book files to the `DroidFish/book` directory on the\n   external storage.\n\n   1. Polyglot books must have the file extension `.bin`.  \n     **Note!** The Android file system may be case sensitive, in which case the\n     extension must be `.bin`, not `.Bin` or `.BIN`.\n\n   1. A *CTG* book consists of three files with file extensions `.ctg`, `.ctb`\n      and `.cto`. You must copy all three files.\n\n   1. an *ABK* book must have the file extension `.abk`.\n\n1. Go to *Left drawer menu* -\u003e *Select opening book*.\n\n1. Select the opening book you want to use.\n\n*Hint!* There are many free opening books available for download from the\ninternet. There is also a free tool called *PolyGlot* that can be used on a PC\nto create polyglot opening books from a collection of PGN games. How to find and\nuse these resources is outside the scope of this manual.\n\n\n# UCI engines\n\nIn addition to the pre-installed chess engines, *DroidFish* can also use third\nparty UCI engines:\n\n* Copy one or more UCI engine binaries to the `DroidFish/uci` directory on the\n  external storage.  \n  **Note!** The binaries must be compiled for Android.\n\n* Go to *Left drawer menu* -\u003e *Manage Chess Engines* -\u003e *Select Chess\n  Engine* and select the engine to use.\n\nExternal engines are started with the current working directory set to\n`DroidFish/uci/logs` on the external storage. This is useful for engines that\nexpect to find data files in a path relative to the current directory.\n\n*Hint!* There are many free chess engines compiled for Android that can be\ndownloaded from the internet. How to find such engines is outside the scope of\nthis document.\n\n## Open exchange engines\n\n*DroidFish* supports the *open exchange chess engine interface*, which is a way\nto package UCI chess engines as Android apps. If you install such an app the\nengine will automatically appear in the list of available engines in\n*DroidFish*.\n\n## Changing UCI options\n\nTo change options for the current chess engine, go to *Left drawer menu* -\u003e\n*Manage chess engines* -\u003e *Set options*. (Alternatively, tap and hold the light\nbulb button and select *Engine options*.) This opens an editor where UCI options\ndefined by the chess engine can be edited. What options are available and what\nthey do depend on the chess engine. Refer to the chess engine documentation for\ndetails.\n\nClick `OK` to send the modified option values and selected button options to the\nengine. If the engine is not thinking the options will be applied immediately.\nOtherwise the options will be applied when the engine stops thinking or starts\nthinking about a new position.\n\nEngine settings are saved, so the next time you use the same chess engine it\nwill use the settings you saved the last time it was used. To restore default\nsettings, open the UCI options editor and click `RESET` and `OK`.\n\n## Using a remote engine server\n\n*DroidFish* can use UCI engines that run on a remote server computer.\n\n* Install chess network server software on the remote computer.\n\n  * For Windows and Linux, install the Engine server software from the\n    [DroidFish](http://hem.bredband.net/petero2b/droidfish/index.html) page.\n\n  * Alternatively for Linux, `mini-inetd` from the `tcputils` package can be\n    used.\n\n* Select *Manage Chess Engines* in the *Left drawer menu*, create a new network\n  engine and enter the host name (or IP address) and port number for the remote\n  engine.\n\n* Go to *Left drawer menu* -\u003e *Manage Chess Engines* -\u003e *Select Chess Engine*\n  and select the engine to use.\n\n**Note!** The remote server protocol simply sends UCI protocol commands over a\nTCP connection using plain text. There is no security or authentication built\ninto the protocol. Therefore a remote server should only be used in a trusted\nprivate network.\n\n**Note!** It is possible to access a private network over the internet by\nrunning VPN server software in the private network. How to set up a VPN server\nis beyond the scope of this document.\n\n\n# Endgame tablebases\n\n## Syzygy\n\n*DroidFish* can use [Syzygy endgame tablebases](https://www.chessprogramming.org/Syzygy_Bases),\nwhich can be downloaded for free from the internet. To use Syzygy tablebases:\n\n* Copy `.rtbw` and optionally `.rtbz` files to the `DroidFish/rtb` directory on\n  the external storage.\n\n* Change settings in *Left drawer menu* -\u003e *Settings* -\u003e *Endgame Tablebases* to\n  control how the tablebases are used.\n\nTablebases containing up to 7 men are supported, although it is probably\nimpractical to use larger than 5-men tablebases for handheld devices because of\nthe very large size of 6-men and 7-men tablebases.\n\n\n## Gaviota\n\n*DroidFish* can use [Gaviota endgame tablebases](http://sites.google.com/site/gaviotachessengine/Home/endgame-tablebases-1),\nwhich can be downloaded for free from the internet. To use Gaviota tablebases:\n\n* Copy `.gtb.cp4` files to the `DroidFish/gtb` directory on the external\n  storage.\n\n* Change settings in *Left drawer menu* -\u003e *Settings* -\u003e *Endgame Tablebases* to\n  control how the tablebases are used.\n\n\n## Tablebases for remote engines\n\nTo configure tablebases for remote engines, go to *Left drawer menu* -\u003e\n*Settings* -\u003e *Endgame Tablebases* and change *GTB Network Directory* and\n*Syzygy Network Directory* to match the paths where the tablebases are installed\non the remote computer.\n\n\n# Interfacing with other apps\n\n## Sharing games and positions\n\nTo share the current game, tap and hold the chess board and select *Share game*\nor *Share as Text* from the menu. This brings up a list of applications that can\nimport the game data. Use *Share game* to send the PGN data to another chess\napp. Use *Share as Text* to send the PGN data as text to a non-chess app, such\nas an email app.\n\nTo share the current position as a PNG image, tap and hold the chess board and\nselect *Share as Image*.\n\nIt is also possible to import/export PGN and FEN/EPD data from/to the\nclipboard. Tap and hold the chess board and select *Clipboard* to use this\nfunction. The *Paste from Clipboard* function automatically detects both PGN and\nFEN/EPD data.\n\n*DroidFish* will also appear in the list of target apps when you share chess\ndata from other chess apps installed on the device.\n\n## Scid on the go\n\nIf the [*Scid on the go*](https://play.google.com/store/apps/details?id=org.scid.android)\napp is installed *DroidFish* can directly open games from Scid database files.\nTo use this function, tap and hold the chess board, select *File* from the menu,\nthen select *Load game from Scid file*. Select the desired file, then select the\ngame to load from the file.\n\n**Hint!** If you later want to load a different game from the same Scid file,\nuse the *folder button* to go directly to the game list for the last used file.\n\n## ChessOcr\n\nIf the [*ChessOcr*](https://play.google.com/store/apps/details?id=com.kgroth.chessocr)\napp is installed *DroidFish* can use that app to scan chess positions from\nmagazines or books and automatically set up the scanned position in\n*DroidFish*. To use this function, tap and hold the chess board and select\n*Retrieve Position* from the menu. Select the ChessOcr app and follow the\ninstructions in that app.\n\nIf the scanned position is valid it is set as the current board position in\n*DroidFish*. If the scanned position is invalid, *DroidFish* enters edit board\nmode with the invalid position. Correct the position to make it valid and click\nthe `OK` button to use the position.\n\n\n# Settings\n\n*DroidFish* has a large number of configurable settings, which can be changed by\nopening the *Left drawer menu* and selecting *Settings*. Some important settings\nnot already explained are described in the following sections.\n\n## Time control\n\nIt is possible to specify the time control as the number of moves to be played\nin a given amount of time. Additionally it is possible to specify a time\nincrement that is added to each player's clock after making a move.\n\nEngine players try their best to respect the specified time control settings,\nbut if you are using a very fast time control on a slow device, it is possible\nthat the engine runs out of time. When the engine has no time left on its clock\nit will play as fast as it can. This can cause some engines to play very weakly,\nso it is best to use a slower time control if this happens on your device.\n\nThe time control is also used for human players, but note that the game does not\nautomatically end if a player runs out of time. It is up to the user to decide\nwhat to do if a player runs out of time.\n\nTime control changes take effect when a new game is started.\n\n## Hash table size\n\nUse *Left drawer menu* -\u003e *Settings* -\u003e *Engine Settings* -\u003e *Hash Table* to\nchange the hash table size used by the chess engine.\n\nIn Android there is a limit for the maximum amount of Java memory an app is\nallowed to use. The limit depends on the device and possibly also on the Android\nversion the device is running. *DroidFish* will not allow a chess engine to use\na larger hash table than this limit. This restriction is enforced because\nAndroid is not designed to run processes requesting a lot of memory, and can\nbecome unstable or crash or reboot if it runs out of memory.\n\nIt is possible to disable this hash table size limit by creating a file called\n`.unsafehash` in the directory `DroidFish/uci`. This feature should only be used\nif you have determined that it does not cause your device to become unstable.\n\n**Note!** The hash table size limit is only enforced for engines running on the\ndevice. Network engines are not affected.\n\n## Text size\n\nThe text size used to display moves and analysis information can be changed\nin *Settings* -\u003e *Appearance* -\u003e *Text Size*.\n\n## Piece names\n\nUse the *Piece Names* setting in the *Appearance* section to control how pieces\nare represented in the move list and analysis information. There are three\navailable choices:\n\n* English letters. The following letters are used:\n  * `P` : Pawn\n  * `N` : Knight\n  * `B` : Bishop\n  * `R` : Rook\n  * `Q` : Queen\n  * `K` : King\n\n* Local language letters. The letters used depend on the current user interface\n  language.\n\n* Figurine notation. Small images are used instead of piece letters.\n\n**Note!** The PGN standard says English letters should be used for identifying\npiece names, so English letters are always used/assumed during PGN\nexport/import.\n\n## Piece set\n\nYou can change the appearance of the chess pieces on the chess board using the\n*Piece Names* option in the *Appearance* section. It is also possible to change\npiece colors in *Color Settings* in the *Appearance* section. Note however that\npiece colors are overwritten if you change the color theme using *Left drawer\nmenu* -\u003e *Set Color Theme*.\n\n## Move announcement\n\nUse *Left drawer menu* -\u003e *Settings* -\u003e *Appearance* -\u003e *Speak moves* to control\nhow played moves are announced. The following settings are available:\n\n* *Off*: Moves are not announced.\n\n* *Speech*: When a move is played by either a human or the computer, the played\n  move is spoken using short algebraic notation. English, German and Spanish\n  speech is available.\n\nEnable *Settings* -\u003e *Appearance* -\u003e *Move sound* to play a sound when the\ncomputer player makes a move.\n\nUse *Settings* -\u003e *Appearance* -\u003e *Enable Vibration* to make the device vibrate\nwhen the computer player makes a move.\n\n## Button configuration\n\nButton actions can be changed from *Left drawer menu* -\u003e *Settings* -\u003e\n*Behavior* -\u003e *Configure Buttons*.\n\nThe three leftmost buttons can be changed by the user. Each button has a main\naction that is triggered when the button is tapped. The main action also\ndetermines the icon used to display the button. Additionally up to 6 extra\nactions can be defined for a button. To invoke the additional actions, tap and\nhold the button, then select the desired action from the menu that opens.\n\nIf all actions for a button are disabled the button is not displayed. Note that\nin *settings* the buttons are named *Custom Button 1/2/3*, where button 3 is the\nleftmost button.\n\nThe three rightmost buttons (the `M` button and the left/right arrow buttons)\nhave predefined actions that cannot be changed by the user.\n\n## Opening book settings\n\nYou can change aspects of the opening book from *Left drawer menu* -\u003e *Settings*\n-\u003e *Other* -\u003e *Opening Book Settings*. The following settings are available:\n\n* *Book Length*: Controls the maximum number of moves the engine will play from\n  the opening book. This setting does not affect opening book hints. The default\n  is *unlimited*.\n\n* *Prefer main lines*: When enabled, moves that are marked as main line moves in\n  the book are given a higher weight so they will be played more often by the\n  chess engine.  \n  **Note!** This option only has an effect for *CTG* opening books.\n\n* *Tournament mode*: When enabled, only book moves that are marked for\n  tournament play are played by the chess engine.  \n  **Note!** This option only has an effect for *CTG* opening books.\n\n* *Book randomization*: Controls how often different book moves are played by\n  the engine. The default is 50% which means that the statistics from the\n  opening book is used unmodified. 100% means that all book moves are played\n  with (almost) the same probability regardless of the statistics from the\n  opening book. 0% means that the book move with the best statistics is played\n  (almost) 100% of the time.\n\n* *Book Filename*: This option is set automatically when *Left drawer menu* -\u003e\n  *Select Opening Book* is used. It is however possible to set this value\n  manually in which case the full path to an opening book file should be\n  specified (including the file extension). This can be useful if you have a\n  very big opening book stored somewhere on the device but it would be\n  impractical to copy it to the `DroidFish/book` directory.\n\n**Note!** The move percentages calculated by *DroidFish* for *CTG* books are\nunlikely to agree with percentages calculated by other chess programs that can\nuse *CTG* books.\n\n**Note!** The move percentages calculated by *DroidFish* for *ABK* books are not\nalways equal to percentages shown in the Arena Chess GUI, because the algorithm\nused by Arena to compute the percentages is unknown.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterosterlund2%2Fdroidfish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterosterlund2%2Fdroidfish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterosterlund2%2Fdroidfish/lists"}