# Manual do &kappname;

Gael
Kleag
de Chalendar

    Kleag@free.fr

José
Pires

    zepires@gmail.com

Tradução
2009
Gael de Chalendar
&FDLNotice;
22/05/2009
4.3

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 ficheiros, um editor de imagens SVG e o &kappname;.

KDE
kdegames
jogo
estratégia
Risco
livre
GPL
visual
editor

## 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 ficheiros, 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 ficheiro 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 capacidades de grafismo, a criação de um novo visual é tão simples como copiar um existente, editar ou alterar as imagens e actualizar os dados num ficheiro de configuração '.desktop', o que é feito pelo &kappname;. Um último passo será editar o ficheiro que descreve os itens a instalar.

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

### Estrutura de pastas e ficheiros

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

  - CMakeLists.txt : Descreve o que deseja instalar.

  - onu.desktop : O ficheiro principal de descrição do visual. Veja a sua descrição em baixo.

- 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 rato 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/ : ficheiros de sons para o visual.

#### A pasta 'Data'

Esta pasta contém apenas um ficheiro, o 'world.desktop'. Este ficheiro é uma descrição do conteúdo do visual. É usado para descrever a organização do mundo e como apresentá-lo. Não tem de o preencher manualmente, dado que será tratado pelo &kappname;. Contudo, por razões de completação, 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 objectivos.

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

##### O grupo ONU

###### Os itens do grupo ONU

Nome do item | Significado
--- | ---
width | 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 por omissão). Deverá existir o mesmo número de marcas 'country' em baixo
nb-nationalities | O número de nacionalidades (6 no visual por omissão). Deverá existir o mesmo número de marcas 'nationality' em baixo
nb-continents | O número de continentes (6 no visual por omissão). Deverá existir o mesmo número de marcas 'continent' em baixo
pool | A localização e nome do ficheiro do mar, em relação à localização do visual (p.ex. 'Images/pool.png')
map-mask | A localização e nome do ficheiro 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 ficheiro do visual (2.0)
name | 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. Só 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 se deverão "mover" em torno da bandeira durante o combate.

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

Item | Significado
--- | ---
width | A largura de referência das imagens das bandeiras
height | A altura de referência das imagens das bandeiras
molduras | 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, 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)
name | 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 actual

##### 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
--- | ---
name | O nome da nacionalidade (p.ex., 'Japão')
leader | O nome que será proposto ao jogador que escolher esta nacionalidade
flag | O nome do ficheiro do gráfico da bandeira do país, no ficheiro 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
--- | ---
name | O nome do continente (p.ex., 'África')
id | O número inteiro identificador do continente
bonus | 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 actual

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

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

###### Itens do objectivo

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

#### A pasta 'Images'

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

##### O ficheiro 'pool.svg'

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

No visual por omissã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 objecto e, para cada vista, as suas imagens. As vistas são organizadas na vertical e as sub-imagens na horizontal. O local de corte da imagem em sub-imagens individuais é determinado pela divisão da altura da imagem pelo número de vista e a largura pelo número de sub-imagens. Estes dados estão no ficheiro '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:

- a olhar para a direita

- a olhar para a esquerda e

- de face 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
cavalry |  | Ícone que representa cinco exércitos
cannon |  | Ícone que representa dez exércitos
firing |  | Ícone que representa exércitos durante um combate
exploding |  | Ícone que representa os exércitos a perder 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, pelo que pode 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 ficheiro 'map-mask.png'

Este é um ficheiro 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 ficheiro 'map.png', para que os utilizadores possam carregar em qualquer ponto de um país visível e seleccionar o correcto. Os países de pequenas ilhas, como a Indonésia, poderão ser maiores que os equivalentes no ficheiro 'map.png', de modo a facilitar a selecçã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 ficheiro '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 ficheiros estão fixos no código, pelo que 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 Ficheiro | Significado
--- | --- | ---
| newNetGame.png | Tenta ligar-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 dos clientes deverão carregar neste botão para terminar de facto a distribuição
| nextPlayer.png | Termina a jogada do jogador actual 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 acção da jogada)

#### A pasta 'Sounds'

Esta pasta contém três ficheiros 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 correcta e o ficheiro SVG, apenas terá de criar os países, jogadores, etc. e associá-los ao elemento de SVG correcto 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.

Gravar Gravar

  Grava o visual editado de momento

## 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 José Nuno Pires zepires@gmail.com

&underFDL; &underGPL;

## Instalação

### Como obter o &kappname;

&install.intro.documentation;

### Compilação e Instalação

&install.compile.documentation;

&documentation.index;