# Il manuale di &kapp;

Gael
Kleag
de Chalendar

    Kleag@free.fr

Dario
Panico

    Dareus_Persarumrex@fastwebnet.it

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

&kapp; è la versione computerizzata di un famoso gioco di strategia. Esistono una versione commerciale e una libera ma io (Gael de Chalendar) ho creato questo gioco inizialmente come esercizio per imparare il C++ e poi l'ho sviluppato fino a questo punto (vedi README per i dettagli).

Alla versione attuale, &kapp; è un gioco con funzionalità di rete per più di un giocatore, con una IA di base. (vedi TODO per i dettagli)

Questa documentazione fornisce le principali informazioni necessarie per iniziare a giocare. Leggi i suggerimenti e i messaggi della barra di stato per completare le informazioni. Un capitolo spiega come creare nuovi temi per &kapp;

Lo scopo del gioco è semplicemente conquistare il Mondo... Lo otterrai attaccando i tuoi vicini con i tuoi eserciti. Pacifista, no? :-)

KDE
giochi kde
gioco
strategia
Rischio
libero
GPL
Rete
IA

## Introduzione

&kapp; è la versione computerizzata di un famoso gioco di strategia. Esistono una versione commerciale e una libera ma io (Gael de Chalendar) ho creato questo gioco inizialmente come esercizio per imparare il C++ e poi l'ho sviluppato fino a questo punto (vedi README per i dettagli).

Ecco una schermata di &kapp; Schermata

Alla versione attuale, &kapp; è un gioco con funzionalità di rete per più di un giocatore, con una IA di base. (vedi TODO per i dettagli)

Questa documentazione fornisce le principali informazioni necessarie per iniziare a giocare. Leggi i suggerimenti e i messaggi della barra di stato per completare le informazioni.

Lo scopo del gioco è semplicemente conquistare il Mondo... Lo otterrai attaccando i tuoi vicini con i tuoi eserciti. Pacifista, no? :-)

## Usare &kapp;

### Giocare a &kapp;

Nota preliminare: si può scorrere la mappa in tre modi. Primo, puoi mettere il mouse vicino al bordo della finestra, e la mappa scorrerà in quella direzione. Secondo, puoi usare la rotellina del mouse: senza modificatore, scorrerà in verticale; premendo il tasto Meta, scorrerà in orizzontale. Inoltre, puoi usare i tasti freccia.

#### Iniziare una partita

Quando &kapp; si avvia, ti accoglie con il menu principale. Il menu principale di &kapp; Menu principale

Nuova partita

  Avvia una nuova partita

Partecipa

  Permette di partecipare a una partita in rete

Carica

  Usa questo per caricare una partita precedentemente salvata

Esci

  Magari alla fine non vuoi giocare?

Se fai clic su Nuova partita, ti si aprirà la finestra di dialogo Nuova partita dove potrai scegliere il numero di giocatori, il tema da usare, il tipo di partita (conquista o per obbiettivi) e infine se giocare la partita in rete o localmente. Finestra di dialogo Nuova partita Finestra di dialogo Nuova partita

Per avviare una partita in rete, seleziona la casella «Partita in rete» sulla destra della casella numerica del numero dei giocatori. Dopo aver fatto clic su Ok, potrai impostare i parametri di rete: numero di giocatori in rete e porta TCP su cui aspettare connessioni. Finestra di dialogo Parametri di rete Finestra di dialogo Parametri di rete

A quel punto i giocatori in rete potranno connettersi selezionando Partecipa nel menu principale e indicando l'IP o l'hostname dell'ospite e il numero della porta che hai precedentemente selezionato. Finestra di dialogo Partecipa a partita in rete Finestra di dialogo Partecipa a partita in rete

Ogni connessione è indicata dal messaggio nella barra di stato. Messaggio di connessione Messaggio di connessione

