# Manual do &kappname;

## Introdução

O &ksirk; é uma versão computorizada de um conhecido jogo de estratégia. O seu visual poderá ser modificado por completo. Este manual explica como criar visuais novos do zero, usando um navegador de arquivos, um editor de imagens SVG e o &kappname;.

Aqui está uma imagem do &kappname; Imagem

Existem três passos principais para criar um novo visual: criar a hierarquia de pastas; criar os gráficos, todos em conjunto, dentro de um arquivo SVG e, finalmente, colocar as imagens e atribuir nomes às coisas com o &kappname;.

## Criar um visual do &ksirk;

O visual do &ksirk; pode ser modificado por completo. Para as pessoas que tenham habilidades gráficas, a criação de um novo visual é tão simples como copiar um existente, editar ou alterar as imagens e atualizar os dados num arquivo de configuração '.desktop', o que é feito pelo &kappname;. Um último passo será editar o arquivo que descreve os itens a instalar.

Todos os exemplos (texto e imagens) são retirados do visual padrão do &ksirk;

### Estrutura de pastas e arquivos

- Data/ : Os dados usados pelo programa para lidar com as imagens do visual.

  - CMakeLists.txt : Descreve o que deseja instalar.

  - onu.desktop : O arquivo principal de descrição do visual. Veja a sua descrição abaixo.

- Images/ : As imagens do visual (mapa, bonecos, etc.)

  - CMakeLists.txt : Descreve o que deseja instalar.

  - pool.svg : o mapa e todas as imagens usadas neste visual.

  - map-mask.png : a imagem que permite ao programa descobrir em que país se encontra o mouse durante o jogo (ver abaixo).

  - *.png : as outras imagens aqui colocadas são as imagens dos botões.

- CMakeLists.txt/ : Descreve o que deseja instalar.

- Sounds/ : arquivos de sons para o visual.

#### A pasta 'Data'

Esta pasta contém apenas um arquivo, o 'world.desktop'. Este arquivo é uma descrição do conteúdo do visual. É usado para descrever a organização do mundo e como apresentá-lo. Você não tem que preenchê-lo manualmente, uma vez que será tratado pelo &kappname;. Contudo, por razões de abrangência, será agora descrita a sua estrutura.

Um grupo 'onu' contém um conjunto de itens 'countries', o conjunto de itens 'nationality' e, por fim, um conjunto de itens 'continent'. Depois, os vários grupos contêm a descrição das diferentes imagens, países, continentes, nacionalidades e objetivos.

As seguintes seções descrevem o conteúdo de cada grupo.

##### O grupo ONU

##### Os itens do grupo ONU

Nome do item | Significado
largura | A largura do mapa do visual
height | A altura do mapa do visual
skinpath | A localização do visual, em relação à localização dos dados da aplicação (p.ex., 'skins/default')
nb-countries | O número de países (42 no visual padrão). Deverá existir o mesmo número de marcas 'country' abaixo
nb-nationalities | O número de nacionalidades (6 no visual padrão). Deverá existir o mesmo número de marcas 'nationality' abaixo
nb-continents | O número de continentes (6 no visual padrão). Deverá existir o mesmo número de marcas 'continent' abaixo
pool | A localização e nome do arquivo do mar, em relação à localização do visual (p.ex. 'Images/pool.svg')
map-mask | A localização e nome do arquivo de máscara do mapa, em relação à localização do visual (p.ex. Images/map-mask.png)
format-version | A versão do formato do arquivo do visual (2.0)
nome | O nome visível do visual
desc | A descrição extensa do visual
fighters-flag-y-diff | A diferença de altura entre as imagens das bandeiras e dos canhões
width-between-flag-and-fighter | O número de pixels entre o pixel do canto superior esquerdo da bandeira e o pixel mais à direita do canhão simples (quando não tiver disparado nem explodido)

##### Os grupos de descrição das imagens

Cada tipo de imagem (bandeira, infantaria, cavalaria, canhão, canhão em disparo e canhão explodido) é definido por um grupo. Somente algumas imagens têm dados de largura. Estas são usadas para o posicionamento relativo durante as animações: os canhões, em disparo ou em explosão, não deverão se "mover" em torno da bandeira durante o combate.

##### Itens do grupo de descrição da imagem

Entrada | Significado
largura | A largura de referência das imagens das bandeiras
height | A altura de referência das imagens das bandeiras
frames | O número de imagens da bandeira
versions | O número de versões das imagens das bandeiras

