====== HoldingNuts Handbook ======

===== Quick start =====

==== How to play? ====
  - **Download:** [[Download]] the latest version of HoldingNuts for your operating system.
  - **Extract:** HoldingNuts is intentionally provided without an installer. Just extract (unzip respectively untar) the downloaded archive.
  - **Run:** Open the directory you extracted the archive to. Start the HoldingNuts client by double-clicking on ''holdingnuts.exe'' respectively ''holdingnuts.sh''.
  - **Connect**: Click on <widget button>Connect</widget> in order to connect to the default HoldingNuts server.

\\

Once you're connected you can:
  * **Chat** with other players in the lobby/foyer.
  * **Join** an existing game by selecting the game in the game list and clicking on <widget button>Register</widget>. The game will start as soon as the table is complete or a game-owner starts it manually.
  * **Create** your own game by clicking on <widget button>Create own game</widget>. Configure the game as desired and click on <widget button>Ok</widget>. Your game has been created and will start as soon as the table is complete.
  * **Configure** the HoldingNuts client as desired by choosing the menu items <widget button>Game</widget> -> <widget button>Settings</widget>.

{{ :handbook:foyer_help.png |Main window help}}

===== HoldingNuts user data directory =====

This table shows the location of the directory containing the settings and user-files:

^ OS ^ Directory ^
| Linux | ''~/.holdingnuts/'' |
| Windows (all) | ''%APPDATA%\HoldingNuts\'' |
| * NT/XP/2000 | ''C:\Documents and Settings\<username>\Application Data\HoldingNuts\'' |
| * Vista/Windows 7 | ''C:\Users\<username>\AppData\Roaming\HoldingNuts\'' |

**Hint:** On Windows you can run the shortcut ''config_directory.lnk'' which opens the right location for you.

These files/directories can be found in it:

^ Name ^  Type  ^ Purpose ^
| ''client.cfg'' |  file  | Client configuration |
| ''server.cfg'' |  file  | Server configuration |
| ''client.log'' |  file  | Client log file //(if logging is enabled)// |
| ''server.log'' |  file  | Server log file //(if logging is enabled)// |
| ''screenshots'' |  directory  | Contains your taken screenshots |

===== Client =====

==== Configuration variables ====
Most variables are configurable via the settings dialog, too.

^ Name ^ Default value ^ Description ^ Version ^
| default_host | game.holdingnuts.net | default host to connect to | >= 0.0.2 |
| default_port | 40888 | default port to connect to | >= 0.0.2 |
| auto_connect | false | automatically connect to default server on startup | >= 0.0.3 |
| player_name | //System user name// | the player name | >= 0.0.2 |
| info_location | | the player's location (e.g. Country) | >= 0.0.2 |
| uuid | //generated on first start// | unique ID for re-connect | >= 0.0.2 |
| locale | | language/locale to use | >= 0.0.2 |
| encoding | UTF-8 | encoding for chat | >= 0.0.5 |
| log | true | log to file | >= 0.0.2 |
| log_timestamp | false | include timestamp in log | >= 0.0.3 |
| log_chat | false | include player chat in log | >= 0.0.2 |
| ui_show_handstrength | true | display hand strength on table | >= 0.0.2 |
| ui_centralized_view | true | enable centralized table view | >= 0.0.3 |
| ui_card_deck | default | card deck to use //(default=4-color deck, classic=2-color deck)// | >= 0.0.2 |
| ui_echo_password | true | echo password for private games by default | >= 0.0.3 |
| ui_bring_to_top | false | raise table window to top if player action expected | >= 0.0.4 |
| sound | true | play sounds | >= 0.0.2 |
| sound_focus | true | only play sound if window has focus | >= 0.0.2 |
| chat_console | false | send raw messages if chat message prefixed with '/' | >= 0.0.3 |
| chat_verbosity_foyer | 0x0f | verbosity level for foyer chat (mask) | >= 0.0.4 |
| chat_verbosity_table | 0x07 | verbosity level for table chat (mask) | >= 0.0.4 |
| version | //current HoldingNuts version// | internal: config file version | >= 0.0.2 |

==== Keyboard shortcuts ====

=== Table ===