Immaginiamo tu mantenga tutte le impostazioni predefinite e selezioni Ok. Allora imposterai due giocatori, uno dopo l'altro. Per ciascuno dovrai scegliere un nome, una nazionalità e, se vuoi, impostare una password in modo che nessun altro possa utilizzare questo giocatore caricando il salvataggio della partita. Infine puoi scegliere se questo giocatore sarà guidato dal computer o da un essere umano. Finestra di dialogo Impostazioni giocatore Finestra di dialogo Impostazioni giocatore

Se scegli di giocare per obbiettivi, l'obbiettivo di ogni giocatore locale sarà mostrato preceduto da un messaggio di avviso che consiglia di non far vedere l'obbiettivo agli altri giocatori vicino al computer. Finestra di dialogo Mostra obbiettivo Finestra di dialogo Mostra obbiettivo Messaggio di avviso Mostra obbiettivo Messaggio di avviso Mostra obbiettivo

#### Distribuzione

All'inizio del gioco, gli stati sono distribuiti a tutti i giocatori. All'inizio ogni stato contiene un'armata (rappresentata da un soldato di fanteria). Ogni giocatore possiede alcune armate da distribuire ai suoi stati nel suo turno (indicato dalla presenza del suo nome e della sua bandiera nella barra di stato). Nota che cinque armate sono rappresentate da un soldato di cavalleria, e dieci da un cannone.

Per mettere un'armata in uno dei tuoi stati, fai clic con il pulsante sinistro del mouse. Per rimuovere un'armata, fai clic con il tasto destro. Nota, come regola generale, che non potrai mai rimuovere un numero di armate superiore a quelle che hai già disposto. Posizionamento armate Posizionamento armate

Quando un giocatore ha distribuito tutte le proprie armate, il giocatore successivo è selezionato automaticamente per svolgere la stessa procedura. Quando tutti i giocatori avranno finito di distribuire le proprie armate, si potrà scegliere tra due possibilità tramite due pulsanti nel pannello di destra:

Ridistribuzione : Ridistribuzione

  Un giocatore vuole cambiare alcune delle sue scelte. Il primo giocatore può quindi rimuovere un'armata che ha messo in uno stato con il tasto destro del mouse, e metterla in un altro con il tasto sinistro. Quando termina, passa il controllo al giocatore successivo con il pulsante «Convalida». Quando tutti i giocatori hanno finito la ridistribuzione, i due pulsanti sono visualizzati di nuovo.

Fine della ridistribuzione : Fine della ridistribuzione

  La ridistribuzione è terminata e il gioco può continuare.

#### Combatti

Dopo la ridistribuzione, inizia il turno. Ogni giocatore gioca a turno. Può scegliere di:

Giocatore Successivo : Passa la mano al giocatore seguente (pulsante nella barra degli strumenti)

  Finisce il turno dell'attuale giocatore e tocca al successivo.

Attacca 1 Attacca 2 Attacca 3 : Attacca con una, due o tre armate Attacca automaticamente

  Per attaccare trascina le armate dallo stato che attacca a quello attaccato. Ti sarà mostrato un menu contestuale con le seguenti voci. Menu di attacco Menu di attacco Affinché uno stato X attacchi uno stato Y con x armate, due condizioni devono essere verificate: 1. i due stati devono confinare; 2. lo stato X deve avere almeno x+1 armate prima dell'attacco. Se l'attacco è valido, è mostrata una finestra di dialogo al difensore se vuole difendere con una due armate o lasciar decidere al computer.

  Dopo la scelta del difensore avrà luogo la battaglia. Quest'ultimo è descritto in seguito. Finestra di dialogo Difesa Finestra di dialogo Difesa

Muovi armate : Muove le armate da uno stato ad un altro

  Questa è l'ultima azione del turno di un giocatore. Dà la possibilità di muovere alcune armate da uno dei propri stati ad un altro, confinante con il primo. Per scegliere i due paesi, fai clic e trascina come per un attacco. Quando entrambe le nazioni sono selezionate, appare un cursore con cui scegliere quante armate vorrai avere in ogni stato.

