# La manuel de &kapp;

Gael
Kleag
de Chalendar

    Kleag@free.fr

&traducteurStanislasZeller;
2002-2008
Gael de Chalendar
&FDLNotice;
18/08/2005
1.03.00

&kapp; est la version informatique d'un jeu de stratégie bien connu. Une version commerciale et d'autres versions libres existent mais moi (Gaël de Chalendar) a créé initialement ce jeu comme un exercice d'apprentissage de C++ et, donc, développé à ce point (se référer au README pour plus de détails).

Dans cette version, &kapp; est un jeu en réseau multi-joueurs avec une IA (se référer au TODO pour plus de détails).

Cette documentation donne les informations nécessaires dont vous avez besoin pour démarrer une partie. Veuillez lire les astuces et les messages de la barre d'état pour compléter ces informations. Un chapitre explique comment créer de nouveaux thèmes pour &kapp;.

Le but de ce jeu est simplement de conquérir le monde... En attaquant ses voisins avec vos armées. Paisible, n'est-ce pas :-)

KDE
jeu kde
jeu
stratégie
Risk
libre
GPL
Réseau
Ordinateur

## Introduction

&kapp; est la version informatique d'un jeu de stratégie bien connu. Une version commerciale et d'autres versions libres existent mais moi (Gaël de Chalendar) a créé initialement ce jeu comme un exercice d'apprentissage de C++ et, donc, développé à ce point (se référer au README pour plus de détails).

Voici une capture d'écran de &kapp; Capture d'écran

Dans cette version, &kapp; est un jeu en réseau multi-joueurs avec une IA (se référer au TODO pour plus de détails).

Cette documentation donne les informations nécessaires dont vous avez besoin pour démarrer une partie. Veuillez lire les astuces et les messages de la barre d'état pour compléter ces informations.

Le but de ce jeu est simplement de conquérir le monde... En attaquant ses voisins avec vos armées. Paisible, n'est-ce pas :-)

## Utilisation de &kapp;

### Jouer à &kapp;

Remarque préliminaire : le plan peut être parcouru avec trois méthodes. La première : vous pouvez coller votre curseur de souris sur les bords de la fenêtre et le plan va se déplacer dans cette direction. La deuxième : vous pouvez utiliser votre molette de souris; sans modificateur, le curseur va se déplacer verticalement ; en pressant la touche Meta, le curseur va se déplacer horizontalement. Et enfin, la troisième : vous pouvez utiliser les flèches du clavier.

#### Démarrer une partie

Quand &kapp; démarre, un menu principal s'affiche. Le menu principal de &kapp; Menu principal

Nouvelle partie

  Démarre une nouvelle partie

Rejoindre

  Permet de rejoindre un jeu en réseau comme client

Charger

  Utilise une partie précédemment enregistrée

Quitter

  Peut-être que finalement vous ne voulez plus jouer ?