^  Key  ^ Function ^ 
|  <widget key>F10</widget>  | create a screenshot |
|  <widget key>Ctrl</widget> + <widget key>F</widget>  | Fold (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>A</widget>  | Allin (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>B</widget>  | Bet (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>R</widget>  | Raise (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>C</widget>  | Call (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>C</widget>  | Check (availability depends on game context) |
|  <widget key>Ctrl</widget> + <widget key>O</widget>  | Sitout |
|  <widget key>Ctrl</widget> + <widget key>K</widget>  | I'm back |


==== Command line options ====

^ Option ^ Purpose ^
| ''-c <config-dir>'' | Use an alternative configuration directory instead of the default user data directory. |

===== Server =====

==== Setup a server ====
Setting up an own server is really easy.

First, create a proper configuration file. The server's config file is ''server.cfg'' (see above sections regarding the location of the file).
These are two possibilities to setup a config:
  * Start and stop the server. If there's no config-file present when the server is started, it'll create one with all available configuration options (default values).
  * Create an own configuration from scratch.

Now you're ready to start the server.
  * Windows: The executable is called ''holdingnuts-server.exe''. Run it by double-clicking on it. A windows-console window with log-messages will appear.
  * Linux: The executable is called ''holdingnuts-server''. Run it in a terminal ''./holdingnuts-server'' (relative path) or just ''holdingnuts-server'' if it's in the executable path.

**Note:** You need to configure your firewall or router to forward a port (default: 40888 TCP) to the server if you want other players to connect from the internet. See [[http://portforward.com/]] for more information.

**Hint on Linux:** Although there is no daemon-mode for running the server in the background you can start the server in a [[wp>GNU_Screen|screen terminal session]]. Just create a new session with the command ''screen'' and then start the server as usual. Press <widget key>CTRL</widget> + <widget key>A</widget> and then <widget key>D</widget> to detach the session. In order to reattach a previous session run the command ''screen -r''.

==== Configuration variables ====

^ Name ^ Default value ^ Description ^ Version ^
| port | 40888 | port the server is listening on | >= 0.0.2 |
| max_clients | 200 | limit for client connections | >= 0.0.2 |
| max_games | 100 | limit for games | >= 0.0.2 |
| max_connections_per_ip | 3 | limit for connections per IP | >= 0.0.2 |
| max_register_per_player | 2 | limit for register per player | >= 0.0.2 |
| max_create_per_player | 2 | limit for creating games per player | >= 0.0.2 |
| log | true | log into file | >= 0.0.2 |
| log_timestamp | true | include timestamp in log | >= 0.0.3 |
| auth_password | | server authentication password; if unset, authentication is disabled | >= 0.0.2 |
| perm_create_user | true | allow regular user to create games | >= 0.0.2 |
| conarchive_expire | 30 * 60 | stored connection data expiration (seconds) | >= 0.0.2 |
| flood_chat_interval | 10 | flood-protect: interval for measureing (seconds) | >= 0.0.2 |
| flood_chat_per_interval | 5 | flood-protect: count of messages allowed in interval | >= 0.0.2 |
| flood_chat_mute | 60 | flood-protect: mute time (seconds) | >= 0.0.2 |
| welcome_message | | welcome message sent on state info | >= 0.0.4 |
| version | //current HoldingNuts version// | internal: config file version | >= 0.0.2 |


==== Command line options ====

^ Option ^ Purpose ^
| ''-c <config-dir>'' | Use an alternative configuration directory instead of the default user data directory. |


===== Troubleshooting =====

==== The client complains about missing data directory ====
Possible causes:
  * Directory ''data'' does not exist or is at wrong location.
  * The client is started in a directory not containing the ''data'' directory.
Solution:
  * on Unix-like OS: Install HoldingNuts properly or run executable within extracted directory or use the ''holdingnuts.sh'' wrapper script.
  * on Windows: Make sure to run the client within the extracted directory. If you're using a shortcut, set the ''working directory'' property to the extracted directory path.

===== Misc =====
==== How to convert a timestamp in log-file into a readable date? ====
If the config option ''log_timestamp'' is set to ''true'', the log entries will contain [[wp>Unix_time|UNIX timestamps]].
  [1240592846 listensock]  (9) accepted connection (85.25.124.113)

On an UNIX-like OS you can convert these timestamps with this simple command:
<code>
$ date -d @1240592846
Fri Apr 24 19:07:26 CEST 2009
</code>