#### Risoluzione del combattimento

Per ogni armata coinvolta si lancerà un dado. Il giocatore che otterrà il numero maggiore sul dado, sia esso l'attaccante o il difensore, vince e quello con il numero più basso perde un numero di armate basato sul numero di dadi lanciati. Riepilogo attacco Riepilogo attacco

Se il numero delle armate nello stato del difensore raggiunge lo 0, lo stato diventa di proprietà dell'attaccante: viene impostata la sua bandiera e una delle sue armate si installa nel suo nuovo stato. Viene allora mostrato il cursore «Muovi armate» come alla fine del turno. Cursore invasione Cursore invasione

#### Fine del turno

Per concludere il turno attuale, se non vuoi muovere armate, puoi fare clic sul pulsante Prossimo giocatore» nella barra degli strumenti.

Quando tutti hanno giocato, la mano finisce. Vengono distribuite alcune armate ai giocatori, a seconda degli stati che possiedono: 1 per ogni gruppo di stati, con un minimo di tre. Inoltre c'è un bonus per i giocatori che possiedono un intero continente, ognuno differente. I valori dei bonus per il tema attuale sono:

##### Bonus per i continenti

Continente | Bonus
--- | ---
Nord America | 5
Sud America | 2
Europa | 5
Africa | 3
Asia | 7
Area del Pacifico | 2

Quando un giocatore termina di distribuire le proprie armate, fa clic su «Convalida» per permettere al giocatore seguente di distribuire le sue armate bonus. Come per la distribuzione iniziale, quando tutti i giocatori hanno disposto tutte le loro armate, possono iniziare un ulteriore giro di ridistribuzione o iniziare una nuova mano...

#### Inviare messaggi agli altri giocatori

Se vuoi comunicare con gli altri giocatori in una partita in locale, beh, parla (a meno che tu non abbia problemi di accessibilità)... Ma se stai partecipando ad una partita in rete, puoi usare lo spazio di chat sul fondo della finestra (può essere nascosto o mostrato usando le frecce). Inserisci il tuo messaggio e premi Invio. Inviare messaggi Inviare messaggi

## Guida ai Comandi

### La finestra principale di &kapp;

#### I pulsanti

Esci : Esce dal gioco

  Fa terminare il programma.

Nuovo Gioco : Nuovo Gioco

  Inizia un nuovo gioco. Verrà visualizzata una finestra di dialogo dove inserire il numero di giocatori. Dopodiché, verrà chiesto il nome di ogni giocatore in un'altra finestra.

## Guida degli Sviluppatori di &kapp;

Si prega di fare riferimento alla documentazione di KDoc per le API. Era piuttosto completa, ma è attualmente un po' datata. Non ci sono commenti nei file `.cpp` di implementazione.

Nota che ho sviluppato originariamente questo gioco in Windoz con Borland C++ e WinG. L'ho portato in &Java; per poi riconvertirlo in C++ e&kde;. All'inizio ho usato il francese o un misto di francese e inglese per nominare gli identificatori (classi, metodi, membri, &etc;). Ho anche usato il francese per i commenti. Quando ho deciso di distribuire questo gioco, ho scelto di convertirlo tutto in inglese... ma chiaramente non sono un madrelingua: per piacere suggeriscimi oppure fai e invia le correzioni, ai commenti del codice o a questa documentazione

## Creare nuovi temi

&kapp; è completamente modificabile. Per quelli che hanno capacità di grafica, creare un nuovo tema è semplice come copiarne uno esistente, modificarlo o cambiare la grafica e aggiornare i dati in un file .desktop di configurazione. L'ultimo passo è modificare il file descrivendo cosa installare.

Tutti gli esempi (testo ed immagini) sono presi dal tema predefinito di &kapp;

### Struttura delle cartelle e dei file