##### Os grupos de descrição dos países

Em cada país que consta no grupo ONU, o item 'countries' contém o seu próprio grupo, cujo nome é o do país. A tabela abaixo apresenta os itens destes grupos.

##### Itens dos países

Nome do item | Significado
id | O número inteiro identificador do país, que deverá começar em zero (0)
nome | O nome visível do país
<sprite>-point | Cada tipo de boneco (bandeira, infantaria, etc.) no país aparece de acordo com uma certa posição definida neste elemento, que consiste em dois números inteiros separados por vírgulas
neighbours | A lista de identificadores dos vizinhos do país atual

##### Os grupos de descrição das nacionalidades

Em cada nacionalidade que aparece no grupo ONU, o item 'nationalities' tem o seu próprio grupo, cujo nome é o da nacionalidade. A tabela abaixo mostra os itens destes grupos.

##### Itens de nacionalidades

Nome do item | Significado
nome | O nome da nacionalidade (p.ex., 'Japão')
leader | O nome que será proposto ao jogador que escolher esta nacionalidade
flag | O nome do arquivo do gráfico da bandeira do país, no arquivo SVG do ONU

##### Os grupos de descrição dos continentes

Em cada continente que aparece no grupo ONU, o item 'continents' tem o seu próprio grupo, cujo nome é o do continente. A tabela abaixo mostra os itens destes grupos.

##### Itens de continentes

Nome do item | Significado
nome | O nome do continente (p.ex., 'África')
id | O número inteiro identificador do continente
bônus | O número de exércitos que são obtidos no fim de jogada, após o jogador possuir todos os países desse continente
continent-countries | A lista de identificadores dos países dentro do continente atual

##### Os grupos de descrição dos objetivos

Em cada objetivo que aparece no grupo ONU, o item 'goals' tem o seu próprio grupo, cujo nome é o do objetivo. A tabela abaixo mostra os itens destes grupos.

##### Itens do objetivo

Nome do item | Significado
type | O tipo de objetivo. Poderá ser 'continents' (continentes), 'countries' (países) ou 'player' (jogador)
nbArmiesByCountry | define o número mínimo de exércitos que o jogador terá que colocar em cada país
nbCountries | define o número de países que o jogador deverá possuir
nbCountriesFallback | Para um tipo de objetivo por jogador, se o jogador de destino for morto por outro, este define o número de países que o jogador terá que conquistar em alternativa
desc | Uma descrição em texto completo do objetivo, com alguns itens de substituição adequados
continentes | A lista de IDs de continentes que o jogador terá que conquistar

#### A pasta 'Images'

Esta pasta contém os botões específicos do &ksirk; e o arquivo SVG completo que contém o mapa e todas as imagens.

##### O arquivo 'pool.svg'

Este arquivo SVG contém o mapa e todas as imagens do jogo. Cada elemento tem um determinado nome para o jogo selecionar e representar em separado.

No visual padrão, são as bandeiras, os soldados e os canhões. A infantaria representa um exército, a cavalaria cinco e os canhões dez. Os canhões são também usados para mostrar as guerras em curso. É por isso que existem três tipos de canhões: estáticos, em disparo ou em explosão.

Cada imagem do gráfico é a concatenação das diversas vistas do objeto e, para cada vista, as suas imagens. As vistas são organizadas na vertical e as subimagens na horizontal. O local de corte da imagem em subimagens individuais é determinado pela divisão da altura da imagem pelo número de vista e a largura pelo número de subimagens. Estes dados estão no arquivo 'onu.desktop'.

Um exemplo de uma imagem de boneco: cannon.png

Para as imagens dos exércitos, existem três diferentes vistas, de cima para baixo:

- olhando para a direita

- olhando para a esquerda e

- olhando para a frente

Para as bandeiras, só existe uma vista. Todos os fundos deverão ser transparentes.

Um exemplo de uma imagem de uma bandeira: italy.png

##### Os elementos do fundo