Le bouton « Nouvelle partie » va afficher une boîte de dialogue où vous pourrez choisir le nombre de joueurs, le thème à utiliser, le type de jeu (conquérir l'objectif ou avoir un objectif spécial) et finalement si la partie doit être jouée en réseau ou en local. La boîte de dialogue de nouveau jeu La boîte de dialogue de nouveau jeu

Pour démarrer une partie en réseau, cochez « Jeu en réseau » sur la droite sur la boîte fléchée du nombre de joueurs. Après avoir cliqué sur Ok, vous pourrez choisir la configuration réseau : le nombre de joueurs en réseau et le port TCP où les connexions seront attendues. Boîte de dialogue de la configuration du jeu en réseau Boîte de dialogue de la configuration du jeu en réseau

Ensuite, les joueurs en réseau peuvent se connecter en choisissant « Rejoindre » sur l'écran d'introduction et en indiquant leur IP ou le nom d'hôte de leur hôte et le numéro de port qu'ils viennent de configurer. Boîte de dialogue de configuration pour rejoindre un jeu en réseau Boîte de dialogue de configuration pour rejoindre un jeu en réseau

Chaque connexion est indiquée par un message en dessous dans la barre d'état. Message de connexion Message de connexion

Supposons que vous laissez tous les paramètres par défaut et cliquez sur Ok. Vous devrez ensuite configurer deux joueurs, l'un après l'autre. Pour chacun d'eux, vous allez choisir un nom, une nationalité, et si vous le voulez, un mot de passe que personne ne pourra réutiliser pour ce joueur quand la partie enregistrée sera chargée. Enfin, vous allez spécifié si le joueur est dirigé par l'ordinateur ou par un joueur humain. La boîte de dialogue de configuration du joueur La boîte de dialogue de configuration du joueur

Ensuite, si vous choisissez de jouer avec un objectif, l'objectif de chaque joueur local est affiché, précédé par un avertissement que les autres joueurs regardant le même ordinateur peuvent discrètement fermer après que l'objectif a été lu. La boîte de dialogue d'affichage du type d'objectif La boîte de dialogue d'affichage du type d'objectif Le message d'avertissement de l'affichage de l'objectif Le message d'avertissement de l'affichage de l'objectif

#### Distribution

Au démarrage de la partie, les pays sont distribués à tous les joueurs. Chaque pays contient une armée (représentée par une unité d'infanterie) au départ. Chaque joueur a des armées à redistribuer à ces pays quand vient leur tour (indiqué par la présence de leur nom et leur drapeau dans la barre d'état). Remarquez que cinq armées sont représentées par un régiment de cavalerie et dix par un canon.

Pour placer une armée sur un de vos pays, cliquez dessus avec le bouton gauche de la souris. Pour supprimer une armée, cliquez avec le bouton droit. Remarquez, qu'en règle générale, vous ne pouvez pas supprimer plus d'armées que le nombre à placer. Armées à placer Armées à placer

Quand un joueur a distribué toutes ses armées, le joueur suivant est automatiquement sélectionné et réalise la même tâche. Quand tous les joueurs ont terminé la distribution de leurs armées, il y a deux possibilités qui peuvent être sélectionnées avec deux boutons affichés sur le panneau de droite :

Redistribution : redistribution

  Un joueur veut modifier quelque uns de ses choix. Le premier joueur peut ensuite supprimer une armée qu'il vient juste de placer sur un pays avec le bouton droit de la souris, et la placer dans un autre pays avec le bouton gauche. Quand il a terminé, il donne le contrôle au joueur suivant avec le bouton « Ok ». Quand tous les joueurs ont terminé leur redistribution, les deux boutons sont encore une fois affichés.

Fin de la redistribution : fin de la redistribution

  La redistribution est terminée et la partie peut continuer.

#### Combat

Après la redistribution, un tour démarre. Chaque joueur joue à tour de rôle. Le joueur a le choix de :

Joueur suivant : donne la main au joueur suivant (bouton sur la barre d'outils).

  Le tour du joueur courant se termine et c'est au tour du joueur suivant.

Attaque 1 Attaque 2 Attaque 3 : attaque avec une, deux ou trois armées Attaque automatique

  Pour attaquer, cliquez avec la souris sur le pays attaquant et glissez le sur le pays que vous attaquez. Un menu contextuel va vous être présenté affichant les entrées ci dessous. Menu attaque Menu attaque Pour qu'un pays X attaque un pays Y avec x armées, deux conditions doivent être remplies : 1. les deux pays doivent être voisins ; 2. le pays X doit avoir au moins x+1 armées avant d'attaquer. Si l'attaque est valable, une boîte de dialogue est affichée si nécessaire pour que le défenseur puisse choisir si il veut défendre avec une ou deux armées ou s'il laisse l'ordinateur décider.

  Quand le choix de défense est effectué, la bataille commence et se termine. Le processus est décrit ci dessous. Boîte de dialogue de défense Boîte de dialogue de défense

Déplacer les armées : déplacer les armées d'un pays à un autre

  Ceci est la dernière action du tour d'un joueur. Cela lui donne la possibilité de déplacer des armées d'un de ces pays vers un pays voisin. Pour choisir deux pays, veuillez sélectionner et déplacer de la même manière qu'une attaque. Quand les deux pays sont sélectionnés, une glissière est affichée avec laquelle vous pouvez choisir combien d'armées seront envoyées sur chaque pays.

#### Conséquence de la bataille

Pour chaque armée dans la bataille correspond un quota de pertes. Le joueur qui a le chiffre le plus élevé sur le dé, qu'il soit attaquant ou défenseur, remporte le tour et celui qui a le chiffre le plus faible sur le dé perd des armées selon le chiffre affiché. Résultat affiché de l'attaque Résultat affiché de l'attaque

Si le nombre d'armées dans le pays attaqué atteint 0, le propriétaire de ce pays change pour le pays attaquant : son drapeau est ajouté et une de ses armées d'attaque est installé sur son nouveau pays. Glissière d'invasion Glissière d'invasion

#### Fin du tour

Pour terminer le tour courant, si vous ne voulez pas déplacer des armées, vous pouvez cliquer sur le bouton « Joueur suivant » sur la barre d'outils.

Quand tous le monde a joué, le tour prend fin. Des armées sont distribuées aux joueurs, en fonction des pays leur appartenant : 1 armée pour chaque groupe de trois pays, avec un minimum de 3. Il y a aussi un bonus pour les joueurs qui détiennent un continent complet, différent pour chaque continent. Les valeurs de ces bonus pour le thème par défaut sont :

##### Bonus gagnés par continents

Continent | Bonus
--- | ---
Amérique du Nord | 5
Amérique du Sud | 2
Europe | 5
Afrique | 3
Asie | 7
Zone Pacifique | 2

Quand un joueur a fini de distribuer ses armées, il clique sur le bouton « Ok » pour permettre au joueur suivant de distribuer à son tour ses armées. Comme pour la distribution initiale, quand tous les joueurs ont placé leurs armées, ils peuvent démarrer une nouveau cycle de distribution ou démarrer un nouveau tour.

#### Envoi de messages aux autres joueurs

Si vous jouez en mode local et voulez communiquer avec les autres joueurs, et bien, parlez (en supposant que vous n'avez pas de problèmes d'accessibilité)... Mais si vous jouez en mode réseau, vous pouvez utiliser la boîte de dialogue de discussion en bas de la fenêtre (elle peut être cachée ou affichée en utilisant les flèches). Saisissez simplement votre message et utilisez la touche « Entrée ». Envoi de messages Envoi de messages

## Référence de commande

### La fenêtre principale de &kapp;

#### Les boutons

Quitter la partie : quitter la partie

  Permet de sortir du programme

Nouvelle partie : nouvelle partie

  Démarre une nouvelle partie. Une boîte de dialogue apparaît vous demandant le nombre de joueurs. À l'étape suivante, chaque joueur doit saisir un nom.

## Guide des développeurs de &kapp;

Veuillez vous référer à la documentation de KDoc pour l'API. Elle est assez complète mais n'est actuellement pas très à jour. Les commentaires sont inexistants dans les fichiers d'implantations `.cpp`.

Remarquez que j'ai à l'origine développé ce jeu sous Windows avec Borland C++ et WinG. Je l'ai porté sous &Java; avant de le convertir en C++ pour &kde;. Au commencement, j'ai utilisé le français et un mixte de français et d'anglais pour nommer mes identifiants (noms de classe, méthodes, membres, &etc;). J'ai aussi utilisé le français pour les commentaires. Quand j'ai décidé de distribuer ce jeu, j'ai tout converti en anglais... Mais je ne suis clairement pas un orateur natif anglais. Veuillez suggérer ou corriger et soumettre vos corrections aux commentaires de ce code ou à cette documentation.

## Création de nouveaux thèmes

&kapp; peut s'adapter à des thèmes décoratifs. Pour ceux qui ont des talents graphiques, la création d'un nouveau thème est aussi simple que copier un thème existant, éditer ou modifier les graphismes et mettre à jour les données dans un fichier de configuration .desktop. Une dernière étape est d'éditer le fichier décrivant ce qui s'installe.

Tous les exemples (textes et images) sont pris du thème par défaut de &kapp;.

### Structure des dossiers et des fichiers

- Data/ : les données utilisées par le programme pour gérer les images du thème.

  - CMakeLists.txt : décrit ce qu'il y a à installer.

  - onu.desktop : fichier principal pour la description du thème. Se référer à sa description ci dessous.

- Images/ : les images du thème (plan, images animées, etc.)

  - CMakeLists.txt : décrit ce qu'il y a à installer.

  - pool.svg : le plan et toutes les images animées utilisées dans le thème.

  - map-mask.png : l'image permettant au programme de trouver sur quel pays se situe la souris durant la partie (voir ci dessous).

  - *.png : les autres images sont des boutons d'images

- CMakeLists.txt/ : décrit ce qu'il y a à installer.

- Sounds/ : les fichiers sonores pour le thème.

### Le dossier Data

#### Le fichier onu.desktop

Le fichier est une description du contenu du thème. Il est utilisé pour décrire l'organisation du monde et comment il s'affiche. Le fichier a la structure suivante :

Un group onu contient un nombre d'entrées de pays, un nombre d'entrées de nationalités et enfin un nombre d'entrées de continents. Viennent plusieurs groupes contenant la description des différents images animées, la description des différents pays, continents, nationalités et objectifs.

La section suivante décrit le contenu de chaque groupe.

##### Le groupe onu

###### Les entrées du groupe onu

Saisissez un nom | Signification
--- | ---
largeur | La largeur du plan du thème
hauteur | La hauteur du plan du thème
skinpath | L'emplacement du thème relatif à l'emplacement des données de l'application (e.g. skins/default).
nb-countries | Le nombre de pays (42 dans le thème par défaut). Cela devrait être un nombre identique aux groupes de pays ci dessous.
nb-nationalities | Le nombre de nationalités (6 dans le thème par défaut). Cela devrait être un nombre identique aux groupes de nationalités ci dessous.
nb-continents | Le nombre de continents (6 dans le thème par défaut). Cela devrait être un nombre identique aux groupes de continents ci dessous.
pool | L'emplacement et le nom du fichier pool relatif à l'emplacement du thème (e.g. Images/pool.svg).
map-mask | L'emplacement et le nom du fichier de map-mask relatif à l'emplacement du thème (e.g. Images/map-mask.png).
format-version | La version du format de fichier du thème (2.0)
name | Le nom d'affichage du thème.
desc | La description du thème.
fighters-flag-y-diff | La différence de hauteur entre les images animées des drapeaux et des canons
width-between-flag-and-fighter | Le nombre de pixels entre le pixel le plus à gauche du drapeau et le pixel le plus à droite d'un simple canon (quand il ne tire pas ou n'explose pas).

##### Les groupes de description des images animées

Chaque type d'image animée (drapeau, infanterie, cavalerie, canon, canon faisant feu et canon explosant) est défini par un groupe. Seulement quelques images animées ont une entré « largeur ». Cette entré est utilisée pour le positionnement relatif pendant les animations : les canons faisant feu ou explosant ne doivent pas se déplacer vers le drapeau du pays pendant la bataille.

###### Les entrées du groupe de description des images animées

Entré | Signification
--- | ---
largeur | La largeur de référence des images animées du drapeau
hauteur | La hauteur de référence des images animées du drapeau
images | Le nombre d'images de l'image animée
versions | Le nombre de versions des images animées du drapeau

##### Les groupes de description des pays

Chaque pays listé dans le groupe onu. L'entré des pays a son propre groupe qui a comme titre le nom du pays. Le tableau ci dessous liste les entrées de ces groupes.

###### Entrées des pays

Saisissez un nom | Signification
--- | ---
id | Le nombre d'identification unique d'entier relatif du pays doit démarrer à zéro (0).
name | Le nom affiché du pays
<sprite>-point | Chaque type d'image animée (drapeau, infanterie, etc.) dans le pays est affiché sur une certaine position définie par l'entrée constituée de deux entiers relatifs séparés par une virgule.
voisins | La liste des ID des voisins du pays courant

##### Les groupes de description des nationalités

Chaque nationalité listé dans le groupe onu. L'entrée des nationalités a son propre groupe qui a comme titre le nom de nationalité. Le tableau ci dessous liste les entrées de ces groupes.

###### Entrées des nationalités

Saisissez un nom | Signification
--- | ---
name | Le nom de la nationalité (e.g. Japon)
Chef | Le nom qui est proposé au joueur choisissant la nationalité
drapeau | Le nom du drapeau animé du pays dans le fichier SVG onu

##### Les groupes de description des continents

Chaque continent listé dans le groupe onu. L'entrée des continents a son propre groupe qui a comme titre le nom du continent. Le tableau ci dessous liste les entrées de ces groupes.

###### Entrées des continents

Saisissez un nom | Signification
--- | ---
name | Le nom du continent (e.g. Afrique)
id | Le nombre d'identification unique d'entier relatif du continent
bonus | Le nombre d'armées obtenu à la fin du tour par le joueur qui est le propriétaire de tous les pays du continent.
continent-pays | La liste des ID des pays à l'intérieur du continent courant

##### Les groupes de description des objectifs

Chaque objectif listé dans le groupe onu. L'entrée des objectifs a son propre groupe qui a comme titre le nom de l'objectif. Le tableau ci dessous liste les entrées de ces groupes.

###### Entrées des l'objectifs

Saisissez un nom | Signification
--- | ---
type | Le type d'objectif. Peut être des continents, des pays ou un joueur
nbArmiesByCountry | Configure le nombre minimal des armées que le joueur doit placer sur chaque pays.
nbPays | Configure le nombre de pays que le joueur doit posséder
nbCountriesFallback | Pour le type d'objectif d'un joueur, si le joueur cible est tué par un autre, un nouvel objectif est configuré pour la conquête du monde à la place.
desc | Une description de l'objectif avec les propriétaires appropriés (*documentation supplémentaire demandée*)
continents | La liste des ID des continents que le joueur doit conquérir

### Le dossier Images

Ce dossier contient les boutons spécifiques à &kapp; et le fichier SVG pool qui contient la carte et toutes les images animées.

#### Le fichier pool.svg

Le fichier SVG contient la carte et toutes les images animées du jeu. Chaque élément est nommé de telle manière que le jeu peut sélectionner et afficher séparément chacun d'eux.

Dans le thème par défaut, les images animées sont les drapeaux, les infanteries, les cavaleries et les canons. L'infanterie représente une armée, cinq pour la cavalerie et dix pour les canons. Les canons sont aussi utilisés pour afficher les armées combattantes. C'est pourquoi il y a trois sortes de canon animé : statique, en mouvement, faisant feu ou explosant.

Chaque image animé est le résultat de plusieurs vues de l'objet et pour chaque vue, ses images. Les vues sont organisées verticalement et les images horizontalement. Où couper l'image en images individuelles est calculé en divisant la hauteur de l'image par le nombre de vues et la largeur par un nombre d'images. Ces données sont disponibles dans le fichier onu.desktop.

Un exemple d'une image animée : cannon.png

Pour les images animées des armées, il y a trois vues différentes, de haut en bas : vision vers la droite, vision vers la gauche et de face. Pour les drapeaux, il y a seulement une vue. Tous les fond des images animées doivent être configurés pour la transparence.

Un exemple d'image animé d'un drapeau : italy.png

##### Les éléments de pool

Nom de l'élément | Extrait d'image | Signification
--- | --- | ---
carte |  | Un thème de la carte du monde. Les pays peuvent avoir des formes, mais doivent être groupés dans des continents reconnaissables à l'œil, par emplacement seulement ou par couleur.
italie |  | Le drapeau de la nation italienne. Il y a une seule entrée pour chaque nation.
infanterie |  |
cavalerie |  |
canon |  |
faisant feu |  |
explosant |  |
Alaska |  |
désrouges |  |
repère1 |  |

#### Le fichier map-mask.png

C'est un fichier PNG représentant aussi un thème de la carte du monde, mais avec des couleurs qui permettent d'identifier chaque pays. Les pays doivent avoir au moins les mêmes formes que les pays correspondants sur le fichier map.png, où l'utilisateur peut cliquer n'importe où dans un pays visible et sélectionner le bon. Les pays, comme les petites îles tel que l'Indonésie dans la carte par défaut peuvent être meilleurs que l'équivalent dans le fichier map.png pour faciliter la sélection du pays. Un extrait de du fichier map-mask

Le composant bleu (dans le modèle RGB) de la couleur d'un pays identifie le pays : index 0 est le pays 0 dans le fichier onu.xml, index 1 est le pays 1, &etc;. Le blanc (0xFFFFFF en RGB) identifie l'absence de pays (mers ou, pourquoi pas des no man's land).

#### Les images des boutons

Les noms de fichier sont codés en dur dans le code, donc ils ne doivent pas être modifiés. Le tableau ci dessous affiche tous les boutons qui doivent être fournis.

##### Les boutons de l'&GUI;

Image | Nom de fichier | Signification
--- | --- | ---
| newNetGame.png | Essaie de se connecter à un jeu en réseau
| distributionArmees.png | Après que tous les joueurs ont placé leurs armées, il est possible de modifier les distributions (nommées « modifier »). Ce bouton demande aussi de faire une distribution.
| distributionArmeesFinie.png | Choisit de ne pas redistribuer. Toutes les fenêtres de clients doivent avoir ce bouton cliqué pour vraiment terminer la distribution.
| joueurSuivant.png | Termine le tour courant du joueur et passe au suivant ou au tour suivant si le joueur courant était le dernier.
| attackOne.png | Choisit de démarrer une attaque avec une armée.
| attackTwo.png | Choisit de démarrer une attaque avec trois armées.
| attackThree.png | Choisit de démarrer une attaque avec trois armées.
| defendOne.png | Choisit de défendre un pays attaqué avec une armée.
| defendTwo.png | Choisit de défendre un pays attaqué avec deux armées.
| moveArmies.png | Choisit de démarrer le mouvement des armées entre deux pays (dernière action du tour).

### Le dossier Sounds

Ce dossier contient trois fichiers sons : roll.wav joué quand les armées se déplacent ; cannon.wav joué quand les canons tirent et crash.wav joué quand un canon explose.

## Foire aux questions

&reporting.bugs; &updating.documentation;

Quelle sera la première question à propos de &kapp; ?

## Remerciements et licence

&kapp;

Copyright du programme 2002-2008 Gael de Chalendar kleag@free.fr

Contributeurs : Robin Doer, Albert Astals Cid, Michal Golunski (traduction polonaise)

Copyright de la documentation 2002-2008 Gael de Chalendar kleag@free.fr

Traduction française par &StanislasZeller;.

&underFDL; &underGPL;

## Installation

### Comment obtenir &kapp;

&install.intro.documentation;

### Compilation et Installation

&install.compile.documentation;

### Configuration

L'entrée du menu de configuration ouvre une boîte de dialogue qui vous permet de : Boîte de dialogue des préférences Boîte de dialogue des préférences

- Active ou désactive les sons :

- configure la vitesse des images animées (de lent à immédiat) :

- Active ou désactive les aides contextuelles affichées :

- Affiche ou cache le nombre d'armées de chaque pays. La capture d'écran suivante affiche un plan quand le nombre d'armées sont affichées. Affiche le nombre d'armées Affiche le nombre d'armées

&documentation.index;