- Data/: Dati utilizzati dal programma per manipolare le immagini del tema.

  - CMakeLists.txt: Descrive cosa installare.

  - onu.desktop: File principale per la descrizione del tema. Vedi sotto per la sua descrizione.

- Images/: Le immagini del tema (mappa, entità, ecc.)

  - CMakeLists.txt: Descrive cosa installare.

  - pool.svg: la mappa e le entità usate in questo tema.

  - map-mask.png: l'immagine che permette al programma di cercare sopra che stato è il mouse durante il gioco (vedi sotto).

  - *.png: le altre immagini qui sono immagini di pulsanti.

- CMakeLists.txt/: Descrive cosa installare.

- Sounds/: file audio per il tema.

### La cartella Data

#### Il file onu.desktop

Questo file è una descrizione dei contenuti del tema. E' usato per descrivere l'organizzazione del mondo e come visualizzarla. Presenta la seguente struttura:

Un gruppo onu contiene un certo numero di stati, un certo numero di nazionalità e per finire un certo numero di continenti. Dunque vari gruppi contengono la descrizione di diverse entità, la descrizione di diversi stati, continenti, nazionalità e obbiettivi.

La sezione seguente descrive i contenuti di ogni gruppo.

##### Gruppo onu

###### Le voci del gruppo onu

Nome della voce | Significato
--- | ---
Larghezza | La larghezza della mappa del tema
altezza | L'altezza della mappa del tema
percorso del tema | Il percorso del tema relativo al percorso dei dati dell'applicazione (e.g. skins/default)
nb-countries | Il numero di stati (42 nel tema predefinito). Ci dovrebbe essere lo stesso numero di gruppi di stato specificati sotto
nb-nationalities | Il numero di nazionalità (6 nel tema predefinito). ci dovrebbe essere lo stesso numero di gruppi di nazionalità di seguito
nb-continents | Il numero di continenti (6 nel tema predefinito). Ci dovrebbero essere lo stesso numero di gruppi continente di seguito
pool | Il percorso e il nome del file con le immagini relativo al percorso del tema (p.e. Images/pool.svg)
map-mask | Il percorso e il nome del file maschera della mappa relativo al percorso del tema (ad es. Images/map-mask.png)
format-version | La versione del formato del file del tema (2.0)
nome | Il nome dell'elemento da mostrare
desc | Una lunga descrizione del tema
fighters-flag-y-diff | La differenza di altezza tra entità bandiere e cannoni
width-between-flag-and-fighter | Il numero di pixel tra il pixel più a sinistra della bandiera e il pixel più a destra del cannone semplice (quando non è né in sparo né in esplosione)

##### I gruppo di descrizione delle entità

Ogni tipo di entità (bandiera, fanteria, cavalleria, cannone, cannone che spara e cannone che esplode) è definita da un gruppo. Solo alcune entità hanno una voce larghezza. Questa voce è usata per il posizionamento relativo durante le animazioni: i cannoni, che sparano o che esplodono, non dovrebbero "muoversi" attorno alla bandiera dello stato durante il combattimento.

###### Voci del gruppo di descrizione delle entità

Voce | Significato
--- | ---
Larghezza | La larghezza di riferimento dei fotogrammi dell'entità bandiera
altezza | L'altezza di riferimento dei fotogrammi dell'entità bandiera
frames | Il numero di fotogrammi dell'entità
versions | Il numero di versioni delle entità bandiera

##### I gruppi di descrizione degli stati

Ogni stato elencato nel gruppo onu ha il suo gruppo, la cui etichetta è il nome dello stato. La tabella seguente elenca le voci di questi gruppi.

###### Voci dello stato

Nome della voce | Significato
--- | ---
id | Il numero intero di identificazione univoca di ogni stato, deve partire da zero (0)
nome | Il nome dello stato da mostrare
<sprite>-point | Ogni tipo di entità (bandiera, fanteria, ecc.) è visualizzata in una certa posizione dello stato definita da questa etichetta, composta da due interi separati da una virgola
neighbours | La lista degli identificativi degli stati confinanti con lo stato corrente