Nome do elemento | Imagem de Exemplo | Significado
map |  | O mapa-mundo do visual. Os países poderão ter diversas formas, mas deverão estar agrupados em continentes perceptíveis, através da sua localização ou da sua cor.
italy |  | A bandeira da Itália. Existe um destes itens para cada nação
infantry |  | Ícone que representa um exército
cavalaria |  | Ícone que representa cinco exércitos
canhão |  | Ícone que representa dez exércitos
firing |  | Ícone que representa exércitos durante um combate
exploding |  | Ícone que representa os exércitos perdendo uma batalha
Alasca |  | A forma do território do Alasca. Isto é usado para realçar o mesmo território. Existe uma destas formas para cada país ou região. A sua cor não é usada, podendo escolher a cor que desejar.
reddices |  | Os dados vermelhos usados para mostrar os resultados das batalhas
bluedices |  | Os dados azuis usados para mostrar os resultados das batalhas
mark1 |  | Esta marca é adicionada às imagens de combate para mostrar o número de exércitos que representam, sendo neste caso 1. Existem também os elementos 'mark2' e 'mark3'.

##### O arquivo 'map-mask.png'

Este é um arquivo PNG que representa também o mapa-mundo do visual, só que com cores codificadas que permitem identificar de forma unívoca cada país. Os países deverão ter pelo menos a mesma forma que os países correspondentes no arquivo 'map.png', para que os usuários possam clicar em qualquer ponto de um país visível e selecionar o correto. Os países de pequenas ilhas, como a Indonésia, poderão ser maiores que os equivalentes no arquivo 'map.png', de modo a facilitar a seleção do país. Uma máscara do mapa de exemplo

A componente azul (no modelo RGB) da cor de um país identifica o país: o índice 0 é o país 0 no arquivo 'onu.xml', o índice 1 é o país 1, &etc; O branco (0xFFFFFF em RGB) identifica a ausência de país (mar ou, porque não, terra-de-ninguém).

##### As imagens dos botões

Os nomes dos arquivos estão fixos no código, assim eles não deverão ser modificados. A tabela abaixo mostra todos os botões que deverão constar.

##### Os botões da &GUI;

Imagem | Nome do Arquivo | Significado
| newNetGame.png | Tenta conectar-se a um jogo em rede
| recycling.png | Depois de todos os jogadores terem colocado os seus exércitos, é possível modificar as distribuições (chamado 'redistribuição'). Este botão pergunta a confirmação de uma redistribuição
| recyclingFinished.png | Opta por não redistribuir. Todas as janelas clientes deverão clicar neste botão para terminar de fato a distribuição
| nextPlayer.png | Termina a jogada do jogador atual e muda para o seguinte, ou para a jogada seguinte, se o jogador for o último
| attackOne.png | Opta por iniciar um ataque com um exército
| attackTwo.png | Opta por iniciar um ataque com dois exércitos
| attackThree.png | Opta por iniciar um ataque com três exércitos
| defendOne.png | Opta por defender um país atacado com um exército
| defendTwo.png | Opta por defender um país atacado com dois exércitos
| moveArmies.png | Opta por iniciar o movimento de exércitos entre dois países (última ação da jogada)

#### A pasta 'Sounds'

Esta pasta contém três arquivos de sons:

- o 'roll.wav', que é tocado quando os exércitos estão em movimento

- o 'cannon.wav', que é tocado quando disparar e

- o 'crash.wav', que é tocado quando um canhão explode

### Usar o &kappname;

Depois de criar os gráficos na pasta correta e o arquivo SVG, você terá apenas que criar os países, jogadores, etc. e associá-los ao elemento de SVG correto na imagem. Isto poderá ser feito com o &kappname;. Lembre-se que cada parte desta aplicação está descrita automaticamente com as dicas e com a ajuda de contexto, que normalmente está acessível com o atalho Ctrl+F1.

Aqui está uma imagem do &kappname; Imagem

## Referência de comandos

### A janela principal do &kappname;

#### Os botões

Carregar Carregar

- Faz com que o programa carregue um visual existente.

Salvar Salvar

- Salva o visual atualmente editado

## Guia de Programação do &kappname;

Veja por favor em http://api.kde.org/ a documentação da API.

## Perguntas e respostas

&updating.documentation;

## Créditos e licença

&kappname;

Programa com 'copyright' 2009 de Gael de Chalendar kleag@free.fr

Documentação com 'copyright' 2009 de Gael de Chalendar kleag@free.fr

Tradução de Marcus Gama marcus.gama@gmail.com

&underFDL; &underGPL;

## Instalação

### Como obter o &kappname;

&install.intro.documentation;

### Compilação e instalação

&install.compile.documentation;
&documentation.index;