2
<!--IMPORTANT: please note that 'Do not change this!' notice does not apply to translators -->
3
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
4
<!ENTITY kajongg "<application>Kajongg</application>">
5
<!ENTITY kappname "&kajongg;">
6
<!ENTITY kappversion "4.9.0"><!--Application version. Use this variable everywhere it is needed.-->
7
<!ENTITY package "kdegames"> <!-- do not change this! -->
8
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
9
<!ENTITY % addindex "IGNORE"> <!-- do not change this! -->
26
<!ENTITY mahjongg "mahjongg">
27
<!ENTITY originalcall "originalcall">
28
<!ENTITY violatesoriginalcall "violatesoriginalcall">
29
<!ENTITY dangerousgame "dangerousgame">
30
<!ENTITY nochoice "nochoice">
33
<!-- TODO: describe the window with the list of tables -->
35
<book lang="&language;"> <!-- do not change this! -->
37
<title>The &kajongg; Handbook</title> <!-- This is the title of this docbook. -->
38
<!-- List of immidiate authors begins here. -->
39
<!--INPORTANT! - All other contributors: [to be determined] -->
43
<firstname>Wolfgang</firstname>
44
<surname>Rohdewald</surname>
46
<email>wolfgang@rohdewald.de</email>
48
<!-- TRANS:ROLES_OF_TRANSLATORS -->
50
<legalnotice>&FDLNotice;</legalnotice>
52
<date>2012-03-28</date><!-- Date of (re)writing, or update.-->
53
<releaseinfo>&kappversion;</releaseinfo><!-- Application version number. Use the variable definitions within header to change this value.-->
55
<!--Short description of this document. Do not change unless necessary!-->
57
<para>This documentation describes the game of &kajongg; version &kappversion;</para>
60
<!--List of relevant keywords-->
62
<keyword>KDE</keyword> <!-- do not change this! -->
63
<keyword>kdegames</keyword> <!-- do not change this! -->
64
<keyword>game</keyword> <!-- do not change this! -->
65
<keyword>kajongg</keyword><!--Application name goes here-->
66
<!-- Game genre. Use as many as necessary. Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
67
<keyword>board</keyword>
68
<keyword>arcade</keyword>
69
<keyword>tile game</keyword>
70
<keyword>tiles</keyword>
71
<!--Number of possible players. It can be: One, Two,..., Multiplayer-->
72
<keyword>four players</keyword>
73
<!--All other relevant keywords-->
76
<!--Content begins here: -->
77
<chapter id="introduction"><title>Introduction</title> <!-- do not change this! -->
78
<note><title>Gametype:</title><para>Board, Arcade</para></note><!-- Game genre. Use as many as necessary. Available game types are: Arcade, Board, Card, Dice, Toys, Logic, Strategy.-->
79
<note><title>Number of possible players:</title><para>Four</para></note><!--Number of possible players. It can be: One, Two,..., Multiplayer-->
81
&kajongg; is a board game created after the famous oriental game of Mah Jong (from Chinese <foreignphrase lang="zh">麻將</foreignphrase>). It is played by four players. Worldwide many different rulesets are in use. Right now &kajongg; supports the Classical Chinese rules as played in Germany, eventually other main rulesets will follow. It is possible to customize or add new rulesets. Please do so and send them to the program author for integration!
84
&kajongg; can be used in two different ways: Scoring a manual game where you play as always without the help of a computer and use &kajongg; for the computation of scores and for bookkeeping. Or you can use &kajongg; to play against any combination of other human players or computer players.
89
<chapter id="screen_layout"><title>The Screen Layout</title>
92
<screeninfo>A screenshot of &kajongg;</screeninfo>
95
<imagedata fileref="gamescreen.png" format="PNG"/>
97
<textobject><phrase>Screenshot</phrase></textobject>
102
A quick explanation of the parts of the game screen.
108
The Toolbar is located beneath the menubar and contains buttons for the most often used actions. The content of the Toolbar can be edited. You can also make it invisible, giving more room to the Board.
110
Depending on the size of your screen you may want to make the toolbar invisible or to move it to the left side of the window. You can do that by right-clicking with the mouse
117
The Board is the largest section of the window. You see the four walls with a length of 18 tiles (the exact number depends on the rules like using bonus tiles or not).
118
The names of the players are written on the walls, together with the current value of the hand (as far as known) and their wind tiles. The prevailing wind has a coloured background, east in the screenshot above.
120
When <link linkend="play">playing</link>, the interior of the walls holds the tiles discarded by the players. They are randomly placed. The last discarded tile has a blue focus frame.
122
When <link linkend="scoreGame">scoring manual games</link>, the interior of the walls has a selection of all available tiles, the central selector. You can assign them to the players using the mouse or the keyboard.
127
<term>Player Region</term>
129
Every player has a screen range for her tiles. The upper row contains exposed tiles, the lower row concealed tiles.
130
When <link linkend="scoreGame">scoring manual games</link>, concealed tiles are shown with a shadow over the entire tile.
131
Bonus tiles go to the right end.
137
The dialog presents choices the player has. Most often it has a timeout with a progress bar showing the remaining time.
141
<term>Status bar</term>
143
The Status bar is located at the bottom of the screen and contains the current totals for the players.
149
<chapter id="scoreGame"><title>Scoring a Manual Game</title> <!-- do not change this! -->
151
In this mode, &kajongg; is only used to do the scoring. You play as usual with real people on a real table and at the end of a game you can tell &kajongg; the tiles a player has in her hand and everything else &kajongg; needs to know for calculating the scores - which is what the program will do. Alternatively you can calculate the hand scores manually and enter them. &kajongg; will then make the payments amongst the players and write the results into a data base. It is possible to suspend a game, start another game with other players and resume old games. All rules will be saved together with the games, so different games can be played with different rules.
155
From the menu, select <guimenu>Game</guimenu> / <guimenuitem>Score Manual Game</guimenuitem> or press <keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>.
158
Now you can either select an existing unfinished game or start a new game. If you start a new game, you will be asked for the players and the ruleset. &kajongg; will propose the same values used for the previous game. If there was no previous game, it will propose the first four defined players. Please note that you cannot change the ruleset or any of its rules after this selection. You can do that beforehand in <link linkend="ruleset-options">the ruleset editor</link>.
161
Now you get a new window titled "Enter the hand results". Read <link linkend="enterhand-tiles">Have &kajongg; compute the score</link> for a detailed description.
164
After saving hand results, continue with the next hand.
167
<sect1 id="enterhand"><title>Entering hand results</title>
168
<sect2 id="enterhand-scores">
169
<title>Scores</title>
171
<screeninfo>A screenshot of &kajongg;</screeninfo>
174
<imagedata fileref="enterhand.png" format="PNG"/>
175
</imageobject> <textobject><phrase>Screenshot</phrase></textobject>
179
This is the window for entering hand results. It automatically shows itself when &kajongg; thinks you might need it. You can always show or hide it by pressing <keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> or by selecting the corresponding menu entry.
182
As always the prevailing wind has its background colored.
185
Here you can manually enter scores for all players. Alternatively you can exactly define which tiles a player had in her hand. If you choose to do that, the corresponding field for the manual score value will be grayed out. &kajongg; will automatically compute the score.
188
After having entered all relevant data for a hand, press the button <guibutton>Save Hand</guibutton>. The hand values will be entered in the data base, and they are also shown in the score table. You might be prompted to change the seating positions of the players but you can choose not to change seats. The proposed changes are currently not customizable - if a ruleset needs something different, we will change that.
191
If the player might have won, the check box in the column "Winner" will be enabled - click this for the winner.
194
The status bar will now show the updated balances for the players, and you can continue with the next hand.
196
<sect3 id="enterhand-manually">
197
<title>Enter the score manually</title>
199
A good player will probably prefer to compute her score himself. In that case you can directly enter it. This is only possible when no tiles are selected for this player.
202
If you enter a manual score, it must already contain everything except penalties, you will have no optional rules to choose from. There is one exception: "Dangerous Game". This does not influence any scores, it is no offense either. It only means the payment between players is different: The offender pays all for all to the winner. The other two players do not exchange payments. This is currently not customizable.
205
<sect3 id="enterhand-tiles">
206
<title>Have &kajongg; compute the score</title>
208
If you explicitly tell &kajongg; what tiles a player holds, entering scores will be grayed out for that player in this window. While associating tiles with a player you will see how her score will grow - but as soon as you add the 14th tile the score goes to zero. That might surprise you but unless you declare this as the winner hand, it is recognized as a long hand which always has zero points. This behaviour is defined by the Classical Chinese ruleset, it might be different if you change the rules or use a different ruleset.
211
You can associate tiles and melds with a player using either the mouse or the keyboard or both. With the mouse simply move tiles by dragging/dropping them to the player region. When dropping the tile, you will be asked what you want to move: Single, Pair, Pung, Kong, Claimed Kong or Chow. The upper row is for exposed tiles, the lower row for concealed tiles. The bonus tiles will appear to the far right. You can also move tiles and melds between rows, between players and back to the central selector.
214
If you prefer using the keyboard, you can use 	 to move between the central selector and the player regions. The keys <keycap>eswnESWN</keycap> move a tile to the players East, South, West and North.
215
The keys <keycap>xX</keycap> move it back to the central selector. <keycap>ESWN</keycap> moves to the concealed row, <keycap>eswn</keycap> moves to the exposed row.
216
You can move the cursor between tiles or melds using the arrow keys, the currently selected tile or meld has a blue frame. Since the key arrows are far away from letters on the keyboard,
217
you can also use the letters <keycap>hjkl</keycap> or <keycap>HJKL</keycap> for moving the cursor. <keycap>hH</keycap> move left, <keycap>jJ</keycap> move down, <keycap>kK</keycap> move up,
218
<keycap>lL</keycap> move right. This is how the unix editor "vi" does it. The &kde; browser konqueror and even this help program also support those keys in the same way. Those keys may differ if you use a language other than English but it is currently not possible to configure them.
221
The options "Last Tile" and "Last Meld" are needed by some rules like "last tile completes pair". They can only be used for the winner hand.
224
In the right part of the window you can manually apply some rules. What rules appear in this list depends on the current ruleset and on the tiles. In the example of the above screen shot, the losing players might have an option "dangerous game" - again depending on the ruleset and on their tiles. It is the aim of the developers to keep this list of manually selectable rules as short as possible. Optimally &kajongg; should always be able to automatically determine whether a rule applies, but sometimes &kajongg; does not have enough information or knowledge to decide.
228
<sect2 id="enterhand-penalties">
229
<title>Penalties</title>
231
<screeninfo>A screenshot of &kajongg;</screeninfo>
234
<imagedata fileref="penalty.png" format="PNG"/>
236
<textobject><phrase>Screenshot</phrase></textobject>
240
In the <link linkend="enterhand">window for entering hand results</link>, the <guibutton>Penalties</guibutton> button will bring up this window where you can enter penalties. This can be done at any point in time independent of the normal scoring mechanism.</para>
241
<para>The <guilabel>Offense</guilabel> selection shows all offenses that might be applicable to the hands the players hold. Choose among them.</para>
242
<para>Now you can adapt the <guilabel>Total Penalty</guilabel>. This is the total sum that is moved from payers to payees. It will be evenly split between them.</para>
243
<para>Depending on the type of offense, the number of payers and payees varies. The right number of players is displayed. If you select a player, &kajongg; ensures that this player only occurs once by adapting the other players.
249
<chapter id="play"><title>Playing</title>
250
<para>At any time, you can enable or disable the Demo Mode. In Demo Mode, the computer will play for you. If no game is currently
251
played, a new game will be started with the last used ruleset.
253
<sect1 id="robotplay">
254
<title>Play against the computer</title>
256
First you will get a login dialog. Enter the game server you want to connect to and your user name. If you choose the special entry "Local Game",
257
you only need to enter your name (or accept the proposed name) and the wanted ruleset. This will immediately start a local game where you play
258
against 3 robot players. However if suspended games exist, they will be displayed in a list. You can then select the game you want to continue with
262
<sect1 id="humanplay">
263
<title>Play with friends</title>
265
If you want to play against other real people, you need a game server to which all players, including yourself, need to connect. Do that by
266
selecting any other host or by manually entering a new host name and by specifying your password for that host. The last used password will be
269
The easiest way is to use the game server at
270
<ulink url="http://www.kde.org/applications/games/kajongg/">kajongg.org</ulink>. &kajongg; will show this one in the list of possible game servers.
271
Please note that for now <ulink url="http://www.kde.org/applications/games/kajongg/">kajongg.org</ulink> only offers a game server but no web page or any other services.
273
If you do not have an account on the game server with the name you entered, you will be asked if you want to open an account. If you say yes, you will get a
274
new dialog where you can enter the wanted password twice. Your account will be created automatically.
276
After a successful login onto the game server, you will get a list of tables with available seats on that game server. Join a table or allocate a new table.
277
If you allocate a new table, wait until more seats are taken by other players. You can start the game on a table you allocated at any time, the seats
278
not taken will be filled by robot players.
280
The table list also shows the name of the ruleset played on that table. The ruleset and its name are sent to the game server by the player initiating the table.
281
If you have an identical ruleset, the table shows your name for the ruleset - this might be helpful if the table initiator speaks another language and named
282
the ruleset differently. Also, if the name of your local ruleset is displayed, it is displayed in black. If however you have no identical ruleset, the name
283
appears in red, and you can use the button <guibutton>Compare</guibutton> to compare it with your own rulesets.
285
If you do not use <ulink url="http://www.kde.org/applications/games/kajongg/">kajongg.org</ulink> or any other existing game server, you can start your own &kajongg; game server in two different ways:
286
<itemizedlist><listitem><para>
287
connect to the server "localhost". This is your own computer. If you do this and no game server is running, it will be started automatically. And when
288
you stop playing, the server will be stopped too.
289
</para></listitem><listitem><para>
290
manually start a server on any computer you want. All you need to do is go to a command line and start
291
the program <literal>kajonggserver</literal>. Entering <literal>kajonggserver --help</literal>
292
will show you all available options like changing the default port. This server will run until you kill it.
293
</para></listitem></itemizedlist>
295
In both cases you need to tell the other players how they can reach your game server. They need the &URL; or simply an IP address and the port your server is
296
listening on. This might be something like <literal>mypc.dyndns.org:8409</literal> where <literal>8409</literal> is the port. Of course you need to configure your firewall such that the remote
297
player can reach that port. The communication will be encrypted.
299
The server computes its default port from its version number.
300
If &kajongg; has version 4.9.5, port 8409 will be used: 8000 plus first version digit * 100 plus middle version digit.
301
If the player enters no port for the wanted game server, the client computes the port in the same way.
302
So if a computer runs several game servers with different program versions, you should normally reach the correct game server automatically.
303
Anyway the game server and the client will make sure that their versions are compatible and warn you otherwise.
305
If you encounter possible bugs, you might want to use the option <literal>--debug=traffic</literal>. This will show you, on the console where the game server has been started,
306
what messages are flowing between the game server and the clients.
308
<sect2 id="playing-caveats">
309
<title>Caveats</title>
310
<itemizedlist><listitem><para>
311
If you want to make sure nobody can cheat none of the human players should have access to the computer the game server is running on. Of course you can never avoid that two players help each other because you cannot know what they really are doing. Two players might even be one and the same person.
312
</para></listitem></itemizedlist>
315
<sect1 id="gamerules"><title>Game rules</title>
316
<para>Worldwide, many different game variants exist. Currently, &kajongg; supports two variants of Classical Chinese, one as played in Germany and one as played in Great Britain. </para><para>
317
This description does not go into details and as such matches both variants.</para><para>
318
However most of the basic rules are the same in most variants.</para>
319
<para>Since the program &kajongg; knows how to play, this description only contains things that might not be obvious.</para>
320
<para>If you want to learn Mah Jong in more detail, please consult the <link linkend="bibliography">bibliography</link>.</para>
321
<sect2 id="gamerules-aim">
322
<title>The aim of the game</title>
323
<para>Each player tries to collect tiles such that she has a winning hand. On achieving this, she calls "Mah Jong". In a winning hand, the tiles are normally grouped into five melds: Four
324
melds with three or four tiles each and a fifth meld consisting of two equal tiles. A normal meld has three or four identical tiles (called Pung
325
and Kong respectively) or three successive tiles like Bamboo 3, Bamboo 4, Bamboo 5 (called Chow).</para>
328
<title>The course of the game</title>
330
Initially, the player with the East wind (as indicated on the wall) has one more tile than the other players. East begins by discarding an unwanted tile.
333
Whenever a tile has been discarded, other players can claim it by saying what they can complete with that tile (Chow, Pung, Kong, Mah Jong).
334
Only the next player can claim a Chow - the other claims are possible for all players. A meld completed by a claim will be exposed - made visible
337
If nobody claims the discarded tile, the next player, South (and then West and North) gets a tile from the wall and discards an unwanted tile.</para>
338
<para>There are several rules about when a Pung can be extended to a Kong (by claiming the forth tile or by getting it from the wall) - these rules
339
are not explained here. But &kajongg; of course knows them and makes sure they are respected. If a Kong is declared, the player automatically gets
340
a replacement tile from the wall - otherwise it would not be possible to build the five melds as mentioned above.
344
<title>Year, Round and Hand</title><para>
345
When a player claims Mah Jong or we end up in a draw, a hand is completed. Now, except for draws, the winds rotate among the players.
346
This is repeated until every player once had every wind. This entire unit is called a round. An entire game, also called year, consists of four such rounds:
347
East wind round, South wind round, West wind round, North wind round. The wind of a round is also called prevailing wind, it can result in
348
higher scores.</para>
349
<para>So a full game (a year) consists of at least 16 hands. Since the winds do not rotate for draws or when the East player says Mah Jong, a higher
350
number of hands is normally needed for a full game.
351
</para></sect2><sect2><title>Bonus tiles</title>
352
<para>A game can contain eight bonus tiles (unless the rules exclude them). They are exposed separately on the right side of the player region
353
as they are never used for building melds. They do however generate bonus points.</para>
354
<para>If a player gets a bonus tile, she will automatically also get a replacement tile from the wall.</para></sect2>
355
<sect2><title>Scoring</title><para>
356
At the end of a hand, the score for each player is computed. First, basis points are counted like 2 points for a simple exposed pung or 20 points
357
for winning. Next, another set of rules is applied - those rules can double the points like one double for a meld of dragons. When the score for
358
each hand is known, differences are paid between players - while the winner gets its full score paid from all other players. East always gets and
359
pays twice her score.</para>
360
<para>Of course &kajongg; knows about all applicable rules but a good player knows what combinations get what score so she can optimize.
361
While learning it is recommended to activate the window <guimenuitem>Explain Scores</guimenuitem>.</para>
362
<para>The exact scoring rules often vary - in &kajongg; you are free to change them with the <link linkend="ruleset-options">the ruleset editor</link>.</para>
363
<para>The ruleset editor also shows you all available rules and their meaning. Place the mouse over them and for the
364
more exotic rules help text will appear.</para>
367
<sect1 id="playing-play">
368
<title>How to play with &kajongg;</title>
370
You will be prompted for what you want to do. This is a little dialog which appears either on the right or at the bottom depending on the size of the window. If
371
you make it broader than high, the dialog appears on the right. Sometimes the dialog will have a timeout - when it is over, the first possible answer is automatically selected for you.
372
This timeout is configurable in the Ruleset Editor, under <guilabel>Options</guilabel>, <guilabel>Claim Timeout</guilabel>.
373
All players should have the same timeout, that is why this is part of the ruleset.
375
If you need to select a tile from your hand, you can move between tiles using the right and left arrow keys or the letters h and l on your keyboard. Of course you can use the mouse too.
377
You can discard a tile by using the keyboard the same way as for all actions. Alternatively, you can use the mouse and move the tile from your hand into the
378
discard area (the interior of the walls). The placement of the tile in the discard area will still be done by the computer - because the placement should be the same for
381
Often, the dialogs will offer choices which are not really applicable like calling Pung when you do not have the needed tiles. This is intended - just like in a real game.
382
But you can configure impossible choices away: <guilabel>Options</guilabel>, <guilabel>Show only possible actions</guilabel>.
384
Discarded tiles are placed randomly between the walls. Some game variants define where the tiles should be placed, this is not yet configurable however. When it becomes configurable, it will be part of the ruleset.
389
<chapter id="interface"><title>Interface Overview</title> <!-- do not change this! -->
390
<!-- This section has to do with menubar. Describe every single entry in order. Use <variablelist> and <varlistentry>. Split the chapter into sections using <sect1(2,3)> for better viewing.-->
392
<sect1 id="game-menu">
393
<title>The <guimenu>Game</guimenu> Menu</title>
395
<varlistentry id="game-menu-scoreGame">
397
<guimenu>Game</guimenu>
398
<guimenuitem>Score Manual Game</guimenuitem>
400
<listitem><para><action>Only score a manually played game.</action></para><para>You can load an old game or start a new game. By default only pending (i.e. unfinished) games are shown in the selection list. You can optionally show all games including finished games. Here you can also delete games.</para></listitem>
402
<varlistentry id="game-menu-play">
404
<guimenu>Game</guimenu>
405
<guimenuitem>Play</guimenuitem>
407
<listitem><para><action>Play with others (people and computers)</action></para></listitem>
409
<varlistentry id="game-menu-abort">
411
<guimenu>Game</guimenu>
412
<guimenuitem>Abort Game</guimenuitem>
414
<listitem><para><action>Abort the current game. If it was a manual game with scoring only, you can resume it later. If you played using &kajongg;, the game is not yet resumable.</action></para></listitem>
418
<guimenu>Game</guimenu>
419
<guimenuitem>Quit &kajongg;</guimenuitem>
421
<listitem><para><action>Quits</action> &kappname;.</para></listitem>
425
<sect1 id="view-menu">
426
<title>The <guimenu>View</guimenu> Menu</title>
428
<varlistentry id="view-scoring">
430
<guimenu>View</guimenu>
431
<guimenuitem>Show Scoring Editor</guimenuitem>
433
<listitem><para><action>Scoring Dialog</action>: Show or hide the scoring dialog. This dialog is explained <link linkend="enterhand">here</link>.
436
<varlistentry id="view-scoretable">
438
<guimenu>View</guimenu>
439
<guimenuitem>Score Table</guimenuitem>
441
<listitem><para><action>Score Table</action>
443
<screeninfo>Score Table</screeninfo>
446
<imagedata fileref="scoretable.png" format="PNG"/>
449
<phrase>Screenshot</phrase>
453
Show the score table. Round/Hand are the current round (East, South, West, North) followed by a count of the hands played in that round.
454
The winner has a green background for her values.
455
The Payments show how much the player paid to or received from all other players with this hand.
456
The Balance shows the current balance for all players.
457
The Chart shows the development of the balance values.
458
The hints give you more details: They show all rules that have been applied to this hand. Just move the mouse over the value you are interested in.</para><para>
459
The lower part shows the used ruleset. Between the score table and the used ruleset you can find a splitter letting you change the relative sizes of both parts.
462
<varlistentry id="view-explain-scores">
464
<guimenu>View</guimenu>
465
<guimenuitem>Explain Scores</guimenuitem>
467
<listitem><para><action>Explain Scores</action></para>
469
<screeninfo>Score Table</screeninfo>
472
<imagedata fileref="explain.png" format="PNG"/>
475
<phrase>Score Table</phrase>
480
Explains how the score for the current hand was computed.
483
<varlistentry id="view-chat">
485
<guimenu>View</guimenu>
486
<guimenuitem>Chat</guimenuitem>
488
<listitem><para><action>Chat</action></para>
490
<screeninfo>Chat Window</screeninfo>
493
<imagedata fileref="chat.png" format="PNG"/>
496
<phrase>Chat Window</phrase>
501
Lets you chat with the other players.
506
<sect1 id="settings-menu">
507
<title>The <guimenu>Settings</guimenu> Menu</title>
511
<guimenu>Settings</guimenu>
512
<guimenuitem>Players</guimenuitem>
514
<listitem><para><action>Add, modify and delete players.</action></para>
515
<para>The passwords in this table are those used by default when logging onto
516
a game server. Changing the password you initially chose
517
for a game server is not yet really helpful because there is no way yet for you to also change
518
your password on the game server. You would have to ask the administrator of the game
519
server to do that for you directly in the data base.</para></listitem>
523
<guimenu>Settings</guimenu>
524
<guimenuitem>Change Visual Angle</guimenuitem>
526
<listitem><para><action>Changes the viewing angle of the tiles counterclockwise.</action></para></listitem>
530
<guimenu>Settings</guimenu>
531
<guimenuitem>Demo Mode</guimenuitem>
533
<listitem><para><action>Enables or disables the Demo Mode. See <link linkend="play">here</link> for details.</action></para></listitem>
535
<varlistentry id="settings-menu-statusbar">
537
<guimenu>Settings</guimenu>
538
<guimenuitem>Show Statusbar</guimenuitem>
540
<listitem><para><action>Shows or hides the Status bar.</action></para></listitem>
544
<guimenu>Settings</guimenu>
545
<guimenuitem>Full Screen Mode</guimenuitem>
547
<listitem><para><action>Switches between full screen mode and normal mode.</action></para></listitem>
549
<varlistentry id="settings-menu-shortcuts">
551
<guimenu>Settings</guimenu>
552
<guimenuitem>Configure Shortcuts...</guimenuitem>
554
<listitem><para><action>Displays a standard &kde; shortcut configuration dialog</action> for the <link linkend="default-keybindings">keyboard shortcuts</link> for &kappname;.</para></listitem>
556
<varlistentry id="settings-menu-toolbar">
558
<guimenu>Settings</guimenu>
559
<guimenuitem>Configure Toolbars...</guimenuitem>
561
<listitem><para><action>Displays a standard &kde; dialog where you can configure the toolbar icons.</action></para></listitem>
563
<varlistentry id="settings-menu-settings">
565
<guimenu>Settings</guimenu>
566
<guimenuitem>Configure &kappname;...</guimenuitem>
568
<listitem><para><action>Opens a <link linkend="configuration">configuration dialog</link> for &kappname;.</action></para></listitem>
572
<guimenu>Settings</guimenu>
573
<guimenuitem>Show Toolbar</guimenuitem>
575
<listitem><para><action>Shows or hides the Toolbar.</action></para></listitem>
579
<sect1 id="help"><!--This is a standard Help menubar entry. Only change if needed.-->
580
<title>The <guimenu>Help</guimenu> Menu</title>
581
&help.menu.documentation;
585
<chapter id="configuration"><title>Game Configuration</title> <!-- do not change this! -->
586
<!--This section describes configuration &GUI;. If your game is configured using menubar exclusively, please remove this section.-->
588
<screeninfo>Configure Dialog</screeninfo>
591
<imagedata fileref="config_play.png" format="PNG"/>
594
<phrase>Configure Dialog</phrase>
599
<para>The menu entry <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kappname;...</guimenuitem></menuchoice> opens the <guilabel>Configure - &kappname;</guilabel> dialog.</para>
600
<para>If you press the <guibutton>Cancel</guibutton> button here, all of your configuration changes will be reverted, including everything you did with the ruleset editor.</para>
602
You can also select the different tabs with the keyboard: <keycombo action="simul">&Ctrl;<keycap>1</keycap></keycombo> selects
603
the first tab <guilabel>Play</guilabel> options, <keycombo action="simul">&Ctrl;<keycap>2</keycap></keycombo> selects
604
the second tab, and so on.
607
<sect1 id="play-options"><title><guilabel>Play</guilabel> options</title>
611
<guilabel>Show tile shadows</guilabel>
614
This shows tiles with borders and shadows. Also there is some space between tile rows, and the wall tiles are shown such that you can see
615
that the wall is two or three tiles high. So if you disable this option, you have a simpler display with slightly larger tiles. This may be helpful
621
<guilabel>Rearrange undisclosed tiles to melds</guilabel>
624
This groups melds in the hand.
625
Sometimes the grouping might not be like you want it, so you might prefer to have no grouping at all, just like in a real world game.
630
<guilabel>Show only possible actions</guilabel>
633
When playing, show only possible actions like "No claim" or "Pung".
638
<guilabel>Propose what to do</guilabel>
641
Whenever you have a choice of actions like claiming a tile or not or like choosing which tile to discard, &kajongg; can help you by making a proposal.
646
<guilabel>Use sounds if available</guilabel>
649
This lets you hear discards and claims. If other players recorded sound files with their own voice, you can hear them.
654
<guilabel>Let others hear my voice</guilabel>
657
If you recorded sound files with your voice this option will let the other players
658
hear your discards and claims with your voice.
663
<guilabel>Animation speed</guilabel>
666
Define how fast the tiles should move around. If you move the slider to the rightmost position, tile movement is not animated:
667
the tiles will simply change place.
672
<sect2><title>Sound</title>
674
Playing gives you a much nicer experience if you hear players claim tiles and announce discards. It also makes playing
675
easier because you can concentrate on your own tiles, you do not have to watch what others discard.
678
&kajongg; comes with voices for different players. It automatically assigns voices to players. For every language there should be
679
four voices, preferably two male and two female. &kajongg; tries to use voices in the same language &kajongg; runs in. If it
680
finds no voices in that language, &kajongg; will fallback to other languages, using the same fallback languages you defined for
681
&kajongg; (see <menuchoice><guimenu>Help</guimenu><guimenuitem>Switch Application Language</guimenuitem></menuchoice>). If no
682
voice files exist yet for your language, you are invited to record and contribute them to &kajongg;.
685
</para><itemizedlist><listitem><para>
686
This is how you can generate voices yourself. There is a separate directory for every voice. There are two groups of voices
687
with different places in the file system:
688
<itemizedlist><listitem><para>
689
Predefined voices for every language. They live in a directory like <filename class="directory">/usr/share/kde4/apps/kajongg/voices/LANG</filename> where
690
LANG is the code for your language. The voice directories directly under <filename class="directory">.../kajongg/voices/</filename> are the US-english
691
versions. Predefined voices are randomly assigned to players. Those voices have names like <literal>"male1 male2 female1 female2"</literal> but those names do not matter, the user will never see them. Also, it makes no sense to define more than four predefined voices per language.
692
</para></listitem><listitem><para>
693
User voices can be defined for a specific user.
694
If &kajongg; makes use of such a voice, it can automatically be transferred to other players
696
Those voices live in a directory like <filename class="directory">~/.kde/share/apps/kajongg/voices/</filename>.
697
So if your login name is joe, this might be <filename class="directory">/home/joe/.kde/share/apps/kajongg/voices/joe/</filename>.
698
The directory <filename class="directory">voices/</filename> might not yet exist - if so, create it.
699
</para></listitem></itemizedlist>
700
</para></listitem><listitem><para>
701
Now that you know where to place your new voice, generate a new directory for it.
702
</para></listitem><listitem><para>
703
In that subfolder, you can place the sound files. They have to be encoded with the <ulink url="http://xiph.org/vorbis/">Ogg Vorbis</ulink> audio compressor, the file names need to
704
have the extension <filename class="extension">.ogg</filename>.
705
A single file has a name like <filename>s3.ogg</filename> - this is Stone 3. You should define such files for all tiles and
706
for all claims and announcements. But if a sound file is missing, nothing bad happens - you just will not hear that sound. Fallback
707
to other voices or languages only works for entire voices, not for single sound files.
708
</para></listitem><listitem><para>
709
After having defined all sound files for a predefined voice, please make sure that the &kajongg; process has write permission in
710
the new voice directory. Start &kajongg; and test the voice. After everything is OK, you can revoke write permission (and you should
711
do so for predefined voices). &kajongg; will automatically generate a file named <filename>md5sum</filename> containing a checksum
712
over all sound files. Whenever you change, add or delete a sound file for a voice, &kajongg; will try to rewrite that file.
713
</para></listitem></itemizedlist>
715
Please make the length of the sound short but speak clearly - this game can be played very fast when you get used to it. It is easier
716
if you first write down a list with everything that should be spoken. Do not read it as a sequence of items, try to pronounce each
717
item as if it were the only one and as you would when playing. Leave room between the items. Reading this needs a little practicing.</para>
719
This is just one possibility to create the sound files:
720
</para><para><itemizedlist><listitem><para>
721
Record a sound file with the program <command>qarecord</command>, save it in the <literal>WAV</literal> format.
722
In this single sound file, speak all of the sounds.
723
</para></listitem><listitem><para>
724
Edit that file with the sound editor <command>audacity</command>. In that editor, use the mouse to mark a range of the sound waves.
725
The editor will play that part. Repeat until you have the correct part selected.
726
This may be easier if you <menuchoice><guimenu>View</guimenu><guimenuitem>Zoom In</guimenuitem></menuchoice>.
727
Use the menu command <menuchoice><guimenu>File</guimenu><guimenuitem>Export Selection</guimenuitem></menuchoice> and save in the ogg format.
728
Under <guilabel>Options</guilabel>, choose low quality - this is sufficient and even
729
wanted because this reduces the time to transfer the sounds to the other players.
730
</para></listitem></itemizedlist></para>
731
<para>The following are the names of the files that you should generate. Always append <filename>.ogg</filename> to them:</para>
734
<title>Sound file names</title>
738
<entry>&s1; .. &s9;</entry><entry>Stone 1 to Stone 9</entry>
741
<entry>&b1; .. &b9;</entry>
742
<entry>Bamboo 1 to Bamboo 9</entry>
745
<entry>&c1; .. &c9;</entry>
746
<entry>Character 1 to Character 9</entry>
749
<entry>&we; &ws; &ww; &wn;</entry>
750
<entry>The winds East, South, West, North</entry>
753
<entry>&db; &dr; &dg;</entry>
754
<entry>The dragons blue/white, red, green</entry>
757
<entry>&chow; &pung; &kong; &mahjongg;</entry>
758
<entry>The major claims</entry>
761
<entry>&originalcall; &violatesoriginalcall;</entry>
762
<entry>Original Call and its violation</entry>
765
<entry>&dangerousgame;</entry>
766
<entry>A player lets off a cannon (dangerous game)</entry>
769
<entry>&nochoice;</entry>
770
<entry>A player declares he has no choice but to play dangerous game</entry>
778
<sect1 id="tiles-options"><title><guilabel>Tiles</guilabel> options</title>
780
<screeninfo>Tileset selector</screeninfo>
783
<imagedata fileref="config_tiles.png" format="PNG"/>
785
<textobject><phrase>Tileset selector</phrase></textobject>
789
Use the <guilabel>Tiles</guilabel> selector to select graphics for the tiles.
793
<sect1 id="background-options"><title><guilabel>Background</guilabel> options</title>
795
<screeninfo>Background selector</screeninfo>
798
<imagedata fileref="config_background.png" format="PNG"/>
800
<textobject><phrase>Background selector</phrase></textobject>
804
Use the <guilabel>Background</guilabel> selector to select a background graphic for the game.
805
</para><para>Some backgrounds like the Chinese Landscape need some time to load. If you feel that
806
the program should start faster or that resizing the main window takes too long, you might try some
811
<sect1 id="ruleset-options"><title>Ruleset Editor</title>
813
<screeninfo>Ruleset Editor</screeninfo>
816
<imagedata fileref="ruleseteditor.png" format="PNG"/>
818
<textobject><phrase>Ruleset Editor</phrase></textobject>
822
Use the Ruleset Editor to customize rulesets. Predefined rulesets are shown in an italic font, customized rulesets have a normal font. Predefined rulesets cannot be changed by the user in any way, however an update of &kajongg; might. Customized rulesets will never be affected by an update.
824
When starting a new game, you will be able to select a ruleset for that game. All rulesets defined in the ruleset editor can be used. The ruleset is saved together with the game, so you can always change rulesets here - your changes will only affect future games.
826
<sect2><title>Rule, Points, x2, Limits</title><para>
827
Simply double click on whatever you want to change.
828
If all values are cleared, this rule will have no influence on the game.
829
Rules cannot be deleted.</para>
831
<sect2><title>Copy and Remove</title><para>
832
You can copy and remove entire rulesets.
834
Again this can even be done if existing games use this ruleset since every game has its own ruleset copy. You can view rulesets for old games: <link linkend="game-menu-scoreGame">Load</link> the old game and <link linkend="view-menu">show its score table</link>.
837
<sect2><title>Compare</title><para>
839
<screeninfo>Ruleset Comparator</screeninfo>
842
<imagedata fileref="differ.png" format="PNG"/>
844
<textobject><phrase>Ruleset Comparator</phrase></textobject>
847
You can select this command when an entire ruleset is selected. It lets you compare the selected ruleset against any other ruleset.
851
<sect1 id="default-keybindings">
852
<title>Default Keybindings</title>
854
<para>The menu entry <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure ...</guimenuitem></menuchoice> allows you to change the default keyboard bindings.</para>
857
The default shortcuts are as follows:
864
<term><keycap>F1</keycap></term>
867
Displays this handbook.
873
<term><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></term>
882
<term><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></term>
885
Play a game with friends or computer players.
891
<term><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></term>
894
Abort the current game.
900
<term><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></term>
909
<term><keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo></term>
912
Show the score table.
918
<term><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></term>
927
<term><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></term>
930
Change the viewing angle.
936
<term><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo></term>
939
Enables or disables the Demo Mode.
945
<term><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></term>
954
<term><keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></term>
968
<appendix id="problems"><title>Known problems</title>
970
<listitem><para>It is not yet possible for the player herself to open an account on the game server.</para></listitem>
971
<listitem><para>In playing mode, penalties are not yet possible.</para></listitem>
972
<listitem><para>The computer players are still rather stupid.</para></listitem>
976
<appendix id="future"><title>Possible future features</title>
978
<listitem><para>Add more rulesets. This should optionally be done by people using those rulesets regularly.</para></listitem>
982
<appendix id="faq"><title>Frequently asked questions</title> <!-- do not change this! -->
983
<!--This chapter is for frequently asked questions. Please use <qandaset> <qandaentry> only!-->
985
<!--Following is a standard list of FAQ questions.-->
987
<question><para>I want to change the way this game looks. Can I? </para></question>
988
<answer><para>Yes. To change the way &kajongg; looks use the <link linkend="settings-menu-settings">menubar</link> to open the <link linkend="configuration">configuration utility</link>.</para></answer>
991
<question><para>Can I use the keyboard to assign tiles to players?</para></question>
992
<answer><para>Yes. See <link linkend="enterhand-tiles">Have &kajongg; compute the score</link></para></answer>
994
<!--Please add more Q&As if needed-->
999
<appendix id="credits"><title>Credits and License</title> <!-- do not change this! -->
1000
<!--This chapter is for credits and licenses.-->
1006
Program Copyright © 2009, 2010, 2011, 2012 <personname><firstname>Wolfgang</firstname><surname>Rohdewald</surname></personname> <email>wolfgang@rohdewald.de</email>
1009
Documentation Copyright © 2009, 2010, 2011, 2012 <personname><firstname>Wolfgang</firstname><surname>Rohdewald</surname></personname> <email>wolfgang@rohdewald.de</email>
1012
<!-- !!!do not change ANYTHING after this line!!!! -->
1013
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
1019
<appendix id="bibliography">
1020
<title>Bibliography</title>
1022
<listitem><para>Das Chinesische Mah-Jongg-Spiel by Uwe Martens 2005, Books on Demand GmbH, Norderstedt. This book is an excellent German reference containing everything you
1023
want to know about the rules used in Germany and many other aspects of the game.</para></listitem>
1024
<listitem><para>The Complete Book of Mah-Jongg by A. D. Millington, 1977 (with several paperback editions up to 2003), Weidenfeld & Nicolson, London.
1025
This is the ultimate reference for Classical Chinese Mah Jong as played in the Western world. It can give you valuable hints about game strategies.</para></listitem>
1026
<listitem><para>Mah-Jong by Gwyn Headley and Yvonne Seeley, 3rd edition, 2008, A & C Black Publishers Ltd., London. This book is a very easy to use reference, concentrating
1027
on the rules as used in Great Britain, defined by the BMJA (The British Mah Jong Association).</para></listitem>
1028
<listitem><para><ulink url="http://en.wikipedia.org/wiki/Mahjong"></ulink></para></listitem>
1029
<listitem><para><ulink url="http://de.wikipedia.org/wiki/Mahjongg"></ulink></para></listitem>
1033
<appendix id="installation">
1034
<title>Installation</title>
1036
Use the .deb package from <ulink url="http://www.kde-apps.org/content/show.php/kajongg?content=103206"></ulink>. If it does not work for you, you can download kajongg-x-y.tar.gz from the same address and then do:
1039
tar xfz kajongg-x-y.tar.gz
1044
In both cases you will manually have to make sure that some other required packages are installed. The debian package does not yet
1045
contain these requirements. &kajongg; needs: (corresponding debian packages in parentheses)
1048
<listitem><para>the KDE4 games library (libkdegames5)</para></listitem>
1049
<listitem><para>Python 2.6 or higher (python)</para></listitem>
1050
<listitem><para>QT4.4 or higher (libqt4-core, libqt4-gui, libqt4-svg, libqt4-sql, libqt4-sql-sqlite)</para></listitem>
1051
<listitem><para>the python bindings for QT4 (python-qt4, python-qt4-sql)</para></listitem>
1052
<listitem><para>the python bindings for KDE4 (python-kde4)</para></listitem>
1053
<listitem><para>the python twisted library (python-twisted-core)</para></listitem>
1054
<listitem><para>sqlite3 (libsqlite3-0)</para></listitem>
1059
&documentation.index;
1064
sgml-minimize-attributes:nil
1065
sgml-general-insert-case:lower
1068
sgml-namecase-general:t
1069
sgml-always-quote-attributes:t
1071
sgml-indent-data:nil
1072
sgml-parent-document:nil
1073
sgml-exposed-tags:nil
1074
sgml-local-catalogs:nil
1075
sgml-local-ecat-files:nil
added
removed
doc/kajongg/index.docbook