##### I gruppi di descrizione delle nazionalità

Ogni nazionalità elencato nel gruppo onu ha il suo gruppo, la cui etichetta è il nome della nazionalità. La tabella seguente elenca le voci di questi gruppi.

###### Nationality entries

Nome della voce | Significato
--- | ---
nome | Il nome della nazionalità (ad es. Giappone)
leader | Il nome proposto al giocatore mentre sceglie la sua nazionalità
flag | Il nome dell'entità della bandiera della nazione nel file SVG onu

##### I gruppi di descrizione dei continenti

Ogni continente elencato nel gruppo onu ha il suo gruppo, la cui etichetta è il nome del continente. La tabella seguente elenca le voci di questi gruppi.

###### Voci continente

Nome della voce | Significato
--- | ---
nome | Il nome del continente (ad es. Africa)
id | Il numero intero di identificazione univoca del continente
bonus | Il numero di armate ottenute alla fine del turno dal giocatore che possiede tutti gli stati di un continente
continent-countries | La lista degli id degli stati appartenenti al continente in questione

##### I gruppi di descrizione degli obbiettivi

Ogni obbiettivo elencato nel gruppo onu ha il suo gruppo, la cui etichetta è il nome dell'obbiettivo. La tabella seguente elenca le voci di questi gruppi.

###### Voci obbiettivo

Nome della voce | Significato
--- | ---
type | Il tipo dell'obbiettivo. Possono essere continenti, stati o giocatori
nbArmiesByCountry | imposta il numero minimo di armate che un giocatore deve posizionare in ogni stato
nbCountries | imposta il numero di stati che il giocatore deve possedere
nbCountriesFallback | Per un obbiettivo di tipo giocatore, se la vittima è uccisa da un altro giocatore, imposta il numero di stati che il giocatore deve conquistare come obbiettivo
desc | Una descrizione testuale dell'obbiettivo con appropriati segnaposto (c'è bisogno di ulteriore documentazione per questo)
continents | La lista degli identificativi dei continenti che un giocatore deve conquistare

### La cartella Images

Questa cartella contiene i pulsanti di &kapp; e il file SVG contenitore che include la mappa e tutte le entità.

#### Il file pool.svg

Questo file SVG contiene la mappa e tutte le entità del gioco. Ogni elemento ha un nome così che il gioco possa selezionare e disegnare separatamente ognuno di essi.

Nel tema predefinito, le entità sono bandiere, fanteria, cavalleria e cannone. La fanteria rappresenta una armata, la cavalleria cinque e i cannoni dieci. I cannoni sono inoltre usati per visualizzare le battaglie in corso. Per questo motivo ci sono tre tipi di entità cannone: quello normale (fermo o in movimento), quello che spara e quello che esplode.

Ogni immagine di entità è costituita valle varie viste dell'oggetto e, per ogni vista, dai suoi fotogrammi. Le viste sono organizzate verticalmente e i fotogrammi orizzontalmente. Dividendo l'altezza dell'immagine per il numero di viste e la larghezza per il numero dei fotogrammi si trova dove tagliare l'immagine nei singoli fotogrammi. Questi dati si trovano nel file onu.desktop.

Un esempio di un'immagine di entità: cannon.png

Per le entità armata ci sono tre viste differenti, dall'alto al basso: guardando a destra, guardando a sinistra e di fronte. Per le bandiere, c'è solo una vista. Tutti gli sfondi delle entità dovrebbero essere trasparenti.

Un esempio di immagine di entità bandiera: italy.png

##### Gli elementi del contenitore

Nome dell'elemento | Immagine di esempio | Significato
--- | --- | ---
map |  | La mappa del mondo del tema. Gli stati possono avere qualsiasi forma, ma dovrebbero essere raggruppati in continenti riconoscibili a colpo d'occhio, solo dalla posizione o dal colore
italy |  | La bandiera della nazione italiana. Ce n'è una per ogni nazionalità
infantry |  |
cavalry |  |
cannon |  |
firing |  |
exploding |  |
Alaska |  |
reddices |  |
mark1 |  |

#### Il file map-mask.png

Questo è un file png che rappresenta anche la mappa del mondo del tema, ma con un codice di colori che permette di identificare univocamente ogni stato. Gli stati devono avere almeno le stesse forme degli stati corrispondenti nel file map.png in modo che gli utenti possano fare clic ovunque in uno stato visibile e selezionare quello corretto. Gli stati con piccole isole come l'Indonesia nella mappa predefinita possono essere più grandi del corrispondente nel file map.png per facilitare la selezione dello stato. Una maschera di mappa di esempio

Il componente blu (secondo il modello RGB) del colore di uno stato identifica lo stato: l'indice 0 è lo stato 0 nel file onu.xml, l'indice 1 è lo stato 1, &etc;. Il bianco (0xFFFFFF in RGB) identifica l'assenza di stato (oceani oppure, perché no, terre di nessuno).

#### Le immagini dei pulsanti

I nomi dei file sono codificati nel codice, in questo modo non saranno modificati. La tabella seguente mostra i pulsanti che dovrebbero essere forniti.

##### I pulsanti della &GUI;

Immagine | Nome del file | Significato
--- | --- | ---
| newNetGame.png | Cerca di partecipare a una partita in rete
| distributionArmees.png | Dopo che tutti i giocatori hanno disposto le loro armate, è possibile modificare le distribuzioni (operazione di ricircolo). Questo pulsante chiede se fare questa ridistribuzione
| distributionArmeesFinie.png | Sceglie di non ridistribuire. Tutte le finestre dei client devono aver cliccato questo pulsante perché termini realmente la distribuzione
| joueurSuivant.png | Termina il turno del giocatore corrente e passa a quello successivo o alla mano successiva se il giocatore corrente era l'ultimo
| attackOne.png | Sceglie di iniziare l'attacco con un'armata
| attackTwo.png | Sceglie di iniziare l'attacco con due armate
| attackThree.png | Sceglie di iniziare l'attacco con un'armata
| defendOne.png | Sceglie di difendere uno stato attaccato con una armata
| defendTwo.png | Sceglie di difendere uno stato attaccato con due armate
| moveArmies.png | Sceglie di iniziare a spostare le armate tra due stati (ultima azione del turno)

### La cartella Sounds

Questa cartella contiene tre file audio: roll.wav che viene riprodotto durante lo spostamento delle armate; caccon.wav riprodotto durante un attacco e crash.wav riprodotto quando un'armata viene distrutta.

## Domande e Risposte

&reporting.bugs; &updating.documentation;

Quale sarà la prima domanda a proposito di &kapp;?

## Ringraziamenti e Accordi di Licenza

&kapp;

Copyright del programma 2002-2008 Gael de Chalendar kleag@free.fr

Contributi di: Robin Doer, Albert Astals Cid, Michal Golunski (traduzione in Polacco).

Copyright della documentazione 2002-2008 Gael de Chalendar kleag@free.fr

Traduzione di Dario PanicoDareus_Persarumrex@fastwebnet.it e Martino Barbon

&underFDL; &underGPL;

## Installazione

### Come ottenere &kapp;

&install.intro.documentation;

### Compilazione e installazione

&install.compile.documentation;

### Configurazione

La voce menu impostazioni apre una finestra di dialogo che ti permette di: Finestra di dialogo Preferenze Finestra di dialogo Preferenze

- abilita o disabilita i suoni:

- imposta la velocità delle entità (da lenta a immediata):

- abilita o disabilita l'aiuto contestuale mostrato nelle finestre a comparsa:

- mostra o nasconde il numero di armate per stato. La schermata seguente mostra la mappa quando il numero di armate è visualizzato. Mostra il numero di armate Mostra il numero di armate

&documentation.index;